feat: initial commit - massive-cloud point cloud processing system

alg/delivery_v1.1/coupler_panel_release/coupler_panel/structures.py

@@ -0,0 +1,148 @@
+"""Result dataclasses for coupler_panel.
+
+These types form the **stable public schema** of the package; their
+field names and semantics are guarded by ``SCHEMA_VERSION`` (see
+``_version.py``).
+
+All numeric units are **mm** for distances and **degree** for angles
+unless otherwise noted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Building blocks
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Hole:
+    """A single detected (or GT) circular hole on the panel."""
+
+    center: tuple[float, float, float]   # (x, y, z), mm
+    radius_mm: float
+    fit_residual_rms_mm: float           # 0 for GT
+    role: str                            # "locating" | "central" | "unknown"
+
+
+@dataclass(frozen=True)
+class HoleSet:
+    """The four locating holes plus an optional central hole.
+
+    ``locating`` is ordered consistently between GT and detection so that
+    Kabsch pairing is index-aligned.
+    """
+
+    locating: tuple[Hole, Hole, Hole, Hole]
+    central: Hole | None = None
+
+    def locating_centers(self) -> np.ndarray:
+        """Return a (4, 3) ndarray of locating-hole centres."""
+        return np.asarray([h.center for h in self.locating], dtype=np.float64)
+
+
+@dataclass(frozen=True)
+class PanelPlane:
+    """The fitted (or GT) panel plane."""
+
+    normal: tuple[float, float, float]   # unit vector, n_x > 0 enforced
+    point_on_plane: tuple[float, float, float]
+    d_offset: float                      # n . x + d = 0
+    inlier_ratio: float                  # 1.0 for GT
+    inlier_residual_rms_mm: float        # 0 for GT
+
+
+@dataclass(frozen=True)
+class ReferenceFrame:
+    """Reference geometry derived from the four-hole panel centre."""
+
+    center_C: tuple[float, float, float]
+    # Reference line L = C + lam * e_x  (always parallel to the +x axis).
+    line_direction: tuple[float, float, float] = (1.0, 0.0, 0.0)
+    # Reference plane: z = C_z. Stored as plane normal + offset.
+    reference_plane_z: float = 0.0
+    # Longitudinal mid-plane: y = C_y.
+    longitudinal_mid_y: float = 0.0
+
+
+@dataclass(frozen=True)
+class StageTiming:
+    """Per-stage wall-clock and peak-memory cost."""
+
+    stage: str
+    seconds: float
+    peak_kib: float
+
+
+# ---------------------------------------------------------------------------
+# Top-level result
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CouplerMeasurement:
+    """Top-level result of the coupler-panel measurement pipeline.
+
+    See ``docs/USAGE.md`` for the stable-API contract.
+    """
+
+    schema_version: str
+    algorithm_version: str
+
+    # --- Primary measurands ---
+    theta_right_deg: float           # atan2(n_y, n_x), with right_axis_sign applied
+    theta_ref_deg: float             # atan2(n_z, n_x)
+    D_y_max_mm: float                # max |y_i - C_y| over panel ROI
+    D_z_max_mm: float                # max |z_i - C_z| over panel ROI
+    dx_y_max_mm: float               # |A| * D_y_max,  A = -n_y / n_x
+    dx_z_max_mm: float               # |B| * D_z_max,  B = -n_z / n_x
+
+    # --- Geometry ---
+    center_C: tuple[float, float, float]
+    normal: tuple[float, float, float]    # n_x > 0
+    holes: HoleSet
+    plane: PanelPlane
+    frame: ReferenceFrame
+
+    # --- Diagnostics ---
+    quality_flags: list[str] = field(default_factory=list)
+    timings: list[StageTiming] = field(default_factory=list)
+    report: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a fully JSON-serialisable dict."""
+        return _to_jsonable(asdict(self))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_jsonable(obj: Any) -> Any:
+    """Recursively convert numpy / tuple structures into plain Python types."""
+    if isinstance(obj, dict):
+        return {k: _to_jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_to_jsonable(v) for v in obj]
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, (np.floating, np.integer)):
+        return obj.item()
+    return obj
+
+
+__all__ = [
+    "Hole",
+    "HoleSet",
+    "PanelPlane",
+    "ReferenceFrame",
+    "StageTiming",
+    "CouplerMeasurement",
+]