ds-msp 0.3.0__py3-none-any.whl

ds_msp/__init__.py

@@ -0,0 +1,47 @@
+from .core.contracts import CameraModel
+from .model import (
+    DoubleSphereCamera,
+    ds_project,
+    ds_unproject,
+    undistort_fisheye,
+    solve_pnp_fisheye,
+)
+from .models import (
+    DoubleSphereModel,
+    EUCMModel,
+    KannalaBrandtModel,
+    OCamModel,
+    RadTanModel,
+    UCMModel,
+)
+from .adapt import convert
+from .ops import Undistorter, solve_pnp
+from .cv import (
+    projectPoints,
+    undistortPoints,
+    distortPoints,
+    initUndistortRectifyMap,
+    undistortImage,
+    estimateNewCameraMatrixForUndistortRectify,
+    solvePnP
+)
+from .ldc import (
+    TI_LDC_MeshGenerator,
+    TI_LDC_PointUndistorter
+)
+
+# Public API (re-exported above). Listing it here documents the surface and tells
+# linters these imports are intentional re-exports, not dead code.
+__all__ = [
+    "CameraModel",
+    "DoubleSphereCamera", "ds_project", "ds_unproject",
+    "undistort_fisheye", "solve_pnp_fisheye",
+    "DoubleSphereModel", "EUCMModel", "KannalaBrandtModel",
+    "OCamModel", "RadTanModel", "UCMModel",
+    "convert", "Undistorter", "solve_pnp",
+    "projectPoints", "undistortPoints", "distortPoints",
+    "initUndistortRectifyMap", "undistortImage",
+    "estimateNewCameraMatrixForUndistortRectify", "solvePnP",
+    "TI_LDC_MeshGenerator", "TI_LDC_PointUndistorter",
+]
+

ds_msp/adapt/__init__.py

@@ -0,0 +1,7 @@
+"""Model conversion ("adapter"): convert calibrated params between models."""
+
+from .convert import convert
+from .evaluate import reprojection_report
+from .sampling import sample_image_grid
+
+__all__ = ["convert", "reprojection_report", "sample_image_grid"]

ds_msp/adapt/convert.py

