opencoverage 0.2.0__py3-none-any.whl

opencoverage/io/qgc.py

@@ -0,0 +1,130 @@
+"""QGroundControl waypoint file export."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from opencoverage.io.coords import path_to_geodetics
+from opencoverage.models import GeodeticCoordinate
+
+
+def _write_command(
+    waypoint_id: int,
+    is_current: int,
+    coordinate_frame: int,
+    command: int,
+    param1: float,
+    param2: float,
+    param3: float,
+    param4: float,
+    latitude: float,
+    longitude: float,
+    altitude: float,
+    auto_continue: int,
+) -> str:
+    return (
+        f"{waypoint_id}\t{is_current}\t{coordinate_frame}\t{command}\t"
+        f"{param1}\t{param2}\t{param3}\t{param4}\t"
+        f"{latitude:.15f}\t{longitude:.15f}\t{altitude:.6f}\t{auto_continue}"
+    )
+
+
+def write_qgc_file(
+    filename: str | Path,
+    *,
+    path: list[tuple[float, float]],
+    flight_height: float,
+    reference: GeodeticCoordinate,
+    home: GeodeticCoordinate | None = None,
+    takeoff: GeodeticCoordinate | None = None,
+    auto_takeoff: bool = False,
+) -> None:
+    """
+    Write a QGroundControl waypoint file from a local-meter path.
+
+    Format follows the legacy QGC WPL 120 tab-separated layout.
+    """
+    geodetics = path_to_geodetics(path, reference, flight_height)
+    lines = ["QGC WPL 120"]
+    waypoint_id = 0
+    current_id = 0
+    auto_continue = 1
+
+    if auto_takeoff and takeoff is not None:
+        lines.append(
+            _write_command(
+                waypoint_id,
+                1 if waypoint_id == current_id else 0,
+                3,
+                22,
+                15,
+                0,
+                0,
+                0,
+                takeoff.latitude,
+                takeoff.longitude,
+                takeoff.altitude,
+                auto_continue,
+            )
+        )
+        waypoint_id += 1
+
+    if geodetics:
+        first = geodetics[0]
+        lines.append(
+            _write_command(
+                waypoint_id,
+                1 if waypoint_id == current_id else 0,
+                3,
+                16,
+                0,
+                0,
+                0,
+                0,
+                first.latitude,
+                first.longitude,
+                first.altitude,
+                auto_continue,
+            )
+        )
+        waypoint_id += 1
+
+    for geo in geodetics:
+        lines.append(
+            _write_command(
+                waypoint_id,
+                1 if waypoint_id == current_id else 0,
+                3,
+                16,
+                0,
+                0,
+                0,
+                0,
+                geo.latitude,
+                geo.longitude,
+                geo.altitude,
+                auto_continue,
+            )
+        )
+        waypoint_id += 1
+
+    if geodetics:
+        first = geodetics[0]
+        lines.append(
+            _write_command(
+                waypoint_id,
+                1 if waypoint_id == current_id else 0,
+                3,
+                17,
+                0,
+                0,
+                15,
+                0,
+                first.latitude,
+                first.longitude,
+                first.altitude,
+                auto_continue,
+            )
+        )
+
+    Path(filename).write_text("\r\n".join(lines) + "\r\n", encoding="utf-8")

opencoverage/io/survey_input.py

@@ -0,0 +1,21 @@
+"""Survey polygon input readers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.io.kml import read_polygon_from_kml
+from opencoverage.io.mission_planner import read_polygon_from_mission_planner
+
+
+def read_survey_map(path: str | Path) -> SurveyMap:
+    """
+    Load a survey map from KML or Mission Planner polygon file.
+
+    Supported extensions: ``.kml``, ``.kmz`` (KML only), ``.poly``, ``.txt``.
+    """
+    suffix = Path(path).suffix.lower()
+    if suffix in {".kml", ".kmz"}:
+        return read_polygon_from_kml(path)
+    return read_polygon_from_mission_planner(path)

opencoverage/mission_splitter.py

