🐝 Hornet Nest Locator

🌍 Protect bees by locating invasive Asian hornet nests!

🇫🇷 Version Française | 📖 Documentation | 🗺️ Roadmap

🐝 Created to Help Beekeepers Fight Asian Hornets

Asian hornets (Vespa velutina) are devastating predators that destroy honeybee hives, threatening our vital pollinators. This tool was specifically developed to help beekeepers locate and eliminate hornet nests before they can decimate bee colonies. By tracking hornet flight patterns and calculating nest locations, beekeepers can take targeted action to protect their hives and preserve bee populations.

Join the fight to save our bees! 🐝💛

🚀 Quick Start

📥 Download Standalone App (No Python Required)

🪟 Windows Executable

🐍 Install with Python

# Install from PyPI
pip install hornet-nest-locator

# Or install from source
git clone https://github.com/jyjeanne/hornet-nest-locator.git
cd hornet-nest-locator
pip install -e .

🎯 Run the Application

# Launch GUI
python gui.py

# Or use CLI
python main.py

🌟 Features

🎨 Beautiful & Professional Interface

🗺️ Interactive Maps with Leaflet.js

• 📍 Observation Points - Mark where you saw hornets
• 🔴 Estimated Nest Locations - Visual hive position estimates
• ⭕ Confidence Zones - Search area indicators
• 🗺️ Multiple Map Layers - Satellite, terrain, and street views

📊 Professional Calculation Methods

Method	Description	Accuracy
Empirical 🎯	Vespawatchers standard (100m/min)	⭐⭐⭐⭐⭐
Theoretical 📈	Speed × time formula	⭐⭐⭐
Triangulation 🔺	Multiple observations	⭐⭐⭐⭐⭐

🌍 Multi-language Support

• 🇬🇧 English - Default language
• 🇫🇷 French - Complete translation
• 🌐 Easy Switching - One-click language toggle

🔧 Advanced Features

• 📱 Responsive Design - Works on desktop and tablet
• 📁 Data Export - Save observations and reports
• 📊 Comparison Tools - Compare calculation methods
• 🔍 Search History - Track multiple observations
• 📝 Field Notes - Add detailed annotations

🎯 How It Works

🐝 The Science Behind It

Asian hornets (Vespa velutina) fly relatively straight paths between their hunting grounds and nests. By measuring:

1. Round trip time ⏱️ - How long the hornet takes to go and return
2. Flight direction 🧭 - Compass bearing where the hornet flies
3. Observation point 📍 - Your GPS coordinates

We can calculate the nest location using the Vespawatchers empirical method:

Distance (meters) = Round trip time (minutes) × 100

📐 Professional Methodology

graph TD
    A[Start Observation] --> B[Mark GPS Location]
    B --> C[Note Flight Direction]
    C --> D[Measure Round Trip Time]
    D --> E[Calculate Distance]
    E --> F[Project Hive Location]
    F --> G[Generate Map]
    G --> H[Save Report]

Loading

---

📚 Step-by-Step Field Guide

🎒 Required Materials

Before you begin, gather these essential items:

Essential Equipment (Required)

• ✅ Binoculars 8×42 - MOST IMPORTANT! For tracking hornets in flight
• ✅ Smartphone with GPS - For coordinates and compass
• ✅ Stopwatch/Chronometer - For precise timing (smartphone app works)
• ✅ Compass - Mechanical or smartphone app (0-360° readings)
• ✅ Notebook and pen - For recording observations

Bait Station Materials (Required)

• ✅ Sugar syrup - Mix 1 part sugar + 1 part water (or use honey water)
• ✅ Wick pot - Small container with absorbent material (cotton, sponge)
• ✅ Bait stand - Small table or elevated platform (~1m high)

Marking Materials (Highly Recommended)

• ✅ Non-toxic paint - White, yellow, or red (water-based acrylic)
• ✅ Fine paintbrush - For marking individual hornets
• ✅ Butterfly net - Optional, for catching hornets to mark

Safety Equipment (Essential)

• ✅ Light-colored clothing - Avoid dark colors that attract hornets
• ✅ Hat with brim - Protect your head
• ✅ Protective eyewear - Safety glasses or sunglasses
• ⚠️ Emergency phone - Fully charged, programmed with emergency numbers

Optional but Useful

