placeframe-core 0.1.0.dev35547537192__py3-none-any.whl

placeframe_core/axis_convention.py

@@ -0,0 +1,48 @@
+from enum import Enum
+
+from numpy import array, float64
+from numpy.typing import NDArray  # noqa: TID251 — tracked in PLE-233
+from scipy.spatial.transform import Rotation
+
+
+class AxisConvention(Enum):
+    OPENCV = "OPENCV"
+    UNITY = "UNITY"
+
+
+basis_unity = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+basis_opencv = array([[1, 0, 0], [0, -1, 0], [0, 0, 1]])
+basic_change_unity_from_opencv = basis_unity.T @ basis_opencv
+basis_change_opencv_from_unity = basic_change_unity_from_opencv.T
+
+
+def change_basis_opencv_from_unity_pose(
+    translation: NDArray[float64], rotation: NDArray[float64]
+) -> tuple[NDArray[float64], NDArray[float64]]:
+    new_translation = basis_change_opencv_from_unity @ translation
+    new_rotation = basis_change_opencv_from_unity @ rotation @ basic_change_unity_from_opencv
+    return new_translation, new_rotation
+
+
+def change_basis_unity_from_opencv_pose(
+    translation: NDArray[float64], rotation: NDArray[float64]
+) -> tuple[NDArray[float64], NDArray[float64]]:
+    new_translation = basic_change_unity_from_opencv @ translation
+    new_rotation = basic_change_unity_from_opencv @ rotation @ basis_change_opencv_from_unity
+    return new_translation, new_rotation
+
+
+def change_basis_unity_from_opencv_points(points: NDArray[float64]) -> NDArray[float64]:
+    return (basic_change_unity_from_opencv @ points.T).T
+
+
+def change_basis_unity_from_opencv_poses(
+    translations: NDArray[float64], orientations_xyzw: NDArray[float64]
+) -> tuple[NDArray[float64], NDArray[float64]]:
+    new_translations = change_basis_unity_from_opencv_points(translations)
+
+    rotation_matrices = Rotation.from_quat(orientations_xyzw).as_matrix()
+    new_rotation_matrices = basic_change_unity_from_opencv @ rotation_matrices @ basis_change_opencv_from_unity
+    new_orientations_xyzw = Rotation.from_matrix(new_rotation_matrices).as_quat()
+
+    return new_translations, new_orientations_xyzw

placeframe_core/calibration.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import math
+import sys
+from pathlib import Path
+
+from numpy import interp, log1p
+from pydantic import BaseModel
+
+
+SCHEMA_VERSION = 2
+
+# Sentinel `pipeline_version` value that bypasses the pipeline-version check in
+# `load_global_calibration`. Use only with placeholder calibrations whose values
+# don't depend on the inference pipeline (zeroed weights, fixed sigma_meas
+# constants). A real calibration fit against a real corpus must pin to the
+# localizer image's CONTEXT_SHA so any pipeline change forces a paired refit.
+PLACEHOLDER_PIPELINE_VERSION = "placeholder"
+
+
+class CalibrationLoadError(RuntimeError):
+    pass
+
+
+class RawLocalizationMetrics(BaseModel):
+    num_inliers: int
+    inlier_ratio: float
+    reproj_error_median: float
+    inlier_coverage: float
+    num_matches: int
+    query_image_diagonal_px: float
+
+
+class RawMapMetrics(BaseModel):
+    map_image_count: int
+    map_point_count: int
+    map_avg_track_length: float
+    map_viewpoint_diversity: float
+
+
+class Features(BaseModel):
+    log_inliers: float
+    inlier_ratio: float
+    reproj_err_norm: float
+    inlier_coverage: float
+    log_num_matches: float
+    log_map_image_count: float
+    log_map_point_count: float
+    map_avg_track_length: float
+    map_viewpoint_diversity: float
+
+    @classmethod
+    def zeros(cls) -> Features:
+        return cls(**dict.fromkeys(cls.model_fields, 0.0))
+
+    @classmethod
+    def compute(cls, *, localization: RawLocalizationMetrics, map_metrics: RawMapMetrics) -> Features:
+        return cls(
+            log_inliers=float(log1p(localization.num_inliers)),
+            inlier_ratio=localization.inlier_ratio,
+            reproj_err_norm=localization.reproj_error_median / localization.query_image_diagonal_px,
+            inlier_coverage=localization.inlier_coverage,
+            log_num_matches=float(log1p(localization.num_matches)),
+            log_map_image_count=float(log1p(map_metrics.map_image_count)),
+            log_map_point_count=float(log1p(map_metrics.map_point_count)),
+            map_avg_track_length=map_metrics.map_avg_track_length,
+            map_viewpoint_diversity=map_metrics.map_viewpoint_diversity,
+        )
+
+
+class ToleranceModel(BaseModel):
+    logistic_weights: Features
+    logistic_intercept: float
+    isotonic_x_breakpoints: list[float]
+    isotonic_y_breakpoints: list[float]
+
+
+class CalibrationArtifact(BaseModel):
+    schema_version: int
+    pipeline_version: str
+    fit_at: str
+    fit_by: str
+    sample_count: int
+    tight: ToleranceModel
+    loose: ToleranceModel
+    sigma_meas_alpha: float
+    sigma_meas_beta: float
+    loose_min: float
+    tight_min: float
+
+    def write(self, path: Path) -> None:
+        path.write_text(self.model_dump_json(indent=2) + "\n", encoding="utf-8")
+
+    @classmethod
+    def read(cls, path: Path) -> CalibrationArtifact:
+        return cls.model_validate_json(path.read_text(encoding="utf-8"))
+
+
+def load_global_calibration(path: Path, expected_pipeline_version: str) -> CalibrationArtifact:
+    if not path.exists():
+        raise CalibrationLoadError(
+            f"Global calibration not found at {path}. "
+            f"Expected pipeline version: {expected_pipeline_version}. "
+            f"Run scripts/fit_calibration.py against this pipeline and commit "
+            f"the resulting docker/localizer/calibration/global.json."
+        )
+
+    calibration = CalibrationArtifact.read(path)
+
+    if calibration.schema_version != SCHEMA_VERSION:
+        raise CalibrationLoadError(
+            f"Unsupported calibration schema_version {calibration.schema_version} "
+            f"in {path}. Localizer expects schema_version {SCHEMA_VERSION}."
+        )
+
+    if calibration.pipeline_version == PLACEHOLDER_PIPELINE_VERSION:
+        print(
+            f"WARNING: loading placeholder calibration from {path}. "
+            f"Pipeline-version check bypassed (expected {expected_pipeline_version}). "
+            "Tight/loose confidence gates are no-ops; outputs are not trustworthy. "
+            "Refit via scripts/fit_calibration.py before relying on calibrated confidences.",
+            file=sys.stderr,
+            flush=True,
+        )
+        return calibration
+
+    if calibration.pipeline_version != expected_pipeline_version:
+        raise CalibrationLoadError(
+            "Global calibration pipeline-version mismatch.\n"
+            f"  Calibration file: {path}\n"
+            f"  File version:     {calibration.pipeline_version}\n"
+            f"  Expected version: {expected_pipeline_version}\n"
+            "Refit calibration against the new pipeline "
+            "(scripts/fit_calibration.py), commit the updated artifact, "
+            "and redeploy."
+        )
+
+    return calibration
+
+
+def _sigmoid(x: float) -> float:
+    return 1.0 / (1.0 + math.exp(-x))
+
+
+def _apply_tolerance(model: ToleranceModel, features: Features) -> float:
+    weights = model.logistic_weights.model_dump()
+    feature_values = features.model_dump()
+    logit = model.logistic_intercept + sum(weights[name] * feature_values[name] for name in feature_values)
+    raw = _sigmoid(logit)
+    if not model.isotonic_x_breakpoints:
+        return raw
+    return float(interp(raw, model.isotonic_x_breakpoints, model.isotonic_y_breakpoints))
+
+
+def apply_global_calibration(calibration: CalibrationArtifact, features: Features) -> tuple[float, float, bool]:
+    tight = _apply_tolerance(calibration.tight, features)
+    loose = _apply_tolerance(calibration.loose, features)
+    return tight, loose, True