@@ -0,0 +1,83 @@
+"""Split long missions according to UAV flight-time limits."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from opencoverage.models import FlightMission, GeodeticCoordinate, UAV
+
+
+class MissionSplitter:
+    """Divide a mission into segments that fit within UAV flight time."""
+
+    def __init__(self, uav: UAV) -> None:
+        self.uav = uav
+
+    def split(self, mission: FlightMission) -> list[FlightMission]:
+        """
+        Split a mission into sub-missions when flight_time_s is configured.
+
+        When flight_time_s is zero, the original mission is returned unchanged.
+        """
+        if self.uav.flight_time_s <= 0 or not mission.path:
+            return [mission]
+
+        segments: list[FlightMission] = []
+        partial_path: list[tuple[float, float]] = []
+        last_point: tuple[float, float] | None = None
+
+        for point in mission.path:
+            partial_path.append(point)
+            elapsed = self.uav.estimate_flight_time(partial_path)
+            if elapsed > self.uav.flight_time_s:
+                partial_path.pop()
+                if partial_path:
+                    segments.append(self._clone_mission(mission, partial_path))
+                partial_path = []
+                if last_point is not None:
+                    partial_path.append(last_point)
+                partial_path.append(point)
+
+            last_point = point
+
+        if partial_path:
+            segments.append(self._clone_mission(mission, partial_path))
+
+        return segments or [mission]
+
+    def save_qgc_files(
+        self,
+        missions: list[FlightMission],
+        base_filename: str | Path,
+        reference: GeodeticCoordinate,
+    ) -> list[Path]:
+        """Save each mission segment as a numbered QGroundControl file."""
+        base_path = Path(base_filename)
+        stem = base_path.stem
+        suffix = base_path.suffix or ".txt"
+        parent = base_path.parent
+
+        saved: list[Path] = []
+        for index, mission in enumerate(missions, start=1):
+            output = parent / f"{stem}{index}{suffix}"
+            mission.save_qgc(output, reference=reference)
+            saved.append(output)
+        return saved
+
+    def _clone_mission(
+        self,
+        mission: FlightMission,
+        path: list[tuple[float, float]],
+    ) -> FlightMission:
+        return FlightMission(
+            path=list(path),
+            flight_height=mission.flight_height,
+            home=mission.home,
+            takeoff=mission.takeoff,
+            reference=mission.reference,
+            auto_takeoff=mission.auto_takeoff,
+            forward_distance=mission.forward_distance,
+            lateral_distance=mission.lateral_distance,
+            capture_rate=mission.capture_rate,
+            flight_time_s=self.uav.estimate_flight_time(path),
+        )

opencoverage/models.py

@@ -0,0 +1,134 @@
+"""Domain models for UAV survey planning."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Sequence
+
+import numpy as np
+
+
+class TargetPlanning(IntEnum):
+    """Planning objective used to derive flight height and capture rate."""
+
+    RESOLUTION = 1
+    VELOCITY = 2
+    ALTITUDE = 3
+
+
+class SearchPatternType(IntEnum):
+    """Available coverage sweep patterns."""
+
+    BACK_AND_FORTH = 1
+    LONG_EDGE = 2
+    OPTIMAL_SWEEP = 3
+    FOLLOWING_WIND = 4
+
+
+@dataclass
+class GeodeticCoordinate:
+    """WGS84 geodetic coordinate."""
+
+    latitude: float
+    longitude: float
+    altitude: float = 0.0
+
+
+@dataclass
+class CartesianCoordinate:
+    """Local Cartesian coordinate in meters (north-east-down style x/y)."""
+
+    x: float
+    y: float
+    z: float = 0.0
+
+
+@dataclass
+class PinholeCamera:
+    """Pinhole camera model. All geometric parameters are in millimeters."""
+
+    pixel_size_mm: float
+    focal_length_mm: float
+    sensor_width_mm: float
+    sensor_height_mm: float
+    capture_rate_s: float = 3.0
+
+    @classmethod
+    def from_config(cls, config: dict[str, float]) -> PinholeCamera:
+        """Build a camera from parsed INI camera section values."""
+        return cls(
+            pixel_size_mm=config["pixel_size_mm"],
+            focal_length_mm=config["focal_length_mm"],
+            sensor_width_mm=config["sensor_width_mm"],
+            sensor_height_mm=config["sensor_height_mm"],
+            capture_rate_s=config.get("capture_rate_s", 3.0),
+        )
+
+
+@dataclass
+class UAV:
+    """Multirotor UAV flight constraints."""
+
+    min_height: float = 70.0
+    max_height: float = 500.0
+    min_velocity: float = 5.0
+    max_velocity: float = 20.0
+    survey_velocity: float = 17.0
+    flight_time_s: float = 0.0
+
+    @classmethod
+    def from_config(cls, config: dict[str, float]) -> UAV:
+        """Build a UAV from parsed INI UAV section values."""
+        return cls(
+            min_height=config["min_height"],
+            max_height=config["max_height"],
+            min_velocity=config.get("min_velocity", 5.0),
+            max_velocity=config.get("max_velocity", 20.0),
+            survey_velocity=config.get("survey_velocity", config.get("velocity", 17.0)),
+            flight_time_s=config.get("flight_time_s", 0.0),
+        )
+
+    def estimate_path_distance(self, path: Sequence[tuple[float, float]]) -> float:
+        """Return total path length in meters."""
+        if len(path) < 2:
+            return 0.0
+        points = np.asarray(path, dtype=float)
+        deltas = np.diff(points, axis=0)
+        return float(np.sum(np.hypot(deltas[:, 0], deltas[:, 1])))
+
+    def estimate_flight_time(self, path: Sequence[tuple[float, float]]) -> float:
+        """Return estimated flight duration in seconds."""
+        if self.survey_velocity <= 0:
+            return 0.0
+        return self.estimate_path_distance(path) / self.survey_velocity
+
+
+@dataclass
+class FlightMission:
+    """Planned survey mission with waypoint path in local coordinates."""
+
+    path: list[tuple[float, float]] = field(default_factory=list)
+    flight_height: float = 0.0
+    home: GeodeticCoordinate | None = None
+    takeoff: GeodeticCoordinate | None = None
+    reference: GeodeticCoordinate | None = None
+    auto_takeoff: bool = False
+    forward_distance: float = 0.0
+    lateral_distance: float = 0.0
+    capture_rate: float = 0.0
+    flight_time_s: float = 0.0
+
+    def save_qgc(self, filename: str, reference: GeodeticCoordinate) -> None:
+        """Export the mission as a QGroundControl waypoint file."""
+        from opencoverage.io.qgc import write_qgc_file
+
+        write_qgc_file(
+            filename,
+            path=self.path,
+            flight_height=self.flight_height,
+            reference=reference,
+            home=self.home,
+            takeoff=self.takeoff,
+            auto_takeoff=self.auto_takeoff,
+        )

