Drone Path Planner

Getting Started

This drone path planner uses TCB (Tension-Continuity-Bias) splines to create smooth flight paths. You can visualize paths in multiple views and control mission execution in real-time.

View Controls

• Top View (XY + Velocity):
  • Click anywhere to add a waypoint
  • Click on a waypoint to edit its properties (position, velocity, action, etc.)
  • Right-click a waypoint to delete it
  • Waypoint colors indicate velocity (blue = slow, red = fast)
• Side View (Altitude Profile):
  • Drag waypoint markers up/down to adjust altitude
  • Click "Lasso" button to enable lasso selection mode
  • In lasso mode: draw around multiple points and set them all to the same altitude
  • Right-click to delete waypoints
• 3D View:
  • Controls: Click and drag to rotate, scroll to zoom, right-drag to pan
  • Coordinate System: Uses Three.js Y-up convention
    • X-axis (Red) = East/West
    • Y-axis (Green) = Altitude (Up/Down)
    • Z-axis (Blue) = North/South
  • Grid: Horizontal grid on ground plane (Y=0), dynamically sized to fit mission
  • Path Color: Blue=slow, Red=fast (based on 3D velocity magnitude)
  • Arrows: Show flight direction and pitch angle
  • Waypoint Numbers: Float above each waypoint sphere
  • 🔄 Pilot View Toggle: Click "🔄 Switch to Pilot View" button to toggle between views
    • Orbital View: Default view - rotate/zoom/pan with mouse, see entire mission
    • Pilot View: First-person camera from drone's perspective with full HUD
    • Switching: Button changes to "Switch to Orbital View" when in pilot mode
    • View Title: Shows current mode (3D Orbital View / 📹 Pilot View)
  • 📹 Pilot View HUD: When in pilot view mode
    • HUD Elements: Airspeed (SPD top-left), Altitude (ALT top-right), Heading (HDG top-center)
    • Artificial Horizon: Center display showing pitch/roll with sky (blue) and ground (brown)
    • Crosshair: Green targeting reticle in center
    • Next Waypoint: Distance and action in yellow (bottom left)
    • Corridor Bounds: Green dashed lines on edges, width in cyan (bottom right)
    • Progress: Mission completion % at bottom center
    • Scrubber Bar: Drag slider at bottom to manually preview any point along path
    • Camera: 75° FOV, positioned 1m above drone, looking 20m ahead
    • Controls Disabled: Orbit controls (rotate/zoom/pan) disabled in pilot view
  • Visual Options:
    • Geofence Box: Red boundary calculated from actual spline path + corridor width
      • Automatically sized to contain entire curved path (not just waypoints)
      • Accounts for TCB spline overshoot beyond waypoint positions
      • Updates dynamically when TCB parameters change
    • Ground Plane: Green transparent surface at Y=0 (ground level)
    • Altitude Ceiling: Red transparent surface at max altitude limit
    • Path Corridor Tube: Blue tube showing ±corridor width along entire path
    • Curvature Indicators: Colored spheres (green=gentle curves, red=sharp turns)
    • Turn Radius Heatmap: Path colored by turn radius (green=wide turns, red=tight turns)
• Waypoint List (Sidebar):
  • Click any waypoint card to select it
  • Useful when waypoints overlap in Top View
  • Shows altitude, velocity, action, and coordinates
  • Selected waypoint highlighted in blue

⚠️ Creating Vertical Waypoints (Climb/Descent)

Waypoint Actions & Rotation

• Available Actions:
  • Flight Control: Takeoff Hover, Hover, Hover Up, Hover to Land, Forward
  • Aircraft Rotation: Rotate Left/Right 45°, Rotate Left/Right 90°, Rotate to Heading, Face Next Waypoint
  • Operations: Take Photo, Lidar Scan, Drop/Raise Payload, Search Lights 1-5
• Attitude Controls (Yaw/Pitch/Roll):
  • Yaw: 0°=North, 90°=East, 180°=South, 270°=West
  • Use rotation actions for in-flight turns
  • Use "Face Next Waypoint" to auto-orient toward next point
  • Use "Rotate to Heading" with custom Yaw value for specific directions