placeframe_core/camera_config.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+# See "Orientation" property here: https://exiv2.org/tags-xmp-tiff.html
+ImageOrientation = Literal[
+    "TOP_LEFT", "TOP_RIGHT", "BOTTOM_RIGHT", "BOTTOM_LEFT", "LEFT_TOP", "RIGHT_TOP", "RIGHT_BOTTOM", "LEFT_BOTTOM"
+]
+
+
+class PinholeCameraConfig(BaseModel):
+    width: int
+    height: int
+    orientation: ImageOrientation
+    fx: float
+    fy: float
+    cx: float
+    cy: float

placeframe_core/capture_session_manifest.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .axis_convention import AxisConvention
+from .camera_config import PinholeCameraConfig
+from .transform import Float3, Float4
+
+
+class RigCameraConfig(BaseModel):
+    id: str
+    ref_sensor: bool
+    rotation: Float4
+    translation: Float3
+    camera_config: PinholeCameraConfig
+
+
+class RigConfig(BaseModel):
+    id: str
+    cameras: list[RigCameraConfig]
+
+
+class CaptureSessionManifest(BaseModel):
+    axis_convention: AxisConvention
+    rigs: list[RigConfig]
+    capture_interval_seconds: float | None = None

placeframe_core/h5.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+from typing import Any, Iterable, Mapping, cast
+
+from h5py import Dataset, File, Group
+from numpy import asarray, float32, uint8
+from numpy.typing import NDArray  # noqa: TID251 — tracked in PLE-233
+
+GLOBAL_DESCRIPTORS_DATASET_NAME = "global_descriptor"
+KEYPOINTS_DATASET_NAME = "keypoints"
+PQ_CODES_DATASET_NAME = "pq_codes"
+GLOBAL_DESCRIPTORS_FILE = "global_descriptors.h5"
+FEATURES_FILE = "features.h5"
+
+
+def write_global_descriptors(root_path: Path, global_descriptors: Mapping[str, NDArray[float32]]):
+    path = root_path / GLOBAL_DESCRIPTORS_FILE
+    with File(str(path), "w") as file:
+        for name, global_descriptor in global_descriptors.items():
+            group = file.create_group(name)
+            _create_dataset(group, GLOBAL_DESCRIPTORS_DATASET_NAME, global_descriptor)
+
+    return GLOBAL_DESCRIPTORS_FILE, path.read_bytes()
+
+
+def write_features(root_path: Path, keypoints: Mapping[str, NDArray[float32]], pq_codes: Mapping[str, NDArray[uint8]]):
+    path = root_path / FEATURES_FILE
+    with File(str(path), "w") as file:
+        for name, image_keypoints in keypoints.items():
+            group = file.create_group(name)
+            _create_dataset(group, KEYPOINTS_DATASET_NAME, image_keypoints)
+            _create_dataset(group, PQ_CODES_DATASET_NAME, pq_codes[name])
+
+    return FEATURES_FILE, path.read_bytes()
+
+
+def _create_dataset(group: Group, name: str, data: Any):
+    group.create_dataset(name, data=data, compression="gzip", compression_opts=9, shuffle=True, chunks=True)
+
+
+def read_global_descriptors(root_path: Path, image_names: Iterable[str]) -> dict[str, NDArray[float32]]:
+    result: dict[str, NDArray[float32]] = {}
+    with File(str(root_path / GLOBAL_DESCRIPTORS_FILE), "r") as file:
+        for name in image_names:
+            group = cast(Group, file[name])
+            result[name] = asarray(cast(Dataset, group[GLOBAL_DESCRIPTORS_DATASET_NAME])[()], dtype=float32)
+
+    return result
+
+
+def read_features(
+    root_path: Path, image_names: Iterable[str]
+) -> tuple[dict[str, NDArray[float32]], dict[str, NDArray[uint8]]]:
+    keypoints_by_name: dict[str, NDArray[float32]] = {}
+    pq_codes_by_name: dict[str, NDArray[uint8]] = {}
+
+    with File(str(root_path / FEATURES_FILE), "r") as file:
+        for name in image_names:
+            group = cast(Group, file[name])
+            keypoints_by_name[name] = asarray(cast(Dataset, group[KEYPOINTS_DATASET_NAME])[()], dtype=float32)
+            pq_codes_by_name[name] = asarray(cast(Dataset, group[PQ_CODES_DATASET_NAME])[()], dtype=uint8)
+
+    return keypoints_by_name, pq_codes_by_name