@@ -0,0 +1,93 @@
+"""
+Camera model conversion ("adapter").
+
+Converts an already-calibrated source model to a target model **without images or
+recalibration**: sample pixels -> unproject with the source -> linear seed the
+target -> refine with Levenberg-Marquardt using each model's **analytic** param
+Jacobian (no autodiff). Mirrors the fisheye-calib-adapter pipeline in pure Python.
+
+Decoupled by dependency injection: ``convert`` takes the source instance and the
+target *class*, so this module imports no concrete model — only the contract and
+SciPy. Works with any model satisfying ``CameraModel``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple, Type
+
+import numpy as np
+from scipy.optimize import least_squares
+
+from ..core.contracts import CameraModel
+from .evaluate import reprojection_report
+from .sampling import sample_image_grid
+
+
+def convert(source: CameraModel, target_cls: Type[CameraModel], *,
+            width: int, height: int, n_samples: int = 500,
+            max_fov_deg: Optional[float] = None,
+            verbose: bool = False) -> Tuple[CameraModel, dict]:
+    """Fit ``target_cls`` parameters to reproduce ``source`` over the image.
+
+    Parameters
+    ----------
+    source : CameraModel
+        The calibrated source model.
+    target_cls : type[CameraModel]
+        The model class to convert into.
+    width, height : int
+        Image size used for sampling and reporting.
+    n_samples : int
+        Approximate number of grid samples used for the fit.
+    max_fov_deg : float, optional
+        Restrict the fitted FOV (full angle). Useful when the target is narrower
+        than the source (e.g. converting a >180 deg fisheye into a pinhole-like
+        model) so the fit is not dragged by unrepresentable rays.
+
+    Returns
+    -------
+    (target, report) : the fitted model and a quality report (see
+    ``reprojection_report``).
+    """
+    # 1. sample pixels -> source bearing rays (forward hemisphere only)
+    pixels = sample_image_grid(width, height, n_samples)
+    rays, valid = source.unproject(pixels)
+    keep = valid & (rays[:, 2] > 1e-6)
+    if max_fov_deg is not None:
+        ang = np.degrees(np.arccos(np.clip(rays[:, 2], -1.0, 1.0)))
+        keep &= ang <= (max_fov_deg / 2.0)
+    rays, pixels = rays[keep], pixels[keep]
+    if len(rays) < len(target_cls.param_names):
+        raise ValueError(
+            f"Too few forward correspondences ({len(rays)}) to fit "
+            f"{target_cls.name}; increase n_samples or max_fov_deg."
+        )
+
+    # 2. linear seed: inherit intrinsics from the source, SVD-seed distortion
+    target = target_cls.from_params(np.zeros(len(target_cls.param_names)))
+    target.initialize_from_correspondences(source.K, rays, pixels)
+
+    # 3. nonlinear refine: minimize project_target(rays) - pixels, analytic Jac.
+    lb, ub = target_cls.param_bounds()
+    x0 = np.clip(target.params, lb, ub)
+
+    def residual(p):
+        uv, _ = target_cls.from_params(p).project(rays)
+        return (uv - pixels).ravel()
+
+    def jac(p):
+        _, _, j_param, _ = target_cls.from_params(p).project_jacobian(rays)
+        return j_param.reshape(-1, p.size)
+
+    res = least_squares(residual, x0, jac=jac, bounds=(lb, ub),
+                        method="trf", x_scale="jac",
+                        verbose=2 if verbose else 0)
+    target = target_cls.from_params(res.x)
+
+    # 4. evaluate over the (possibly FOV-restricted) image region
+    report = reprojection_report(source, target, width, height,
+                                 max_fov_deg=max_fov_deg, gt_params=None)
+    report["converged"] = bool(res.success)
+    report["source_model"] = source.name
+    report["target_model"] = target_cls.name
+    return target, report

ds_msp/adapt/evaluate.py

@@ -0,0 +1,54 @@
+"""
+Conversion quality evaluation (pure numpy + the CameraModel contract).
+
+Reprojection Error (RE) = || project_target(unproject_source(u)) - u ||, plus
+FOV coverage so lossy conversions (e.g. fisheye -> pinhole) are visible, never
+silent.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from .sampling import sample_image_grid
+
+
+def reprojection_report(source, target, width: int, height: int,
+                        n_samples: int = 2000,
+                        max_fov_deg: Optional[float] = None,
+                        gt_params: Optional[np.ndarray] = None) -> dict:
+    """Measure how well ``target`` reproduces ``source`` over the image.
+
+    Returns a dict with rms/max/median pixel error, sample counts, FOV coverage,
+    and (if ``gt_params`` given) parameter error. ``max_fov_deg`` restricts the
+    evaluated region to match a narrower target (e.g. pinhole/RadTan), so the
+    report reflects the region the target is meant to cover rather than being
+    dominated by unrepresentable peripheral rays.
+    """
+    pixels = sample_image_grid(width, height, n_samples)
+    rays, valid = source.unproject(pixels)
+    keep = valid & (rays[:, 2] > 1e-6)
+    if max_fov_deg is not None:
+        ang_all = np.degrees(np.arccos(np.clip(rays[:, 2], -1.0, 1.0)))
+        keep &= ang_all <= (max_fov_deg / 2.0)
+    pixels_k, rays_k = pixels[keep], rays[keep]
+
+    uv, vt = target.project(rays_k)
+    ok = vt
+    err = np.linalg.norm(uv[ok] - pixels_k[ok], axis=1)
+
+    ang = np.degrees(np.arccos(np.clip(rays_k[:, 2], -1.0, 1.0)))
+    report = {
+        "rms_px": float(np.sqrt(np.mean(err ** 2))) if err.size else float("nan"),
+        "max_px": float(err.max()) if err.size else float("nan"),
+        "median_px": float(np.median(err)) if err.size else float("nan"),
+        "n_sampled": int(len(pixels)),
+        "n_forward": int(keep.sum()),
+        "n_target_valid": int(ok.sum()),
+        "fov_covered_deg": float(2.0 * ang.max()) if ang.size else float("nan"),
+    }
+    if gt_params is not None:
+        report["param_error"] = float(np.linalg.norm(np.asarray(gt_params) - target.params))
+    return report

ds_msp/adapt/sampling.py

