geopyv-dev 0.1.10__cp313-cp313-win_amd64.whl

geopyv_dev/__init__.py

@@ -0,0 +1,393 @@
+from ._geopyv_dev import *
+import geopyv_dev._geopyv_dev as _core
+
+from .calibration import Calibration, CalibrationParams
+
+from .plots import (
+    inspect_subset,
+    inspect_mesh,
+    inspect_sequence,
+    inspect_particle,
+    inspect_field,
+    convergence_subset,
+    convergence_mesh,
+    convergence_sequence,
+    contour_mesh,
+    contour_sequence,
+    contour_field,
+    history_particle,
+    history_field,
+    trace_particle,
+    trace_field,
+    standard_error_validation,
+    mean_error_validation,
+    noise_standard_error_validation,
+    noise_mean_error_validation,
+    strain_error_validation,
+    spatial_error_validation,
+)
+from .wrappers import (
+    SubsetWrapper,
+    MeshWrapper,
+    ParticleWrapper,
+)
+
+
+
+# ---------------------------------------------------------------------------
+# Auto-wrap helpers
+# ---------------------------------------------------------------------------
+
+def _wrap(raw):
+    if isinstance(raw, _core.Subset):
+        return Subset._new_from_inner(raw)
+    if isinstance(raw, _core.Mesh):
+        return Mesh._new_from_inner(raw)
+    if isinstance(raw, _core.Sequence):
+        return Sequence._new_from_inner(raw)
+    if isinstance(raw, _core.Particle):
+        return Particle._new_from_inner(raw)
+    if isinstance(raw, _core.Field):
+        return Field._new_from_inner(raw)
+    if isinstance(raw, _core.ParticleSolution):
+        return ParticleWrapper(raw)
+    return raw
+
+
+# ---------------------------------------------------------------------------
+# IO — shadow _core.save / _core.load
+# ---------------------------------------------------------------------------
+
+def save(path, obj):
+    """Serialise a solution object to a .pyv file.
+
+    Accepts wrapped or raw MeshSolution / FieldSolution / SequenceSolution.
+    """
+    _core.save(path, getattr(obj, '_inner', obj))
+
+
+def load(path):
+    """Load a .pyv file and return an auto-wrapped solution object."""
+    return _wrap(_core.load(path))
+
+
+# ---------------------------------------------------------------------------
+# Solve-wrapping classes — shadow the PyO3 originals
+# ---------------------------------------------------------------------------
+
+class Subset:
+    """Reference subset for DIC. Wraps PySubset with inspect/convergence."""
+
+    def __init__(self, coord, local_mask, f_img, g_img, subset_order=1):
+        self._inner = _core.Subset(coord, local_mask, f_img, g_img, subset_order=subset_order)
+
+    @classmethod
+    def _new_from_inner(cls, inner):
+        obj = cls.__new__(cls)
+        obj._inner = inner
+        return obj
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __repr__(self):
+        return repr(self._inner)
+
+    def solve(self, p_0=None, algorithm="icgn",
+              max_norm=1e-3, max_iterations=50, tolerance=0.75):
+        """Run the DIC solver. Mutates the object; returns None.
+
+        Parameters
+        ----------
+        p_0 : list[float], optional
+            Initial warp vector. Defaults to zeros matching order.
+        algorithm : str, optional
+            "icgn" (default) or "fagn".
+        max_norm : float, optional
+            Convergence norm threshold. Default 1e-3.
+        max_iterations : int, optional
+            Iteration limit. Default 50.
+        tolerance : float, optional
+            Minimum acceptable C_ZNCC for solved=True. Default 0.75.
+        """
+        import warnings
+        algo = algorithm.lower()
+        kwargs = dict(p_0=p_0, max_norm=max_norm,
+                      max_iterations=max_iterations, tolerance=tolerance)
+        if algo == "icgn":
+            self._inner.solve_icgn(**kwargs)
+        elif algo == "fagn":
+            self._inner.solve_fagn(**kwargs)
+        else:
+            warnings.warn(
+                f"Unknown algorithm '{algo}'; falling back to 'icgn'.",
+                UserWarning,
+                stacklevel=2,
+            )
+            self._inner.solve_icgn(**kwargs)
+
+    def save(self, path):
+        """Save the solved subset to a .pyv file."""
+        self._inner.save(path)
+
+    def inspect(self, **kwargs):
+        return inspect_subset(self._inner, **kwargs)
+
+    def convergence(self, **kwargs):
+        return convergence_subset(self._inner, **kwargs)
+
+
+class Mesh:
+    """DIC mesh. solve() mutates in place and returns None."""
+
+    def __init__(self, boundary, target_nodes, f_img, g_img,
+                 size=(1, 1000), exclusions=None, exclusions_hard=None, mesh_order=2):
+        self._inner = _core.Mesh(
+            boundary, target_nodes, f_img, g_img,
+            size=size, exclusions=exclusions, exclusions_hard=exclusions_hard,
+            mesh_order=mesh_order,
+        )
+
+    @classmethod
+    def _new_from_inner(cls, inner):
+        obj = cls.__new__(cls)
+        obj._inner = inner
+        return obj
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __repr__(self):
+        return repr(self._inner)
+
+    def solve(self, local_mask, seed_coord, seed_warp=None, **kwargs):
+        """Run the DIC solver. Mutates in place; returns None."""
+        self._inner.solve(local_mask, seed_coord, seed_warp=seed_warp, **kwargs)
+
+    def save(self, path):
+        """Save the solved mesh to a .pyv file."""
+        self._inner.save(path)
+
+    def inspect(self, **kwargs):
+        return inspect_mesh(self._inner, **kwargs)
+
+    def convergence(self, quantity="C_ZNCC", **kwargs):
+        return convergence_mesh(self._inner, quantity, **kwargs)
+
+    def contour(self, quantity, **kwargs):
+        return contour_mesh(self._inner, quantity, **kwargs)
+
+
+class Sequence:
+    """Multi-pair DIC sequence. solve() mutates in place and returns None."""
+
+    def __init__(self, image_dir, boundary, target_nodes,
+                 size=(1.0, 1000.0), exclusions=None, mesh_order=2):
+        self._inner = _core.Sequence(
+            image_dir, boundary, target_nodes,
+            size=size, exclusions=exclusions, mesh_order=mesh_order,
+        )
+
+    @classmethod
+    def _new_from_inner(cls, inner):
+        obj = cls.__new__(cls)
+        obj._inner = inner
+        return obj
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __repr__(self):
+        return repr(self._inner)
+
+    def solve(self, *args, **kwargs):
+        self._inner.solve(*args, **kwargs)
+
+    @property
+    def mesh_solutions(self):
+        return [MeshWrapper(m) for m in self._inner.mesh_solutions]
+
+    @property
+    def meshes(self):
+        return self.mesh_solutions
+
+    @property
+    def solved(self):
+        return self._inner.solved
+
+    @property
+    def unsolvable(self):
+        return self._inner.unsolvable
+
+    @property
+    def override_log(self):
+        return self._inner.override_log
+
+    @property
+    def reference_updates(self):
+        return self._inner.reference_updates
+
+    @property
+    def mesh_paths(self):
+        return self._inner.mesh_paths
+
+    def mesh_solution_at(self, idx):
+        return MeshWrapper(self._inner.mesh_solution_at(idx))
+
+    def all_c_zncc(self):
+        return self._inner.all_c_zncc()
+
+    def inspect(self, mesh_idx, subset_idx=None, **kwargs):
+        return inspect_sequence(self, mesh_idx=mesh_idx, subset_idx=subset_idx, **kwargs)
+
+    def convergence(self, mesh_idx=None, quantity="C_ZNCC", **kwargs):
+        return convergence_sequence(self, mesh_idx=mesh_idx, quantity=quantity, **kwargs)
+
+    def contour(self, quantity, mesh_idx, **kwargs):
+        return contour_sequence(self, mesh_idx=mesh_idx, quantity=quantity, **kwargs)
+
+    def save(self, path):
+        _core.save(path, self._inner)
+
+
+class Field:
+    """Particle field built from a solved Sequence. solve() mutates in place and returns None."""
+
+    def __init__(self, sequence_solution, track=True, depth=1.0,
+                 coordinates=None, volumes=None):
+        raw = getattr(sequence_solution, '_inner', sequence_solution)
+        self._inner = _core.Field(raw, track=track, depth=depth,
+                                  coordinates=coordinates, volumes=volumes)
+
+    @classmethod
+    def _new_from_inner(cls, inner):
+        obj = cls.__new__(cls)
+        obj._inner = inner
+        return obj
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __repr__(self):
+        return repr(self._inner)
+
+    def solve(self, factor=0.0, true_incs=True, calibration=None):
+        cal = getattr(calibration, '_inner', calibration)
+        self._inner.solve(factor=factor, true_incs=true_incs, calibration=cal)
+
+    @property
+    def particles(self):
+        return [ParticleWrapper(p) for p in self._inner.particles]
+
+    def inspect(self, **kwargs):
+        return inspect_field(self, **kwargs)
+
+    def contour(self, quantity, **kwargs):
+        return contour_field(self, quantity, **kwargs)
+
+    def history(self, particle_index, quantity="warps", **kwargs):
+        return history_field(self, particle_index, quantity, **kwargs)
+
+    def trace(self, quantity="warps", component=0, **kwargs):
+        return trace_field(self, quantity, component, **kwargs)
+
+    def save(self, path):
+        _core.save(path, self._inner)
+
+
+class Particle:
+    """Lagrangian/Eulerian particle. solve() mutates in place and returns None."""
+
+    def __init__(self, source, coordinate, initial_warp=None, track=True):
+        raw = getattr(source, '_inner', source)
+        self._inner = _core.Particle(raw, coordinate, initial_warp=initial_warp, track=track)
+
+    @classmethod
+    def _new_from_inner(cls, inner):
+        obj = cls.__new__(cls)
+        obj._inner = inner
+        return obj
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __repr__(self):
+        return repr(self._inner)
+
+    def solve(self, factor=0.0, true_incs=True, calibration=None):
+        cal = getattr(calibration, '_inner', calibration)
+        self._inner.solve(factor=factor, true_incs=true_incs, calibration=cal)
+
+    def solve_increment(self, m):
+        return self._inner.solve_increment(m)
+
+    def inspect(self, **kwargs):
+        return inspect_particle(self._inner, **kwargs)
+
+    def history(self, quantity="warps", **kwargs):
+        return history_particle(self._inner, quantity, **kwargs)
+
+    def trace(self, quantity="warps", component=0, **kwargs):
+        return trace_particle(self._inner, quantity, component, **kwargs)
+
+    def save(self, path):
+        _core.save(path, self._inner)
+
+
+class Validation:
+    """Validation of DIC results against ground-truth Speckle warps."""
+
+    def __init__(self, speckle, fields, labels):
+        raw_speckle = getattr(speckle, '_inner', speckle)
+        raw_fields  = [getattr(f, '_inner', f) for f in fields]
+        self._inner = _core.Validation(raw_speckle, raw_fields, labels)
+        self._solution = None
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def solve(self, cumulative=True, skim=None):
+        self._solution = self._inner.solve(cumulative=cumulative, skim=skim)
+
+    def standard_error(self, component, **kwargs):
+        self._check_solved()
+        return standard_error_validation(self._solution, component, **kwargs)
+
+    def mean_error(self, component, **kwargs):
+        self._check_solved()
+        return mean_error_validation(self._solution, component, **kwargs)
+
+    def noise_standard_error(self, component, **kwargs):
+        self._check_solved()
+        return noise_standard_error_validation(self._solution, component, **kwargs)
+
+    def noise_mean_error(self, component, **kwargs):
+        self._check_solved()
+        return noise_mean_error_validation(self._solution, component, **kwargs)
+
+    def strain_error(self, **kwargs):
+        self._check_solved()
+        return strain_error_validation(self._solution, **kwargs)
+
+    def spatial_error(self, field_index, time_index, **kwargs):
+        self._check_solved()
+        return spatial_error_validation(self._solution, field_index, time_index, **kwargs)
+
+    @property
+    def solution(self):
+        self._check_solved()
+        return self._solution
+
+    def n_frames(self, field_index=0):
+        self._check_solved()
+        import numpy as np
+        return np.asarray(self._solution.fields[field_index].applied).shape[0]
+
+    def n_particles(self, field_index=0):
+        self._check_solved()
+        import numpy as np
+        return np.asarray(self._solution.fields[field_index].applied).shape[1]
+
+    def _check_solved(self):
+        if self._solution is None:
+            raise RuntimeError("call solve() first")