placeframe_core/image_preprocess.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from io import BytesIO
+
+from PIL import Image as PILImage
+from PIL.Image import Resampling, Transpose
+
+from .camera_config import ImageOrientation, PinholeCameraConfig
+
+# Standardizes per-pixel scale across cameras with different resolutions, so the feature extractor's
+# fixed-pixel receptive field sees comparable structure regardless of source camera.
+LOCAL_FEATURE_RESIZE_SHORTER_SIDE = 1024
+
+
+def canonicalize_image(image_buffer: bytes, orientation: ImageOrientation) -> PILImage.Image:
+    image = PILImage.open(BytesIO(image_buffer))
+    image = _orient(image, orientation)
+    new_width, new_height = _resized_dimensions(image.width, image.height)
+    if (new_width, new_height) != (image.width, image.height):
+        image = image.resize((new_width, new_height), Resampling.LANCZOS)
+    return image.convert("RGB")
+
+
+def canonicalize_intrinsics(camera: PinholeCameraConfig):
+    width, height, fx, fy, cx, cy = _oriented_intrinsics(camera)
+    new_width, new_height = _resized_dimensions(width, height)
+    scale_x = new_width / width
+    scale_y = new_height / height
+    return new_width, new_height, fx * scale_x, fy * scale_y, cx * scale_x, cy * scale_y
+
+
+def _resized_dimensions(width: int, height: int) -> tuple[int, int]:
+    scale = LOCAL_FEATURE_RESIZE_SHORTER_SIDE / min(width, height)
+    return round(width * scale), round(height * scale)
+
+
+def _orient(image: PILImage.Image, orientation: ImageOrientation) -> PILImage.Image:
+    match orientation:
+        case "TOP_LEFT":
+            return image
+        case "TOP_RIGHT":
+            return image.transpose(Transpose.FLIP_LEFT_RIGHT)
+        case "BOTTOM_RIGHT":
+            return image.transpose(Transpose.ROTATE_180)
+        case "BOTTOM_LEFT":
+            return image.transpose(Transpose.FLIP_TOP_BOTTOM)
+        case "LEFT_TOP":
+            return image.transpose(Transpose.TRANSPOSE)
+        case "RIGHT_TOP":
+            return image.transpose(Transpose.ROTATE_270)
+        case "RIGHT_BOTTOM":
+            return image.transpose(Transpose.TRANSVERSE)
+        case "LEFT_BOTTOM":
+            return image.transpose(Transpose.ROTATE_90)
+
+
+def _oriented_intrinsics(camera: PinholeCameraConfig) -> tuple[int, int, float, float, float, float]:
+    width = camera.width
+    height = camera.height
+
+    if camera.orientation == "TOP_LEFT":
+        return camera.width, camera.height, camera.fx, camera.fy, camera.cx, camera.cy
+
+    if camera.orientation == "TOP_RIGHT":
+        return camera.width, camera.height, camera.fx, camera.fy, (width - camera.cx), camera.cy
+
+    if camera.orientation == "BOTTOM_RIGHT":
+        return camera.width, camera.height, camera.fx, camera.fy, (width - camera.cx), (height - camera.cy)
+
+    if camera.orientation == "BOTTOM_LEFT":
+        return camera.width, camera.height, camera.fx, camera.fy, camera.cx, (height - camera.cy)
+
+    new_width = camera.height
+    new_height = camera.width
+
+    if camera.orientation == "LEFT_TOP":
+        return new_width, new_height, camera.fy, camera.fx, camera.cy, camera.cx
+
+    if camera.orientation == "RIGHT_TOP":
+        return new_width, new_height, camera.fy, camera.fx, (height - camera.cy), camera.cx
+
+    if camera.orientation == "RIGHT_BOTTOM":
+        return new_width, new_height, camera.fy, camera.fx, (height - camera.cy), (width - camera.cx)
+
+    if camera.orientation == "LEFT_BOTTOM":
+        return new_width, new_height, camera.fy, camera.fx, camera.cy, (width - camera.cx)
+
+    raise ValueError(f"Unknown orientation: {camera.orientation!r}")