@@ -0,0 +1,24 @@
+"""
+Sampling strategies for model conversion.
+
+Pure numpy. Produces the pixel/ray correspondences the converter fits against.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def sample_image_grid(width: int, height: int, n_samples: int = 500) -> np.ndarray:
+    """Regular grid of pixel centers, aspect-ratio preserving (FCA-style).
+
+    Returns ``(M, 2)`` float64 pixels with ``M ≈ n_samples``.
+    """
+    nx = max(2, int(round(np.sqrt(n_samples * width / height))))
+    ny = max(2, int(round(np.sqrt(n_samples * height / width))))
+    cw = width / nx
+    ch = height / ny
+    xs = (np.arange(nx) + 0.5) * cw
+    ys = (np.arange(ny) + 0.5) * ch
+    gx, gy = np.meshgrid(xs, ys, indexing="xy")
+    return np.stack([gx.ravel(), gy.ravel()], axis=-1).astype(np.float64)

ds_msp/calib/__init__.py

@@ -0,0 +1,19 @@
+"""Generic calibration (bundle adjustment) for any CameraModel.
+
+``calibrate`` and ``AprilGridTarget`` are dependency-light. ``detect_aprilgrid``
+needs the optional ``aprilgrid`` backend (``pip install ds_msp[calib]``) and is
+imported lazily so this package stays importable without it.
+"""
+
+from .bundle import calibrate
+from .targets import AprilGridTarget
+
+__all__ = ["calibrate", "AprilGridTarget", "detect_aprilgrid"]
+
+
+def __getattr__(name: str):
+    # Lazy: only pull in the OpenCV+aprilgrid detection adapter on demand.
+    if name == "detect_aprilgrid":
+        from .detect import detect_aprilgrid
+        return detect_aprilgrid
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ds_msp/calib/bundle.py

@@ -0,0 +1,147 @@
+"""
+Generic bundle-adjustment calibration for ANY camera model.
+
+Given checkerboard correspondences and an initial model (for intrinsics seed +
+the model type), jointly refines intrinsics and per-image extrinsics by
+Levenberg-Marquardt using the model's **analytic** projection Jacobian (no
+autodiff). Works for DS/UCM/EUCM/KB/RadTan or any ``CameraModel``.
+
+Decoupled: imports only the contract + SciPy/OpenCV; the model type comes from
+the injected ``init_model`` (no concrete-model import).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+import cv2
+import numpy as np
+from scipy.optimize import least_squares
+
+from ..core.contracts import CameraModel
+
+
+def _seed_poses(init_model, X_world_list, keypoints_list, visibility_list):
+    rvecs, tvecs = [], []
+    for Xw, uv, vis in zip(X_world_list, keypoints_list, visibility_list):
+        Xv = Xw[vis].astype(np.float64)
+        uvv = uv[vis].astype(np.float64)
+        rays, vr = init_model.unproject(uvv)
+        use = vr & (rays[:, 2] > 1e-6)
+        if use.sum() >= 4:
+            pn = rays[use, :2] / rays[use, 2:3]
+            ok, rv, tv = cv2.solvePnP(Xv[use], pn, np.eye(3), None)
+            if ok:
+                rvecs.append(rv.ravel())
+                tvecs.append(tv.ravel())
+                continue
+        rvecs.append(np.zeros(3))
+        tvecs.append(np.array([0.0, 0.0, 1.5]))
+    return rvecs, tvecs
+
+
+def calibrate(init_model: CameraModel,
+              X_world_list: List[np.ndarray],
+              keypoints_list: List[np.ndarray],
+              visibility_list: List[np.ndarray],
+              *, max_nfev: int = 200, verbose: int = 0,
+              loss: str = "linear", f_scale: float = 1.0) -> Dict:
+    """Calibrate any model from checkerboard correspondences.
+
+    Parameters
+    ----------
+    loss : str
+        Robust loss for the least-squares solve (SciPy ``least_squares`` kernels):
+        ``"linear"`` (plain L2), ``"huber"``, ``"soft_l1"``, ``"cauchy"``. A robust
+        kernel keeps *every* corner but **down-weights** large residuals instead of
+        letting one mis-localized corner drag the L2 fit — the right tool when a few
+        peripheral corners are mis-detected. Prefer this over hard outlier dropping.
+    f_scale : float
+        Residual scale (px) at which down-weighting kicks in; residuals below it stay
+        ~quadratic. ~1 px is sensible for sub-pixel-targeted corner detection.
+
+    Returns a dict ``{model, poses, rms_px, success}`` where ``poses`` is a list of
+    ``(rvec, tvec)`` per image and ``rms_px`` is the **true** reprojection RMS over
+    valid observations (independent of ``loss``, so it stays comparable across kernels).
+    """
+    cls = type(init_model)
+    P = len(cls.param_names)
+    n_img = len(X_world_list)
+    sizes = [len(X) for X in X_world_list]
+
+    rvecs, tvecs = _seed_poses(init_model, X_world_list, keypoints_list, visibility_list)
+    x0 = np.concatenate([init_model.params]
+                        + [np.concatenate([r, t]) for r, t in zip(rvecs, tvecs)])
+
+    lb_i, ub_i = cls.param_bounds()
+    ext_lb = np.array([-np.pi, -np.pi, -np.pi, -10.0, -10.0, 1e-3])
+    ext_ub = np.array([np.pi, np.pi, np.pi, 10.0, 10.0, 50.0])
+    lb = np.concatenate([lb_i] + [ext_lb] * n_img)
+    ub = np.concatenate([ub_i] + [ext_ub] * n_img)
+    x0 = np.clip(x0, lb, ub)
+
+    def residual(p):
+        m = cls.from_params(p[:P])
+        out = []
+        off = P
+        for Xw, uv, vis in zip(X_world_list, keypoints_list, visibility_list):
+            r, t = p[off:off + 3], p[off + 3:off + 6]
+            off += 6
+            R, _ = cv2.Rodrigues(r)
+            Xc = (R @ Xw.T).T + t
+            uvp, valid = m.project(Xc)
+            diff = np.zeros_like(uv, dtype=np.float64)
+            mask = vis & valid
+            diff[mask] = uvp[mask] - uv[mask]
+            out.append(diff.ravel())
+        return np.concatenate(out)
+
+    def jac(p):
+        m = cls.from_params(p[:P])
+        J = np.zeros((2 * sum(sizes), P + 6 * n_img), dtype=np.float64)
+        row = 0
+        off = P
+        for i, (Xw, uv, vis) in enumerate(zip(X_world_list, keypoints_list, visibility_list)):
+            r = p[off:off + 3]
+            t = p[off + 3:off + 6]
+            off += 6
+            R, jacR = cv2.Rodrigues(r)
+            Xc = (R @ Xw.T).T + t
+            _, J_point, J_param, valid = m.project_jacobian(Xc)
+            mask = (vis & valid)[:, None, None].astype(np.float64)
+            dR = jacR.T.reshape(3, 3, 3)
+            dXc_dr = np.einsum('abc,nb->nac', dR, Xw)
+            J_rvec = np.einsum('nij,njc->nic', J_point, dXc_dr)
+            J_ext = np.concatenate([J_rvec, J_point], axis=-1) * mask
+            J_par = J_param * mask
+            N = sizes[i]
+            J[row:row + 2 * N, 0:P] = J_par.reshape(2 * N, P)
+            ec = P + 6 * i
+            J[row:row + 2 * N, ec:ec + 6] = J_ext.reshape(2 * N, 6)
+            row += 2 * N
+        return J
+
+    res = least_squares(residual, x0, jac=jac, bounds=(lb, ub),
+                        method="trf", x_scale="jac", max_nfev=max_nfev, verbose=verbose,
+                        loss=loss, f_scale=f_scale)
+
+    model = cls.from_params(res.x[:P])
+    poses = [(res.x[P + 6 * i:P + 6 * i + 3], res.x[P + 6 * i + 3:P + 6 * i + 6])
+             for i in range(n_img)]
+
+    # True reprojection RMS over valid observations. Computed directly (not from
+    # res.cost) so it means the same thing under any robust ``loss``: a robust
+    # kernel reshapes the cost, but the pixel error of the fit is what we report.
+    sq, n = 0.0, 0
+    off = P
+    for Xw, uv, vis in zip(X_world_list, keypoints_list, visibility_list):
+        r, t = res.x[off:off + 3], res.x[off + 3:off + 6]
+        off += 6
+        R, _ = cv2.Rodrigues(r)
+        uvp, valid = model.project((R @ Xw.T).T + t)
+        m = vis & valid
+        d = uvp[m] - uv[m]
+        sq += float((d * d).sum())
+        n += int(m.sum())
+    rms = float(np.sqrt(sq / n)) if n else float("nan")
+    return {"model": model, "poses": poses, "rms_px": rms, "success": bool(res.success)}