opencoverage/parameters.py

@@ -0,0 +1,132 @@
+"""Survey parameter calculations derived from camera and UAV models."""
+
+from __future__ import annotations
+
+from opencoverage.models import PinholeCamera, TargetPlanning, UAV
+
+
+def flight_height_from_resolution(spatial_resolution_mm: float, camera: PinholeCamera) -> float:
+    """Compute flight height in meters for a target ground resolution."""
+    height_m = (spatial_resolution_mm * camera.focal_length_mm) / camera.pixel_size_mm
+    return height_m / 1000.0
+
+
+def spatial_resolution_from_height(flight_height_m: float, camera: PinholeCamera) -> float:
+    """Compute ground resolution in mm/pixel for a given flight height."""
+    resolution_m = camera.pixel_size_mm * flight_height_m / camera.focal_length_mm
+    return resolution_m * 1000.0
+
+
+def lateral_line_spacing(
+    flight_height_m: float,
+    lateral_overlap: float,
+    camera: PinholeCamera,
+) -> float:
+    """Distance between adjacent sweep lines in meters."""
+    return (
+        (flight_height_m / camera.focal_length_mm)
+        * camera.sensor_width_mm
+        * (1.0 - lateral_overlap)
+    )
+
+
+def forward_trigger_distance(
+    flight_height_m: float,
+    forward_overlap: float,
+    camera: PinholeCamera,
+) -> float:
+    """Forward camera trigger distance in meters."""
+    return (
+        (flight_height_m / camera.focal_length_mm)
+        * camera.sensor_height_mm
+        * (1.0 - forward_overlap)
+    )
+
+
+def cruise_height_for_velocity(
+    velocity_m_s: float,
+    forward_overlap: float,
+    camera: PinholeCamera,
+) -> float:
+    """Compute flight height that matches velocity and camera capture rate."""
+    return (
+        velocity_m_s
+        * camera.capture_rate_s
+        * camera.focal_length_mm
+        / (camera.sensor_height_mm * (1.0 - forward_overlap))
+    )
+
+
+def capture_rate_for_height(
+    flight_height_m: float,
+    forward_overlap: float,
+    velocity_m_s: float,
+    camera: PinholeCamera,
+) -> float:
+    """Required capture interval in seconds for the given flight parameters."""
+    trigger_distance = forward_trigger_distance(flight_height_m, forward_overlap, camera)
+    return trigger_distance / velocity_m_s
+
+
+def minimum_survey_height(
+    forward_overlap: float,
+    camera: PinholeCamera,
+    uav: UAV,
+) -> float:
+    """Minimum feasible survey height given UAV minimum velocity."""
+    min_trigger = camera.capture_rate_s * uav.min_velocity
+    return (min_trigger * camera.focal_length_mm) / (
+        camera.sensor_height_mm * (1.0 - forward_overlap)
+    )
+
+
+def resolve_survey_parameters(
+    *,
+    uav: UAV,
+    camera: PinholeCamera,
+    lateral_overlap: float,
+    forward_overlap: float,
+    target: TargetPlanning,
+    target_value: float,
+) -> dict[str, float]:
+    """
+    Resolve flight height, spatial resolution, velocity, and trigger distance.
+
+    Mirrors the parameter selection logic from the original C++ SearchPattern class.
+    """
+    if target == TargetPlanning.RESOLUTION:
+        flight_height = flight_height_from_resolution(target_value, camera)
+        spatial_resolution = target_value
+        velocity = uav.survey_velocity
+    elif target == TargetPlanning.ALTITUDE:
+        flight_height = target_value
+        spatial_resolution = spatial_resolution_from_height(flight_height, camera)
+        velocity = uav.survey_velocity
+    elif target == TargetPlanning.VELOCITY:
+        velocity = target_value
+        flight_height = cruise_height_for_velocity(velocity, forward_overlap, camera)
+        spatial_resolution = spatial_resolution_from_height(flight_height, camera)
+    else:
+        raise ValueError(f"Unsupported planning target: {target}")
+
+    if flight_height < uav.min_height:
+        flight_height = uav.min_height
+        spatial_resolution = spatial_resolution_from_height(flight_height, camera)
+
+    if flight_height > uav.max_height:
+        flight_height = uav.max_height
+        spatial_resolution = spatial_resolution_from_height(flight_height, camera)
+
+    trigger_distance = forward_trigger_distance(flight_height, forward_overlap, camera)
+    required_capture_rate = capture_rate_for_height(
+        flight_height, forward_overlap, velocity, camera
+    )
+
+    return {
+        "flight_height": flight_height,
+        "spatial_resolution": spatial_resolution,
+        "velocity": velocity,
+        "trigger_distance": trigger_distance,
+        "required_capture_rate": required_capture_rate,
+        "lateral_spacing": lateral_line_spacing(flight_height, lateral_overlap, camera),
+    }