placeframe_core/lightglue.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NewType
+
+from lightglue import LightGlue  # type: ignore
+from numpy import bool_, dtype, float32, intp, ndarray
+from torch import Tensor, from_numpy, inference_mode, tensor  # type: ignore
+from torch.nn.utils.rnn import pad_sequence
+
+from .numpy_ops import compress, nonzero
+
+NumMatches = NewType("NumMatches", int)
+
+MatchIndices = dict[
+    tuple[str, str],
+    tuple[ndarray[tuple[NumMatches], dtype[intp]], ndarray[tuple[NumMatches], dtype[intp]]],
+]
+
+# Per-image-name dicts for the matcher's two distinct positional arguments. Branded at the dict
+# level so pyright catches positional swaps at the call site — passing Keypoints where Descriptors
+# is expected (or vice versa) is a type error, even though both wrap dict[str, Tensor] at runtime.
+Keypoints = NewType("Keypoints", dict[str, Tensor])
+Descriptors = NewType("Descriptors", dict[str, Tensor])
+KeypointsArrays = NewType("KeypointsArrays", dict[str, ndarray[tuple[int, int], dtype[float32]]])
+DescriptorsArrays = NewType("DescriptorsArrays", dict[str, ndarray[tuple[int, int], dtype[float32]]])
+
+
+def lightglue_match(
+    lightglue: LightGlue,
+    pairs: list[tuple[str, str]],
+    keypoints: KeypointsArrays,
+    descriptors: DescriptorsArrays,
+    sizes: dict[str, tuple[int, int]],
+    batch_size: int,
+    device: str,
+    on_progress: Callable[[int], None] | None = None,
+) -> MatchIndices:
+    keypoints_tensors = Keypoints({name: from_numpy(kp).to(device) for name, kp in keypoints.items()})
+    descriptors_tensors = Descriptors({name: from_numpy(desc).to(device) for name, desc in descriptors.items()})
+
+    return lightglue_match_tensors(
+        lightglue, pairs, keypoints_tensors, descriptors_tensors, sizes, batch_size, device, on_progress
+    )
+
+
+def lightglue_match_tensors(
+    lightglue: LightGlue,
+    pairs: list[tuple[str, str]],
+    keypoints: Keypoints,
+    descriptors: Descriptors,
+    sizes: dict[str, tuple[int, int]],
+    batch_size: int,
+    device: str,
+    on_progress: Callable[[int], None] | None = None,
+) -> MatchIndices:
+    num_batches = (len(pairs) + batch_size - 1) // batch_size
+    match_indices: MatchIndices = {}
+    for batch_start in range(0, len(pairs), batch_size):
+        print(f"Matching features: batch {batch_start // batch_size + 1} of {num_batches}")
+        batch_pairs = pairs[batch_start : batch_start + batch_size]
+
+        with inference_mode():
+            matches = lightglue({
+                "image0": {
+                    "keypoints": pad_sequence([keypoints[a] for a, _ in batch_pairs], batch_first=True),
+                    "descriptors": pad_sequence([descriptors[a] for a, _ in batch_pairs], batch_first=True),
+                    "image_size": tensor([sizes[a] for a, _ in batch_pairs], device=device),
+                },
+                "image1": {
+                    "keypoints": pad_sequence([keypoints[b] for _, b in batch_pairs], batch_first=True),
+                    "descriptors": pad_sequence([descriptors[b] for _, b in batch_pairs], batch_first=True),
+                    "image_size": tensor([sizes[b] for _, b in batch_pairs], device=device),
+                },
+            })["matches0"]
+
+        for i, (image_a, image_b) in enumerate(batch_pairs):
+            image_a_num_keypoints = keypoints[image_a].shape[0]
+
+            # Get actual batch matches (without padding), move to CPU, and convert to numpy
+            batch_matches = matches[i, :image_a_num_keypoints].cpu().numpy().astype(intp)
+
+            # Mask out non-matches (-1)
+            mask: ndarray[tuple[int], dtype[bool_]] = batch_matches >= 0
+            match_indices[(image_a, image_b)] = (nonzero(mask)[0], compress(mask, batch_matches))
+
+        if on_progress is not None:
+            on_progress(batch_start + len(batch_pairs))
+
+    return match_indices

placeframe_core/localization_metrics.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+
+
+# Localizer hyperparameters. The localizer falls back to these when callers omit the values, and
+# fit_calibration passes them explicitly to api.localize_image and persists them on each
+# localization_evaluations row. The (reconstruction_id, frame_timestamp, retrieval_top_k,
+# ransac_threshold, pipeline_version) cache key in localization_evaluations relies on caller and
+# fallback agreeing, so both sides must read these constants from one source.
+RETRIEVAL_TOP_K_DEFAULT = 12
+RANSAC_THRESHOLD_DEFAULT = 8.0
+
+
+class LocalizationMetrics(BaseModel):
+    inlier_ratio: float
+    reprojection_error_median: float
+    num_inliers: int
+    num_correspondences: int
+    num_matches: int
+    inlier_coverage: float
+    confidence_tight: float
+    confidence_loose: float
+    confidence_is_calibrated: bool
+    measurement_covariance: list[list[float]]
+    pnp_covariance: list[list[float]]
+    pipeline_version: str