ds_msp/calib/detect.py

@@ -0,0 +1,99 @@
+"""
+AprilGrid detection adapter — pixels in, tag corners out.
+
+The one place in the library that depends on an AprilTag backend. It wraps the
+pure-Python ``aprilgrid`` detector (``pip install ds_msp[calib]``) and OpenCV for
+image loading + subpixel corner refinement, and hands back per-image
+``{tag_id: (4, 2)}`` dictionaries that ``AprilGridTarget.build_correspondences``
+turns into calibration inputs. Isolating the heavy/optional dependency here keeps
+the rest of ``ds_msp`` installable and importable without it.
+
+**Why a dedicated AprilGrid backend and not OpenCV's aruco or apriltag3?**
+Kalibr-style boards (TUM-VI, EuRoC, …) print each tag with a **2-cell black
+border**; stock AprilTag-3 / aruco assume a **1-cell** border, locate the tag quad
+but then sample the code bits at the wrong places and decode nothing. The
+``aprilgrid`` package defaults to the 2-cell border, which is why it succeeds where
+the others silently return zero detections.
+
+Imports: numpy + OpenCV always; ``aprilgrid`` lazily (only when you detect).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Sequence
+
+import cv2
+import numpy as np
+
+_SUBPIX_CRITERIA = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.01)
+
+
+def _load_gray_u8(path: str) -> np.ndarray:
+    """Load an image as contiguous 8-bit grayscale (TUM-VI ships 16-bit PNGs)."""
+    img = cv2.imread(path, cv2.IMREAD_UNCHANGED)
+    if img is None:
+        raise FileNotFoundError(path)
+    if img.ndim == 3:
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    if img.dtype != np.uint8:
+        img = (img.astype(np.float64) / 256.0).clip(0, 255).astype(np.uint8)
+    return np.ascontiguousarray(img)
+
+
+def _make_detector(family: str):
+    try:
+        from aprilgrid import Detector  # optional dependency
+    except ImportError as exc:  # pragma: no cover - import-guard
+        raise ImportError(
+            "AprilGrid detection needs the 'aprilgrid' package. Install it with:\n"
+            "    pip install ds_msp[calib]      (or: pip install aprilgrid)\n"
+            "It defaults to Kalibr's 2-cell tag border, which AprilTag-3/aruco do not."
+        ) from exc
+    return Detector(family)
+
+
+def detect_aprilgrid(
+    image_paths: Sequence[str], *,
+    family: str = "t36h11", min_tags: int = 6, refine: bool = True,
+    subpix_window: int = 5,
+) -> List[Dict[int, np.ndarray]]:
+    """Detect AprilGrid tags in a list of images.
+
+    Parameters
+    ----------
+    image_paths : sequence of str
+        Paths to the calibration frames.
+    family : str
+        AprilTag family of the board (TUM-VI / Kalibr default is ``"t36h11"``).
+    min_tags : int
+        Skip frames where fewer than this many tags are found (a near-empty frame
+        contributes little and risks outliers).
+    refine : bool
+        Apply ``cv2.cornerSubPix`` to each corner. The raw detector localizes to
+        ~pixel; subpixel refinement is what brings calibration RMS from ~0.6 px to
+        ~0.2 px (Kalibr does the same).
+
+    Returns
+    -------
+    list of dict
+        One ``{tag_id: (4, 2) float64}`` per *kept* frame, corners in the detector's
+        order (bottom-left, bottom-right, top-right, top-left) — matching
+        ``AprilGridTarget.object_points``.
+    """
+    detector = _make_detector(family)
+    w = (subpix_window, subpix_window)
+    out: List[Dict[int, np.ndarray]] = []
+    for path in image_paths:
+        gray = _load_gray_u8(path)
+        dets = detector.detect(gray)
+        if len(dets) < min_tags:
+            continue
+        frame: Dict[int, np.ndarray] = {}
+        for d in dets:
+            corners = np.ascontiguousarray(
+                np.asarray(d.corners, dtype=np.float32).reshape(4, 1, 2))
+            if refine:
+                cv2.cornerSubPix(gray, corners, w, (-1, -1), _SUBPIX_CRITERIA)
+            frame[int(d.tag_id)] = corners.reshape(4, 2).astype(np.float64)
+        out.append(frame)
+    return out

ds_msp/calib/targets.py

@@ -0,0 +1,99 @@
+"""
+Calibration target geometry — the 3D model of the board you photograph.
+
+Pure NumPy, no OpenCV, no detector. An ``AprilGridTarget`` knows where every tag
+corner sits in 3D board coordinates (metres), and turns per-image tag detections
+into the ``(X_world, keypoints, visibility)`` correspondence lists that
+``ds_msp.calib.bundle.calibrate`` consumes. Detection (which needs OpenCV + an
+AprilTag backend) lives separately in ``detect.py``; this module stays dependency
+-light so the board math can be imported and unit-tested on its own.
+
+Imports: numpy only.
+"""
+
+from __future__ import annotations
+
+from typing import List, Mapping, Tuple
+
+import numpy as np
+
+
+class AprilGridTarget:
+    """A Kalibr-style AprilGrid: a ``rows x cols`` grid of AprilTags.
+
+    Geometry follows Kalibr's convention exactly so detections from a board
+    calibrated by Kalibr/Basalt line up:
+
+    - Tag ids run row-major from the bottom-left corner: ``id = row * cols + col``.
+    - Each tag's four corners are ordered **counter-clockwise starting bottom-left**
+      ``(BL, BR, TR, TL)`` — the same order the AprilGrid detector returns them.
+    - Tags are squares of side ``tag_size`` (metres) separated by a gap of
+      ``tag_spacing * tag_size`` (``tag_spacing`` is Kalibr's gap/size ratio).
+
+    ``tag_size`` only sets absolute scale, which affects the recovered *extrinsic*
+    translations, not the intrinsics — so a slightly wrong board size still yields
+    correct ``fx, fy, cx, cy`` and distortion.
+    """
+
+    def __init__(self, tag_rows: int = 6, tag_cols: int = 6,
+                 tag_size: float = 0.088, tag_spacing: float = 0.3) -> None:
+        self.tag_rows = int(tag_rows)
+        self.tag_cols = int(tag_cols)
+        self.tag_size = float(tag_size)
+        self.tag_spacing = float(tag_spacing)
+
+    @property
+    def n_tags(self) -> int:
+        return self.tag_rows * self.tag_cols
+
+    def object_points(self, tag_id: int) -> np.ndarray:
+        """3D board coordinates (metres) of one tag's 4 corners, ``(4, 3)``.
+
+        Order matches the detector: bottom-left, bottom-right, top-right, top-left.
+        """
+        if not 0 <= tag_id < self.n_tags:
+            raise ValueError(f"tag_id {tag_id} out of range [0, {self.n_tags})")
+        row, col = divmod(tag_id, self.tag_cols)
+        pitch = self.tag_size * (1.0 + self.tag_spacing)
+        s = self.tag_size
+        x0, y0 = col * pitch, row * pitch
+        return np.array([[x0,     y0,     0.0],
+                         [x0 + s, y0,     0.0],
+                         [x0 + s, y0 + s, 0.0],
+                         [x0,     y0 + s, 0.0]], dtype=np.float64)
+
+    def all_object_points(self) -> np.ndarray:
+        """Every corner of the board, ``(n_tags * 4, 3)`` in tag-id order."""
+        return np.concatenate([self.object_points(t) for t in range(self.n_tags)])
+
+    def build_correspondences(
+        self, detections_per_image: List[Mapping[int, np.ndarray]],
+        *, min_corners: int = 8,
+    ) -> Tuple[List[np.ndarray], List[np.ndarray], List[np.ndarray]]:
+        """Turn per-image ``{tag_id: (4, 2) pixels}`` into calibration inputs.
+
+        Returns ``(X_world_list, keypoints_list, visibility_list)`` ready for
+        ``ds_msp.calib.bundle.calibrate``. Images with fewer than ``min_corners``
+        detected corners are dropped (too few to constrain a pose).
+        """
+        X_world_list: List[np.ndarray] = []
+        keypoints_list: List[np.ndarray] = []
+        visibility_list: List[np.ndarray] = []
+        for det in detections_per_image:
+            obj, pix = [], []
+            for tag_id, corners in det.items():
+                corners = np.asarray(corners, dtype=np.float64).reshape(-1, 2)
+                if corners.shape[0] != 4:
+                    continue
+                obj.append(self.object_points(int(tag_id)))
+                pix.append(corners)
+            if not obj:
+                continue
+            X = np.concatenate(obj)
+            uv = np.concatenate(pix)
+            if len(X) < min_corners:
+                continue
+            X_world_list.append(X)
+            keypoints_list.append(uv)
+            visibility_list.append(np.ones(len(X), dtype=bool))
+        return X_world_list, keypoints_list, visibility_list

ds_msp/core/__init__.py

@@ -0,0 +1,14 @@
+"""Core contracts and shared primitives (dependency-free foundation layer)."""
+
+from .contracts import (
+    CameraModel,
+    Params,
+    Pixels,
+    Points3D,
+    Rays,
+    Valid,
+)
+from .pinhole import balanced_pinhole_K
+
+__all__ = ["CameraModel", "Points3D", "Pixels", "Rays", "Valid", "Params",
+           "balanced_pinhole_K"]