opencoverage 0.2.0__py3-none-any.whl

opencoverage/__init__.py

@@ -0,0 +1,26 @@
+"""OpenCoverage: coverage path planning for UAV aerial surveying."""
+
+from opencoverage.mission_splitter import MissionSplitter
+from opencoverage.models import (
+    FlightMission,
+    GeodeticCoordinate,
+    PinholeCamera,
+    SearchPatternType,
+    TargetPlanning,
+    UAV,
+)
+from opencoverage.planner import plan
+
+__all__ = [
+    "FlightMission",
+    "GeodeticCoordinate",
+    "MissionSplitter",
+    "PinholeCamera",
+    "SearchPatternType",
+    "TargetPlanning",
+    "UAV",
+    "plan",
+    "__version__",
+]
+
+__version__ = "0.2.0"

opencoverage/cli.py

@@ -0,0 +1,60 @@
+"""Command-line interface for OpenCoverage."""
+
+from __future__ import annotations
+
+import argparse
+
+from opencoverage.io.config import load_planner_config
+from opencoverage.mission_splitter import MissionSplitter
+from opencoverage.planner import plan
+
+
+def main() -> int:
+    """Run mission planning from the command line."""
+    parser = argparse.ArgumentParser(
+        description="Plan a UAV coverage mission from a polygon and configuration file.",
+    )
+    parser.add_argument("polygon", help="Path to input polygon file (KML or Mission Planner)")
+    parser.add_argument("config", help="Path to INI configuration file")
+    parser.add_argument("output", help="Path to output QGroundControl waypoint file")
+    parser.add_argument(
+        "--gpu",
+        action="store_true",
+        help="Use CuPy for optimal sweep angle search when available",
+    )
+    parser.add_argument(
+        "--split",
+        action="store_true",
+        help="Split the mission according to UAV flight time limits",
+    )
+    args = parser.parse_args()
+
+    parsed_config = load_planner_config(args.config)
+    result = plan(
+        polygon=args.polygon,
+        config=args.config,
+        gpu=args.gpu,
+        split=args.split,
+    )
+    missions = result if isinstance(result, list) else [result]
+
+    reference = missions[0].reference
+    if reference is None:
+        raise SystemExit("Mission is missing a geodetic reference point.")
+
+    if len(missions) == 1:
+        mission = missions[0]
+        mission.save_qgc(args.output, reference=reference)
+        print(f"Saved {len(mission.path)} waypoints to {args.output}")
+        print(f"Flight height: {mission.flight_height:.2f} m")
+        return 0
+
+    splitter = MissionSplitter(parsed_config["uav_model"])
+    saved = splitter.save_qgc_files(missions, args.output, reference=reference)
+    for path in saved:
+        print(f"Saved mission segment to {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

opencoverage/geometry/__init__.py

@@ -0,0 +1,6 @@
+"""Geometry helpers for survey maps and coordinate transforms."""
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.geometry.transforms import rotate_points, rotate_polygon
+
+__all__ = ["SurveyMap", "rotate_points", "rotate_polygon"]

opencoverage/geometry/map.py

@@ -0,0 +1,117 @@
+"""Polygon map representation backed by Shapely."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from shapely.geometry import LineString, Point, Polygon
+
+from opencoverage.geometry.transforms import rotate_polygon
+from opencoverage.models import GeodeticCoordinate
+
+
+@dataclass
+class SurveyMap:
+    """Survey area defined as a local-meter polygon."""
+
+    polygon: Polygon
+    reference: GeodeticCoordinate | None = None
+    home: GeodeticCoordinate | None = None
+    takeoff: GeodeticCoordinate | None = None
+    _home_local: tuple[float, float] | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_polygon(cls, polygon: Polygon, **kwargs) -> SurveyMap:
+        """Create a map from an existing Shapely polygon."""
+        if polygon.is_empty or not polygon.is_valid:
+            raise ValueError("Survey polygon must be non-empty and valid")
+        return cls(polygon=polygon, **kwargs)
+
+    def copy(self) -> SurveyMap:
+        """Return a shallow copy of the map."""
+        return SurveyMap(
+            polygon=Polygon(self.polygon),
+            reference=self.reference,
+            home=self.home,
+            takeoff=self.takeoff,
+            _home_local=self._home_local,
+        )
+
+    def rotated_copy(self, angle_rad: float) -> SurveyMap:
+        """Return a new map with the polygon rotated by angle_rad."""
+        rotated = rotate_polygon(self.polygon, angle_rad)
+        return SurveyMap(
+            polygon=rotated,
+            reference=self.reference,
+            home=self.home,
+            takeoff=self.takeoff,
+            _home_local=self._home_local,
+        )
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        """Return polygon axis-aligned bounds (minx, miny, maxx, maxy)."""
+        return self.polygon.bounds
+
+    @property
+    def vertices(self) -> np.ndarray:
+        """Return exterior vertices as an (N, 2) array."""
+        coords = list(self.polygon.exterior.coords[:-1])
+        return np.asarray(coords, dtype=float)
+
+    def extreme_vertices(self) -> dict[str, tuple[float, float]]:
+        """Return left, right, top, and bottom vertices of the polygon."""
+        coords = list(self.polygon.exterior.coords[:-1])
+        left = min(coords, key=lambda p: p[0])
+        right = max(coords, key=lambda p: p[0])
+        bottom = min(coords, key=lambda p: p[1])
+        top = max(coords, key=lambda p: p[1])
+        return {"left": left, "right": right, "bottom": bottom, "top": top}
+
+    def sweep_width(self) -> float:
+        """Return horizontal extent used for back-and-forth sweep planning."""
+        extremes = self.extreme_vertices()
+        return extremes["right"][0] - extremes["left"][0]
+
+    def sweep_height(self) -> float:
+        """Return vertical extent of the polygon."""
+        extremes = self.extreme_vertices()
+        return extremes["top"][1] - extremes["bottom"][1]
+
+    def intersect_vertical_line(self, x: float) -> list[tuple[float, float]]:
+        """
+        Intersect the polygon with a vertical line at coordinate x.
+
+        Returns intersection points sorted by ascending y.
+        """
+        minx, miny, maxx, maxy = self.bounds
+        line = LineString([(x, miny - 1.0), (x, maxy + 1.0)])
+        intersection = self.polygon.intersection(line)
+
+        points: list[tuple[float, float]] = []
+        if intersection.is_empty:
+            return points
+
+        if isinstance(intersection, Point):
+            points.append((intersection.x, intersection.y))
+        elif intersection.geom_type == "MultiPoint":
+            points.extend((point.x, point.y) for point in intersection.geoms)
+        elif intersection.geom_type == "LineString":
+            points.extend(intersection.coords)
+        elif intersection.geom_type == "MultiLineString":
+            for segment in intersection.geoms:
+                points.extend(segment.coords)
+
+        unique: list[tuple[float, float]] = []
+        seen: set[tuple[float, float]] = set()
+        for point in sorted(points, key=lambda p: p[1]):
+            key = (round(point[0], 9), round(point[1], 9))
+            if key not in seen:
+                seen.add(key)
+                unique.append(point)
+        return unique
+
+    def replace_polygon(self, polygon: Polygon) -> None:
+        """Replace the internal polygon, for example after rotation."""
+        self.polygon = polygon

opencoverage/geometry/transforms.py

@@ -0,0 +1,43 @@
+"""Coordinate transforms for polygons and waypoint paths."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from shapely.affinity import rotate as shapely_rotate
+from shapely.geometry import Polygon
+
+
+def rotate_polygon(polygon: Polygon, angle_rad: float, origin: tuple[float, float] = (0.0, 0.0)) -> Polygon:
+    """Rotate a polygon by angle_rad around origin."""
+    return shapely_rotate(polygon, angle_rad, origin=origin, use_radians=True)
+
+
+def rotate_points(
+    points: list[tuple[float, float]],
+    angle_rad: float,
+    origin: tuple[float, float] = (0.0, 0.0),
+) -> list[tuple[float, float]]:
+    """Rotate a list of 2D points by angle_rad around origin."""
+    if not points:
+        return []
+
+    ox, oy = origin
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+    rotated: list[tuple[float, float]] = []
+
+    for x, y in points:
+        dx = x - ox
+        dy = y - oy
+        rotated.append((ox + cos_a * dx - sin_a * dy, oy + sin_a * dx + cos_a * dy))
+
+    return rotated
+
+
+def rotation_matrix(angle_rad: float) -> np.ndarray:
+    """Return a 2x2 rotation matrix for angle_rad."""
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+    return np.array([[cos_a, -sin_a], [sin_a, cos_a]], dtype=float)

opencoverage/gpu/__init__.py

@@ -0,0 +1,5 @@
+"""Optional GPU acceleration backends."""
+
+from opencoverage.gpu._backend import cupy_available, get_array_module
+
+__all__ = ["cupy_available", "get_array_module"]

opencoverage/gpu/_backend.py

@@ -0,0 +1,35 @@
+"""Optional GPU backend helpers (CuPy). CPU is always the default."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def cupy_available() -> bool:
+    """Return True when CuPy is installed and a CUDA device is accessible."""
+    try:
+        import cupy as cp
+
+        return cp.cuda.is_available()
+    except ImportError:
+        return False
+
+
+def get_array_module(prefer_gpu: bool = False) -> Any:
+    """
+    Return NumPy or CuPy for numeric kernels.
+
+    GPU is only selected when explicitly requested and CuPy is available.
+    """
+    if prefer_gpu:
+        try:
+            import cupy as cp
+
+            if cp.cuda.is_available():
+                return cp
+        except ImportError:
+            pass
+
+    import numpy as np
+
+    return np

opencoverage/gpu/optimal_sweep.py

@@ -0,0 +1,42 @@
+"""GPU-accelerated optimal sweep angle search."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from opencoverage.gpu._backend import get_array_module
+
+
+def find_optimal_sweep_angle(
+    vertices: np.ndarray,
+    n_steps: int = 10_000,
+    prefer_gpu: bool = False,
+) -> float:
+    """
+    Find the rotation angle in [0, pi) that minimizes sweep width.
+
+    Parameters
+    ----------
+    vertices:
+        Polygon vertices as an (N, 2) array in local meters.
+    n_steps:
+        Number of angles to evaluate.
+    prefer_gpu:
+        Use CuPy when available.
+    """
+    xp = get_array_module(prefer_gpu)
+    points = xp.asarray(vertices, dtype=float)
+    x = points[:, 0]
+    y = points[:, 1]
+
+    alphas = xp.linspace(0.0, xp.pi, n_steps, endpoint=False)
+    cos_a = xp.cos(alphas)[:, xp.newaxis]
+    sin_a = xp.sin(alphas)[:, xp.newaxis]
+
+    rotated_x = cos_a * x - sin_a * y
+    widths = rotated_x.max(axis=1) - rotated_x.min(axis=1)
+    best_index = int(widths.argmin())
+
+    if prefer_gpu and xp.__name__ == "cupy":
+        return float(xp.asnumpy(alphas[best_index]))
+    return float(alphas[best_index])

opencoverage/io/__init__.py

@@ -0,0 +1,6 @@
+"""Input/output helpers for configuration and mission files."""
+
+from opencoverage.io.config import load_planner_config
+from opencoverage.io.survey_input import read_survey_map
+
+__all__ = ["load_planner_config", "read_survey_map"]

opencoverage/io/config.py

@@ -0,0 +1,79 @@
+"""INI configuration file loader."""
+
+from __future__ import annotations
+
+import configparser
+from pathlib import Path
+
+from opencoverage.models import PinholeCamera, SearchPatternType, TargetPlanning, UAV
+
+
+def _parse_bool(value: str) -> bool:
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _parse_value(raw: str) -> str | float | int | bool:
+    """Parse INI value, stripping inline comments after semicolon."""
+    cleaned = raw.split(";", 1)[0].strip()
+    if cleaned.lower() in {"true", "false"}:
+        return _parse_bool(cleaned)
+    if "." in cleaned:
+        return float(cleaned)
+    try:
+        return int(cleaned)
+    except ValueError:
+        return cleaned
+
+
+def load_planner_config(path: str | Path) -> dict:
+    """
+    Load planner, UAV, and camera settings from an INI file.
+
+    Returns a dictionary with keys: planner, uav, camera, and model instances.
+    """
+    parser = configparser.ConfigParser()
+    parser.read(path)
+
+    planner_section = {key: _parse_value(value) for key, value in parser.items("Planner")}
+    uav_section = {key: _parse_value(value) for key, value in parser.items("UAV")}
+    camera_section = {key: _parse_value(value) for key, value in parser.items("Camera")}
+
+    planner = {
+        "search_pattern": SearchPatternType(int(planner_section["searchpattern"])),
+        "auto_takeoff": bool(planner_section.get("autotakeoff", False)),
+        "lateral_overlap": float(planner_section["lateraloverlap"]),
+        "forward_overlap": float(
+            planner_section.get("forwardoverlap", planner_section.get("fordwardoverlap", 0.7))
+        ),
+        "spatial_resolution_mm": float(planner_section.get("spatialresolution", 40)),
+        "target_velocity": float(planner_section.get("targetvelocity", 17)),
+        "target_planning": TargetPlanning(
+            int(planner_section.get("targetplanning", TargetPlanning.VELOCITY))
+        ),
+        "wind_direction_deg": float(planner_section.get("winddirection", 0)),
+    }
+
+    uav_config = {
+        "flight_time_s": float(uav_section.get("flighttime", 0)),
+        "survey_velocity": float(uav_section.get("velocity", planner["target_velocity"])),
+        "min_height": float(uav_section["minheight"]),
+        "max_height": float(uav_section["maxheight"]),
+        "min_velocity": float(uav_section.get("minvelocity", 5)),
+        "max_velocity": float(uav_section.get("maxvelocity", 20)),
+    }
+
+    camera_config = {
+        "pixel_size_mm": float(camera_section["pixelsize"]),
+        "focal_length_mm": float(camera_section["focallenght"]),
+        "sensor_width_mm": float(camera_section["sensorwidth"]),
+        "sensor_height_mm": float(camera_section["sensorheight"]),
+        "capture_rate_s": float(camera_section.get("capturerate", 3)),
+    }
+
+    return {
+        "planner": planner,
+        "uav": uav_config,
+        "camera": camera_config,
+        "uav_model": UAV.from_config(uav_config),
+        "camera_model": PinholeCamera.from_config(camera_config),
+    }

opencoverage/io/coords.py

@@ -0,0 +1,72 @@
+"""Coordinate conversion between geodetic and local meters."""
+
+from __future__ import annotations
+
+from pyproj import Transformer
+from shapely.geometry import Polygon
+
+from opencoverage.models import GeodeticCoordinate
+
+
+def _local_crs(reference: GeodeticCoordinate) -> str:
+    return (
+        "+proj=aeqd +lat_0={lat} +lon_0={lon} +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs".format(
+            lat=reference.latitude,
+            lon=reference.longitude,
+        )
+    )
+
+
+def geodetics_to_local_polygon(
+    geodetics: list[GeodeticCoordinate],
+    reference: GeodeticCoordinate,
+) -> Polygon:
+    """Project geodetic coordinates to a local meter polygon."""
+    transformer = Transformer.from_crs(
+        "EPSG:4326",
+        _local_crs(reference),
+        always_xy=True,
+    )
+
+    local_coords: list[tuple[float, float]] = []
+    for geo in geodetics:
+        x, y = transformer.transform(geo.longitude, geo.latitude)
+        local_coords.append((x, y))
+
+    if local_coords[0] != local_coords[-1]:
+        local_coords.append(local_coords[0])
+
+    return Polygon(local_coords)
+
+
+def local_to_geodetic(
+    x: float,
+    y: float,
+    reference: GeodeticCoordinate,
+    altitude: float | None = None,
+) -> GeodeticCoordinate:
+    """Convert local meter coordinates back to geodetic."""
+    transformer = Transformer.from_crs(
+        _local_crs(reference),
+        "EPSG:4326",
+        always_xy=True,
+    )
+    lon, lat = transformer.transform(x, y)
+    return GeodeticCoordinate(
+        latitude=lat,
+        longitude=lon,
+        altitude=reference.altitude if altitude is None else altitude,
+    )
+
+
+def path_to_geodetics(
+    path: list[tuple[float, float]],
+    reference: GeodeticCoordinate,
+    flight_height_m: float,
+) -> list[GeodeticCoordinate]:
+    """Convert a local waypoint path to geodetic coordinates at flight height."""
+    waypoint_altitude = reference.altitude + flight_height_m
+    return [
+        local_to_geodetic(x, y, reference, altitude=waypoint_altitude)
+        for x, y in path
+    ]

opencoverage/io/kml.py

@@ -0,0 +1,50 @@
+"""KML polygon reader."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from shapely.geometry import Polygon
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.io.coords import geodetics_to_local_polygon
+from opencoverage.models import GeodeticCoordinate
+
+
+def _parse_coordinates(text: str) -> list[GeodeticCoordinate]:
+    """Parse KML coordinate tuples (lon, lat, alt)."""
+    coords: list[GeodeticCoordinate] = []
+    for chunk in text.strip().split():
+        parts = chunk.split(",")
+        if len(parts) < 2:
+            continue
+        lon = float(parts[0])
+        lat = float(parts[1])
+        alt = float(parts[2]) if len(parts) > 2 else 0.0
+        coords.append(GeodeticCoordinate(latitude=lat, longitude=lon, altitude=alt))
+    return coords
+
+
+def read_polygon_from_kml(path: str | Path) -> SurveyMap:
+    """Read the first polygon found in a KML file into a SurveyMap."""
+    tree = ET.parse(path)
+    root = tree.getroot()
+
+    coordinates_text = None
+    for element in root.iter():
+        tag = element.tag.split("}")[-1]
+        if tag == "coordinates" and element.text:
+            coordinates_text = element.text
+            break
+
+    if not coordinates_text:
+        raise ValueError(f"No polygon coordinates found in KML file: {path}")
+
+    geodetics = _parse_coordinates(coordinates_text)
+    if len(geodetics) < 3:
+        raise ValueError("KML polygon must contain at least three coordinates")
+
+    reference = geodetics[0]
+    polygon = geodetics_to_local_polygon(geodetics, reference)
+    return SurveyMap.from_polygon(polygon, reference=reference)

opencoverage/io/mission_planner.py

@@ -0,0 +1,35 @@
+"""Mission Planner polygon file reader."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.io.coords import geodetics_to_local_polygon
+from opencoverage.models import GeodeticCoordinate
+
+
+def read_polygon_from_mission_planner(path: str | Path) -> SurveyMap:
+    """
+    Read a polygon from a Mission Planner poly file.
+
+    Each non-empty line contains ``latitude longitude`` in decimal degrees.
+    """
+    geodetics: list[GeodeticCoordinate] = []
+    content = Path(path).read_text(encoding="utf-8")
+
+    for line in content.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        latitude = float(parts[0])
+        longitude = float(parts[1])
+        altitude = float(parts[2]) if len(parts) > 2 else 0.0
+        geodetics.append(GeodeticCoordinate(latitude=latitude, longitude=longitude, altitude=altitude))
+
+    if len(geodetics) < 3:
+        raise ValueError(f"Mission Planner file must contain at least three points: {path}")
+
+    reference = geodetics[0]
+    polygon = geodetics_to_local_polygon(geodetics, reference)
+    return SurveyMap.from_polygon(polygon, reference=reference)