placeframe_core/model_wrappers.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal, NewType, cast
+
+from torch import Tensor
+
+from .lightglue import (
+    Descriptors,
+    DescriptorsArrays,
+    Keypoints,
+    KeypointsArrays,
+    MatchIndices,
+    lightglue_match,
+    lightglue_match_tensors,
+)
+from .tensor_types import TT
+
+RetrievalDim = NewType("RetrievalDim", int)
+NumKeypoints = NewType("NumKeypoints", int)
+LocalDescDim = NewType("LocalDescDim", int)
+
+LocalFeatureOutput = tuple[TT[NumKeypoints, Literal[2]], TT[NumKeypoints, LocalDescDim]]
+
+
+def make_global_descriptor_extractor(model: Any) -> Callable[[Tensor], TT[RetrievalDim]]:
+    def extract(image: Tensor) -> TT[RetrievalDim]:
+        return cast(TT[RetrievalDim], model({"image": image})["global_descriptor"][0])
+
+    return extract
+
+
+def make_local_feature_extractor(model: Any) -> Callable[[Tensor], LocalFeatureOutput]:
+    def extract(image: Tensor) -> LocalFeatureOutput:
+        output = model({"image": image})
+        return (
+            cast(TT[NumKeypoints, Literal[2]], output["keypoints"][0]),
+            cast(TT[NumKeypoints, LocalDescDim], output["descriptors"][0]),
+        )
+
+    return extract
+
+
+def make_local_feature_matcher_for_tensors(model: Any, device: str):
+    def match(
+        pairs: list[tuple[str, str]],
+        keypoints: Keypoints,
+        descriptors: Descriptors,
+        sizes: dict[str, tuple[int, int]],
+        batch_size: int,
+        on_progress: Callable[[int], None] | None = None,
+    ) -> MatchIndices:
+        return lightglue_match_tensors(model, pairs, keypoints, descriptors, sizes, batch_size, device, on_progress)
+
+    return match
+
+
+def make_local_feature_matcher_for_arrays(model: Any, device: str):
+    def match(
+        pairs: list[tuple[str, str]],
+        keypoints: KeypointsArrays,
+        descriptors: DescriptorsArrays,
+        sizes: dict[str, tuple[int, int]],
+        batch_size: int,
+        on_progress: Callable[[int], None] | None = None,
+    ) -> MatchIndices:
+        return lightglue_match(model, pairs, keypoints, descriptors, sizes, batch_size, device, on_progress)
+
+    return match

placeframe_core/numpy_ops.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import cast, overload
+
+from numpy import bool_, dtype, generic, intp, ndarray
+from numpy import compress as _compress
+from numpy import nonzero as _nonzero
+from numpy import zeros as _zeros
+
+
+@overload
+def zeros[A: int, T: generic](shape: tuple[A], dtype: type[T]) -> ndarray[tuple[A], dtype[T]]: ...
+@overload
+def zeros[A: int, B: int, T: generic](shape: tuple[A, B], dtype: type[T]) -> ndarray[tuple[A, B], dtype[T]]: ...
+@overload
+def zeros[A: int, B: int, C: int, T: generic](
+    shape: tuple[A, B, C], dtype: type[T]
+) -> ndarray[tuple[A, B, C], dtype[T]]: ...
+def zeros(shape: tuple[int, ...], dtype: type[generic]) -> ndarray[tuple[int, ...], dtype[generic]]:
+    return _zeros(shape, dtype=dtype)
+
+
+def nonzero[A: int, B: int](
+    array: ndarray[tuple[A], dtype[generic]],
+) -> tuple[ndarray[tuple[B], dtype[intp]]]:
+    return cast("tuple[ndarray[tuple[B], dtype[intp]]]", _nonzero(array))
+
+
+def compress[A: int, B: int, T: generic](
+    condition: ndarray[tuple[A], dtype[bool_]],
+    array: ndarray[tuple[A], dtype[T]],
+) -> ndarray[tuple[B], dtype[T]]:
+    return cast("ndarray[tuple[B], dtype[T]]", _compress(condition, array))

