updated more of optv - see native_backend_unification.md

Author: alexlib

docs/native_backend_unification.md

@@ -39,6 +39,29 @@ points:
 - `openptv_python.image_processing.preprocess_image()`
 - `openptv_python.segmentation.targ_rec()`
 
+## Native optv submodules
+
+When `optv` is installed, the backend can use these submodules directly:
+
+| optv submodule | Used for |
+| --- | --- |
+| `optv.calibration` | Calibration objects and calibration-file handling |
+| `optv.correspondences` | Stereo correspondences and single-camera correspondences |
+| `optv.epipolar` | Epipolar-curve generation |
+| `optv.image_processing` | High-pass preprocessing |
+| `optv.imgcoord` | Image-coordinate conversion helpers |
+| `optv.orientation` | Point reconstruction and calibration routines |
+| `optv.parameters` | Control, sequence, target, tracking, and volume parameters |
+| `optv.segmentation` | Target recognition |
+| `optv.tracker` | Tracking orchestration |
+| `optv.tracking_framebuf` | Targets, target arrays, frames, and target-file IO |
+| `optv.transforms` | Pixel/metric conversion helpers |
+| `optv.version` | Package version metadata |
+
+The current backend preference is to route to these native modules whenever the
+`optv` engine is selected and the submodule is available, while preserving the
+Python compatibility path as the fallback.
+
 The rest of the 3D-PTV pipeline is already callable from Python without native
 bindings, and the stress suite shows that several later stages also have native
 parity paths available:

src/openptv_python/_native_compat.py

@@ -26,19 +26,31 @@ def _optional_import(module_name: str) -> ModuleType | None:
 
 
 optv_calibration = _optional_import("optv.calibration")
+optv_correspondences = _optional_import("optv.correspondences")
+optv_epipolar = _optional_import("optv.epipolar")
 optv_image_processing = _optional_import("optv.image_processing")
+optv_imgcoord = _optional_import("optv.imgcoord")
+optv_orientation = _optional_import("optv.orientation")
 optv_parameters = _optional_import("optv.parameters")
 optv_segmentation = _optional_import("optv.segmentation")
+optv_tracker = _optional_import("optv.tracker")
 optv_tracking_framebuf = _optional_import("optv.tracking_framebuf")
+optv_transforms = _optional_import("optv.transforms")
 
 HAS_OPTV = any(
     module is not None
     for module in (
         optv_calibration,
+        optv_correspondences,
+        optv_epipolar,
         optv_image_processing,
+        optv_imgcoord,
+        optv_orientation,
         optv_parameters,
         optv_segmentation,
+        optv_tracker,
         optv_tracking_framebuf,
+        optv_transforms,
     )
 )
 
@@ -49,6 +61,38 @@ def _optional_import(module_name: str) -> ModuleType | None:
     and hasattr(optv_parameters, "ControlParams")
 )
 
+HAS_NATIVE_CORRESPONDENCES = (
+    optv_correspondences is not None
+    and hasattr(optv_correspondences, "correspondences")
+    and hasattr(optv_correspondences, "single_cam_correspondence")
+    and hasattr(optv_correspondences, "MatchedCoords")
+)
+
+HAS_NATIVE_ORIENTATION = (
+    optv_orientation is not None
+    and hasattr(optv_orientation, "point_positions")
+    and hasattr(optv_orientation, "multi_cam_point_positions")
+    and hasattr(optv_orientation, "external_calibration")
+    and hasattr(optv_orientation, "full_calibration")
+    and hasattr(optv_orientation, "match_detection_to_ref")
+)
+
+HAS_NATIVE_TRANSFORMS = (
+    optv_transforms is not None
+    and hasattr(optv_transforms, "convert_arr_pixel_to_metric")
+    and hasattr(optv_transforms, "convert_arr_metric_to_pixel")
+)
+
+HAS_NATIVE_IMGCOORD = (
+    optv_imgcoord is not None
+    and hasattr(optv_imgcoord, "image_coordinates")
+    and hasattr(optv_imgcoord, "flat_image_coordinates")
+)
+
+HAS_NATIVE_TRACKER = optv_tracker is not None and hasattr(optv_tracker, "Tracker")
+
+HAS_NATIVE_EPIPOLAR = optv_epipolar is not None and hasattr(optv_epipolar, "epipolar_curve")
+
 HAS_NATIVE_SEGMENTATION = (
     optv_segmentation is not None
     and hasattr(optv_segmentation, "target_recognition")
@@ -224,15 +268,33 @@ def should_use_native(feature_name: str | None = None) -> bool:
     if feature_name in {None, "", "preprocess_image"}:
         return HAS_NATIVE_PREPROCESS
 
+    if feature_name == "correspondences":
+        return HAS_NATIVE_CORRESPONDENCES
+
     if feature_name == "target_recognition":
         return HAS_NATIVE_SEGMENTATION
 
+    if feature_name in {"orientation", "point_positions"}:
+        return HAS_NATIVE_ORIENTATION
+
     if feature_name == "calibration":
         return HAS_NATIVE_CALIBRATION
 
+    if feature_name == "transforms":
+        return HAS_NATIVE_TRANSFORMS
+
+    if feature_name == "imgcoord":
+        return HAS_NATIVE_IMGCOORD
+
     if feature_name == "targets":
         return HAS_NATIVE_TARGETS
 
+    if feature_name == "tracker":
+        return HAS_NATIVE_TRACKER
+
+    if feature_name == "epipolar":
+        return HAS_NATIVE_EPIPOLAR
+
     return HAS_OPTV
 
 

src/openptv_python/_native_convert.py

@@ -16,7 +16,7 @@
     optv_tracking_framebuf,
 )
 from .calibration import Calibration