Path Rotation Tools

• Set rotation angle in degrees (default: 45°)
• Click "↶ Rotate Left" to rotate entire path counterclockwise
• Click "↷ Rotate Right" to rotate entire path clockwise
• Rotation is around the centroid (center) of all waypoints

Mission Control

• Starting a Mission:
  • Create at least 2 waypoints
  • Click ▶ Start to begin mission execution
  • Watch the red pulsing marker move along the planned path
• During Mission:
  • Click ⏸ Pause to pause/resume
  • Click ⏹ Stop to end the mission
  • Adjust Mission Speed (0.1x - 5x) to speed up/slow down playback
  • Monitor progress, status, and current waypoint in Mission Control panel
• Mid-Mission Editing:
  • Enable "Allow Mid-Mission Edits" checkbox
  • Add new waypoints by clicking in Top View
  • Delete waypoints (right-click)
  • Edit waypoint properties (click on waypoint)
  • Rotate entire path using rotation controls
  • Enable "Auto-Recalculate Path" to immediately apply changes
  • The drone will continue along the updated path while maintaining approximate progress

TCB Parameters

TCB (Tension-Continuity-Bias) parameters control how the spline curves between waypoints. You can set global defaults in the control panel, and override per-waypoint for precise control.

Global TCB Parameters (Control Panel)

• Tension: Controls how sharply the curve bends (-1 to 1)
  • High (0.8-1.0): Tight, sharp curves - use for precision
  • Low (-1.0 to 0): Loose, smooth curves - use for speed
• Continuity: Controls how corners are rounded (-1 to 1)
• Bias: Controls curve direction bias before/after waypoint (-1 to 1)
• Samples: Number of interpolated points per segment (higher = smoother)

Per-Waypoint TCB Override

• Click any waypoint to open the editor dialog
• Scroll to the "TCB Parameters (optional)" section
• Enter values to override global defaults for that specific waypoint
• Leave blank to use global defaults

Understanding Plots & Analysis Tools

The planner provides multiple plots to analyze your flight path's dynamic characteristics. All plots are computed from the 3D spline path in real-time.

Plot Types

• Acceleration Plot (Red)
  • Shows 3D acceleration magnitude vs. distance along path
  • Spikes indicate rapid velocity changes (tight turns, climbs/descents)
  • High tension TCB values create higher acceleration peaks
  • Use to verify acceleration stays within drone limits
• Jerk Plot (Purple)
  • Shows rate of change of acceleration (derivative of acceleration)
  • High jerk = uncomfortable or potentially damaging maneuvers
  • Smooth jerk = comfortable flight with gradual changes
  • Critical for payload operations and passenger comfort
• Velocity Plot (Blue - modal only)
  • Shows 3D speed magnitude: √(v_x² + v_y² + v_z²)
  • Includes horizontal and vertical velocity components
  • Vertical climbs/descents increase total speed
  • Color-coded on 3D path (blue=slow, red=fast)
• Curvature Plot (Green - modal only)
  • Curvature κ = 1/turn_radius (measured in 1/meters)
  • High curvature = tight turns requiring speed reduction
  • Low curvature = gentle curves allowing higher speeds
  • Used by dynamic constraints to optimize velocity profile

Using the Plots

• Main View: Acceleration and Jerk plots update in real-time as you edit waypoints
  • Quick overview of dynamic characteristics
  • Immediate feedback when adjusting TCB parameters
• Expanded View: Click "🔍 Expand" button on any plot
  • Opens full-screen modal with 4 tabs: Velocity, Acceleration, Jerk, Curvature
  • Larger, more detailed visualization with axis labels
  • Better for detailed analysis and screenshots
  • Close with ✕ button or Escape key

Understanding Velocity & Kinematics

The planner calculates full 3D velocity including horizontal (X, Y) and vertical (Z) components.

• Velocity Vector: Computed at each point along the spline path
  • v = (v_x, v_y, v_z)
  • Includes changes in altitude (climb/descent rates)
• Speed (Magnitude): Total velocity considering all three dimensions
  • speed = √(v_x² + v_y² + v_z²)
