Metadata-Version: 2.5
Name: uav-coverage-path-planner
Version: 1.0.0
Summary: Constraint-aware genetic optimization for UAV area-coverage routes
Project-URL: Homepage, https://github.com/luoyuejun9/uav-coverage-path-planner
Project-URL: Repository, https://github.com/luoyuejun9/uav-coverage-path-planner
Project-URL: Issues, https://github.com/luoyuejun9/uav-coverage-path-planner/issues
Author: luoyuejun9
License: MIT
License-File: LICENSE
Keywords: coverage-path-planning,drone,genetic-algorithm,route-planning,uav
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# UAV Coverage Path Planner

[![Tests](https://github.com/luoyuejun9/uav-coverage-path-planner/actions/workflows/tests.yml/badge.svg)](https://github.com/luoyuejun9/uav-coverage-path-planner/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A standalone Python library and CLI for constraint-aware UAV area-coverage route planning. It creates lawnmower routes inside a polygon and uses a deterministic genetic algorithm to jointly optimize:

- heading angle;
- lane spacing;
- cruise speed.

The optimizer derives feasible lane-spacing and speed bounds from generic camera geometry, desired ground sampling distance (GSD), overlap requirements, capture interval, aircraft speed, range, flight time and reserve energy. It contains no maps, hardware drivers, user data, model files, branding assets, or application code.

中文说明见 [README_zh-CN.md](README_zh-CN.md)。

## Install

```bash
python -m pip install uav-coverage-path-planner
```

For development:

```bash
git clone https://github.com/luoyuejun9/uav-coverage-path-planner.git
cd uav-coverage-path-planner
python -m pip install -e ".[dev]"
pytest
```

## Quick start

```python
from uav_coverage_path_planner import PlanningProblem, optimize_coverage_route

problem = PlanningProblem(
    boundary=((0, 0), (160, 10), (180, 110), (95, 145), (10, 105)),
    takeoff_point=(-25, -30),
    task_height_m=55,
)
result = optimize_coverage_route(problem)

print(result.optimized.heading_deg)
print(result.optimized.lane_spacing_m)
print(result.optimized.cruise_speed_mps)
```

`local_xy` is the default coordinate system and uses metres. Set `coordinate_system="wgs84"` to pass `(longitude, latitude)` points; the library internally applies a local equirectangular projection and returns the route in WGS84 again.

## CLI

```bash
uav-route-optimize examples/synthetic_mission.json --output output
```

This writes only runtime results to `output/`:

- `result.json` — full optimization result;
- `route.geojson` — coverage polyline;
- `convergence.csv` — generation history;
- `population.csv` — final population sample;
- `analysis.png` — four-panel diagnostic chart.

The included mission is a synthetic local-metre example. It contains no real locations.

## Model

For a chromosome `x = [heading, lane_spacing, cruise_speed]`, the algorithm minimizes:

`J(x) = w_geometry × J_geometry + w_time × J_time + w_energy × J_energy + w_quality × J_quality + w_speed × J_speed`

subject to GSD, side-overlap, forward-overlap, capture-interval, speed, range and reserve-energy constraints. Infeasible individuals are ranked behind feasible individuals and carry a violation penalty. The default population is 50, with two deterministic restarts and early stopping after stagnant generations.

`fine`, `balanced`, `efficient`, and `custom` profiles only change objective weights and quality constraints supplied by the caller; they do not encode a specific aircraft or commercial platform.

## Reproducibility

Pass `OptimizationConfig(seed=...)` for a repeatable run. If no seed is supplied, a stable seed is derived from the mission definition.

## Safety note

This package is a planning aid, not a flight controller. Validate all routes, geofencing, terrain clearance, communications, local aviation rules and aircraft limits before operating a UAV.

## License

MIT. See [LICENSE](LICENSE).
