🚁 AeroMind

3D A* pathfinding for UAVs with no-fly zone avoidance and real-time Cesium visualization

English • 中文

🌐 Try Live Demo | 📚 Docs | 💬 中文文档

</div>

🎬 Live Demo | 在线演示

3D Path Planning Demo

Interactive Demo: Click here to try it online! | 在线演示: 点击体验！

3D A* pathfinding with no-fly zone avoidance | 3D A*寻路算法 + 禁飞区智能规避

🟢 Start Point → 🔴 End Point | 起点 → 终点
🟥 No-Fly Zones (Red 3D volumes) | 禁飞区（红色立体区域）
✨ Optimized Path (Cyan glowing line) | 优化路径（青色发光路径）
🚁 Flight Animation with trail effect | 飞行动画与尾迹效果

English

🎯 Features

🧠 Core Algorithm

✅ 3D A* Pathfinding (26-direction search)
✅ No-fly zone intelligent avoidance
✅ Customizable grid resolution
✅ Path smoothing algorithms
✅ Zero external dependencies

</td> <td width="50%">

🎨 Visualization

✅ Interactive 3D Cesium map
✅ Real-time flight animation
✅ Bilingual UI (EN/中文)
✅ Mobile responsive design
✅ One-click demo (no installation!)

</td> </tr> </table>

⚡ Quick Start | 快速开始

🎯 Choose Your Path | 选择你的方式:

🌐 Option 1: Online Demo (Fastest! No Installation Required)

Just visit the live demo - that's it!

👉 https://zguoxu.github.io/AeroMind/

✅ Works in any modern browser (Chrome, Firefox, Edge, Safari)
✅ Interactive 3D visualization with Cesium.js
✅ Click "Start Planning" to see the path planning in action
✅ Bilingual UI (English/中文)
⚡ No clone, no install, no setup!

Perfect for: Quick preview, sharing demos, mobile devices

💻 Option 2: Run Local Demo (For Development)

Clone the repository and run the 3D visualization locally:

Step 1: Clone the repository

git clone https://github.com/Zguoxu/AeroMind.git
cd AeroMind

Step 2: Run the demo script

Windows:

start start-demo.bat

Or simply double-click start-demo.bat file in File Explorer.

macOS/Linux:

bash start-demo.sh

Or simply double-click start-demo.sh file in Finder/File Manager (if executable permission is set).

What happens:

✅ Automatically starts local HTTP server (Python or Node.js)
✅ Opens browser at http://localhost:8000/visualization/standalone.html
✅ Full 3D Cesium visualization with no CORS errors
✅ Edit code and refresh to see changes

Perfect for: Local development, customization, offline use

⚠️ Important: Do NOT directly open visualization/standalone.html by double-clicking. Modern browsers block Cesium's Web Workers when opened from file:// protocol. Always use the demo scripts.

🚀 Option 3: Run Command-Line Example

See path planning results in your terminal:

Step 1: Clone the repository (if not already done)

git clone https://github.com/Zguoxu/AeroMind.git
cd AeroMind

Step 2: Run the hello-world example

node examples/1-quick-start/hello-world.js

Expected Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚁 AeroMind - Hello World Example
   3D A* Path Planning for UAVs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📍 Start Point | 起点: Lat 41.748, Lng 123.362, Alt 100m
📍 End Point | 终点: Lat 41.733, Lng 123.413, Alt 120m

⏳ Planning path... | 正在规划路径...

✅ Path Planning Successful! | 路径规划成功！

📊 Flight Statistics | 飞行统计:
   • Total Waypoints | 总航点数: 52
   • Total Distance | 总距离: 4.61 km
   • Estimated Time | 预计时长: 5.1 min
   • Max Altitude | 最高高度: 120 m

Perfect for: Understanding the algorithm, testing parameters, CI/CD integration

Prerequisites: Node.js >= 12.0.0

📦 Option 4: Use as Library in Your Project

Integrate AeroMind into your own application:

Step 1: Add to your project

# Copy the core algorithm file to your project
cp path/to/AeroMind/src/AStar3DPathPlanner.js your-project/lib/

Step 2: Use in your code

const AStar3DPathPlanner = require('./lib/AStar3DPathPlanner')