• Pitch Angle: Automatically computed from vertical motion
  • pitch = atan2(dir_z, horizontal)
• Acceleration & Jerk: Computed in 3D including vertical components
• Curvature: Accounts for 3D path curvature (not just horizontal turns)

⛈️ Weather & Environment System

Simulate realistic atmospheric conditions and their effects on flight paths using detailed physics-based weather modeling and real-time weather data from OpenWeatherMap API.

🌍 Real-Time Weather API (Multi-Provider Support)

Connect to multiple weather API providers to fetch current real-world weather conditions. Supports automatic fallback if one provider is down.

Available API Providers:

• 🆓 Open-Meteo (Recommended for testing)
  • No API key required - works immediately!
  • Unlimited free API calls
  • Open source weather forecasting
  • Coordinates only (no city name search)
• OpenWeatherMap
  • 1,000 API calls/day free tier
  • Supports coordinates and city name search
  • Get API key: openweathermap.org/api
• WeatherAPI.com
  • 1 million API calls/month free tier
  • Supports coordinates and city name search
  • Get API key: weatherapi.com
• Tomorrow.io
  • 500 API calls/day free tier
  • Coordinates only (no city name search)
  • Get API key: tomorrow.io

How to Use:

1. Select Provider: Choose from dropdown (Open-Meteo selected by default - no key needed)
2. Configure API Key (if required): Enter and save your API key for providers that require one
3. Fetch Weather:
   • By Coordinates: Enter lat/lon and click 🌐
   • By City: Enter city name and click 🔍 (OpenWeatherMap/WeatherAPI only)
   • Mission Location: Click 📍 to use mission start coordinates
4. Switch Providers: If one provider is down or rate-limited, simply switch to another provider from the dropdown
5. Real Conditions: Get actual wind speed, wind direction, precipitation, storms, and atmospheric conditions
6. Cache: Weather data cached for 10 minutes to reduce API calls (cache cleared when switching providers)
7. Status Display: Real-time feedback shows location name, weather description, and fetch status
8. Key Management: Each provider's API key is saved independently in browser localStorage

💾 Download Weather Snapshot + Satellite Maps

Archive complete weather conditions with timestamped satellite imagery for mission records and analysis.

What Gets Downloaded:

1. JSON Data File: Complete weather snapshot including:
   • Metadata: Timestamp (ISO + local), provider, location, coordinates, mission coverage area
   • Weather Conditions: Temperature (C/F), humidity, pressure, visibility, cloud cover, description with emoji
   • Wind Data: Speed (m/s, km/h, mph, knots), direction (degrees + cardinal), vertical wind
   • Atmospheric Hazards: Storm intensity/level, turbulence risk, roughness
   • Flight Suitability: Wind condition, visibility condition, overall assessment (GO/NO-GO)
2. Satellite Weather Maps (if using OpenWeatherMap):
   • 🌥️ Clouds: Satellite cloud coverage imagery
   • 🌧️ Precipitation: Rain/snow intensity overlay
   • 📊 Pressure: Atmospheric pressure map
   • 💨 Wind: Wind speed/direction visualization
   • 🌡️ Temperature: Temperature distribution map
3. RainViewer Radar (always included):
   • ⚡ Live precipitation radar imagery (free, no API key required)
   • Auto-adjusts zoom level to find available radar coverage

How to Download:

1. Fetch weather data using coordinates, city name, or mission location
2. Wait for "✓ Weather loaded" status message
3. Click "💾 Download Weather Snapshot + Satellite Maps" button (becomes enabled after weather fetch)
4. Multiple files download automatically:
   • weather_snapshot_location_timestamp.json
   • weather_snapshot_location_timestamp_map_clouds.png
   • weather_snapshot_location_timestamp_map_precipitation.png
   • weather_snapshot_location_timestamp_map_pressure.png
   • weather_snapshot_location_timestamp_map_wind.png
   • weather_snapshot_location_timestamp_map_temperature.png
   • weather_snapshot_location_timestamp_radar.png

Weather Presets