opencoverage/patterns/__init__.py

@@ -0,0 +1,15 @@
+"""Coverage search pattern implementations."""
+
+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
+
+__all__ = [
+    "BackAndForthPattern",
+    "FollowingWindPattern",
+    "LongEdgePattern",
+    "OptimalSweepPattern",
+    "SearchPattern",
+]

opencoverage/patterns/back_forth.py

@@ -0,0 +1,57 @@
+"""Back-and-forth (boustrophedon) coverage sweep pattern."""
+
+from __future__ import annotations
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.geometry.transforms import rotate_points
+from opencoverage.models import FlightMission
+from opencoverage.patterns.base import SearchPattern
+
+
+class BackAndForthPattern(SearchPattern):
+    """Generate parallel sweep lines across the polygon bounding width."""
+
+    LEFT_TO_RIGHT = 1
+    RIGHT_TO_LEFT = -1
+    BOTTOM_UP = 1
+    TOP_DOWN = -1
+
+    def calculate(self) -> FlightMission:
+        waypoints = self.generate_pattern(self.survey_map)
+        return self.build_mission(waypoints)
+
+    def generate_rotated_pattern(self, angle_rad: float) -> list[tuple[float, float]]:
+        """Generate a back-and-forth path after rotating the map by angle_rad."""
+        rotated_map = self.survey_map.rotated_copy(angle_rad)
+        waypoints = self.generate_pattern(rotated_map)
+        return rotate_points(waypoints, -angle_rad)
+
+    def generate_pattern(self, survey_map: SurveyMap) -> list[tuple[float, float]]:
+        """Generate waypoint path for the given map."""
+        extremes = survey_map.extreme_vertices()
+        left_point = extremes["left"]
+        right_point = extremes["right"]
+
+        horizontal_order = self.LEFT_TO_RIGHT
+        vertical_order = self.BOTTOM_UP
+        lateral_displacement = self.lateral_spacing * horizontal_order
+
+        if horizontal_order == self.LEFT_TO_RIGHT:
+            line_x = left_point[0]
+            min_x = left_point[0]
+            max_x = right_point[0]
+        else:
+            line_x = right_point[0]
+            min_x = left_point[0]
+            max_x = right_point[0]
+
+        waypoints: list[tuple[float, float]] = []
+
+        while min_x <= line_x <= max_x:
+            points = survey_map.intersect_vertical_line(line_x)
+            points.sort(key=lambda p: p[1], reverse=vertical_order == self.TOP_DOWN)
+            vertical_order *= -1
+            waypoints.extend(points)
+            line_x += lateral_displacement
+
+        return waypoints

