Initial public release

backend/app/services/detection_qa_service.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import Any
+from uuid import UUID
+
+from pyproj import CRS, Transformer
+from shapely.geometry import GeometryCollection, MultiPolygon, Polygon, box
+from shapely.geometry.base import BaseGeometry
+from shapely.ops import transform as shapely_transform
+from shapely.ops import unary_union
+from shapely.validation import make_valid
+
+from app.core.errors import AppError
+from app.services.qa_service import QaMatchEvidence
+
+
+@dataclass(frozen=True)
+class DetectionQaCoverage:
+    geometry: BaseGeometry
+    manifest_path: str
+    tile_count: int
+    source_crs_values: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class CoveragePopulation:
+    geometries: list[tuple[dict[str, Any], BaseGeometry]]
+    raw_count: int
+    evaluated_count: int
+    excluded_outside_count: int
+    clipped_boundary_count: int
+
+
+class DetectionQaService:
+    @staticmethod
+    def tile_manifest_path(parameters: Any) -> str | None:
+        if not isinstance(parameters, dict):
+            return None
+        value = parameters.get("tile_manifest_path")
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        nested = parameters.get("parameters_json")
+        if isinstance(nested, dict):
+            value = nested.get("tile_manifest_path")
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return None
+
+    @staticmethod
+    def build_tile_coverage(
+        manifest: dict[str, Any],
+        *,
+        manifest_path: str,
+        expected_dataset_id: UUID | None,
+    ) -> DetectionQaCoverage:
+        manifest_dataset_id = manifest.get("source_dataset_id") or manifest.get("source_raster_id")
+        if expected_dataset_id is not None and manifest_dataset_id and str(manifest_dataset_id) != str(expected_dataset_id):
+            raise AppError(
+                code="DETECTION_QA_COVERAGE_MISMATCH",
+                message="Detection tile manifest belongs to a different raster dataset",
+                details={
+                    "analysis_dataset_id": str(expected_dataset_id),
+                    "manifest_dataset_id": str(manifest_dataset_id),
+                },
+                status_code=422,
+            )
+
+        tiles = manifest.get("tiles")
+        if not isinstance(tiles, list) or not tiles:
+            raise AppError(
+                code="DETECTION_QA_COVERAGE_INVALID",
+                message="Detection tile manifest has no usable tile coverage",
+                status_code=422,
+            )
+
+        default_crs = manifest.get("crs") or manifest.get("source_crs") or manifest.get("dataset_crs")
+        coverage_parts: list[BaseGeometry] = []
+        source_crs_values: set[str] = set()
+        target_crs = CRS.from_epsg(4326)
+
+        for tile_index, tile in enumerate(tiles):
+            if not isinstance(tile, dict):
+                raise DetectionQaService._coverage_error("Tile manifest entries must be objects", tile_index)
+            raw_bounds = tile.get("bounds")
+            if not isinstance(raw_bounds, (list, tuple)) or len(raw_bounds) != 4:
+                raise DetectionQaService._coverage_error("Tile manifest entries require four bounds values", tile_index)
+            try:
+                left, bottom, right, top = (float(value) for value in raw_bounds)
+            except (TypeError, ValueError) as exc:
+                raise DetectionQaService._coverage_error("Tile bounds must be numeric", tile_index) from exc
+            if not all(isfinite(value) for value in (left, bottom, right, top)) or left >= right or bottom >= top:
+                raise DetectionQaService._coverage_error("Tile bounds must define a finite non-empty extent", tile_index)
+
+            raw_crs = tile.get("crs") or default_crs
+            if not isinstance(raw_crs, str) or not raw_crs.strip():
+                raise DetectionQaService._coverage_error("Tile coverage requires explicit CRS metadata", tile_index)
+            try:
+                source_crs = CRS.from_user_input(raw_crs)
+            except Exception as exc:
+                raise DetectionQaService._coverage_error("Tile coverage CRS is invalid", tile_index) from exc
+            source_crs_values.add(source_crs.to_string())
+
+            tile_geometry: BaseGeometry = box(left, bottom, right, top)
+            if source_crs != target_crs:
+                transformer = Transformer.from_crs(source_crs, target_crs, always_xy=True)
+                tile_geometry = shapely_transform(transformer.transform, tile_geometry)
+            tile_geometry = DetectionQaService._valid_geometry(tile_geometry, tile_index=tile_index)
+            coverage_parts.append(tile_geometry)
+
+        coverage_geometry = DetectionQaService._valid_geometry(unary_union(coverage_parts))
+        min_x, min_y, max_x, max_y = coverage_geometry.bounds
+        if min_x < -180 or max_x > 180 or min_y < -90 or max_y > 90:
+            raise AppError(
+                code="DETECTION_QA_COVERAGE_INVALID",
+                message="Transformed tile coverage falls outside EPSG:4326 bounds",
+                details={"bounds": [min_x, min_y, max_x, max_y]},
+                status_code=422,
+            )
+        return DetectionQaCoverage(
+            geometry=coverage_geometry,
+            manifest_path=manifest_path,
+            tile_count=len(tiles),
+            source_crs_values=tuple(sorted(source_crs_values)),
+        )
+
+    @staticmethod
+    def filter_population(
+        geometries: list[tuple[dict[str, Any], BaseGeometry]],
+        coverage: DetectionQaCoverage,
+        *,
+        raw_count: int | None = None,
+    ) -> CoveragePopulation:
+        evaluated: list[tuple[dict[str, Any], BaseGeometry]] = []
+        resolved_raw_count = len(geometries) if raw_count is None else raw_count
+        if resolved_raw_count < len(geometries):
+            raise ValueError("raw_count cannot be smaller than the supplied geometry population")
+        excluded_outside_count = resolved_raw_count - len(geometries)
+        clipped_boundary_count = 0
+
+        for feature, geometry in geometries:
+            if geometry.is_empty or not geometry.intersects(coverage.geometry):
+                excluded_outside_count += 1
+                continue
+            try:
+                clipped = geometry.intersection(coverage.geometry)
+            except Exception as exc:
+                raise AppError(
+                    code="GEOMETRY_OPERATION_UNSUPPORTED",
+                    message="Unable to clip QA geometry to persisted tile coverage",
+                    details={"reason": str(exc)},
+                    status_code=422,
+                ) from exc
+            if clipped.is_empty or (geometry.geom_type in {"Polygon", "MultiPolygon"} and clipped.area <= 0):
+                excluded_outside_count += 1
+                continue
+            clipped = DetectionQaService._valid_geometry(clipped)
+            if not coverage.geometry.covers(geometry):
+                clipped_boundary_count += 1
+            evaluated.append((feature, clipped))
+
+        return CoveragePopulation(
+            geometries=evaluated,
+            raw_count=resolved_raw_count,
+            evaluated_count=len(evaluated),
+            excluded_outside_count=excluded_outside_count,
+            clipped_boundary_count=clipped_boundary_count,
+        )
+
+    # A polygon whose area is within this fraction of its own bounding box is
+    # an axis-aligned rectangle for practical purposes.
+    RECTANGULAR_AREA_RATIO = 0.99
+
+    @staticmethod
+    def candidate_geometry_mode(geometries: list[tuple[dict[str, Any], BaseGeometry]]) -> str:
+        """Say whether the candidates are detector boxes or true footprints.
+
+        It matters for reading the score. An axis-aligned box can never reach
+        IoU 1 against a rotated or L-shaped building footprint, so a strict
+        footprint IoU understates a box detector by a fixed amount that has
+        nothing to do with whether it found the building.
+        """
+
+        polygonal = [
+            geometry
+            for _, geometry in geometries
+            if geometry.geom_type in {"Polygon", "MultiPolygon"} and geometry.area > 0
+        ]
+        if not polygonal:
+            return "unknown"
+        rectangular = sum(
+            1
+            for geometry in polygonal
+            if geometry.area / geometry.envelope.area >= DetectionQaService.RECTANGULAR_AREA_RATIO
+        )
+        return "axis_aligned_boxes" if rectangular == len(polygonal) else "footprint_polygons"
+
+    @staticmethod
+    def box_to_footprint_diagnostics(
+        strict_evidence: QaMatchEvidence,
+        envelope_evidence: QaMatchEvidence,
+        *,
+        iou_threshold: float,
+        candidate_geometry_mode: str = "unknown",
+    ) -> dict[str, Any]:
+        envelope_metrics = DetectionQaService._metrics(envelope_evidence)
+        diagnostics = {
+            "diagnostic_only": True,
+            "canonical_method": "candidate_polygon_vs_reference_footprint_iou",
+            "diagnostic_method": "candidate_polygon_vs_reference_envelope_iou",
+            "iou_threshold": iou_threshold,
+            "candidate_geometry_mode": candidate_geometry_mode,
+            "strict_matches": strict_evidence.matches,
+            "envelope_matches": envelope_evidence.matches,
+            "possible_box_to_footprint_mismatch_count": max(0, envelope_evidence.matches - strict_evidence.matches),
+            **envelope_metrics,
+        }
+        if candidate_geometry_mode == "axis_aligned_boxes":
+            diagnostics["interpretation"] = (
+                "Candidates are axis-aligned detector boxes. The strict footprint IoU therefore has a "
+                "ceiling below 1 for rotated or non-rectangular buildings; the envelope figures isolate "
+                "detection quality from that shape mismatch."
+            )
+        return diagnostics
+
+    @staticmethod
+    def _metrics(evidence: QaMatchEvidence) -> dict[str, Any]:
+        precision = (
+            evidence.matches / (evidence.matches + evidence.false_positives)
+            if evidence.matches + evidence.false_positives > 0
+            else None
+        )
+        recall = (
+            evidence.matches / (evidence.matches + evidence.false_negatives)
+            if evidence.matches + evidence.false_negatives > 0
+            else None
+        )
+        f1_score = None
+        if precision is not None and recall is not None:
+            f1_score = (2 * precision * recall) / (precision + recall) if precision + recall > 0 else 0.0
+        mean_iou = (
+            sum(evidence.match_iou_values) / len(evidence.match_iou_values)
+            if evidence.match_iou_values
+            else None
+        )
+        return {
+            "envelope_false_positives": evidence.false_positives,
+            "envelope_false_negatives": evidence.false_negatives,
+            "envelope_precision": precision,
+            "envelope_recall": recall,
+            "envelope_f1_score": f1_score,
+            "envelope_mean_iou": mean_iou,
+        }
+
+    @staticmethod
+    def _valid_geometry(geometry: BaseGeometry, *, tile_index: int | None = None) -> BaseGeometry:
+        if not geometry.is_valid:
+            geometry = make_valid(geometry)
+        if geometry.is_empty or not geometry.is_valid:
+            raise DetectionQaService._coverage_error("Tile coverage geometry is empty or invalid", tile_index)
+        if isinstance(geometry, GeometryCollection):
+            polygonal_parts = [part for part in geometry.geoms if isinstance(part, (Polygon, MultiPolygon)) and not part.is_empty]
+            if polygonal_parts:
+                geometry = unary_union(polygonal_parts)
+        return geometry
+
+    @staticmethod
+    def _coverage_error(message: str, tile_index: int | None = None) -> AppError:
+        details = {"tile_index": tile_index} if tile_index is not None else None
+        return AppError(
+            code="DETECTION_QA_COVERAGE_INVALID",
+            message=message,
+            details=details,
+            status_code=422,
+        )