• ☀️ Calm: No wind (0 m/s) - ideal conditions
• 🍃 Light Breeze: 3 m/s from West - gentle wind
• 💨 Moderate Wind: 8 m/s from South - noticeable drift
• 🌬️ Strong Wind: 15 m/s from North - significant compensation needed
• ➡️ Crosswind: 12 m/s from East - perpendicular challenge
• ⛈️ Light Storm: 10 m/s with moderate turbulence and downdrafts
• 🌪️ Severe Storm: 20 m/s with heavy turbulence and strong downdrafts

Manual Weather Controls

• Wind Speed: 0-25 m/s base wind at reference altitude (10m)
• Wind Direction: 0-360° (0°=North, 90°=East, 180°=South, 270°=West)
• Storm Intensity: 0-100% affects turbulence, gusts, and downdrafts
• Vertical Wind: -10 to +10 m/s (negative = downdraft, positive = updraft)
• Terrain Roughness: Affects wind shear profile
  • 🏖️ Smooth (water/airport) - minimal wind variation
  • 🌾 Open Field - typical grassland profile
  • 🌲 Forest/Suburb - increased turbulence
  • 🏙️ Urban/City - complex wind patterns
• Wind Compensation: 0-100% how well vehicle corrects for drift
  • 0% = No compensation (pure drift)
  • 80% = Realistic autopilot (default)
  • 100% = Perfect compensation (impossible in reality)

Physics Model Features

• Altitude-Dependent Wind: Wind speed increases with altitude using power law boundary layer model
• Wind Shear: Wind direction veers (rotates) with altitude (~15°/1000m)
• Turbulence: von Kármán spectrum approximation with multiple frequency components
• Gusts: Periodic sudden wind increases with smooth rise/decay envelope
• Storm Effects: Amplified turbulence, downdrafts, and random gusts
• Real-time Updates: Weather conditions evolve during mission execution

Visualization Options

• Show Actual Path (with drift): Red path showing where vehicle actually goes vs. blue planned path
  • Orange drift vectors show wind displacement at intervals
  • Live drift distance displayed on current position
  • Legend shows planned vs. actual paths
• Show Wind Direction Arrows (3D View): Wind vectors at multiple altitudes
  • Arrows displayed outside path area for clarity
  • Arrow length proportional to wind speed
  • Color-coded: 🔵 Blue=calm, 🟡 Yellow=moderate, 🔴 Red=strong
  • Shows wind at 10m, 20m, 40m, 60m altitudes
• Show Animated Wind Flow (3D View): Real-time particle animation
  • 200 particles flowing with wind currents
  • Adaptive amplification makes even light winds visible
  • Color-coded by speed: 🔵 Deep Blue=slow, 🟣 Purple=medium, 🔴 Red=fast
  • Particles fade over 5 seconds and respawn
  • Shows turbulence, gusts, and vertical winds in real-time
  • Note: May impact performance on slower computers - can be disabled

How to Use Weather System

1. Enable Weather: Check "Enable Weather Effects" in Weather & Environment panel
2. Choose Conditions: Select a preset or manually adjust wind/storm parameters
3. Run Mission: Start the mission to see real-time wind effects
4. Visualize Drift: Check "Show Actual Path" to see where vehicle actually goes
5. See Wind Field: Enable wind arrows and/or animated flow in 3D View
6. Adjust Compensation: Lower compensation % to see more drift effect

🤖 AI Mission Analysis

Pure JavaScript AI-powered mission analysis system that evaluates safety, predicts risks, and provides intelligent recommendations - NO external libraries or dependencies.

Mission Risk Assessment

• Overall Risk Score (0-100): Comprehensive mission risk evaluation combining multiple factors
  • 0-20: LOW risk - Excellent conditions
  • 20-40: MODERATE risk - Manageable conditions
  • 40-60: HIGH risk - Challenging conditions
  • 60-80: SEVERE risk - Dangerous conditions
  • 80-100: EXTREME risk - Mission not recommended
• Risk Factors Analyzed:
  • Wind Risk: Wind speed impact on mission safety
  • Turbulence Risk: Atmospheric instability assessment
  • Storm Risk: Precipitation and severe weather evaluation
  • Altitude Risk: Low altitude terrain hazards
  • Path Risk: Path complexity and sharp turns
  • Duration Risk: Mission length considerations
