How swetha-arul/constraint-based-drone-route-planner works
1. Overall shape
- This is a single-process Python mission-planning simulator for autonomous drones, centered on a shared 3D voxel environment.
- The code is organized as small domain modules under src/, with main.py acting as the orchestration layer rather than a reusable library entrypoint.
2. Core runtime flow
- src/main.py wires the system together in this order: build environment → generate weather/obstacles → run planning → run preflight check → start visualization/simulation → handle mid-flight replanning if needed.
- Most subsystems read from and mutate the same grid state, so the grid is the main integration boundary.
3. Environment model
- src/environment/grid.py provides the 3D occupancy grid, with cells classified as free, obstacle, or no-fly.
- src/environment/constraints.py defines restricted regions, specifically cuboid no-fly zones that are baked into the grid before planning begins.
- The environment is the authoritative source for spatial legality; other modules query it rather than maintaining separate maps.
4. Static and dynamic hazards
- Static hazards come from the environment setup: buildings, trees, and no-fly volumes occupy grid cells.
- Dynamic hazards are handled as live obstacles during simulation; these can be introduced mid-flight and force replanning.
- Weather is modeled separately from occupancy, but still affects route selection through added traversal cost.
5. Weather subsystem
- src/weather/weather_model.py generates randomized weather zones each run, including rain, wind, and storm regions.
- Weather does not block cells; instead it contributes step penalties that influence the planner’s cost function.
- The README describes rain as also being visualized, indicating the weather model feeds both planning and rendering concerns.
6. Energy and feasibility model
- src/battery/battery_model.py computes per-step energy usage using distance, payload weight, altitude change, and weather penalties.
- This model is central to feasibility: the planner prunes any path whose cumulative energy would exceed the configured battery capacity.
- Energy consumption is therefore not just a simulation detail; it is part of route search and mission viability.
7. Planning subsystem
- src/planner/planner.py implements the main 3D A* search over the grid.
- The planner is battery-constrained, meaning search nodes are discarded as soon as their projected cost exceeds the battery budget.
- The planner is the main decision engine for the mission, producing the initial route and any later reroutes.
8. Preflight authorization
- src/decision/preflight_checker.py acts as a GO/NO-GO gate before takeoff.
- It checks three things: a route exists, the route is legal against the grid snapshot, and the mission length is within a fixed budget.
- This module is a boundary between planning and execution: it prevents a visually plausible route from entering simulation if it violates constraints.
9. Route validation
- src/validation/route_validator.py provides waypoint-by-waypoint legality checks against a grid snapshot.
- It is used by the preflight stage and can also support live validation if the environment changes.
- This is the repository’s explicit safety-check layer, separate from route generation.
10. Recovery and replanning
- src/recovery/replanner.py handles mission recovery when a new obstacle appears ahead of the drone.
- The simulation looks ahead a short distance, detects a conflict, applies a flat replanning penalty, and calls back into the planner from the current position to the goal.
- This creates a closed-loop control path: execution can feed back into planning without restarting the entire mission.
11. Visualization and interaction
- src/visualization/simulator.py uses PyVista to render the 3D grid, the drone, the planned spline, and the executed trail.
- It also handles user interaction, including right-click obstacle placement that triggers the replanning path.
- Visualization is not passive; it is part of the runtime system because it can alter the environment during simulation.
12. System boundaries and data ownership
- The architecture cleanly separates concerns into environment, cost modeling, planning, validation, decision, recovery, and visualization.
- However, these modules are tightly coupled through shared grid state and cost parameters, so the grid plus battery capacity are the key cross-cutting inputs.
- The repo is best understood as a simulation pipeline with one authoritative world model and multiple consumers of that model.
13. Technologies and execution context
- The implementation is Python 3.9+ with numpy for grid/data handling and pyvista for 3D rendering and interaction.
- There is no indication of external services, databases, or distributed components; all behavior appears local and in-memory.
- The architecture is therefore a self-contained scientific/simulation application rather than a server or CLI-only utility.
14. What to emphasize in a diagram
- Show main.py as the coordinator.
- Show a central 3D grid/environment feeding planner, validator, and simulator.
- Show weather and battery as cost-model inputs into planning and runtime energy tracking.
- Show preflight as a gate before simulation, and recovery as a loop from simulation back to planning when dynamic obstacles appear.
Main entry points: main.py main.py · planner.py A* Planner · grid.py 3D Grid · simulator.py Simulator
Components 10
Orchestration
Top-level mission flow and runtime coordination.
- main.py · Wires environment setup, planning, preflight, simulation, and replanning.
src/main.py
Environment
Shared 3D world model and spatial constraints.
- 3D Grid · Authoritative occupancy map for free, obstacle, and no-fly cells.
src/environment/grid.py - No-fly Zones · Cuboid restricted regions baked into the grid before planning.
src/environment/constraints.py
Cost Models
Weather and energy models that influence route feasibility.
- Weather Model · Generates rain, wind, and storm regions that add traversal penalty.
src/weather/weather_model.py - Battery Model · Computes per-step energy use from distance, payload, altitude, and weather.
src/battery/battery_model.py
Planning
Route search and recovery when the mission state changes.
- A* Planner · Battery-constrained 3D A* search that produces initial and rerouted paths.
src/planner/planner.py - Replanner · Replans from the current position when a new obstacle blocks the path.
src/recovery/replanner.py
Safety
Preflight and route legality checks.
- Preflight Check · Verifies route existence, legality, and mission length before takeoff.
src/decision/preflight_checker.py - Route Validator · Checks waypoints against a grid snapshot for route safety.
src/validation/route_validator.py
Runtime
Simulation and interactive execution loop.
- Simulator · Renders the grid, drone, planned path, and executed trail in PyVista.
src/visualization/simulator.py
Connections 20
- main.py → 3D Grid: builds · Creates the shared spatial world model.
- main.py → No-fly Zones: applies · Loads restricted regions into the environment.
- main.py → Weather Model: generates · Creates per-run weather zones.
- main.py → Battery Model: configures · Supplies battery budget and consumption assumptions.
- main.py → A* Planner: plans · Runs route search before execution.
- main.py → Preflight Check: checks · Performs GO/NO-GO validation before takeoff.
- main.py → Simulator: starts · Launches the visualization and execution loop.
- A* Planner → 3D Grid: reads · Searches over the occupancy grid.
- A* Planner → Weather Model: costs · Uses weather penalties in path scoring.
- A* Planner → Battery Model: budgets · Prunes paths that exceed energy capacity.
- Preflight Check → Route Validator: uses · Delegates route legality checks.
- Preflight Check → 3D Grid: verifies · Checks the planned route against the latest grid snapshot.
- Simulator → 3D Grid: renders · Visualizes obstacles, no-fly cells, and dynamic changes.
- Simulator → A* Planner: requests · Triggers replanning when the path is obstructed.
- Replanner → A* Planner: calls · Reuses the planner from the current drone position.
- Replanner → 3D Grid: updates · Responds to newly introduced obstacles.
- Simulator → Replanner: detects · Looks ahead and initiates recovery on conflict.
- Weather Model → Simulator: visualizes · Feeds weather display in the runtime view.
- Battery Model → A* Planner: constrains · Shapes feasible route search space.
- Route Validator → 3D Grid: checks · Evaluates waypoints against spatial legality.