-from .parameters import ControlPar, TargetPar
+from .parameters import ControlPar, SequencePar, TargetPar, TrackPar, VolumePar
 from .tracking_frame_buf import Target
 
 
@@ -114,6 +114,77 @@ def to_native_control_par(cpar: ControlPar):
     return native
 
 
+def to_native_volume_par(vpar: VolumePar):
+    if not isinstance(vpar, VolumePar):
+        return vpar
+
+    parameters_module = _optv_parameters_module()
+    native = parameters_module.VolumeParams()
+    native.set_X_lay(list(vpar.get_X_lay()))
+    native.set_Zmin_lay(list(vpar.get_Zmin_lay()))
+    native.set_Zmax_lay(list(vpar.get_Zmax_lay()))
+    native.set_cn(vpar.get_cn())
+    native.set_cnx(vpar.get_cnx())
+    native.set_cny(vpar.get_cny())
+    native.set_csumg(vpar.get_csumg())
+    native.set_corrmin(vpar.get_corrmin())
+    native.set_eps0(vpar.get_eps0())
+    return native
+
+
+def to_native_sequence_par(spar: SequencePar):
+    if not isinstance(spar, SequencePar):
+        return spar
+
+    parameters_module = _optv_parameters_module()
+
+    try:
+        native = parameters_module.SequenceParams(num_cams=spar.get_num_cams())
+    except TypeError:
+        native = parameters_module.SequenceParams()
+
+    native.set_first(spar.get_first())
+    native.set_last(spar.get_last())
+
+    img_base_name = spar.get_img_base_name()
+    if isinstance(img_base_name, (list, tuple)):
+        try:
+            native.set_img_base_name(list(img_base_name))
+        except TypeError:
+            for cam_index, base_name in enumerate(img_base_name):
+                native.set_img_base_name(cam_index, base_name)
+
+    return native
+
+
+def to_native_track_par(tpar: TrackPar):
+    if not isinstance(tpar, TrackPar):
+        return tpar
+
+    parameters_module = _optv_parameters_module()
+    native = parameters_module.TrackingParams()
+    for attr_name in (
+        "dvxmin",
+        "dvxmax",
+        "dvymin",
+        "dvymax",
+        "dvzmin",
+        "dvzmax",
+        "dangle",
+        "dacc",
+        "add",
+        "dsumg",
+        "dn",
+        "dnx",
+        "dny",
+    ):
+        getter = getattr(tpar, f"get_{attr_name}", None)
+        setter = getattr(native, f"set_{attr_name}", None)
+        if callable(getter) and callable(setter):
+            setter(getter())
+    return native
+
+
 def to_native_target_par(tpar: TargetPar):
     if not isinstance(tpar, TargetPar):
         return tpar

src/openptv_python/correspondences.py

@@ -13,6 +13,12 @@
     PT_UNUSED,
 )
 from ._native_compat import get_multimedia_par, get_num_cams