placeframe_core/opq.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+from typing import cast
+
+from faiss import (  # type: ignore
+    OPQMatrix,
+    ProductQuantizer,
+    read_ProductQuantizer,  # type: ignore
+    read_VectorTransform,  # type: ignore
+    write_ProductQuantizer,  # type: ignore
+    write_VectorTransform,  # type: ignore
+)
+from numpy import ascontiguousarray, float32, uint8
+from numpy.linalg import norm
+from numpy.typing import NDArray  # noqa: TID251 — tracked in PLE-233
+
+OPQ_MATRIX_FILE = "opq_matrix.tf"
+PQ_QUANTIZER_FILE = "pq_quantizer.pq"
+
+
+def train_opq_matrix(number_of_subvectors: int, number_of_training_iterations: int, training_unit: NDArray[float32]):
+    opq_matrix = OPQMatrix(training_unit.shape[1], number_of_subvectors)
+    opq_matrix.niter = number_of_training_iterations
+    opq_matrix.verbose = True
+    opq_matrix.train(training_unit)  # type: ignore
+    return opq_matrix
+
+
+def train_pq_quantizer(
+    number_of_subvectors: int, number_of_bits_per_subvector: int, opq_matrix: OPQMatrix, training_unit: NDArray[float32]
+):
+    rotated_training_unit = opq_matrix.apply(training_unit)  # type: ignore
+    product_quantizer = ProductQuantizer(training_unit.shape[1], number_of_subvectors, number_of_bits_per_subvector)
+    product_quantizer.verbose = True
+    product_quantizer.train(rotated_training_unit)  # type: ignore
+    return product_quantizer
+
+
+def encode_descriptors(
+    opq_matrix: OPQMatrix, product_quantizer: ProductQuantizer, image_descriptors: dict[str, NDArray[float32]]
+):
+    images_codes: dict[str, NDArray[uint8]] = {}
+    for i, name in enumerate(image_descriptors.keys()):
+        print(f"Encoding image {i + 1} of {len(image_descriptors)}")
+        descriptors_contiguous = ascontiguousarray(image_descriptors[name])
+        descriptors_rotated = cast(NDArray[float32], opq_matrix.apply(descriptors_contiguous))  # type: ignore
+        codes = cast(NDArray[uint8], product_quantizer.compute_codes(descriptors_rotated))  # type: ignore
+        images_codes[name] = codes
+
+    return images_codes
+
+
+def decode_descriptors(opq_matrix: OPQMatrix, product_quantizer: ProductQuantizer, pq_codes: dict[int, NDArray[uint8]]):
+    descriptors: dict[int, NDArray[float32]] = {}
+    for image_id, code in pq_codes.items():
+        decoded = cast(NDArray[float32], product_quantizer.decode(code))  # type: ignore
+        reversed_transformed = cast(NDArray[float32], opq_matrix.reverse_transform(decoded))  # type: ignore
+        descriptors[image_id] = _l2_normalize_rows(reversed_transformed)
+
+    return descriptors
+
+
+def _l2_normalize_rows(matrix: NDArray[float32]) -> NDArray[float32]:
+    return (matrix / (norm(matrix, axis=1, keepdims=True).astype(float32) + float32(1e-12))).astype(float32, copy=False)
+
+
+def write_opq_matrix(opq_matrix: OPQMatrix, root_path: Path):
+    path = root_path / OPQ_MATRIX_FILE
+    write_VectorTransform(opq_matrix, str(path))
+    return OPQ_MATRIX_FILE, path.read_bytes()
+
+
+def write_pq_quantizer(pq_quantizer: ProductQuantizer, root_path: Path):
+    path = root_path / PQ_QUANTIZER_FILE
+    write_ProductQuantizer(pq_quantizer, str(path))
+    return PQ_QUANTIZER_FILE, path.read_bytes()
+
+
+def read_opq_matrix(root_path: Path):
+    return cast(OPQMatrix, read_VectorTransform(str(root_path / OPQ_MATRIX_FILE)))
+
+
+def read_pq_quantizer(root_path: Path):
+    return cast(ProductQuantizer, read_ProductQuantizer(str(root_path / PQ_QUANTIZER_FILE)))

placeframe_core/reconstruction_manifest.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .reconstruction_metrics import ReconstructionMetrics
+from .reconstruction_options import ReconstructionOptions
+
+
+MANIFEST_VERSION = 1
+
+
+class Manifest(BaseModel):
+    options: ReconstructionOptions
+    metrics: ReconstructionMetrics

placeframe_core/reconstruction_metrics.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PhaseTiming(BaseModel):
+    phase: str = Field(description="ReconstructionStatus value of the phase, e.g. 'extracting_features'.")
+    duration_seconds: float = Field(description="Wall-clock seconds the phase spent in-flight.")
+
+
+class ReconstructionMetrics(BaseModel):
+    reprojection_pixel_error_50th_percentile: Optional[float] = Field(
+        default=None,
+        description="Median reprojection error in pixels across all valid 2D observations in registered images.",
+    )
+    reprojection_pixel_error_90th_percentile: Optional[float] = Field(
+        default=None,
+        description="90th percentile reprojection error in pixels across all valid 2D observations.",
+    )
+    track_length_50th_percentile: Optional[float] = Field(
+        default=None,
+        description="Median number of distinct images observing each 3D point.",
+    )
+    all_verified_matches: Optional[int] = Field(
+        default=None, description="Total number of verified matches across all image pairs."
+    )
+    all_verified_match_rate: Optional[float] = Field(
+        default=None, description="Percentage of image pairs that passed two-view geometry verification."
+    )
+    all_verified_match_inliers_mean: Optional[float] = Field(
+        default=None, description="Mean inlier count among verified image pairs."
+    )
+    all_verified_match_inliers_median: Optional[float] = Field(
+        default=None, description="Median inlier count among verified image pairs."
+    )
+    stereo_verified_matches: Optional[int] = Field(
+        default=None, description="Number of verified stereo pairs (same frame, different sensors)."
+    )
+    stereo_verified_match_rate: Optional[float] = Field(
+        default=None, description="Percentage of stereo pairs that passed verification."
+    )
+    stereo_verified_match_inliers_mean: Optional[float] = Field(
+        default=None, description="Mean inlier count among verified stereo pairs."
+    )
+    stereo_verified_match_inliers_median: Optional[float] = Field(
+        default=None, description="Median inlier count among verified stereo pairs."
+    )
+    map_image_count: Optional[int] = Field(
+        default=None, description="Number of registered images in the reconstruction."
+    )
+    map_point_count: Optional[int] = Field(
+        default=None, description="Number of triangulated 3D points in the reconstruction."
+    )
+    map_avg_track_length: Optional[float] = Field(
+        default=None, description="Mean number of image observations per 3D point."
+    )
+    map_viewpoint_diversity: Optional[float] = Field(
+        default=None,
+        description="1 minus the magnitude of the mean unit viewing direction across registered cameras; 0 means uniform direction, approaches 1 as viewpoints spread.",
+    )
+    gravity_aligned_in_map_frame: Optional[bool] = Field(
+        default=None,
+        description="True when per-frame gravity samples aligned the map's vertical axis; False when no samples were available and only origin-shift was applied.",
+    )
+    gravity_sample_count: Optional[int] = Field(
+        default=None,
+        description="Number of registered frames that contributed gravity samples to the map-frame alignment.",
+    )
+    prior_drift_residual_rms_m: Optional[float] = Field(
+        default=None,
+        description="RMS residual in meters of a rigid Umeyama fit from map camera centers to VIO position priors; None for multi-camera captures, which run priors-off and carry no per-frame positions.",
+    )
+    prior_drift_residual_max_m: Optional[float] = Field(
+        default=None,
+        description="Maximum residual in meters of the same Umeyama fit; surfaces single-frame outliers the RMS smooths over.",
+    )
+    phase_timings: Optional[list[PhaseTiming]] = Field(
+        default=None,
+        description="Per-phase wall-clock durations in execution order, captured at each set_phase boundary.",
+    )
+    pipeline_version: Optional[str] = Field(
+        default=None,
+        description="RECONSTRUCTOR_SHA of the image that produced this reconstruction.",
+    )

