placeframe-core 0.1.0.dev35547537192__tar.gz

placeframe_core-0.1.0.dev35547537192/.gitignore

@@ -0,0 +1,35 @@
+**/__pycache__
+**/*.pyc
+**/*.pyo
+**/*.pyd
+**/.venv/
+**/*.egg-info
+**/dist/
+**/build/
+!/build/
+**/*.sln
+**/*.slnx
+**/bin/
+**/obj/
+**/bin.meta
+**/obj.meta
+.pytest_cache
+.ruff_cache
+.vs
+.act
+.env
+.env.shas
+.secrets
+score/compose.yaml
+score/manifests.yaml
+score/.score-compose/
+score/.score-k8s/
+metadata.json
+storage/
+tidy-commits.json
+.build-version.json
+artifacts/
+.pnpm-store/
+.placeframe/
+.claude/scheduled_tasks.lock
+bookmark.md

placeframe_core-0.1.0.dev35547537192/AGENTS.md

@@ -0,0 +1,102 @@
+# packages/python/core/
+
+## What this is
+
+`placeframe_core` is the workspace Python package that holds the vocabulary shared between Placeframe's backend services. It contains the Pydantic schemas that travel over HTTP and through Postgres JSONB columns, the coordinate-frame primitives that bridge OpenCV-space (reconstructor / COLMAP) and Unity-space (phone clients / localizer responses), the image and intrinsics canonicalization used by both the map-builder and the query path, the HDF5 / FAISS-OPQ on-disk artifact formats, and the global confidence-calibration model. The distribution name is `placeframe-core` (published to PyPI under that name; tag ledger `placeframe-core-python-v*`) and every import is `from placeframe_core.<module>`. `docker/api/`, `docker/lease-server/`, `docker/localizer/`, `docker/reconstructor/`, `docker/zed-capture/`, and `scripts/` declare it as a workspace dep. See `docker/AGENTS.md` for the service mesh that consumes these types.
+
+## Shape
+
+The package is flat: 16 leaf modules under `src/placeframe_core/`, no `__init__.py` re-exports, every consumer imports from a leaf. There are no tests inside `placeframe_core/`; behaviour is exercised end-to-end from the consumer test suites (`docker/localizer/tests/test_build_metrics.py`, `docker/reconstructor/tests/test_rig.py`, `scripts/tests/test_fit_calibration.py`).
+
+### Modules by role
+
+**Wire-format schemas (Pydantic; serialize to HTTP / JSONB / the generated C# client).**
+
+- `transform.py` — `Float3`, `Float4(x,y,z,w)`, `Transform(translation, rotation)`. Smallest building block; carried in URLs, capture manifests, and localization responses. Quaternion order is xyzw everywhere.
+- `camera_config.py` — `ImageOrientation` (the 8 EXIF orientation tags as a Literal) and `PinholeCameraConfig(width, height, orientation, fx, fy, cx, cy)`. Foundational.
+- `capture_session_manifest.py` — `RigCameraConfig`, `RigConfig`, `CaptureSessionManifest(axis_convention, rigs, capture_interval_seconds | None)`. The structured payload a phone client uploads alongside the image tar. `ref_sensor: bool` on `RigCameraConfig` identifies the rig origin.
+- `reconstruction_options.py` — 32 optional Pydantic fields describing the reconstructor's COLMAP pipeline: keyframe-selection thresholds, sequential/spatial/retrieval pair-generation knobs, RANSAC thresholds, BA toggles, triangulation gates, OPQ params, pose-prior sigma, and `held_out_frame_timestamps` (used by calibration to exclude specific frames so they can be re-localized as held-out queries).
+- `reconstruction_metrics.py` — 33 optional fields covering classic SfM metrics, match-verification counts (stereo / same-sensor / cross-sensor splits), map-quality features for the calibration model (`map_image_count`, `map_point_count`, `map_avg_track_length`, `map_viewpoint_diversity`), Umeyama-alignment residuals against ground-truth poses, per-phase wall-clock timings, and the reconstructor `pipeline_version`.
+- `reconstruction_manifest.py` — `MANIFEST_VERSION = 1` and `Manifest(options, metrics)`. Stored as JSONB in `reconstructions.manifest`. The version constant is stamped onto `row.manifest_version` at write time.
+- `localization_metrics.py` — `LocalizationMetrics`, the per-query response payload (inlier ratio, reprojection error, inlier counts, calibrated confidences, 6x6 measurement and PnP covariances, pipeline version). Also exposes `RETRIEVAL_TOP_K_DEFAULT = 12` and `RANSAC_THRESHOLD_DEFAULT = 8.0`. Caller and fallback must read these from one source because the `(reconstruction_id, frame_timestamp, retrieval_top_k, ransac_threshold, pipeline_version)` cache key in `localization_evaluations` relies on agreement.
+
+**Coordinate-frame math.**
+
+- `axis_convention.py` — `AxisConvention` enum (`OPENCV`, `UNITY`) plus four pure-numpy primitives built on a single basis-change matrix `diag(1, -1, 1)`: `change_basis_opencv_from_unity_pose`, `change_basis_unity_from_opencv_pose`, `change_basis_unity_from_opencv_points`, `change_basis_unity_from_opencv_poses` (vectorized, takes xyzw quaternions). OpenCV is `+X right, +Y down, +Z forward`; Unity is `+X right, +Y up, +Z forward`. The enum is a tag, not a dispatch — callers branch on it themselves.
+
+**Image / intrinsics canonicalization.**
+
+- `image_preprocess.py` — the producer/consumer agreement. `canonicalize_image(buffer, orientation)` EXIF-orients then LANCZOS-resizes the shorter side to `LOCAL_FEATURE_RESIZE_SHORTER_SIDE = 1024`. `canonicalize_intrinsics(camera)` applies the matching orientation swap and rescale to `fx/fy/cx/cy` (an 8-branch match where diagonal flips swap width/height *and* fx/fy *and* cx/cy axes). `tile_image(image)` slides a 1024px window with `RETRIEVAL_TILE_OVERLAP_FRACTION = 0.5` overlap. The reconstructor runs all three at map-build time; the localizer runs them at query time. `NumImages`, `MaxTiles`, `NumQueryTiles` `NewType` brands live here.
+
+**On-disk artifact format.**
+
+- `h5.py` — `GLOBAL_DESCRIPTORS_FILE = "global_descriptors.h5"`, `FEATURES_FILE = "features.h5"`, gzip-compressed chunked writers and image-name-keyed readers. The reconstructor writes; the localizer reads. Dataset names `global_descriptor`, `keypoints`, `pq_codes` are constants here.
+- `opq.py` — FAISS OPQ matrix and product-quantizer training, encoding, decoding, and IO. File names `opq_matrix.tf` and `pq_quantizer.pq` pinned here. `decode_descriptors` L2-normalizes its reconstructed descriptors (with a `+1e-12` float32 denominator to avoid divide-by-zero).
+
+**Confidence-calibration model.**
+
+- `calibration.py` — `SCHEMA_VERSION = 2`. `RawLocalizationMetrics` and `RawMapMetrics` are the per-query and per-map raw inputs. `Features.compute(localization, map_metrics)` produces a 10-feature vector: `log1p` of inlier / match / image / point counts, `reproj_error_median / image_diagonal`, plus four ratios and diversities. `ToleranceModel` carries `logistic_weights` (Features-shaped), `logistic_intercept`, and an isotonic table (`isotonic_x_breakpoints`, `isotonic_y_breakpoints`). `CalibrationArtifact` bundles a `tight` and `loose` `ToleranceModel`, `sigma_meas_alpha` / `sigma_meas_beta` for the measurement-covariance scaling `Sigma_meas = alpha * Sigma_pnp + beta * I_6`, `loose_min` / `tight_min` floors, and version metadata. `load_global_calibration(path, expected_pipeline_version)` raises `CalibrationLoadError` with a remediation message if the file is missing, the schema version mismatches, or the pipeline version mismatches. `apply_global_calibration(calibration, features)` returns `(tight, loose, True)` — the third element is always literal `True`.
+
+**Inference glue and typing shims (torch-aware).**
+
+- `lightglue.py` — wraps `lightglue.LightGlue`. `Keypoints` / `Descriptors` `NewType`s over `dict[str, Tensor]` (and `*Arrays` variants for numpy input) brand the matcher's positional arguments so pyright catches keypoints/descriptors swaps. `lightglue_match` batches pairs, pads variable-length keypoint sequences, masks out `-1` non-matches.
+- `model_wrappers.py` — four thin closures around a "model" callable: extract global descriptor, extract local features, run the matcher on tensors, run the matcher on numpy arrays. `RetrievalDim`, `NumKeypoints`, `LocalDescDim` `NewType` brands.
+- `tensor_types.py` — `TT[*Shape]`: a generic subclass of `torch.Tensor` at type-check time, collapsed to plain `torch.Tensor` at runtime via `__class_getitem__`. The runtime collapse is required because `TT[Shape...]` must evaluate inside `cast()` calls and module-level tuple aliases.
+- `numpy_ops.py` — shape-typed re-exports of `numpy.zeros` (overloaded for 1D / 2D / 3D), `nonzero`, `compress`, propagating dimension brands through PEP 695 generics.
+
+**Stub.**
+
+- `main.py` — six-line `print("Hello from core!")`. `uv init` scaffolding; not registered as a script.
+
+### Consumer map
+
+Ranked by import volume:
+
+    localizer  (30 sites)  -- localize, build_metrics, map, main, schemas, torch_ops, tests
+    reconstructor (22)     -- run_reconstruction, rig, main, metrics_builder, options_builder, tests
+    api (13)               -- routers/{localization, reconstructions, leases, capture_sessions}
+    zed-capture (4)        -- zed/zed.py (manifest writer)
+    scripts                -- fit_calibration, tune_reconstruction
+
+The most-imported leaves are `axis_convention` and `calibration` (8 sites each), `reconstruction_metrics` (7), then `transform`, `capture_session_manifest`, and `camera_config` (6 each).
+
+### Map / query contract
+
+The reason this package is the hub of the stack: every artifact the reconstructor produces is read back by the localizer, byte-for-byte. The constants that pin the contract live in core:
+
+    reconstructor                       localizer
+    -------------                       ---------
+    h5.write_global_descriptors    -->  h5.read_global_descriptors
+    h5.write_features              -->  h5.read_features
+    opq.{train,encode,write}       -->  opq.{read,decode}
+    image_preprocess.canonicalize  -->  image_preprocess.canonicalize    (same constants, both sides)
+    image_preprocess.tile_image    -->  image_preprocess.tile_image
+    model_wrappers.RetrievalDim    -->  model_wrappers.RetrievalDim      (phantom shape brand)
+
+Flipping `LOCAL_FEATURE_RESIZE_SHORTER_SIDE`, `RETRIEVAL_TILE_OVERLAP_FRACTION`, an HDF5 dataset name, or an OPQ file name in core without rebuilding every existing map silently degrades retrieval quality without raising.
+
+## Constraints
+
+**One flat package, no `__init__.py` re-exports.** Every consumer reaches into a leaf module, which makes the dependency graph immediately legible from import lines alone: `from placeframe_core.opq import decode_descriptors` says exactly what the consumer touches. The cost is verbose import blocks at the call site (the localizer's `localize.py` imports from `placeframe_core.model_wrappers` on two separate lines); the benefit is no parallel public-surface drift between `__init__.py` and the leaves.
+
+**Pydantic on the schema side, pure numpy/torch on the math side.** Schemas need OpenAPI-generability and JSON round-tripping (they end up in C# via `generate-clients` and in Postgres JSONB via the API). Math functions need numpy-array-in / numpy-array-out so they compose with both the reconstructor's training loop and the localizer's per-query path with no Pydantic overhead. The two halves of the package never wrap each other.
+
+**`AxisConvention` is a tag, not a dispatch.** The enum lives on `CaptureSessionManifest` and labels the producer's coordinate system, but core does not branch on it internally — callers do (the reconstructor's `rig.py` calls `change_basis_opencv_from_unity_pose` when the manifest is `UNITY`). Keeping the dispatch out of core means consumers can localize their own coordinate logic without paying for an indirection on every pose.
+
+**Quaternion order is xyzw everywhere.** Matches `scipy.spatial.transform.Rotation.from_quat`'s default and the Unity / glTF convention. No `Float4`-with-wxyz ambiguity.
+
+**`tensor_types.TT[*Shape]` runtime-collapses to `torch.Tensor`.** PEP 695 generic-class syntax is type-checker only, but `TT[Shape...]` appears inside `cast()` calls and module-level tuple aliases that *do* evaluate at runtime. `__class_getitem__` returning plain `torch.Tensor` is what lets both `cast(TT[NumKeypoints, LocalDescDim], ...)` and `LocalFeatureOutput = tuple[TT[NumKeypoints, Literal[2]], TT[NumKeypoints, LocalDescDim]]` work. The same pattern is in `numpy_ops` for ndarray shape brands.
+
+**`NewType` brands on phantom dimension types (`RetrievalDim`, `NumImages`, `MaxTiles`, `NumQueryTiles`, `NumKeypoints`, `LocalDescDim`).** They cost nothing at runtime and let pyright catch axis-order mistakes when the reconstructor's `(NumImages, MaxTiles, RetrievalDim)` tile array is sliced or transposed against the localizer's expectation. The same brand-typing trick is applied to the matcher's positional arguments (`Keypoints` vs. `Descriptors`).
+
+**Manifest fields default to `Optional[X] = None`.** Reconstruction is incremental: the reconstructor fills `ReconstructionMetrics` field by field during a multi-minute run, and the API accepts partial `ReconstructionOptions` blobs from clients that don't want to specify every COLMAP knob. The cost is that downstream readers must None-check; the alternative — fresh-write defaults — would either fabricate misleading numbers or split the model into write-time and read-time variants.
+
+**The torch / lightglue dependency lives in core but is not declared in `pyproject.toml`.** A `DEP003` deptry exemption documents the asymmetry. The canonical PyTorch dep lives in `neural-networks` behind conflicting `cpu` / `cuda` / `rocm` extras, so declaring bare `torch` here would conflict. Consumers that touch the torch-aware modules (`lightglue`, `model_wrappers`, `tensor_types`) must also depend on `neural-networks` with the matching extra; the API does not depend on `neural-networks` and never imports those modules.
+
+**Calibration is the only place with a real algorithm and the only place with a real version check.** `load_global_calibration` raises loudly on schema or pipeline mismatch. Every other versioned thing in core (notably `MANIFEST_VERSION`) trusts the caller. The asymmetry is deliberate where the calibration artifact is concerned — a wrong-version calibration silently miscalibrates every confidence in production — but is a known gap for the manifest path.
+
+## See also
+
+- `docker/AGENTS.md` -- the service mesh that consumes these types. Core is the vocabulary on the arrows between services; that doc describes the arrows.
+- `scripts/src/scripts/fit_calibration.py` -- the producer of `docker/localizer/calibration/global.json`. Reads `placeframe_core.calibration`, `placeframe_core.capture_session_manifest`, and `placeframe_core.localization_metrics`'s defaults.
+- `packages/generated/` -- the OpenAPI client packages (Python and C#) generated from API routes that respond with `placeframe_core` schemas. A schema change here requires running `generate-clients`.

placeframe_core-0.1.0.dev35547537192/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

placeframe_core-0.1.0.dev35547537192/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,5 @@
+# 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/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from core!")
+
+
+if __name__ == "__main__":
+    main()

placeframe_core-0.1.0.dev35547537192/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "placeframe-core"
+version = "0.1.0.dev35547537192"
+description = "Placeframe domain logic: camera configs, coordinate transforms, metrics"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "scipy>=1.16.3",
+    "faiss-cpu>=1.12.0",
+    "pillow>=12.0.0",
+    "numpy>=2.4.0",
+    "pydantic>=2.12.5",
+    "h5py>=3.15.1",
+]
+
+[dependency-groups]
+dev = ["scipy-stubs>=1.16.3.0"]
+
+[tool.deptry.per_rule_ignores]
+# Code in this package directly imports 'torch', but cannot directly depend on torch, because torch has multiple conflicting 
+# platform-specific variants that are declared using 'extras' in the 'neural-networks' package, and declaring bare 'torch' 
+# directly in this package would lead to dependency conflicts; we therefore must ignore deptry's check for this specific package
+DEP003 = ["torch", "lightglue"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/placeframe_core"]
+include = ["src/placeframe_core/py.typed"]

placeframe_core-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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-0.1.0.dev35547537192/src/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