colmap4d 1.0.1__tar.gz → 1.0.2__tar.gz

colmap4d-1.0.2/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: colmap4d
+Version: 1.0.2
+Summary: Standard COLMAP sparse model + per-image and per-point timestamps (x, y, z, t).
+Author: colmap4d authors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Kiri-Innovation/colmap4d
+Project-URL: Repository, https://github.com/Kiri-Innovation/colmap4d
+Project-URL: Specification, https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md
+Project-URL: Changelog, https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/CHANGELOG.md
+Keywords: colmap,sfm,4d,dynamic-scene,gaussian-splatting
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: model
+Requires-Dist: pycolmap>=0.6; extra == "model"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# colmap4d
+
+[![PyPI](https://img.shields.io/pypi/v/colmap4d)](https://pypi.org/project/colmap4d/)
+[![CI](https://github.com/Kiri-Innovation/colmap4d/actions/workflows/ci.yml/badge.svg)](https://github.com/Kiri-Innovation/colmap4d/actions/workflows/ci.yml)
+[![spec v1.0 frozen](https://img.shields.io/badge/spec-v1.0%20frozen-blue)](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md)
+
+**A standard COLMAP sparse model + one timestamp per image + one timestamp per point.**
+Every image and every point becomes an independent sample in spacetime `(x, y, z, t)`.
+Nothing else: frame sync is just timestamps being close, and any discretization is a
+derived view or a render parameter, never stored data.
+
+colmap4d adds up to three **sidecar** files to an ordinary COLMAP model and changes no
+existing file — so old tools open it as a perfectly normal (static) reconstruction, while a
+4D-aware viewer unlocks a free 3D view + a draggable time axis.
+
+> Spec **v1.0 — frozen.** See [the specification](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md);
+> Part I and the conformance goldens are normative, and changes follow
+> [the CHANGELOG](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/CHANGELOG.md).
+>
+> colmap4d is an **independent, community extension** of the COLMAP output format. It is **not
+> affiliated with or endorsed by** the COLMAP project; "COLMAP" is used only to name the format
+> it extends.
+
+## Which one are you?
+
+| I want to… | go to |
+|------------|-------|
+| **Read** colmap4d data (the common case) | [Quick start](#read-colmap4d-data-quick-start) below — `pip install colmap4d`, three lines |
+| **Produce** colmap4d data (convert / write) | [`docs/converters.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/docs/converters.md) |
+| **Build a second implementation** (C++/Rust/JS) | [the spec](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md): implement Part I, then pass every fixture in [`conformance/golden/`](https://github.com/Kiri-Innovation/colmap4d/tree/main/conformance/golden) at the `v1.0` tag |
+| **Contribute** (human or AI agent) | [`CONTRIBUTING.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/CONTRIBUTING.md) + [`AGENTS.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/AGENTS.md) |
+| **Drive colmap4d from an AI agent** | the [colmap4d skill](https://github.com/Kiri-Innovation/colmap4d/blob/main/skills/colmap4d/SKILL.md) |
+
+More detail: [repository layout, dev commands & versioning](https://github.com/Kiri-Innovation/colmap4d/blob/main/docs/repo-layout.md).
+
+## Read colmap4d data (quick start)
+
+Read a COLMAP model together with its time layer — **zero dependencies**:
+
+```python
+import colmap4d
+
+mv = colmap4d.load_model_view("path/to/sparse")   # COLMAP model dir, with or without sidecars
+
+mv.point_time(42)              # -> t_ns (int64 ns), or None if the point is temporally-unbounded
+mv.image_time(1)               # -> t_ns, or None
+mv.effective_points_t()        # {point3d_id: t_ns}, dangling ids already dropped
+mv.sidecars.time_meta          # {"clock_domain": "utc_ntp", ...} or None
+```
+
+Just the timestamps, without the base model: `colmap4d.load_sidecars("path/to/sparse")`.
+
+A plain COLMAP model (no sidecars) loads fine: empty times, all points temporally-unbounded —
+the backward-compatibility baseline. The reader is standard-library only; `pip install
+'colmap4d[model]'` adds pycolmap for authoritative parsing and 3.12 rigs/frames support.
+
+Uploading time to a GPU (4DGS/NeRF)? Rebase first — raw epoch ns overflows float32; upload
+`(t − t0)` seconds as float32 via `colmap4d.rebase_to_seconds_f32(t, mv.t0_ns())`.
+
+## License
+
+[Apache-2.0](https://github.com/Kiri-Innovation/colmap4d/blob/main/LICENSE).
+
+<!-- link-audit: all README external links verified absolute (2026-09-04, PyPI render safety) -->

colmap4d-1.0.2/README.md

@@ -0,0 +1,64 @@
+# colmap4d
+
+[![PyPI](https://img.shields.io/pypi/v/colmap4d)](https://pypi.org/project/colmap4d/)
+[![CI](https://github.com/Kiri-Innovation/colmap4d/actions/workflows/ci.yml/badge.svg)](https://github.com/Kiri-Innovation/colmap4d/actions/workflows/ci.yml)
+[![spec v1.0 frozen](https://img.shields.io/badge/spec-v1.0%20frozen-blue)](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md)
+
+**A standard COLMAP sparse model + one timestamp per image + one timestamp per point.**
+Every image and every point becomes an independent sample in spacetime `(x, y, z, t)`.
+Nothing else: frame sync is just timestamps being close, and any discretization is a
+derived view or a render parameter, never stored data.
+
+colmap4d adds up to three **sidecar** files to an ordinary COLMAP model and changes no
+existing file — so old tools open it as a perfectly normal (static) reconstruction, while a
+4D-aware viewer unlocks a free 3D view + a draggable time axis.
+
+> Spec **v1.0 — frozen.** See [the specification](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md);
+> Part I and the conformance goldens are normative, and changes follow
+> [the CHANGELOG](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/CHANGELOG.md).
+>
+> colmap4d is an **independent, community extension** of the COLMAP output format. It is **not
+> affiliated with or endorsed by** the COLMAP project; "COLMAP" is used only to name the format
+> it extends.
+
+## Which one are you?
+
+| I want to… | go to |
+|------------|-------|
+| **Read** colmap4d data (the common case) | [Quick start](#read-colmap4d-data-quick-start) below — `pip install colmap4d`, three lines |
+| **Produce** colmap4d data (convert / write) | [`docs/converters.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/docs/converters.md) |
+| **Build a second implementation** (C++/Rust/JS) | [the spec](https://github.com/Kiri-Innovation/colmap4d/blob/main/spec/colmap4d-v1.0.md): implement Part I, then pass every fixture in [`conformance/golden/`](https://github.com/Kiri-Innovation/colmap4d/tree/main/conformance/golden) at the `v1.0` tag |
+| **Contribute** (human or AI agent) | [`CONTRIBUTING.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/CONTRIBUTING.md) + [`AGENTS.md`](https://github.com/Kiri-Innovation/colmap4d/blob/main/AGENTS.md) |
+| **Drive colmap4d from an AI agent** | the [colmap4d skill](https://github.com/Kiri-Innovation/colmap4d/blob/main/skills/colmap4d/SKILL.md) |
+
+More detail: [repository layout, dev commands & versioning](https://github.com/Kiri-Innovation/colmap4d/blob/main/docs/repo-layout.md).
+
+## Read colmap4d data (quick start)
+
+Read a COLMAP model together with its time layer — **zero dependencies**:
+
+```python
+import colmap4d
+
+mv = colmap4d.load_model_view("path/to/sparse")   # COLMAP model dir, with or without sidecars
+
+mv.point_time(42)              # -> t_ns (int64 ns), or None if the point is temporally-unbounded
+mv.image_time(1)               # -> t_ns, or None
+mv.effective_points_t()        # {point3d_id: t_ns}, dangling ids already dropped
+mv.sidecars.time_meta          # {"clock_domain": "utc_ntp", ...} or None
+```
+
+Just the timestamps, without the base model: `colmap4d.load_sidecars("path/to/sparse")`.
+
+A plain COLMAP model (no sidecars) loads fine: empty times, all points temporally-unbounded —
+the backward-compatibility baseline. The reader is standard-library only; `pip install
+'colmap4d[model]'` adds pycolmap for authoritative parsing and 3.12 rigs/frames support.
+
+Uploading time to a GPU (4DGS/NeRF)? Rebase first — raw epoch ns overflows float32; upload
+`(t − t0)` seconds as float32 via `colmap4d.rebase_to_seconds_f32(t, mv.t0_ns())`.
+
+## License
+
+[Apache-2.0](https://github.com/Kiri-Innovation/colmap4d/blob/main/LICENSE).
+
+<!-- link-audit: all README external links verified absolute (2026-09-04, PyPI render safety) -->

{colmap4d-1.0.1 → colmap4d-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "colmap4d"
-version = "1.0.1"
+version = "1.0.2"
 description = "Standard COLMAP sparse model + per-image and per-point timestamps (x, y, z, t)."
 readme = "README.md"
 requires-python = ">=3.9"

{colmap4d-1.0.1 → colmap4d-1.0.2}/src/colmap4d/__init__.py

@@ -7,6 +7,7 @@ dependency, not implemented yet).
 
 from __future__ import annotations
 
+from colmap4d.groups import GridDiscard, GridGroup, GridGrouping, GridSample, group_by_grid
 from colmap4d.model import (
     ModelView,
     load_model_view,
@@ -31,13 +32,18 @@ from colmap4d.sidecar import (
     write_times_txt,
 )
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 
 __all__ = [
     "TIMELESS",
+    "GridDiscard",
+    "GridGroup",
+    "GridGrouping",
+    "GridSample",
     "ModelView",
     "Sidecars",
     "is_temporally_unbounded",
+    "group_by_grid",
     "load_model_view",
     "load_sidecars",
     "read_base_model",

colmap4d-1.0.2/src/colmap4d/convert/fixed_rig.py

@@ -0,0 +1,204 @@
+"""Convert fixed-rig multi-camera captures to colmap4d using pre-calibrated poses.
+
+For fixed camera arrays where intrinsics and extrinsics are calibrated once and reused,
+this converter takes a rig calibration file and timestamped images, and produces a
+colmap4d model where camera poses are from the calibration (not re-estimated).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from colmap4d import sidecar
+from colmap4d.rig_calibration import RigCalibration
+
+
+@dataclass
+class TimestampedImage:
+    """Image with timestamp."""
+
+    camera_name: str  # e.g., "cam1"
+    frame_index: int  # Frame number in sequence
+    timestamp_ns: int  # Nanosecond timestamp
+    image_path: Path | None = None  # Path to image file (optional)
+
+
+def _fmt(x: float) -> str:
+    """Format float for COLMAP text files."""
+    return f"{x:.12g}"
+
+
+def _write_cameras_txt(path: Path, calibration: RigCalibration) -> dict[str, int]:
+    """Write cameras.txt from rig calibration.
+
+    Returns:
+        Mapping from camera_name to CAMERA_ID
+    """
+    lines = ["# CAMERA_ID, MODEL, WIDTH, HEIGHT, PARAMS[]\n"]
+
+    camera_id_map = {}
+    for cam_id, (name, cam) in enumerate(sorted(calibration.cameras.items()), start=1):
+        intr = cam.intrinsics
+        lines.append(
+            f"{cam_id} {intr.model} {intr.width} {intr.height} "
+            + " ".join(_fmt(p) for p in intr.params)
+            + "\n"
+        )
+        camera_id_map[name] = cam_id
+
+    lines.insert(1, f"# Number of cameras: {len(camera_id_map)}\n")
+    path.write_text("".join(lines), encoding="utf-8")
+    return camera_id_map
+
+
+def _write_images_txt(
+    path: Path,
+    images: list[TimestampedImage],
+    calibration: RigCalibration,
+    camera_id_map: dict[str, int],
+) -> dict[int, int]:
+    """Write images.txt with poses from rig calibration.
+
+    Returns:
+        Mapping from IMAGE_ID to timestamp_ns
+    """
+    lines = [
+        "# IMAGE_ID, QW, QX, QY, QZ, TX, TY, TZ, CAMERA_ID, NAME\n",
+        "#   POINTS2D[] as (X, Y, POINT3D_ID)\n",
+    ]
+
+    times = {}
+    image_id = 1
+
+    for img in sorted(images, key=lambda x: (x.frame_index, x.camera_name)):
+        cam_name = img.camera_name
+        if cam_name not in calibration.cameras:
+            raise ValueError(f"Camera {cam_name} not in rig calibration")
+
+        cam = calibration.cameras[cam_name]
+        ext = cam.extrinsics
+        cam_id = camera_id_map[cam_name]
+
+        # Image name includes frame index for clarity
+        image_name = f"frame_{img.frame_index:04d}/{cam_name}.jpg"
+
+        lines.append(
+            f"{image_id} {_fmt(ext.qw)} {_fmt(ext.qx)} {_fmt(ext.qy)} {_fmt(ext.qz)} "
+            f"{_fmt(ext.tx)} {_fmt(ext.ty)} {_fmt(ext.tz)} {cam_id} {image_name}\n"
+        )
+        lines.append("\n")  # Empty POINTS2D line (no observations yet)
+
+        times[image_id] = img.timestamp_ns
+        image_id += 1
+
+    lines.insert(2, f"# Number of images: {len(images)}\n")
+    path.write_text("".join(lines), encoding="utf-8")
+    return times
+
+
+def _write_points3d_txt(path: Path) -> None:
+    """Write empty points3D.txt (placeholder for now)."""
+    lines = [
+        "# POINT3D_ID, X, Y, Z, R, G, B, ERROR, TRACK[] as (IMAGE_ID, POINT2D_IDX)\n",
+        "# Number of points: 0\n",
+    ]
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def convert_fixed_rig_to_colmap4d(
+    calibration_path: Path,
+    images: list[TimestampedImage],
+    output_dir: Path,
+    clock_domain: str = "utc_ntp",
+) -> None:
+    """Convert fixed-rig captures to colmap4d using pre-calibrated poses.
+
+    Args:
+        calibration_path: Path to rig calibration JSON
+        images: List of timestamped images
+        output_dir: Output directory for colmap4d model
+        clock_domain: Time synchronization method (e.g., "utc_ntp")
+    """
+    # Load calibration
+    calibration = RigCalibration.load(calibration_path)
+    print(f"📐 Loaded rig calibration: {calibration.rig_id}")
+    print(f"   Calibrated: {calibration.calibrated_at}")
+    print(f"   Cameras: {len(calibration.cameras)}")
+
+    # Validate images match calibration
+    image_cameras = {img.camera_name for img in images}
+    calib_cameras = set(calibration.cameras.keys())
+    missing = calib_cameras - image_cameras
+    if missing:
+        print(f"⚠️  Warning: calibration has cameras not in images: {missing}")
+
+    extra = image_cameras - calib_cameras
+    if extra:
+        raise ValueError(f"Images contain cameras not in calibration: {extra}")
+
+    # Create output directory
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write COLMAP base model with fixed poses (binary format to handle empty POINTS2D)
+    print(f"\n📝 Writing COLMAP model to {output_dir}...")
+    camera_id_map = _write_cameras_txt(output_dir / "cameras.txt", calibration)
+
+    # Build images using colmap_io structures
+    from colmap4d.colmap_io import Image as ColmapImage
+    from colmap4d.colmap_io import write_images_bin
+
+    colmap_images = {}
+    times_dict = {}
+    image_id = 1
+
+    for img in sorted(images, key=lambda x: (x.frame_index, x.camera_name)):
+        cam_name = img.camera_name
+        if cam_name not in calibration.cameras:
+            raise ValueError(f"Camera {cam_name} not in rig calibration")
+
+        cam = calibration.cameras[cam_name]
+        ext = cam.extrinsics
+        cam_id = camera_id_map[cam_name]
+        image_name = f"frame_{img.frame_index:04d}/{cam_name}.jpg"
+
+        # ColmapImage with empty POINTS2D
+        colmap_images[image_id] = ColmapImage(
+            id=image_id,
+            name=image_name,
+            camera_id=cam_id,
+            qvec=[ext.qw, ext.qx, ext.qy, ext.qz],
+            tvec=[ext.tx, ext.ty, ext.tz],
+            xys=[],
+            point3D_ids=[],
+        )
+        times_dict[image_id] = img.timestamp_ns
+        image_id += 1
+
+    write_images_bin(output_dir / "images.bin", colmap_images)
+    image_times = times_dict
+
+    _write_points3d_txt(output_dir / "points3D.txt")
+
+    # Write colmap4d sidecars
+    print("📝 Writing colmap4d sidecars...")
+
+    # times.txt
+    sidecar.write_times_txt(output_dir / "times.txt", image_times)
+
+    # time_meta.json
+    meta = {
+        "colmap4d_spec": "1.0",
+        "time_convention": "mid_exposure",
+        "clock_domain": clock_domain,
+        "rig_id": calibration.rig_id,
+        "rig_calibration_source": str(calibration_path),
+        "note": "Fixed rig - poses from pre-calibration, not SfM",
+    }
+    sidecar.write_time_meta(output_dir / "time_meta.json", meta)
+
+    print("\n✅ Conversion complete!")
+    print(f"   Output: {output_dir}")
+    print(f"   Images: {len(images)}")
+    print(f"   Frames: {len(set(img.frame_index for img in images))}")
+    print(f"   Cameras per frame: {len(image_cameras)}")