placeframe_core/reconstruction_options.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ReconstructionOptions(BaseModel):
+    deterministic_seed: Optional[int] = Field(
+        default=None,
+        description="PRNG seed and single-threaded gate for reproducible reconstructions; None means non-deterministic.",
+    )
+    keyframe_min_distance_m: float = Field(
+        default=1.0,
+        description="Minimum VIO-translation distance (meters) between successive kept keyframes; frames closer to the last kept frame than this are dropped before feature extraction.",
+    )
+    sequential_window_m: float = Field(
+        default=3.0,
+        description="VIO-path-distance window (meters) used to enumerate same-rig sequential pairs. For each keyframe, every later keyframe whose cumulative segment-by-segment path length along the VIO trajectory is within this many metres is paired with it. Path distance — not straight-line distance — so doubling back along the trajectory (e.g. corridor return pass) walks away from earlier frames rather than landing on them. Scales the temporal match-graph backbone to actual device motion: stationary stretches shrink to almost no extra pairs, fast-motion stretches grow to cover the swept arc.",
+    )
+    retrieval_neighbors: int = Field(
+        default=20,
+        description="Top-K most-similar images (DIR cosine) paired with each image for loop closures; 0 disables retrieval.",
+    )
+    retrieval_min_score: float = Field(
+        default=0.35,
+        description="Minimum cosine similarity for retrieval candidates; drops visually-weak matches before BA.",
+    )
+    ransac_max_error: float = Field(
+        default=2.0,
+        description="Two-view RANSAC inlier threshold in pixels; lower is stricter.",
+    )
+    ransac_min_inlier_ratio: float = Field(
+        default=0.25,
+        description="Two-view RANSAC minimum inlier ratio to accept a pair's geometry.",
+    )
+    two_view_min_num_inliers: int = Field(
+        default=30,
+        description="Absolute minimum inlier count for a verified two-view geometry, applied alongside ransac_min_inlier_ratio. Raised above pycolmap's SIFT-era default of 15 to reject small false-positive clusters on repetitive structure.",
+    )
+    triangulation_minimum_angle: float = Field(
+        default=3.0,
+        description="Minimum triangulation angle in degrees; applied at creation time and again in mapper filtering.",
+    )
+    mapper_filter_max_reprojection_error: float = Field(
+        default=2.0,
+        description="Post-BA outlier reprojection threshold in pixels; points exceeding it are culled.",
+    )
+    bundle_adjustment_global_frames_ratio: float = Field(
+        default=1.5,
+        description="Frame-count growth ratio that triggers a global BA event; larger = fewer events.",
+    )
+    bundle_adjustment_global_function_tolerance: float = Field(
+        default=1e-3,
+        description="Ceres function tolerance for global BA exit; larger = earlier exit on residual plateaus.",
+    )
+    pose_prior_position_sigma_m: float = Field(
+        default=0.05,
+        description="Standard deviation in meters for the position prior covariance; consumed only by monocular captures (multi-camera captures run priors-off).",
+    )
+    pair_vio_em_max_rotation_disagreement_deg: float = Field(
+        default=25.0,
+        description="At two-view verification time, every sequential pair whose VIO poses carry rotation has its essential-matrix relative pose compared against the VIO-implied relative pose. The pair is rejected (its two-view geometry deleted from the database) when the angle between the two rotations exceeds this threshold. Sequential-only because retrieval pairs span genuine loop closures where VIO drift can disagree with the essential matrix legitimately, and intra-frame stereo is already validated by the rig constraint. 0 disables. Applied only to pairs with 7-column VIO rows (quaternion present).",
+    )
+    pair_vio_em_max_translation_direction_deg: float = Field(
+        default=60.0,
+        description="Companion to pair_vio_em_max_rotation_disagreement_deg: bounds the angle between the essential-matrix translation direction (camera-1 origin direction in camera-2) and the VIO-implied translation direction for the same camera pair. Skipped when the essential-matrix baseline is below pair_vio_em_min_baseline_m, where translation direction is ill-conditioned. 0 disables.",
+    )
+    pair_vio_em_min_baseline_m: float = Field(
+        default=0.3,
+        description="Essential-matrix-baseline floor below which the VIO-vs-essential-matrix translation-direction component is skipped. Near-co-located camera pairs (intra-rig stereo timing jitter, hover frames in slow motion) have ill-defined essential-matrix translation direction; the rotation component still applies.",
+    )
+    max_keypoints_per_image: int = Field(
+        default=2500,
+        description="Maximum ALIKED keypoints retained per image.",
+    )
+    held_out_frame_timestamps: Optional[list[int]] = Field(
+        default=None,
+        description="Frame timestamps (ms) to exclude from this reconstruction so they can later be localized as held-out queries.",
+    )