+from ._native_compat import HAS_NATIVE_CORRESPONDENCES, optv_correspondences, should_use_native
+from ._native_convert import (
+    to_native_calibration,
+    to_native_control_par,
+    to_native_volume_par,
+)
 from .epi import epi_mm
 from .find_candidate import find_candidate
 from .parameters import ControlPar, VolumePar
@@ -557,6 +563,27 @@ def py_correspondences(
         previous 3).
     """
     num_cams = get_num_cams(cparam)
+
+    if should_use_native("correspondences") and HAS_NATIVE_CORRESPONDENCES and optv_correspondences is not None:
+        native_cals = [to_native_calibration(cal) for cal in calib]
+        native_vparam = to_native_volume_par(vparam)
+        native_cparam = to_native_control_par(cparam)
+
+        if num_cams == 1:
+            return optv_correspondences.single_cam_correspondence(
+                img_pts,
+                flat_coords,
+                native_cals,
+            )
+
+        return optv_correspondences.correspondences(
+            img_pts,
+            flat_coords,
+            native_cals,
+            native_vparam,
+            native_cparam,
+        )
+
     frm = Frame(num_cams, MAX_TARGETS)
 
     # Special case of a single camera, follow the single_cam_correspondence docstring

src/openptv_python/multimed.py

@@ -16,6 +16,26 @@
 from .vec_utils import vec_norm
 
 
+def _mm_nlay(mm: MultimediaPar) -> int:
+    return int(mm.get_nlay()) if hasattr(mm, "get_nlay") else int(mm.nlay)
+
+
+def _mm_n1(mm: MultimediaPar) -> float:
+    return float(mm.get_n1()) if hasattr(mm, "get_n1") else float(mm.n1)
+
+
+def _mm_n2(mm: MultimediaPar) -> list[float]:
+    return list(mm.get_n2()) if hasattr(mm, "get_n2") else list(mm.n2)
+
+
+def _mm_d(mm: MultimediaPar) -> list[float]:
+    return list(mm.get_d()) if hasattr(mm, "get_d") else list(mm.d)
+
+
+def _mm_n3(mm: MultimediaPar) -> float:
+    return float(mm.get_n3()) if hasattr(mm, "get_n3") else float(mm.n3)
+
+
 def multimed_nlay(
     cal: Calibration, mm: MultimediaPar, pos: np.ndarray
 ) -> Tuple[float, float]:
@@ -32,7 +52,7 @@ def multimed_nlay(
 def multimed_r_nlay(cal: Calibration, mm: MultimediaPar, pos: np.ndarray) -> float:
     """Calculate the radial shift for the multimedia model."""
     # 1-medium case
-    if mm.n1 == 1 and mm.nlay == 1 and mm.n2[0] == 1 and mm.n3 == 1:
+    if _mm_n1(mm) == 1 and _mm_nlay(mm) == 1 and _mm_n2(mm)[0] == 1 and _mm_n3(mm) == 1:
         return 1.0
 
     #  interpolation using the existing mmlut
@@ -44,11 +64,11 @@ def multimed_r_nlay(cal: Calibration, mm: MultimediaPar, pos: np.ndarray) -> flo
             return mmf
 
     mmf = fast_multimed_r_nlay(
-        mm.nlay,
-        mm.n1,
-        np.array(mm.n2),
-        mm.n3,
-        np.array(mm.d),
+        _mm_nlay(mm),
+        _mm_n1(mm),
+        np.array(_mm_n2(mm)),
+        _mm_n3(mm),
+        np.array(_mm_d(mm)),
         cal.ext_par.x0,
         cal.ext_par.y0,
         cal.ext_par.z0,
@@ -117,7 +137,7 @@ def trans_cam_point(
     origin = np.r_[ex.x0, ex.y0, ex.z0]  # type: ignore
     pos = pos.astype(np.float64)
 
-    return fast_trans_cam_point(origin, mm.d[0], glass_dir, pos)
+    return fast_trans_cam_point(origin, _mm_d(mm)[0], glass_dir, pos)
 
 
 @njit(fastmath=True, cache=True, nogil=True)
@@ -176,7 +196,7 @@ def back_trans_point(
     -------
         A numpy array representing the position of the point in the camera coordinate system.
     """
-    return fast_back_trans_point(glass, mm.d[0], cross_c, cross_p, pos_t)
+    return fast_back_trans_point(glass, _mm_d(mm)[0], cross_c, cross_p, pos_t)
 
 
 @njit(fastmath=True, cache=True, nogil=True)