opencoverage 0.2.0__py3-none-any.whl

opencoverage/patterns/long_edge.py

@@ -0,0 +1,35 @@
+"""Long-edge aligned coverage sweep pattern."""
+
+from __future__ import annotations
+
+import math
+
+from opencoverage.models import FlightMission
+from opencoverage.patterns.back_forth import BackAndForthPattern
+
+
+class LongEdgePattern(BackAndForthPattern):
+    """Align sweep lines perpendicular to the polygon longest edge."""
+
+    def calculate(self) -> FlightMission:
+        rotation = self._long_edge_rotation()
+        waypoints = self.generate_rotated_pattern(rotation)
+        return self.build_mission(waypoints)
+
+    def _long_edge_rotation(self) -> float:
+        """Return rotation angle that aligns the longest edge with the x-axis."""
+        coords = list(self.survey_map.polygon.exterior.coords[:-1])
+        origin = coords[0]
+        target = coords[1]
+        max_distance = 0.0
+
+        for index, start in enumerate(coords):
+            end = coords[(index + 1) % len(coords)]
+            distance = (end[0] - start[0]) ** 2 + (end[1] - start[1]) ** 2
+            if distance > max_distance:
+                max_distance = distance
+                origin = start
+                target = end
+
+        edge_angle = math.atan2(target[1] - origin[1], target[0] - origin[0])
+        return math.pi / 2.0 - edge_angle

opencoverage/patterns/optimal_sweep.py

@@ -0,0 +1,38 @@
+"""Optimal sweep direction coverage pattern."""
+
+from __future__ import annotations
+
+from opencoverage.gpu.optimal_sweep import find_optimal_sweep_angle
+from opencoverage.models import FlightMission
+from opencoverage.patterns.back_forth import BackAndForthPattern
+
+
+class OptimalSweepPattern(BackAndForthPattern):
+    """
+    Find the sweep rotation that minimizes horizontal coverage width.
+
+    Uses a brute-force search over [0, pi). When ``gpu=True`` and CuPy is
+    installed, the search runs on the GPU.
+    """
+
+    def __init__(
+        self,
+        uav,
+        camera,
+        survey_map,
+        *,
+        gpu: bool = False,
+        n_angle_steps: int = 10_000,
+    ) -> None:
+        super().__init__(uav, camera, survey_map)
+        self.gpu = gpu
+        self.n_angle_steps = n_angle_steps
+
+    def calculate(self) -> FlightMission:
+        angle = find_optimal_sweep_angle(
+            self.survey_map.vertices,
+            n_steps=self.n_angle_steps,
+            prefer_gpu=self.gpu,
+        )
+        waypoints = self.generate_rotated_pattern(angle)
+        return self.build_mission(waypoints)

opencoverage/planner.py