geopyv_dev/calibration.py

@@ -0,0 +1,273 @@
+import logging
+import re
+import glob
+
+import numpy as np
+
+import geopyv_dev._geopyv_dev as _core
+
+log = logging.getLogger(__name__)
+
+
+class CalibrationParams:
+    """Thin Python wrapper around the Rust CalibrationParams.
+
+    Parameters
+    ----------
+    intmat : array-like (3, 3)
+        Camera intrinsic matrix.
+    extmat : array-like (4, 4)
+        Extrinsic matrix for the chosen object plane.
+    dist : array-like (5,)
+        Distortion coefficients [k1, k2, p1, p2, k3].
+    """
+
+    def __init__(self, intmat, extmat, dist):
+        self._inner = _core.CalibrationParams(
+            np.asarray(intmat, dtype=np.float64),
+            np.asarray(extmat, dtype=np.float64),
+            np.asarray(dist, dtype=np.float64),
+        )
+
+    def o2i(self, objpnts):
+        return self._inner.o2i(np.asarray(objpnts, dtype=np.float64))
+
+    def i2o(self, imgpnts):
+        return self._inner.i2o(np.asarray(imgpnts, dtype=np.float64))
+
+    @property
+    def intmat(self):
+        return self._inner.intmat
+
+    @property
+    def extmat(self):
+        return self._inner.extmat
+
+    @property
+    def dist(self):
+        return self._inner.dist
+
+    def __repr__(self):
+        return repr(self._inner)
+
+
+class Calibration:
+    """Camera calibration using a ChArUco board and OpenCV.
+
+    Parameters
+    ----------
+    calibration_dir : str
+        Directory containing calibration images.
+    common_name : str, optional
+        Filename prefix for the calibration images.
+    file_format : str, optional
+        Image extension (default '.jpg').
+    dictionary : cv2.aruco.Dictionary, optional
+        ArUco dictionary to use.
+    board_parameters : tuple (columns, rows, square_length, marker_length)
+        ChArUco board specification.
+    show : bool, optional
+        Display the board pattern at initialisation.
+    """
+
+    def __init__(
+        self,
+        *,
+        calibration_dir=".",
+        common_name="",
+        file_format=".jpg",
+        dictionary=None,
+        board_parameters=None,
+        show=False,
+    ):
+        try:
+            import cv2
+            from cv2 import aruco
+        except ImportError as exc:
+            raise ImportError("opencv-python is required for Calibration") from exc
+
+        if not calibration_dir.endswith("/"):
+            calibration_dir += "/"
+        if not file_format.startswith("."):
+            file_format = "." + file_format
+
+        self._calibration_dir = calibration_dir
+        self._common_name = common_name
+        self._file_format = file_format
+        self._dictionary = (
+            dictionary
+            if dictionary is not None
+            else aruco.getPredefinedDictionary(cv2.aruco.DICT_5X5_1000)
+        )
+        self.solved = False
+        self.params = None
+
+        columns, rows, square_length, marker_length = board_parameters
+        self._board = aruco.CharucoBoard(
+            (columns, rows), square_length, marker_length, self._dictionary
+        )
+        self._objpnts = self._board.getChessboardCorners()
+
+        if show:
+            import matplotlib.pyplot as plt
+            imboard = self._board.generateImage((290, 180))
+            fig, ax = plt.subplots()
+            ax.imshow(imboard, interpolation="nearest")
+            ax.axis("off")
+            plt.show()
+
+        pattern = calibration_dir + common_name + "*" + file_format
+        self._calibration_images = sorted(glob.glob(pattern))
+        if not self._calibration_images:
+            raise FileNotFoundError(f"No images found matching {pattern!r}")
+        if len(self._calibration_images) < 10:
+            log.warning(
+                "%d images found; at least 10 are recommended.",
+                len(self._calibration_images),
+            )
+
+        img0 = cv2.imread(self._calibration_images[0])
+        self._image_size = img0.shape[:2]
+
+    def solve(self, *, ext_id=None, binary_threshold=None, acceptance_threshold=50):
+        """Run the ArUco/ChArUco calibration pipeline.
+
+        Parameters
+        ----------
+        ext_id : int, optional
+            Numeric suffix of the calibration image to use as the object plane.
+            Defaults to the last accepted image.
+        binary_threshold : float, optional
+            Pixel threshold for binarisation before corner detection.
+        acceptance_threshold : int, optional
+            Minimum ChArUco corners for a frame to be accepted (default 50).
+        """
+        try:
+            import cv2
+        except ImportError as exc:
+            raise ImportError("opencv-python is required for Calibration.solve") from exc
+
+        self._binary_threshold = binary_threshold
+        self._ext_id = ext_id
+
+        allCorners, allIds, imsize = self._read_chessboards(acceptance_threshold)
+        if not allCorners:
+            raise RuntimeError("Calibration failed: no usable frames detected.")
+
+        self._calibrate_camera(allCorners, allIds, imsize)
+        self._extrinsic_matrix_generator()
+        self.solved = True
+
+        self._dist = self._dist.flatten()
+        self.params = CalibrationParams(self._intmat, self._extmat, self._dist)
+
+    def _read_chessboards(self, acceptance_threshold):
+        import cv2
+
+        criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 100, 1e-5)
+        allCorners, allIds, accepted = [], [], []
+
+        for path in self._calibration_images:
+            frame = cv2.imread(path)
+            gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+            gray = cv2.GaussianBlur(gray, (5, 5), 0)
+
+            if self._binary_threshold is not None:
+                _, src = cv2.threshold(gray, self._binary_threshold, 255, cv2.THRESH_BINARY)
+            else:
+                src = gray
+
+            arcnrs, arids, _ = cv2.aruco.detectMarkers(
+                src, self._dictionary, parameters=cv2.aruco.DetectorParameters()
+            )
+            if not arcnrs:
+                continue
+            for c in arcnrs:
+                cv2.cornerSubPix(gray, c, (3, 3), (-1, -1), criteria)
+            ret, chcnrs, chids = cv2.aruco.interpolateCornersCharuco(
+                arcnrs, arids, gray, self._board
+            )
+            if chcnrs is not None and chids is not None and len(chcnrs) > acceptance_threshold:
+                allCorners.append(chcnrs)
+                allIds.append(chids)
+                accepted.append(path)
+
+        self._accepted_images = accepted
+        # Determine extrinsic image index
+        if self._ext_id is not None:
+            indices = [int(re.findall(r"\d+", p)[-1]) for p in accepted]
+            try:
+                self._index = indices.index(self._ext_id)
+            except ValueError:
+                log.warning("ext_id %s not found in accepted images; using last.", self._ext_id)
+                self._index = len(accepted) - 1
+        else:
+            self._index = len(accepted) - 1
+
+        imsize = cv2.imread(accepted[0], cv2.IMREAD_GRAYSCALE).shape if accepted else (0, 0)
+        return allCorners, allIds, imsize
+
+    def _calibrate_camera(self, allCorners, allIds, imsize):
+        import cv2
+
+        h, w = imsize
+        cam_init = np.array([[1000., 0., w / 2.], [0., 1000., h / 2.], [0., 0., 1.]])
+        dist_init = np.zeros((5, 1))
+        _, self._intmat, self._dist, self._rot, self._trans = (
+            cv2.aruco.calibrateCameraCharuco(
+                charucoCorners=allCorners,
+                charucoIds=allIds,
+                board=self._board,
+                imageSize=(w, h),
+                cameraMatrix=cam_init,
+                distCoeffs=dist_init,
+            )
+        )
+        self._rot = np.asarray(self._rot)
+        self._trans = np.asarray(self._trans)
+
+    def _extrinsic_matrix_generator(self):
+        import cv2
+
+        n = len(self._rot)
+        extmats = np.zeros((n, 4, 4))
+        extmats[:, 3, 3] = 1.0
+        extmats[:, :3, 3] = self._trans[:, :3].reshape(-1, 3)
+        for i in range(n):
+            extmats[i, :3, :3], _ = cv2.Rodrigues(self._rot[i])
+        self._extmats = extmats
+        self._extmat = extmats[self._index]
+
+    def calibrate(self, obj, override=False):
+        """Calibrate a Region in-place by mapping its nodes to object space.
+
+        Parameters
+        ----------
+        obj : CircleRegion or PathRegion
+            The region to calibrate.
+        override : bool, optional
+            Re-calibrate even if already marked calibrated.
+        """
+        if not self.solved or self.params is None:
+            raise RuntimeError("Call solve() before calibrate().")
+
+        region_types = (_core.CircleRegion, _core.PathRegion)
+        if not isinstance(obj, region_types):
+            raise TypeError(
+                f"calibrate() only supports CircleRegion / PathRegion; got {type(obj).__name__}"
+            )
+
+        if obj.calibrated and not override:
+            return
+
+        obj.current_nodes = self.params.i2o(obj.current_nodes)
+        obj.history_nodes = [self.params.i2o(n) for n in obj.history_nodes]
+
+        c = self.params.i2o(np.array([obj.current_centre]))
+        obj.current_centre = tuple(c[0].tolist())
+
+        obj.history_centres = [
+            tuple(self.params.i2o(np.array([ctr]))[0].tolist())
+            for ctr in obj.history_centres
+        ]
+        obj.calibrated = True