opencoverage/patterns/base.py

@@ -0,0 +1,74 @@
+"""Base class for coverage search patterns."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from opencoverage.geometry.map import SurveyMap
+from opencoverage.models import FlightMission, PinholeCamera, TargetPlanning, UAV
+from opencoverage.parameters import resolve_survey_parameters
+
+
+class SearchPattern(ABC):
+    """Abstract coverage path planner."""
+
+    def __init__(self, uav: UAV, camera: PinholeCamera, survey_map: SurveyMap) -> None:
+        self.uav = uav
+        self.camera = camera
+        self.survey_map = survey_map
+        self.lateral_overlap = 0.0
+        self.forward_overlap = 0.0
+        self.target = TargetPlanning.VELOCITY
+        self.target_value = 0.0
+        self.flight_height = 0.0
+        self.spatial_resolution = 0.0
+        self.velocity = 0.0
+        self.trigger_distance = 0.0
+        self.lateral_spacing = 0.0
+        self.flight_time_s = 0.0
+
+    def set_search_parameters(
+        self,
+        lateral_overlap: float,
+        forward_overlap: float,
+        target_value: float,
+        target: TargetPlanning,
+    ) -> None:
+        """Configure overlap ratios and the planning objective."""
+        self.lateral_overlap = lateral_overlap
+        self.forward_overlap = forward_overlap
+        self.target = target
+        self.target_value = target_value
+
+        params = resolve_survey_parameters(
+            uav=self.uav,
+            camera=self.camera,
+            lateral_overlap=lateral_overlap,
+            forward_overlap=forward_overlap,
+            target=target,
+            target_value=target_value,
+        )
+        self.flight_height = params["flight_height"]
+        self.spatial_resolution = params["spatial_resolution"]
+        self.velocity = params["velocity"]
+        self.trigger_distance = params["trigger_distance"]
+        self.lateral_spacing = params["lateral_spacing"]
+
+    def build_mission(self, waypoints: list[tuple[float, float]]) -> FlightMission:
+        """Create a FlightMission from a local waypoint path."""
+        capture_rate = self.trigger_distance / self.velocity if self.velocity else 0.0
+        return FlightMission(
+            path=waypoints,
+            flight_height=self.flight_height,
+            home=self.survey_map.home,
+            takeoff=self.survey_map.takeoff,
+            reference=self.survey_map.reference,
+            forward_distance=self.trigger_distance,
+            lateral_distance=self.lateral_spacing,
+            capture_rate=capture_rate,
+            flight_time_s=self.uav.estimate_flight_time(waypoints),
+        )
+
+    @abstractmethod
+    def calculate(self) -> FlightMission:
+        """Compute the coverage mission."""

opencoverage/patterns/following_wind.py

@@ -0,0 +1,33 @@
+"""Wind-aligned coverage sweep pattern."""
+
+from __future__ import annotations
+
+import math
+
+from opencoverage.models import FlightMission
+from opencoverage.patterns.back_forth import BackAndForthPattern
+
+
+class FollowingWindPattern(BackAndForthPattern):
+    """
+    Align sweep lines with a wind direction.
+
+    Wind direction uses meteorological convention in degrees:
+    0 = from north, 90 = from east, 180 = from south, 270 = from west.
+    """
+
+    def __init__(
+        self,
+        uav,
+        camera,
+        survey_map,
+        *,
+        wind_direction_deg: float = 0.0,
+    ) -> None:
+        super().__init__(uav, camera, survey_map)
+        self.wind_direction_deg = wind_direction_deg
+
+    def calculate(self) -> FlightMission:
+        rotation = math.radians(self.wind_direction_deg)
+        waypoints = self.generate_rotated_pattern(rotation)
+        return self.build_mission(waypoints)