// 1. Create planner instance
const planner = new AStar3DPathPlanner({
  gridResolution: 100,   // Grid size in meters
  maxIterations: 50000   // Max search iterations
})

// 2. Define no-fly zones (optional)
planner.setNoFlyZones([
  {
    name: 'Airport Restricted Zone',
    south_lat: 41.740, north_lat: 41.745,
    west_lng: 123.370, east_lng: 123.380,
    min_altitude: 0, max_altitude: 300
  }
])

// 3. Plan the path - just one line!
const result = planner.planPath(
  { lat: 41.748, lng: 123.362, altitude: 100 },  // Start
  { lat: 41.733, lng: 123.413, altitude: 120 }   // End
)

// 4. Use the results
if (result.success) {
  console.log('✅ Path found!')
  console.log('Distance:', result.statistics.totalDistance, 'm')
  console.log('Waypoints:', result.path.length)
  console.log('Flight time:', result.statistics.totalTimeMinutes, 'min')

  // Access the path
  result.path.forEach((waypoint, index) => {
    console.log(`${index}: (${waypoint.lat}, ${waypoint.lng}, ${waypoint.altitude}m)`)
  })
} else {
  console.error('❌ Path planning failed:', result.message)
}

Perfect for: Production applications, custom integrations, research projects

Zero dependencies! The core algorithm is pure JavaScript.

📖 Examples

| Example | Description | Difficulty | Run | |---------|-------------|------------|-----| | Hello World | 10 lines to get started | ⭐ Beginner | node examples/1-quick-start/hello-world.js | | Basic Planning | Complete features demo | ⭐⭐ Easy | node examples/2-basic/basic-path-planning.js | | Performance Test | Compare different resolutions | ⭐⭐⭐ Advanced | node examples/3-advanced/performance-comparison.js | | Cesium Integration | 3D visualization integration | ⭐⭐⭐ Advanced | See code example |

🎨 Visualize with Cesium.js

// Convert path to Cesium format
const cesiumPositions = result.path.map(waypoint =>
  Cesium.Cartesian3.fromDegrees(
    waypoint.lng,
    waypoint.lat,
    waypoint.altitude
  )
)

// Add to viewer
viewer.entities.add({
  polyline: {
    positions: cesiumPositions,
    width: 8,
    material: new Cesium.PolylineGlowMaterialProperty({
      glowPower: 0.2,
      color: Cesium.Color.CYAN
    })
  }
})

🔧 Performance Tuning

| Grid Resolution | Computation Time | Path Quality | Best For | |----------------|------------------|--------------|----------| | 50m | Slow (high detail) | Very detailed | Dense urban obstacles | | 100m ⭐ | Medium | Good balance | General use cases | | 150m | Fast | Coarse | Long-distance planning |

Recommendations:

Urban (many obstacles): 50m
Balanced performance: 100m (recommended)
Long-range sparse area: 150m

📊 Algorithm Comparison

| Algorithm | Pros | Cons | Best For | |-----------|------|------|----------| | A* ⭐ | Guaranteed shortest path, efficient | Memory intensive | Static environments | | RRT | Fast, handles complex spaces | Non-optimal paths | Dynamic environments | | Dijkstra | Always optimal | Slower than A* | When heuristic unavailable |

📚 API Documentation

Constructor

new AStar3DPathPlanner({
  gridResolution: 100,   // Grid cell size in meters (default: 100)
  maxIterations: 50000   // Max A* iterations (default: 50000)
})

Methods

`planPath(start, end, options)`

Plans a 3D path from start to end.

Parameters:

start (Object): {lat, lng, altitude} - Starting point
end (Object): {lat, lng, altitude} - Ending point
options (Object):
- gridResolution (Number): Override grid resolution
- cruiseAltitude (Number): Cruise altitude in meters
- smoothPath (Boolean): Enable path smoothing

Returns:

{
  success: true,
  path: [{lat, lng, altitude}, ...],
  statistics: {
    totalWaypoints: 52,
    totalDistance: 4612,       // meters
    totalTimeMinutes: 5.1,     // minutes
    maxAltitude: 120,          // meters
    minAltitude: 0,            // meters
    averageSpeed: 15           // m/s
  }
}

`setNoFlyZones(zones)`

Sets no-fly zones for obstacle avoidance.