@@ -0,0 +1,216 @@
+"""High-level mission planning API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from shapely.geometry import Polygon
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.io.config import load_planner_config
+from opencoverage.io.survey_input import read_survey_map
+from opencoverage.mission_splitter import MissionSplitter
+from opencoverage.models import (
+    FlightMission,
+    GeodeticCoordinate,
+    PinholeCamera,
+    SearchPatternType,
+    TargetPlanning,
+    UAV,
+)
+from opencoverage.patterns.back_forth import BackAndForthPattern
+from opencoverage.patterns.base import SearchPattern
+from opencoverage.patterns.following_wind import FollowingWindPattern
+from opencoverage.patterns.long_edge import LongEdgePattern
+from opencoverage.patterns.optimal_sweep import OptimalSweepPattern
+
+PATTERN_ALIASES: dict[str, SearchPatternType] = {
+    "back_forth": SearchPatternType.BACK_AND_FORTH,
+    "back-and-forth": SearchPatternType.BACK_AND_FORTH,
+    "long_edge": SearchPatternType.LONG_EDGE,
+    "long-edge": SearchPatternType.LONG_EDGE,
+    "optimal_sweep": SearchPatternType.OPTIMAL_SWEEP,
+    "optimal-sweep": SearchPatternType.OPTIMAL_SWEEP,
+    "following_wind": SearchPatternType.FOLLOWING_WIND,
+    "following-wind": SearchPatternType.FOLLOWING_WIND,
+}
+
+
+def _resolve_pattern_type(pattern: str | SearchPatternType) -> SearchPatternType:
+    if isinstance(pattern, SearchPatternType):
+        return pattern
+    normalized = pattern.lower().replace(" ", "_")
+    if normalized not in PATTERN_ALIASES:
+        raise ValueError(f"Unknown pattern: {pattern}")
+    return PATTERN_ALIASES[normalized]
+
+
+def _resolve_target(
+    target: str | TargetPlanning,
+    target_value: float | None,
+    config: dict | None,
+) -> tuple[TargetPlanning, float]:
+    if config is not None:
+        planner = config["planner"]
+        resolved_target = planner["target_planning"]
+        if target_value is None:
+            if resolved_target == TargetPlanning.RESOLUTION:
+                target_value = planner["spatial_resolution_mm"]
+            elif resolved_target == TargetPlanning.VELOCITY:
+                target_value = planner["target_velocity"]
+            else:
+                target_value = config["uav"]["min_height"]
+        return resolved_target, float(target_value)
+
+    if isinstance(target, str):
+        target_map = {
+            "resolution": TargetPlanning.RESOLUTION,
+            "velocity": TargetPlanning.VELOCITY,
+            "altitude": TargetPlanning.ALTITUDE,
+        }
+        resolved_target = target_map[target.lower()]
+    else:
+        resolved_target = target
+
+    if target_value is None:
+        raise ValueError("target_value is required when no config file is provided")
+
+    return resolved_target, float(target_value)
+
+
+def _build_pattern(
+    pattern_type: SearchPatternType,
+    uav: UAV,
+    camera: PinholeCamera,
+    survey_map: SurveyMap,
+    *,
+    gpu: bool = False,
+    wind_direction_deg: float = 0.0,
+    n_angle_steps: int = 10_000,
+) -> SearchPattern:
+    if pattern_type == SearchPatternType.BACK_AND_FORTH:
+        return BackAndForthPattern(uav, camera, survey_map)
+    if pattern_type == SearchPatternType.LONG_EDGE:
+        return LongEdgePattern(uav, camera, survey_map)
+    if pattern_type == SearchPatternType.OPTIMAL_SWEEP:
+        return OptimalSweepPattern(
+            uav,
+            camera,
+            survey_map,
+            gpu=gpu,
+            n_angle_steps=n_angle_steps,
+        )
+    if pattern_type == SearchPatternType.FOLLOWING_WIND:
+        return FollowingWindPattern(
+            uav,
+            camera,
+            survey_map,
+            wind_direction_deg=wind_direction_deg,
+        )
+    raise ValueError(f"Unsupported pattern: {pattern_type}")
+
+
+def _load_survey_map(
+    polygon: Polygon | str | Path,
+    *,
+    home: GeodeticCoordinate | None = None,
+    takeoff: GeodeticCoordinate | None = None,
+    reference: GeodeticCoordinate | None = None,
+) -> SurveyMap:
+    if isinstance(polygon, (str, Path)):
+        survey_map = read_survey_map(polygon)
+    elif isinstance(polygon, Polygon):
+        survey_map = SurveyMap.from_polygon(polygon, reference=reference)
+    else:
+        raise TypeError("polygon must be a Shapely Polygon or a file path")
+
+    if reference is not None:
+        survey_map.reference = reference
+    if home is not None:
+        survey_map.home = home
+    if takeoff is not None:
+        survey_map.takeoff = takeoff
+    return survey_map
+
+
+def plan(
+    *,
+    polygon: Polygon | str | Path,
+    config: str | Path | None = None,
+    uav: UAV | None = None,
+    camera: PinholeCamera | None = None,
+    pattern: str | SearchPatternType = "back_forth",
+    lateral_overlap: float | None = None,
+    forward_overlap: float | None = None,
+    target: str | TargetPlanning = "velocity",
+    target_value: float | None = None,
+    home: GeodeticCoordinate | None = None,
+    takeoff: GeodeticCoordinate | None = None,
+    reference: GeodeticCoordinate | None = None,
+    split: bool = False,
+    gpu: bool = False,
+    wind_direction_deg: float = 0.0,
+    n_angle_steps: int = 10_000,
+) -> FlightMission | list[FlightMission]:
+    """
+    Plan a coverage mission for a survey polygon.
+
+    When ``split`` is True, the mission is divided into segments that respect
+    the UAV ``flight_time_s`` limit.
+    """
+    parsed_config = load_planner_config(config) if config is not None else None
+
+    if parsed_config is not None:
+        uav = uav or parsed_config["uav_model"]
+        camera = camera or parsed_config["camera_model"]
+        lateral_overlap = (
+            lateral_overlap if lateral_overlap is not None else parsed_config["planner"]["lateral_overlap"]
+        )
+        forward_overlap = (
+            forward_overlap
+            if forward_overlap is not None
+            else parsed_config["planner"]["forward_overlap"]
+        )
+        if isinstance(pattern, str) and pattern in {"back_forth", "back-and-forth"}:
+            pattern = parsed_config["planner"]["search_pattern"]
+        wind_direction_deg = parsed_config["planner"].get("wind_direction_deg", wind_direction_deg)
+    else:
+        if uav is None or camera is None:
+            raise ValueError("uav and camera are required when no config file is provided")
+        if lateral_overlap is None or forward_overlap is None:
+            raise ValueError("overlap values are required when no config file is provided")
+
+    pattern_type = _resolve_pattern_type(pattern)
+    survey_map = _load_survey_map(
+        polygon,
+        home=home,
+        takeoff=takeoff,
+        reference=reference,
+    )
+
+    resolved_target, resolved_target_value = _resolve_target(target, target_value, parsed_config)
+
+    search_pattern = _build_pattern(
+        pattern_type,
+        uav,
+        camera,
+        survey_map,
+        gpu=gpu,
+        wind_direction_deg=wind_direction_deg,
+        n_angle_steps=n_angle_steps,
+    )
+    search_pattern.set_search_parameters(
+        lateral_overlap=float(lateral_overlap),
+        forward_overlap=float(forward_overlap),
+        target_value=resolved_target_value,
+        target=resolved_target,
+    )
+    mission = search_pattern.calculate()
+
+    if parsed_config is not None:
+        mission.auto_takeoff = parsed_config["planner"]["auto_takeoff"]
+
+    should_split = bool(split)
+    if should_split:
+        return MissionSplitter(uav).split(mission)
+    return mission

opencoverage-0.2.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: opencoverage
+Version: 0.2.0
+Summary: Coverage path planning for UAV aerial surveying
+Project-URL: Homepage, https://github.com/irvingvasquez/opencoverage
+Project-URL: Repository, https://github.com/irvingvasquez/opencoverage
+Project-URL: Documentation, https://github.com/irvingvasquez/opencoverage#readme
+Project-URL: Issues, https://github.com/irvingvasquez/opencoverage/issues
+Author-email: Juan Irving Vasquez <jvasquezg@ipn.mx>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coverage-path-planning,drone,precision-agriculture,survey,uav
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyproj>=3.6
+Requires-Dist: shapely>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=13.0; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# OpenCoverage
+
+Coverage path planning for UAV aerial surveying. OpenCoverage computes waypoint
+flight paths that fully cover a terrain polygon, with support for camera overlap,
+flight constraints, and multiple sweep patterns.
+
+Python reimplementation of the original UAV Planning library, using Shapely
+instead of CGAL. CPU execution is the default; optional GPU acceleration via CuPy
+is available for the optimal sweep search.
+
+## Features
+
+- **Search patterns**: back-and-forth, long-edge, optimal sweep, following-wind
+- **Planning targets**: spatial resolution, cruise velocity, or fixed altitude
+- **Mission splitting** by UAV flight-time limits
+- **Input formats**: KML polygons, Mission Planner `.poly` files, INI configuration
+- **Output**: QGroundControl WPL 120 waypoint files
+- **Optional GPU**: CuPy acceleration for optimal sweep angle search
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+Optional GPU support:
+
+```bash
+pip install -e ".[gpu]"
+```
+
+## Quick start
+
+```python
+from shapely.geometry import Polygon
+
+import opencoverage as oc
+
+polygon = Polygon([(0, 0), (100, 0), (100, 80), (0, 80)])
+
+mission = oc.plan(
+    polygon=polygon,
+    uav=oc.UAV(min_height=70, max_height=500, survey_velocity=17),
+    camera=oc.PinholeCamera(
+        pixel_size_mm=0.0032,
+        focal_length_mm=8.43,
+        sensor_width_mm=6.55,
+        sensor_height_mm=4.92,
+        capture_rate_s=3,
+    ),
+    pattern="optimal_sweep",
+    lateral_overlap=0.8,
+    forward_overlap=0.7,
+    target="velocity",
+    target_value=17.0,
+)
+
+print(len(mission.path), "waypoints at", mission.flight_height, "m")
+```
+
+## Command line
+
+```bash
+opencoverage examples/sample_field.kml config/quad_tetracam.ini mission.txt
+opencoverage examples/sample_field.poly config/quad_tetracam.ini mission.txt --split
+opencoverage examples/sample_field.kml config/quad_tetracam.ini mission.txt --gpu
+```
+
+## Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `back_forth` | Standard boustrophedon sweep |
+| `long_edge` | Sweep lines perpendicular to the longest polygon edge |
+| `optimal_sweep` | Minimize horizontal sweep width over rotation angles |
+| `following_wind` | Align sweeps with meteorological wind direction |
+
+## Project layout
+
+```
+src/opencoverage/
+├── models.py            # UAV, camera, mission dataclasses
+├── parameters.py        # Survey parameter formulas
+├── planner.py           # High-level plan() API
+├── mission_splitter.py  # Flight-time mission splitting
+├── geometry/            # Shapely map and transforms
+├── patterns/            # Coverage search patterns
+├── io/                  # Config, KML, QGC, coordinate conversion
+└── gpu/                 # Optional CuPy kernels
+```
+
+## License
+
+MIT License. Copyright (c) J. Irving Vasquez-Gomez.

opencoverage-0.2.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+opencoverage/__init__.py,sha256=JXd5nL8Uitp0XQDkV16s22aK-_231O2e0XV4Z0BYFTI,534
+opencoverage/cli.py,sha256=BRnYP-y3pgFU8JmlostHJk-R9bz1tIcVLfpEIs8K-Lc,1984
+opencoverage/mission_splitter.py,sha256=1MaRZC0BtxlJZSoC2AxKrhETPfFQl4iB6JiVTzhb1Xw,2815
+opencoverage/models.py,sha256=cgOk8zZqdwr9SsKGKp1i9Yj9agAlnuWSTUbidxYFIeg,3918
+opencoverage/parameters.py,sha256=KUqQHSJdy3n-BiJ9OHRqbWT2u553uZN5jODYoH3simU,4459
+opencoverage/planner.py,sha256=z_3nSwyCHENJUaDeAEa1AsOB4WCCYFWs1hELvK-GOm4,7423
+opencoverage/geometry/__init__.py,sha256=MykmvDdZNt16vJdEMv106Ypk5MmEUhDqnDVd7A4C9rQ,250
+opencoverage/geometry/map.py,sha256=ZmU4Oea96MOdmYAWv4ro1fS2zqDIgpSx8YBxImKN-X8,4415
+opencoverage/geometry/transforms.py,sha256=tSy6dGkYNDJQ48-1Zp9hk_3Awl4rrgZPmJ1B-goEaXY,1268
+opencoverage/gpu/__init__.py,sha256=brf3tSorembLz0m8gcQPlqSTQTslnx-sf5vDDxGskcw,164
+opencoverage/gpu/_backend.py,sha256=BrM4u6bT812xBIoFlJjrk-ef9e-POZFNKvm1SJd-r3M,765
+opencoverage/gpu/optimal_sweep.py,sha256=iUxfQM8IbX3a2eqp1i0V9D6ZG1J40bGfe0yNrRGhgVc,1124
+opencoverage/io/__init__.py,sha256=SJY596r2dOc7LJgQ_B1eGGE9QxctgBBehygFAU22sPw,231
+opencoverage/io/config.py,sha256=-yejas5meJ2llwJVoi48iGsgoztPMtLT-bsEx6nlyjA,3005
+opencoverage/io/coords.py,sha256=XKVwxUBMnbMVuiKr6acqOp5MbA9VY9duEsAfOfHQsQ4,2031
+opencoverage/io/kml.py,sha256=JwN_nyzQmJHPoy3s1HgZEVotQxK4vNIK9VvjxYCvKhw,1648
+opencoverage/io/mission_planner.py,sha256=2p7GnUmjwGWjz1c-bzDrc4WUc-U6maH5DxsuzgPwQ4U,1218
+opencoverage/io/qgc.py,sha256=spYHWjjLTDRWSLTUoMWQn1qgVWZxdj2NW08PA6GQtrQ,3232
+opencoverage/io/survey_input.py,sha256=G_pJKmCfU9VN69V6WCVOsSVrBksNGAbEBfcB8piPqwk,660
+opencoverage/patterns/__init__.py,sha256=z9BJVGU4Ow_emAdo3flsujNxON5iE212y3g6LaunUDI,505
+opencoverage/patterns/back_forth.py,sha256=GCAkhrNfHV_I1Zx_jMOBTMgpQPjhLx8nOwkARtwi6Gw,2072
+opencoverage/patterns/base.py,sha256=dOEHCl5stHJ-gMBPFks2lu-gQ-5crNQUxmz4unasSe4,2674
+opencoverage/patterns/following_wind.py,sha256=3RzbHuaGw5NpWzxfZBlrxlOcPegn1I5jumV6JZNFyqI,907
+opencoverage/patterns/long_edge.py,sha256=C9HQlX_d8f_B-2zkC3sdjD2nx4phokBM7IsQSBHS_Eo,1232
+opencoverage/patterns/optimal_sweep.py,sha256=QlXmOaAwxgj_ifjlsIjCmE9INKtlSh7196K5fF0hD-s,1114
+opencoverage-0.2.0.dist-info/METADATA,sha256=CIZ6Aw4wZfQmhvqhH3PeJ2kGq77X5WtAL2hUsdFlmsA,4115
+opencoverage-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+opencoverage-0.2.0.dist-info/entry_points.txt,sha256=2MpVVSkV48CuLQ2dYOdN4utrtEmROnf3GgQtxXSBjbY,55
+opencoverage-0.2.0.dist-info/licenses/LICENSE,sha256=WhZX_X8abVtWg47GfAfXZTXMRhThh4Hq48i17ru-Rls,1085
+opencoverage-0.2.0.dist-info/RECORD,,

opencoverage-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

opencoverage-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencoverage = opencoverage.cli:main

opencoverage-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2026 J. Irving Vasquez-Gomez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.