• Go/No-Go Decision: AI recommendation on mission viability
  • 🟢 GO: Safe to proceed
  • 🟡 PROCEED WITH CAUTION: Acceptable but monitor closely
  • 🔴 NO-GO: Mission not recommended
• Success Probability: Estimated likelihood (0-100%) of mission completion without incidents

Intelligent Recommendations

• Prioritized Guidance: AI generates recommendations ranked by urgency
  • CRITICAL: Immediate action required
  • HIGH: Important safety consideration
  • MEDIUM: Suggested optimization
  • LOW: Minor improvement opportunity
• Actionable Advice: Specific suggestions including:
  • Altitude adjustments for safer flight
  • Wind compensation optimization
  • Path modifications to avoid hazards
  • Mission postponement recommendations
  • Speed reduction in challenging segments
• Optimal Wind Compensation: AI calculates ideal compensation percentage (50-95%) based on current conditions with one-click "Apply" button

DARPA LIFT Mission-Aware Intelligence

The AI automatically understands DARPA LIFT mission operations and distinguishes between different waypoint types:

• Operational Waypoints (Automatically Detected):
  • Takeoff/Landing: First and last waypoints - Expected at ground level (2-5m)
  • Cargo Operations: Low-altitude middle waypoints (< 20m) - Pickup/dropoff points
  • ✓ AI recognizes these should be low and does NOT flag them as dangerous
• Transit Waypoints:
  • In-flight cruise waypoints (≥ 20m altitude)
  • Evaluated against DARPA standard: 250 feet (76.2m)
  • AI recommends increasing if below safe transit altitude
• Smart Assessment: AI only evaluates transit waypoints against DARPA 250ft standard, not operational waypoints
  • Example: Mission with takeoff at 2m, transit at 76m, landing at 3m → Excellent risk score
  • No false warnings about ground-level operations being "too low"

Predictive Analysis

• Turbulence Hotspot Detection: Predicts zones of severe/moderate turbulence along flight path
  • Shows altitude and severity of each hotspot
  • Accounts for wind speed, altitude, and storm intensity
  • Color-coded: 🔴 Severe, 🟡 Moderate, 🔵 Light
• Critical Warnings: Automatic alerts for dangerous conditions exceeding safe operating limits

Understanding Recommendation Priority

• CRITICAL Priority: 🔴 Immediate safety concern - Must address before mission
  • Example: Storm conditions present, transit waypoints dangerously low
  • Action: Do not proceed until resolved
• HIGH Priority: 🟠 Important safety consideration - Should address
  • Example: Strong winds, transit altitudes below safe limits, severe turbulence zones
  • Action: Strongly recommended to adjust before mission
• MEDIUM Priority: 🟡 Optimization suggestion - Nice to have
  • Example: Wind compensation optimization (80% → 90%), transit below DARPA nominal
  • Action: Optional improvement for better performance
  • Note: MEDIUM recommendations are suggestions, not safety warnings!
• LOW Priority: 🔵 Minor improvement opportunity
  • Example: Long mission duration - check fuel/battery
  • Action: Good practice but not urgent

How to Use AI Analysis

1. Plan Mission: Add waypoints and configure weather conditions
2. Run Analysis: Click "🤖 Analyze Mission" button in AI Mission Analysis section
3. Review Results: Check risk score, go/no-go decision, and success probability
4. Read Recommendations: Review prioritized safety recommendations
5. Apply Suggestions: Adjust mission parameters based on AI advice (e.g., click "Apply" for optimal wind compensation)
6. View Details: Expand "📊 View Detailed Risk Factors" to see individual risk component scores
7. Check Hotspots: Review turbulence zones to understand challenging flight segments

File Operations

• New: Clear current path and start fresh
• Save: Export path to JSON file (includes per-waypoint TCB parameters)
• Load: Import path from JSON file (restores TCB overrides)
• CSV: Export path data to CSV with all computed values (velocity, acceleration, curvature, etc.)

Keyboard Shortcuts

• Escape: Close modals or control panel (mobile)