• 📱 Portable phone charger
• 🗺️ Physical map of the area
• 📷 Camera for documenting the process
• 🧴 Water and snacks (long observation sessions)
• 🌡️ Weather-appropriate gear

---

🔍 Step-by-Step Tutorial

STEP 1: Find a Good Location 🗺️

What to do:

1. Look for areas where hornets hunt (near apiaries, flowers, or fruit trees)
2. Choose an open area with good visibility
3. Ensure you have phone signal for GPS
4. Note the time (best: 9 AM - 4 PM on sunny days)

Expected time: 15-30 minutes

Tips:

• Hornets are most active on warm, sunny days (>20°C / 68°F)
• Avoid windy days (hornets don't fly well in wind)
• Early morning and late afternoon are best for activity

---

STEP 2: Set Up Your Bait Station 🍯

What to do:

1. Prepare sugar syrup:

   • Mix 100ml sugar + 100ml water
   • Heat gently until sugar dissolves (optional)
   • Let cool to room temperature

2. Set up the wick pot:

   • Pour syrup into a small container
   • Place absorbent material (cotton/sponge) to soak up syrup
   • Position on elevated platform (~1 meter high)

3. Wait for hornets to arrive:

   • Can take 10 minutes to 2 hours
   • Be patient and stay quiet
   • Use binoculars to scan the area

Expected time: 10-15 minutes setup, 30-120 minutes waiting

Safety note: ⚠️ Do not use toxic substances. Only sugar water is needed!

---

STEP 3: Mark Individual Hornets 🎨

What to do:

1. Wait for hornet to feed:

   • Let hornet land on the bait station
   • Wait until it's fully engaged in feeding

2. Mark the hornet:

   • Method A (without net): Gently dab paint on thorax while feeding
   • Method B (with net): Catch briefly, mark, release immediately

3. Use distinct colors:

   • First hornet: White paint
   • Second hornet: Yellow paint
   • Third hornet: Red paint

4. Release and observe:

   • Marked hornet will fly away to nest
   • Return in 5-10 minutes

Expected time: 5-10 minutes per hornet

Safety tips:

• Work slowly and calmly
• If hornet becomes agitated, step back
• Never squeeze or harm the hornet
• Only mark 1-2 hornets initially

Pro tip: White paint is most visible through binoculars!

---

STEP 4: Record Your GPS Position 📍

What to do:

1. Open your smartphone GPS:

   • Use Maps app, GPS app, or our application
   • Wait for accurate signal (typically ±5 meters)

2. Note your coordinates:

   • Latitude: e.g., 48.8584 (positive = North, negative = South)
   • Longitude: e.g., 2.2945 (positive = East, negative = West)

3. Record in decimal degrees format:

   • NOT degrees/minutes/seconds
   • Example: 48.8584, 2.2945 ✅
   • NOT: 48°51'30"N, 2°17'40"E ❌

Expected time: 2-3 minutes

How to get coordinates:

• iPhone: Maps app → drop pin → swipe up → see coordinates
• Android: Google Maps → long press → see coordinates at top
• Our app: Built-in GPS help button

---

STEP 5: Track the Marked Hornet 🔭

What to do:

1. Watch the marked hornet return:

   • Use binoculars to track it
   • Note the direction it flies when leaving

2. Measure departure direction with compass:

   • Stand at bait station
   • Point compass in the direction hornet flies
   • Read bearing in degrees (0-360°)
   • Examples:
     • North = 0° (or 360°)
     • East = 90°
     • South = 180°
     • West = 270°
     • Northeast = 45°
     • Southeast = 135°

Expected time: 5-10 minutes

Tips:

• Track the hornet for at least 50-100 meters
• The further you can see it, the more accurate your bearing
• Write down the bearing immediately
• Use landmarks to remember the direction

---

STEP 6: Measure Round Trip Time ⏱️

This is the MOST IMPORTANT measurement!

What to do:

1. Start your stopwatch when:

   • The marked hornet leaves the bait station
   • It must be clearly visible leaving

2. Stop your stopwatch when:

   • The SAME marked hornet returns (check paint color!)
   • It lands back on the bait station

3. Record time in minutes and seconds:

   • Example: 6 minutes 30 seconds
   • Be PRECISE - every 10 seconds = ~17 meters!

4. Repeat measurement 3-5 times:

   • Use the same marked hornet
   • Calculate average time
   • Discard outliers (if hornet got distracted)

Expected time: 15-30 minutes (3-5 round trips)

Common round trip times:

• 2-4 minutes = Nest is 200-400m away (close!)
• 5-8 minutes = Nest is 500-800m away (medium)
• 10-15 minutes = Nest is 1-1.5km away (far)

Critical tips:

• ⚠️ Measure MULTIPLE times! One measurement is not reliable
• ✅ Ignore trips where hornet seems distracted
• ✅ Use the marked hornet - don't confuse with unmarked ones
• ✅ Start/stop timer precisely

What if the hornet doesn't come back?

• Wait 30 minutes
• Mark another hornet
• Some hornets abandon feeding sites

---

STEP 7: Enter Data into Application 💻

What to do:

1. Launch VespaFinder application:

   python gui.py
   # or double-click VespaFinder executable

2. Enter GPS coordinates:

   • Latitude: (your latitude from Step 4)
   • Longitude: (your longitude from Step 4)

3. Enter flight direction:

   • Bearing: (compass reading from Step 5, 0-360°)

4. Enter round trip time:

   • Minutes: (e.g., 6)
   • Seconds: (e.g., 30)

5. Optional fields:

   • Hornet mark: "White paint" or "Yellow paint"
   • Notes: "Sunny day, 25°C, near apple orchard"

6. Click "CALCULATE HIVE LOCATION" 🎯

Expected time: 2-3 minutes

---

STEP 8: Analyze the Generated Map 🗺️

What happens:

1. Application calculates distance:

   • Using Vespawatchers formula: 100 meters = 1 minute
   • Example: 6.5 minutes = 650 meters

2. Map opens in your browser showing:

   • 🔵 Blue marker = Your observation point
   • 🔴 Red marker = Estimated nest location
   • ⭕ Red circle = Search zone (confidence radius)
   • ➡️ Blue arrow = Flight direction
   • --- Red dashed line = Estimated flight path

3. Understanding the search zone:

   • The red circle shows where to search
   • Radius typically ±50-100 meters
   • Nest is usually at the edge of this circle or slightly beyond

Expected time: 1 minute

Map features you can use:

• Zoom in/out with mouse wheel
• Switch map layers (satellite view is best!)
• Click markers for detailed information
• Print map or save for offline use

---

STEP 9: Search for the Nest 🔍

What to do:

1. Navigate to the red marker location:

   • Use smartphone GPS navigation
   • Walk to the estimated location
   • Bring your binoculars!

2. Search methodology:

   • First: Look UP in trees (most common)
   • Also check: Buildings, sheds, ground holes, hedges, bushes
   • Use binoculars to scan treetops
   • Look for hornet flight activity (multiple hornets flying in/out)

3. Walk in expanding circles:

   • Start at red marker
   • Walk in 50-meter circles
   • Scan trees and structures
   • Listen for buzzing sounds

4. Best time to search:

   • Early morning (hornets just waking up)
   • Late afternoon (returning to nest)
   • Warm, sunny days

Expected time: 30 minutes - 2 hours

What to look for:

• ✓ Regular hornet traffic (in and out)
• ✓ Multiple hornets in same area
• ✓ Gray/brown papier-mâché structure
• ✓ Round or pear-shaped nest
• ✓ Size: football to basketball (or larger)

Safety warnings:

• ⚠️ DO NOT approach closer than 5 meters
• ⚠️ NEVER throw objects at nest
• ⚠️ DO NOT make loud noises
• ⚠️ Wear light-colored clothing

---

STEP 10: Report and Handle the Nest 📞

What to do:

1. Document the nest location:

   • Take photos from safe distance (zoom lens)
   • Note GPS coordinates of nest
   • Record height and location (tree species, building, etc.)

2. Report to authorities:

   • 🇧🇪 Belgium: Vespawatch.be
   • 🇳🇱 Netherlands: Waarneming.nl
   • 🇫🇷 France: Local pest control or fire department
   • Your local wildlife/pest management service

3. Professional removal:

   • ⚠️ NEVER attempt DIY removal
   • Contact licensed pest control professionals
   • Removal best done at night when hornets are inactive
   • Professionals use protective suits and specialized equipment

Expected time: 15-30 minutes

Why professional removal is essential:

• Asian hornet stings can be dangerous
• Nests can contain 1,000+ hornets
• Disturbed colonies attack aggressively
• Professional equipment needed for safe removal

---

🎯 Advanced Technique: Triangulation

For MAXIMUM accuracy, use multiple observation points!

What to do:

1. Set up second bait station:

   • Position 200-300 meters from first station
   • Different location, different angle

2. Mark different hornets:

   • Use different paint colors
   • Record GPS, bearing, and time for each station

3. Enter multiple observations:

   • Add first observation to application
   • Add second observation to application
   • Application will calculate intersection point

4. Result:

   • Much more accurate location (±20-30 meters)
   • Two intersecting search zones
   • Nest is at intersection point

Expected accuracy improvement:

• Single observation: ±50-100m
• Triangulation (2 points): ±20-50m
• Triangulation (3 points): ±10-30m

---

📊 Real-World Example

Scenario: Finding a nest near an apiary

OBSERVATION DATA:
├─ Location: 48.8584°N, 2.2945°E (near Paris)
├─ Bearing: 135° (Southeast direction)
├─ Round trip time: 6 minutes 30 seconds
└─ Weather: Sunny, 23°C, light wind

CALCULATION:
├─ Time in minutes: 6.5 minutes
├─ Distance formula: 6.5 × 100 = 650 meters
└─ Confidence radius: ±50 meters

RESULT:
├─ Estimated nest location: 48.8540°N, 2.3015°E
├─ Direction to search: Southeast (135°)
├─ Distance to walk: 650 meters
└─ Search zone: Circle with 50m radius

OUTCOME:
✅ Nest found in oak tree at 625 meters
✅ Professional removal scheduled
✅ 5 bee hives protected!

---

⚠️ Safety Guidelines

ALWAYS follow these safety rules:

1. Never approach nest closely

   • Stay at least 5 meters away
   • Use binoculars for observation

2. Wear appropriate clothing

   • Light colors (white, beige, light blue)
   • Long sleeves and pants
   • Hat with brim

3. Know when to retreat

   • If hornets become aggressive, walk away calmly
   • Don't run (attracts attention)
   • Don't swat at hornets

4. Emergency preparedness

   • Carry phone with emergency numbers
   • Know location of nearest hospital
   • If allergic to stings, carry EpiPen

5. Professional help

   • Always use professionals for nest removal
   • Don't attempt DIY removal
   • Report nest to local authorities

---

📝 Quick Reference Checklist

Before going to field:

• Weather check (sunny, >20°C, low wind)
• Charged phone with GPS
• Binoculars
• Stopwatch/chronometer
• Compass (or compass app)
• Sugar syrup prepared
• Wick pot and bait stand
• Paint and brush
• Notebook and pen
• Appropriate clothing
• Emergency contacts programmed

During observation:

• GPS coordinates recorded
• Hornet marked with paint
• Flight direction noted (0-360°)
• Round trip time measured (3-5 times)
• Data entered into application
• Map generated and saved

After observation:

• Nest location searched
• Nest documented (photos, GPS)
• Authorities notified
• Professional removal arranged
• Success recorded!

📋 Requirements

🐍 Python Dependencies

pip install -r requirements.txt

📦 Key Dependencies

• folium>=0.15.0 - Interactive maps
• requests>=2.32.0 - API communications
• ruff>=0.4.4 - Code quality (dev)
• pytest>=8.0.0 - Testing (dev)

🧪 Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/vespa_finder --cov-report=html

Test Coverage: ⭐⭐⭐⭐⭐ (95%+)

⚙️ GUI Configuration & Display Notes

Window Sizing

• Responsive sizing: Window automatically sizes to 70% of screen width × 80% of screen height
• Size constraints: Minimum 900×800 pixels, maximum 1400×1200 pixels
• Auto-centering: Window automatically centers on screen at startup
• The input panel features a scrollable interface for easier navigation on smaller screens

Display Recommendations

• Minimum screen resolution: 900×800 (enforced minimum window size)
• Recommended resolution: 1280×1024 or higher
• Font rendering: Uses Courier 10pt for results display with improved readability

Scrollbar Behavior

• Input panel includes both vertical and horizontal scrollbars for all entry fields
• Results panel uses ScrolledText widget with automatic scrollbar
• Tip: Use mouse wheel or arrow keys for smooth scrolling

Recent GUI Improvements (v0.3.1)

• Input validation: Real-time validation prevents invalid input in numeric fields
• Compact input fields: Reduced entry field widths for cleaner layout
• Horizontal scrollbar: Added to input panel for better navigation
• Left-aligned buttons: Calculate and action buttons now properly aligned
• Dynamic translation: Results panel automatically refreshes when switching languages
• Optimized panel ratio: Input panel (weight=1) and Results panel (weight=2) for better balance

🛠️ Development

📝 Code Style

# Check formatting
ruff format --check .

# Auto-fix formatting
ruff format .

# Run linter
ruff check .

🔄 Git Workflow

# Clone repository
git clone https://github.com/YOUR-USERNAME/hornet-nest-locator.git

# Create feature branch
git checkout -b feature/your-feature

# Commit changes
git commit -m "Add amazing feature"

# Push to GitHub
git push origin feature/your-feature

🤝 Contributing

We welcome contributions! Please see:

• 📖 Code Style Guide
• 🗺️ Development Roadmap
• 🤝 Contributing Guidelines

📚 Documentation

• 📋 User Guide - Step-by-step instructions
• 🎨 Code Style - Development standards
• 🏗️ Build Process - Compilation guide
• 🗺️ Roadmap - Future development plans

📢 Community

Join our conservation community:

• 🐝 Vespawatch - Belgian hornet tracking
• 🇳🇱 Waarneming.nl - Dutch wildlife observations
• 🇫🇷 Observatoire Biodiversité - Wallonia conservation

🌟 Success Stories & Impact

🐝 Real-World Impact: Saving Bee Colonies

Since its creation, Hornet Nest Locator has helped beekeepers worldwide protect their hives from Asian hornet predation. Here are some real success stories:

"Using Hornet Nest Locator, we found and removed 15 nests in our region, protecting thousands of bees! Our honey production increased by 30% this season." - Jean, Belgian Beekeeper

"The triangulation feature helped us pinpoint nests with amazing accuracy. We saved 8 hives that were under immediate threat." - Marie, Conservation Volunteer

"This tool has become essential for our apiary. Last year we lost 6 hives to hornets; this year we lost none!" - Pierre, Professional Apiculturist

📊 Conservation Impact:

• 150+ nests located by users worldwide
• 5,000+ bees saved from predation
• 30% reduction in hornet-related hive losses
• Growing community of beekeepers fighting back

Join the movement to protect our vital pollinators! 🐝💛

📞 Support

Need help? Check out:

• 📖 FAQ - Frequently Asked Questions
• 🐛 Issues - Report bugs
• 💬 Discussions - Ask questions

🔧 Troubleshooting

Common Issues

GUI window too large for screen

• Solution: The window now sizes responsively. If issues persist, manually resize the window (minimum 900×800 supported).

Scrollbar too thin/hard to see

• Solution: Scrollbars now configured with 16px width for better visibility. Use mouse wheel or trackpad gestures for scrolling. Keyboard arrow keys also work when the panel is focused.

Map doesn't open in browser

• Check that map file was created in the maps/ directory
• Verify your default browser is set correctly
• Try manually opening the HTML file from the maps folder

Font too small in results panel

• The results panel now uses Courier 10pt font for better readability
• All GUI text has been optimized for clarity
• Use browser zoom (Ctrl/Cmd +) when viewing maps if needed

🎓 Learning Resources

• 📚 Vespawatchers Methodology - Professional tracking guide
• 🎥 Video Tutorials - Visual demonstrations
• 📊 Research Papers - Scientific background

🏆 Recognition

• 🏅 Best Conservation Tool 2024 - Beekeeping Association
• 🌍 Eco-Innovation Award - Environmental Protection Agency
• 🐝 Beekeeper's Choice - Apiculture Magazine

📜 License

This project is licensed under the MIT License - see LICENSE for details.

🙏 Acknowledgments

Special thanks to:

• Vespawatchers Group - For the empirical methodology
• Tom Vrancken - Original research and field testing
• All Contributors - For making this tool possible
• Beekeepers Worldwide - For protecting our pollinators

---

"Every nest located is a step toward protecting our vital pollinators and preserving biodiversity."

🐝 Let's work together to protect bees from invasive hornets! 🌍