adjusting to optv

Author: alexlib

docs/native_backend_unification.md

@@ -10,6 +10,20 @@ The important user-facing contract is simple:
 - the same Python calls should work with and without `optv` installed
 - native acceleration is an implementation detail, not a second API surface
 
+## Implementation Checklist
+
+Use this checklist when adding or changing backend routing:
+
+- [ ] Import backend-facing symbols from `pyptv._backend`, not directly from `optv` or `openptv_python`, in pipeline code.
+- [ ] Ensure the active engine is selected through `_native_compat.set_engine()` and queried through `should_use_native(...)` or the backend helper functions.
+- [ ] When `optv` is installed and selected, use the native module objects and native parameter/calibration classes.
+- [ ] When `optv` is missing or disabled, keep the Python/Numba fallback path callable with the same function signatures.
+- [ ] Convert Python objects to native objects at backend boundaries only; do not leak backend-specific types into unrelated code paths.
+- [ ] Convert native objects back to Python objects only when a downstream caller still expects the Python implementation model.
+- [ ] Preserve input and output shapes between backends for detection, correspondences, calibration, reconstruction, and tracking.
+- [ ] Keep a fallback path for calibration routines that fail in the native backend, but make sure the fallback sees the same data model as the native path.
+- [ ] Add or update tests whenever a backend boundary changes so the native and Python paths stay behaviorally aligned.
+
 The runtime flow is:
 
 | Layer | Responsibility |
@@ -94,6 +108,15 @@ The important distinction is not whether a native implementation exists. It is
 whether the normal `openptv_python` runtime path already chooses that native
 implementation transparently for the user.
 
+### Contract Rules
+
+- `pyptv._backend` is the only layer that should decide which implementation is active.
+- Public helpers must keep one stable signature, regardless of backend.
+- Backend-specific object construction must stay inside conversion helpers or backend dispatch code.
+- If a native routine expects a native object type, the wrapper must build it before the call.
+- If a fallback routine expects Python dataclasses, the wrapper must convert back before the call.
+- A failed native path may fall back to Python, but only after restoring or rebuilding the input objects the fallback expects.
+
 ## Why `tests/test_native_stress_performance.py` matters
 
 The best executable description of this backend strategy is

src/openptv_python/imgcoord.py

@@ -10,6 +10,19 @@
 from .trafo import flat_to_dist
 
 
+def _as_python_calibration(cal: Calibration) -> Calibration:
+    if isinstance(cal, Calibration):
+        return cal
+
+    from ._native_convert import from_native_calibration
+
+    converted = from_native_calibration(cal)
+    if not isinstance(converted, Calibration):
+        raise TypeError("Unsupported calibration object")
+
+    return converted
+
+
 def flat_image_coord(
     orig_pos: np.ndarray, cal: Calibration, mm: MultimediaPar
 ) -> Tuple[float, float]:
@@ -28,6 +41,8 @@ def flat_image_coord(
     if orig_pos.shape != (3,):
         raise ValueError("orig_pos must be a 3D vector")
 
+    cal = _as_python_calibration(cal)
+
     cal_t = Calibration(mmlut=cal.mmlut)
 
     # This block calculate 3D position in an imaginary air-filled space,
@@ -76,6 +91,8 @@ def img_coord(
     pos: np.ndarray, cal: Calibration, mm: MultimediaPar
 ) -> Tuple[float, float]:
     """Estimate metric coordinates in image space (mm)."""
+    cal = _as_python_calibration(cal)
+
     # Estimate metric coordinates in image space using flat_image_coord()
     if pos.shape[0] != 3:
         raise ValueError("pos must be a 3D vector")
@@ -95,6 +112,8 @@ def image_coordinates(
     orig_pos: np.ndarray, cal: Calibration, mm: MultimediaPar
 ) -> np.ndarray:
     """Image coordinates in array mode."""
+    cal = _as_python_calibration(cal)
+
     npoints = orig_pos.shape[0]
     out = np.empty((npoints, 2), dtype=float)
 

src/pyptv/standalone_calibration.py

@@ -11,10 +11,11 @@
 
 import numpy as np
 
-from openptv_python.calibration import Calibration
-from openptv_python.orientation import external_calibration, full_calibration
+from openptv_python._native_compat import should_use_native
 from openptv_python.parameters import OrientPar
-from openptv_python.tracking_frame_buf import TargetArray
+from openptv_python.calibration import Calibration as PythonCalibration
+
+from ._backend import Calibration, external_calibration, full_calibration, TargetArray
 
 from .parameter_manager import ParameterManager
 from . import ptv
@@ -156,14 +157,30 @@ def _select_four_indices(mode: str, n: int) -> np.ndarray:
     raise ValueError(f"Unknown init mode: {mode}")
 
 
+def _select_manual_orientation_indices(pm: ParameterManager, cam: int, n: int) -> np.ndarray:
+    man_ori = pm.parameters.get("man_ori")
+    if isinstance(man_ori, dict):
+        nr = man_ori.get("nr")
+        if isinstance(nr, list) and len(nr) >= (cam + 1) * 4:
+            cam_nr = nr[cam * 4 : cam * 4 + 4]
+            indices = np.asarray([int(idx) - 1 for idx in cam_nr], dtype=int)
+            if np.all((0 <= indices) & (indices < n)):
+                return indices
+
+    return _select_four_indices("first4", n)
+
+
 def _load_or_init_calibration(ori_path: Path) -> Calibration:
-    cal = Calibration()
     addpar_path = Path(str(ori_path).replace(".ori", ".addpar"))
 
     if ori_path.exists() and addpar_path.exists():
-        cal.from_file(str(ori_path), str(addpar_path))
+        if should_use_native("orientation"):
+            cal = Calibration()
+            cal.from_file(str(ori_path), str(addpar_path))
+            return cal
+        return PythonCalibration.from_file(str(ori_path), str(addpar_path))
 
-    return cal
+    return Calibration() if should_use_native("orientation") else PythonCalibration()
 
 
 def run_standalone_calibration(
@@ -206,20 +223,26 @@ def run_standalone_calibration(
         targs = targets_from_xy(xy[cam], pnr)
 
         if init_external is not None:
-            idx4 = _select_four_indices(init_external, len(pnr))
+            if init_external == "first4":
+                idx4 = _select_manual_orientation_indices(pm, cam, len(pnr))
+            else:
+                idx4 = _select_four_indices(init_external, len(pnr))
             sel_xyz = np.asarray(xyz[pnr[idx4]], dtype=float)
             sel_xy = np.asarray(xy[cam][idx4], dtype=float)
 
             ok = external_calibration(cal, sel_xyz, sel_xy, cpar)
             if ok is False:
-                raise RuntimeError(f"external_calibration failed for camera {cam}")
+                print(
+                    f"external_calibration failed for camera {cam}; "
+                    "continuing with the loaded calibration"
+                )
 
         residuals, targ_ix, err_est = full_calibration(
             cal,
             np.asarray(xyz, dtype=float),
             targs,
             cpar,
-            _orient_par_from_flags(flags),
+            list(flags) if should_use_native("orientation") else _orient_par_from_flags(flags),
         )
 
         packed = np.array(
@@ -235,11 +258,11 @@ def run_standalone_calibration(
         if np.any(np.isnan(np.hstack(packed))):
             raise ValueError(f"Calibration for camera {cam} contains NaNs")
 
-        calibrations.append(cal)
-
         if write:
             addpar_path = Path(str(ori_path).replace(".ori", ".addpar"))
             ori_path.parent.mkdir(parents=True, exist_ok=True)
             cal.write(str(ori_path).encode(), str(addpar_path).encode())
 
+        calibrations.append(cal)
+
     return calibrations