placeframe_core/tensor_types.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import torch
+
+if TYPE_CHECKING:
+
+    class TT[*Shape](torch.Tensor): ...
+
+else:
+    # PEP 695 generic-class syntax is type-checker only. At runtime, TT[Shape...]
+    # must evaluate (e.g. inside cast() and module-level tuple[...] aliases),
+    # so collapse subscription to plain torch.Tensor.
+    class TT:
+        def __class_getitem__(cls, _params: object) -> type[torch.Tensor]:
+            return torch.Tensor

placeframe_core/transform.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class Float3(BaseModel):
+    x: float
+    y: float
+    z: float
+
+
+class Float4(BaseModel):
+    x: float
+    y: float
+    z: float
+    w: float
+
+
+class Transform(BaseModel):
+    translation: Float3
+    rotation: Float4

placeframe_core-0.1.0.dev35547537192.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: placeframe-core
+Version: 0.1.0.dev35547537192
+Summary: Placeframe domain logic: camera configs, coordinate transforms, metrics
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: faiss-cpu>=1.12.0
+Requires-Dist: h5py>=3.15.1
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: scipy>=1.16.3
+Description-Content-Type: text/markdown
+
+# placeframe-core
+
+Domain vocabulary for Placeframe's backend: Pydantic wire schemas (transforms, camera configs, capture manifests, reconstruction options/metrics), OpenCV↔Unity coordinate-frame primitives, image and intrinsics canonicalization, HDF5/FAISS-OPQ artifact formats, and the global confidence-calibration model. Distribution name `placeframe-core`, import name `placeframe_core`.
+
+Consumed by the `api`, `lease-server`, `localizer`, `reconstructor`, `zed-capture`, and `scripts` packages in the [placeframe](https://github.com/outernet-foundation/placeframe) repo. Versions are published to PyPI from per-package git tags; the committed `pyproject.toml` version is a permanent `0.0.0.dev0` sentinel patched at publish time.

placeframe_core-0.1.0.dev35547537192.dist-info/RECORD

@@ -0,0 +1,20 @@
+placeframe_core/axis_convention.py,sha256=W3sHw0RFe9DAhf46jiY8VrMptLdBub-7BYAHL4dd79A,1905
+placeframe_core/calibration.py,sha256=yBtorsBWM-Ti8MxPXI7xjZuCnepqufV9q6HaRWrV7cc,5521
+placeframe_core/camera_config.py,sha256=pz5pvLhMWra0xLmAMSANU6CkP52XGKqExQ0kz77d4bQ,474
+placeframe_core/capture_session_manifest.py,sha256=kVMWWaiDPPo2FK0TthOOGVWAU-0Zn3uVf2ps_lSofZo,582
+placeframe_core/h5.py,sha256=7VaZpK2iIzXW6iq7hAPUlcTVR73vizLUE11S-T4t0jU,2611
+placeframe_core/image_preprocess.py,sha256=fDouVHMT8lsbVWKRENXsGgLHMOkTcGUtXU1mTE9vsSA,3550
+placeframe_core/lightglue.py,sha256=V1AQAHsjqZBVGC2pweHgUOA8_sxX8IT8MDkSZ7QKL4o,3870
+placeframe_core/localization_metrics.py,sha256=vSoSDfa9pAwMiZ5T9zyGbsdbpZU27q8K9iH70T4Vuko,944
+placeframe_core/model_wrappers.py,sha256=SRzqm1Tu-DaEt775z8FBcHMtAjLwifY3cNyI8LURPk0,2148
+placeframe_core/numpy_ops.py,sha256=MV9d3EVce-DtzLvRitlApk6w3UHeXmeGh-sdwXTIVps,1191
+placeframe_core/opq.py,sha256=uomGrNJ48EFkgVoxXp5Orr761W2_fvizruHptxxMsP4,3395
+placeframe_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+placeframe_core/reconstruction_manifest.py,sha256=IZAfQ9BzOk2owahTS1Ud6r6ZR2S1lLExHSzaq7pqMX4,306
+placeframe_core/reconstruction_metrics.py,sha256=0k0P0RZErdBIBb2Mf0M_XKwOAA9CBj3ctnV-OqtsOk4,4173
+placeframe_core/reconstruction_options.py,sha256=Xt6LfrweoNLCig49N53UcCEbCrJ0O2TL2TSh4WOiU0A,5227
+placeframe_core/tensor_types.py,sha256=svnB8TnY4kiBqWzc5g734l5zCVqWfcY2aFK7LbJBhuQ,485
+placeframe_core/transform.py,sha256=Vv5FwaVWAXMiEwN2X1h9qf2DDm-lVeXVDtBS5FMdHWk,287
+placeframe_core-0.1.0.dev35547537192.dist-info/METADATA,sha256=2KuZPmkMBesC7u_ACDQeXDRvr2zz9vpAdBMc5NWRwPs,1170
+placeframe_core-0.1.0.dev35547537192.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+placeframe_core-0.1.0.dev35547537192.dist-info/RECORD,,

placeframe_core-0.1.0.dev35547537192.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any