colmap4d 1.0.1__py3-none-any.whl

colmap4d/model.py

@@ -0,0 +1,111 @@
+"""Full colmap4d model = COLMAP base model + time sidecars.
+
+This is the reference reader's core entry point: ``import colmap4d`` then
+``colmap4d.load_model_view(dir)`` gives you a model whose images and points carry time.
+
+The COLMAP base model (cameras/images/points3D) is read by :mod:`colmap4d.colmap_io`, a
+zero-dependency pure-Python reader — so the default path needs no compiled dependency.
+Where **pycolmap** is installed it is preferred (authoritative, and it understands the 3.12
+rigs/frames binary variants); :func:`read_reconstruction` exposes it for callers that need
+full geometry (e.g. the per-frame converter).
+
+Model-aware behavior lives here: the timeless (Part I.A) and dangling-ignored (Part I.D)
+rules are applied against the actual set of model ids, and :mod:`colmap4d.validate`'s graded
+checks are wired to that id set.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from colmap4d import colmap_io, sidecar, validate
+from colmap4d.colmap_io import BaseModel
+from colmap4d.sidecar import TIMELESS, Sidecars
+
+
+def read_base_model(model_dir: str | Path) -> BaseModel:
+    """Read the COLMAP base model with the zero-dependency pure-Python reader."""
+    return colmap_io.read_model(model_dir)
+
+
+def read_reconstruction(model_dir: str | Path) -> Any:
+    """Read the base model via pycolmap (optional dependency), returning its
+    ``pycolmap.Reconstruction``. Use when you need full geometry (poses, 2D observations,
+    rigs/frames). Raises a clear error if pycolmap is not installed."""
+    try:
+        import pycolmap
+    except ImportError as e:  # pragma: no cover - exercised only without the extra
+        raise ImportError(
+            "read_reconstruction needs pycolmap. Install it with:  pip install 'colmap4d[model]'"
+            "   (or: pip install pycolmap). For a dependency-free read use read_base_model()."
+        ) from e
+    return pycolmap.Reconstruction(str(model_dir))
+
+
+@dataclass
+class ModelView:
+    """A COLMAP base model joined with its colmap4d time sidecars.
+
+    The join applies the two Part I rules that need the base model:
+      * temporally-unbounded (I.A): a model point absent from ``points_t`` has time ``None``.
+      * dangling ids ignored (I.D): sidecar ids absent from the model are dropped from the
+        ``effective_*`` views (they remain in ``sidecars`` raw, and are a ``validate`` warning).
+    """
+
+    base: BaseModel
+    sidecars: Sidecars
+
+    def image_ids(self) -> set[int]:
+        return self.base.image_ids()
+
+    def point_ids(self) -> set[int]:
+        return self.base.point_ids()
+
+    def effective_times(self) -> dict[int, int]:
+        """image_id -> t_ns, restricted to images present in the model."""
+        ids = self.image_ids()
+        return {i: t for i, t in self.sidecars.times.items() if i in ids}
+
+    def effective_points_t(self) -> dict[int, int]:
+        """point3d_id -> t_ns, restricted to points present in the model (dangling dropped)."""
+        ids = self.point_ids()
+        return {p: t for p, t in self.sidecars.points_t.items() if p in ids}
+
+    def image_time(self, image_id: int) -> int | None:
+        """t_ns for a model image, or ``None`` if it carries no timestamp."""
+        if image_id not in self.image_ids():
+            raise KeyError(f"image {image_id} not in model")
+        return self.sidecars.times.get(image_id, TIMELESS)
+
+    def point_time(self, point3d_id: int) -> int | None:
+        """t_ns for a model point, or ``TIMELESS`` (None) if temporally-unbounded."""
+        if point3d_id not in self.point_ids():
+            raise KeyError(f"point3D {point3d_id} not in model")
+        return self.sidecars.points_t.get(point3d_id, TIMELESS)
+
+    def t0_ns(self) -> int | None:
+        """Rebase origin = min timestamp over the model's **effective** records (spec I.B).
+
+        Computed over the dangling-dropped join (``effective_times`` ∪ ``effective_points_t``),
+        so a dangling id with an early timestamp cannot shift t0 — this is the authoritative t0
+        two implementations must agree on. ``None`` if the model carries no timestamps.
+        (``Sidecars.t0_ns`` is the model-less approximation over raw records.)
+        """
+        vals = list(self.effective_times().values()) + list(self.effective_points_t().values())
+        return min(vals) if vals else None
+
+
+def load_model_view(model_dir: str | Path, strict: bool = False) -> ModelView:
+    """Read the COLMAP model (zero-dep) + sidecars and return a joined :class:`ModelView`."""
+    base = read_base_model(model_dir)
+    sc = sidecar.load_sidecars(model_dir, strict=strict)
+    return ModelView(base, sc)
+
+
+def validate_full(model_dir: str | Path) -> list[validate.Problem]:
+    """Run the complete validate suite, wiring the model's id sets (read zero-dep) so the
+    dangling-id checks (Part I.D) actually fire. Compute status with ``validate.exit_code``."""
+    base = read_base_model(model_dir)
+    return validate.validate(model_dir, image_ids=base.image_ids(), point_ids=base.point_ids())

colmap4d/sidecar.py

@@ -0,0 +1,255 @@
+"""Zero-dependency reader/writer for the colmap4d time sidecars.
+
+This module handles ONLY the colmap4d delta over a standard COLMAP sparse model:
+
+    times      -- per-image timestamps      (times.txt      / times.bin)
+    points_t   -- per-point timestamps       (points_t.txt   / points_t.bin)
+    time_meta  -- time-axis semantics/prov.  (time_meta.json)
+
+It deliberately does NOT parse the COLMAP base model (cameras/images/points3D).
+That belongs in ``model.py`` and is delegated to pycolmap (an optional dependency),
+keeping "I just want to read the timestamps" a standard-library-only path.
+
+Timestamps are int64 nanoseconds (see spec Part I.B). ``points_t`` is a PARTIAL map:
+a point absent from it is *temporally-unbounded* and is represented here by simple
+absence from the returned dict (see :func:`is_temporally_unbounded`).
+
+Binary layout is defined normatively by the spec, section **I.E "Binary sidecar layout"**
+(little-endian, uint64 count prefix; times record = uint32 image_id + int64 t_ns; points_t
+record = uint64 point3d_id + int64 t_ns; id widths match COLMAP's image_t/point3D_t). This
+module implements that section — the spec, not this docstring, is the source of truth.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Canonical sidecar file names, relative to a COLMAP sparse model directory.
+TIMES_TXT = "times.txt"
+TIMES_BIN = "times.bin"
+POINTS_T_TXT = "points_t.txt"
+POINTS_T_BIN = "points_t.bin"
+TIME_META_JSON = "time_meta.json"
+
+# Struct formats (little-endian). Count prefix is a uint64.
+_COUNT = struct.Struct("<Q")
+_TIMES_REC = struct.Struct("<Iq")  # uint32 image_id, int64 t_ns
+_POINTS_T_REC = struct.Struct("<Qq")  # uint64 point3d_id, int64 t_ns
+
+# Sentinel for a point with no timestamp (present at all t).
+TIMELESS = None
+
+
+# --------------------------------------------------------------------------- #
+# raw pair parsing (duplicates preserved) + normative collapse to a dict
+# --------------------------------------------------------------------------- #
+def _parse_txt_pairs(path: str | Path) -> list[tuple[int, int]]:
+    """All ``(ID, T_NS)`` rows of a text sidecar, in file order, dups preserved."""
+    pairs: list[tuple[int, int]] = []
+    with open(path, encoding="utf-8") as f:
+        for raw in f:
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split()
+            if len(parts) < 2:
+                raise ValueError(f"{path}: malformed line: {raw!r}")
+            pairs.append((int(parts[0]), int(parts[1])))
+    return pairs
+
+
+def _parse_bin_pairs(path: str | Path, rec: struct.Struct) -> list[tuple[int, int]]:
+    """All ``(ID, T_NS)`` records of a binary sidecar, in file order, dups preserved."""
+    data = Path(path).read_bytes()
+    (count,) = _COUNT.unpack_from(data, 0)
+    off = _COUNT.size
+    pairs: list[tuple[int, int]] = []
+    for _ in range(count):
+        key, t_ns = rec.unpack_from(data, off)
+        pairs.append((key, t_ns))
+        off += rec.size
+    return pairs
+
+
+def _pairs_to_dict(pairs: list[tuple[int, int]], strict: bool, path: str | Path) -> dict[int, int]:
+    """Collapse raw pairs to id->t_ns. Duplicate ids resolve **last-wins** (spec Part I:
+    a writer MUST NOT emit duplicates; a reader SHOULD accept and take the last one).
+    ``strict=True`` opts into raising on a duplicate instead."""
+    out: dict[int, int] = {}
+    for key, t_ns in pairs:
+        if strict and key in out:
+            raise ValueError(f"{path}: duplicate id {key} (strict mode)")
+        out[key] = t_ns  # last-wins
+    return out
+
+
+def _write_id_time_txt(path: str | Path, mapping: dict[int, int], header: str) -> None:
+    lines = [header.rstrip("\n") + "\n"]
+    for key in sorted(mapping):
+        lines.append(f"{key} {mapping[key]}\n")
+    Path(path).write_text("".join(lines), encoding="utf-8")
+
+
+def _write_id_time_bin(path: str | Path, mapping: dict[int, int], rec: struct.Struct) -> None:
+    buf = bytearray(_COUNT.pack(len(mapping)))
+    for key in sorted(mapping):
+        buf += rec.pack(key, mapping[key])
+    Path(path).write_bytes(bytes(buf))
+
+
+# --------------------------------------------------------------------------- #
+# times
+# --------------------------------------------------------------------------- #
+def read_times_txt(path: str | Path, strict: bool = False) -> dict[int, int]:
+    """image_id -> t_ns, from times.txt (last-wins on dup ids; see :func:`_pairs_to_dict`)."""
+    return _pairs_to_dict(_parse_txt_pairs(path), strict, path)
+
+
+def read_times_bin(path: str | Path, strict: bool = False) -> dict[int, int]:
+    """image_id -> t_ns, from times.bin (last-wins on dup ids)."""
+    return _pairs_to_dict(_parse_bin_pairs(path, _TIMES_REC), strict, path)
+
+
+def read_times_pairs(path: str | Path) -> list[tuple[int, int]]:
+    """Raw (image_id, t_ns) rows with duplicates preserved (for validation)."""
+    if str(path).endswith(".bin"):
+        return _parse_bin_pairs(path, _TIMES_REC)
+    return _parse_txt_pairs(path)
+
+
+def write_times_txt(path: str | Path, times: dict[int, int]) -> None:
+    _write_id_time_txt(
+        path,
+        times,
+        f"# colmap4d times: IMAGE_ID, T_NS (int64 ns)\n# Number of images: {len(times)}",
+    )
+
+
+def write_times_bin(path: str | Path, times: dict[int, int]) -> None:
+    _write_id_time_bin(path, times, _TIMES_REC)
+
+
+# --------------------------------------------------------------------------- #
+# points_t
+# --------------------------------------------------------------------------- #
+def read_points_t_txt(path: str | Path, strict: bool = False) -> dict[int, int]:
+    """point3d_id -> t_ns, from points_t.txt (PARTIAL map; last-wins on dup ids)."""
+    return _pairs_to_dict(_parse_txt_pairs(path), strict, path)
+
+
+def read_points_t_bin(path: str | Path, strict: bool = False) -> dict[int, int]:
+    """point3d_id -> t_ns, from points_t.bin (PARTIAL map; last-wins on dup ids)."""
+    return _pairs_to_dict(_parse_bin_pairs(path, _POINTS_T_REC), strict, path)
+
+
+def read_points_t_pairs(path: str | Path) -> list[tuple[int, int]]:
+    """Raw (point3d_id, t_ns) rows with duplicates preserved (for validation)."""
+    if str(path).endswith(".bin"):
+        return _parse_bin_pairs(path, _POINTS_T_REC)
+    return _parse_txt_pairs(path)
+
+
+def write_points_t_txt(path: str | Path, points_t: dict[int, int]) -> None:
+    _write_id_time_txt(
+        path,
+        points_t,
+        "# colmap4d points_t: POINT3D_ID, T_NS (int64 ns); PARTIAL map, "
+        "absent point == temporally-unbounded\n"
+        f"# Number of points with a timestamp: {len(points_t)}",
+    )
+
+
+def write_points_t_bin(path: str | Path, points_t: dict[int, int]) -> None:
+    _write_id_time_bin(path, points_t, _POINTS_T_REC)
+
+
+def is_temporally_unbounded(points_t: dict[int, int], point3d_id: int) -> bool:
+    """True if the point has no timestamp (present at all t). See spec Part I.A."""
+    return point3d_id not in points_t
+
+
+# --------------------------------------------------------------------------- #
+# time_meta
+# --------------------------------------------------------------------------- #
+def read_time_meta(path: str | Path) -> dict:
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_time_meta(path: str | Path, meta: dict) -> None:
+    Path(path).write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+
+
+# --------------------------------------------------------------------------- #
+# directory-level loading (backward compatible)
+# --------------------------------------------------------------------------- #
+@dataclass
+class Sidecars:
+    """The colmap4d time layer for one sparse model directory.
+
+    A plain COLMAP model (no sidecars) yields empty maps and ``time_meta is None``;
+    this is the backward-compatibility baseline and must never raise.
+    """
+
+    times: dict[int, int] = field(default_factory=dict)
+    points_t: dict[int, int] = field(default_factory=dict)
+    time_meta: dict | None = None
+
+    def point_time(self, point3d_id: int) -> int | None:
+        """t_ns for a point, or ``TIMELESS`` (None) if temporally-unbounded."""
+        return self.points_t.get(point3d_id, TIMELESS)
+
+    def t0_ns(self) -> int | None:
+        """Rebase origin = min timestamp over the **raw** sidecar records — an APPROXIMATION.
+
+        The authoritative t0 (spec I.B) is the min over the model-joined, dangling-dropped
+        records; this method has no base model, so a dangling id with an early timestamp would
+        pull it earlier. Use ``colmap4d.model.ModelView.t0_ns()`` when the base model is
+        available. ``None`` when there are no timestamps at all.
+        """
+        vals = list(self.times.values()) + list(self.points_t.values())
+        return min(vals) if vals else None
+
+
+def load_sidecars(model_dir: str | Path, strict: bool = False) -> Sidecars:
+    """Load the time sidecars from a COLMAP sparse model directory.
+
+    Binary is preferred over text when both are present (matching COLMAP). Missing
+    sidecars are treated as empty, never as an error. Duplicate ids resolve last-wins
+    (spec Part I); pass ``strict=True`` to raise on a duplicate instead.
+
+    Note: this reader does not know the base model, so it cannot drop ids that are
+    absent from the model. Ignoring model-absent (dangling) ids is the consuming
+    layer's job (spec Part I: a reader MUST ignore ids not present in the model); see
+    ``colmap4d.model`` and ``colmap4d.validate``.
+    """
+    d = Path(model_dir)
+    sc = Sidecars()
+
+    if (d / TIMES_BIN).exists():
+        sc.times = read_times_bin(d / TIMES_BIN, strict=strict)
+    elif (d / TIMES_TXT).exists():
+        sc.times = read_times_txt(d / TIMES_TXT, strict=strict)
+
+    if (d / POINTS_T_BIN).exists():
+        sc.points_t = read_points_t_bin(d / POINTS_T_BIN, strict=strict)
+    elif (d / POINTS_T_TXT).exists():
+        sc.points_t = read_points_t_txt(d / POINTS_T_TXT, strict=strict)
+
+    if (d / TIME_META_JSON).exists():
+        sc.time_meta = read_time_meta(d / TIME_META_JSON)
+
+    return sc
+
+
+def rebase_to_seconds_f32(t_ns: int, t0_ns: int) -> float:
+    """Convert an int64-ns timestamp to a rebased float ``(t - t0)`` in seconds.
+
+    Rendering/GPU code MUST rebase before narrowing to float32: raw ns (~1.7e18)
+    overflows float32's 24-bit mantissa, but ``(t - t0)`` over a capture spans only
+    seconds and keeps ~microsecond precision as float32. See spec Part I.B.
+    """
+    return (t_ns - t0_ns) / 1e9

colmap4d/validate.py

@@ -0,0 +1,184 @@
+"""`colmap4d validate` — model sanity checks with graded severity and exit codes.
+
+Conformance is a claim a CI job must be able to reject, so `validate` grades problems
+instead of only warning (all-warnings ⇒ exit 0 always ⇒ "conforms" becomes unfalsifiable):
+
+    ERROR   -- violates a spec MUST; exit code is non-zero. Duplicate ids and
+               device/camera_id conflicts are the writer's bug and land here.
+    WARNING -- suspicious but has legitimate uses (e.g. a sidecar kept as a superset
+               of a filtered model); exit code stays 0 unless the caller opts into
+               `strict=True`, which promotes WARNINGs to failures for strict pipelines.
+
+Reader tolerance (last-wins on duplicates, ignore model-absent ids) is defined in the
+spec and implemented in :mod:`colmap4d.sidecar`; this module reports on those situations
+rather than silently absorbing them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from colmap4d import sidecar
+
+ERROR = "ERROR"
+WARNING = "WARNING"
+
+
+@dataclass
+class Problem:
+    severity: str  # ERROR | WARNING
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"[{self.severity}] {self.code}: {self.message}"
+
+
+def exit_code(problems: list[Problem], strict: bool = False) -> int:
+    """0 if clean; non-zero if any ERROR, or (when ``strict``) any WARNING."""
+    if any(p.severity == ERROR for p in problems):
+        return 1
+    if strict and any(p.severity == WARNING for p in problems):
+        return 1
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# individual checks
+# --------------------------------------------------------------------------- #
+def check_duplicate_ids(pairs: list[tuple[int, int]], kind: str) -> list[Problem]:
+    """ERROR per id that appears more than once (writer MUST NOT emit duplicates;
+    readers last-wins, so the earlier timestamps are silently lost)."""
+    counts: dict[int, int] = {}
+    order: list[int] = []
+    for key, _ in pairs:
+        if key not in counts:
+            order.append(key)
+        counts[key] = counts.get(key, 0) + 1
+    problems: list[Problem] = []
+    for key in order:
+        if counts[key] > 1:
+            problems.append(
+                Problem(
+                    ERROR,
+                    f"{kind}.duplicate_id",
+                    f"id {key} appears {counts[key]} times in the {kind} sidecar; a writer "
+                    f"MUST NOT emit duplicates (readers take last-wins, losing the rest).",
+                )
+            )
+    return problems
+
+
+def check_dangling_ids(keys: list[int], valid_ids: set[int], kind: str) -> list[Problem]:
+    """WARNING if the sidecar references ids absent from the model.
+
+    Worded to name the real hazard: after an SfM re-run the dangerous case is not the id
+    that vanished but the one that still exists yet now points at a *different* image —
+    a silently mislabeled timestamp. A dangling id is often the only visible symptom.
+    """
+    dangling = sorted({k for k in keys if k not in valid_ids})
+    if not dangling:
+        return []
+    sample = ", ".join(str(k) for k in dangling[:5]) + (" …" if len(dangling) > 5 else "")
+    return [
+        Problem(
+            WARNING,
+            f"{kind}.dangling_id",
+            f"{len(dangling)} id(s) in the {kind} sidecar are not in the model ({sample}). "
+            f"If SfM was re-run, ids may be globally misaligned — surviving ids can now "
+            f"point at different entities, silently mislabeling timestamps. Regenerate the "
+            f"sidecar from the current model rather than trusting the survivors.",
+        )
+    ]
+
+
+def check_time_meta_present(times: dict[int, int], time_meta: dict | None) -> list[Problem]:
+    """WARNING if a ``times`` sidecar exists but ``time_meta`` is absent (spec I.C). Without it
+    the timestamps have no declared clock domain / exposure convention and are only a relative
+    axis; a producer SHOULD declare provenance."""
+    if times and time_meta is None:
+        return [
+            Problem(
+                WARNING,
+                "time_meta.absent",
+                "times sidecar present but time_meta.json is absent; timestamps have undeclared "
+                "semantics (relative time only — MUST NOT be compared across models or to "
+                "wall-clock). A producer SHOULD write time_meta declaring clock_domain and "
+                "time_convention.",
+            )
+        ]
+    return []
+
+
+def check_device_camera_ids_unique(time_meta: dict | None) -> list[Problem]:
+    """ERROR if a CAMERA_ID is attributed to more than one device (spec Part I: one
+    image cannot be timestamped by two clocks). Absent time_meta/devices/camera_ids is OK.
+    """
+    if not time_meta:
+        return []
+    devices = time_meta.get("devices")
+    if not isinstance(devices, dict):
+        return []
+    problems: list[Problem] = []
+    seen: dict[int, str] = {}
+    for device_id, dev in devices.items():
+        if not isinstance(dev, dict):
+            continue
+        for cam_id in dev.get("camera_ids", []) or []:
+            prior = seen.get(cam_id)
+            if prior is not None and prior != device_id:
+                problems.append(
+                    Problem(
+                        ERROR,
+                        "time_meta.camera_id_conflict",
+                        f"CAMERA_ID {cam_id} is attributed to multiple devices "
+                        f"({prior!r} and {device_id!r}); a camera belongs to one clock.",
+                    )
+                )
+            else:
+                seen[cam_id] = device_id
+    return problems
+
+
+# --------------------------------------------------------------------------- #
+# orchestration
+# --------------------------------------------------------------------------- #
+def validate(
+    model_dir: str | Path,
+    *,
+    image_ids: set[int] | None = None,
+    point_ids: set[int] | None = None,
+) -> list[Problem]:
+    """Run all available checks over a model directory and return graded problems.
+
+    Duplicate-id and device/camera checks need no base model. Dangling-id checks run only
+    when the caller supplies the model's id sets (``image_ids`` / ``point_ids``); wiring
+    those from the base model via pycolmap belongs to :mod:`colmap4d.model` (not yet built).
+    Compute process status with :func:`exit_code`.
+    """
+    d = Path(model_dir)
+    problems: list[Problem] = []
+
+    for bin_name, txt_name, kind, valid in (
+        (sidecar.TIMES_BIN, sidecar.TIMES_TXT, "times", image_ids),
+        (sidecar.POINTS_T_BIN, sidecar.POINTS_T_TXT, "points_t", point_ids),
+    ):
+        path = (
+            d / bin_name
+            if (d / bin_name).exists()
+            else (d / txt_name if (d / txt_name).exists() else None)
+        )
+        if path is None:
+            continue
+        pairs = (
+            sidecar.read_times_pairs(path) if kind == "times" else sidecar.read_points_t_pairs(path)
+        )
+        problems += check_duplicate_ids(pairs, kind)
+        if valid is not None:
+            problems += check_dangling_ids([k for k, _ in pairs], valid, kind)
+
+    sc = sidecar.load_sidecars(d)
+    problems += check_time_meta_present(sc.times, sc.time_meta)
+    problems += check_device_camera_ids_unique(sc.time_meta)
+    return problems

colmap4d-1.0.1.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: colmap4d
+Version: 1.0.1
+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
+
+**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 [`spec/colmap4d-v1.0.md`](spec/colmap4d-v1.0.md); Part I and the
+> conformance goldens are normative, and changes follow [`spec/CHANGELOG.md`](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.
+
+## 30-second quickstart
+
+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.image_ids()                 # {1, 2, 3, ...}
+mv.image_time(1)               # -> t_ns (int64 nanoseconds), or None if no timestamp
+mv.point_time(42)              # -> t_ns, or None if the point is temporally-unbounded
+mv.effective_times()           # {image_id: t_ns} for images in the model
+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 reading the base model:
+
+```python
+sc = colmap4d.load_sidecars("path/to/sparse")
+sc.times[image_id]             # -> t_ns
+sc.point_time(point3d_id)      # -> t_ns, or None (temporally-unbounded)
+```
+
+Validate a model (graded checks, non-zero exit on ERROR):
+
+```python
+from colmap4d import validate_full
+from colmap4d.validate import exit_code
+problems = validate_full("path/to/sparse")     # duplicate ids = ERROR, dangling = WARNING
+code = exit_code(problems, strict=False)        # 0 if clean
+```
+
+A plain COLMAP model (no sidecars) loads fine: empty times, all points temporally-unbounded —
+the backward-compatibility baseline.
+
+The reader is **standard-library only**. `colmap4d.colmap_io` parses the classic COLMAP
+txt/bin base model; where `pycolmap` is installed (optional extra `pip install
+'colmap4d[model]'`) it is preferred for authoritative parsing and 3.12 rigs/frames support.
+
+## Repository layout
+
+```
+spec/          the format specification (normative surface)
+src/colmap4d/  reference implementation
+  sidecar.py     zero-dep read/write of times / points_t / time_meta
+  colmap_io.py   zero-dep COLMAP base-model reader/writer (classic txt/bin)
+  model.py       base model + sidecars join (ModelView, load_model_view, validate_full)
+  convert/       importers: the format's "writer" side
+    per_frame_colmap.py   N per-frame COLMAP dirs -> one colmap4d model
+  validate.py    graded checks (duplicate=ERROR, dangling=WARNING) + exit codes
+  groups.py      derived pseudo-frame grouping                 (placeholder)
+conformance/   hand-authored golden models + tests (the executable spec)
+docs/          open questions, notes
+```
+
+## Viewer
+
+The interactive 4D viewer is a **separate project** (different stack, heavier build,
+faster release cadence). Today that is the `ColmapUtil` React viewer living alongside this
+repo (`../ColmapUtil`); it already opens standard COLMAP models and is being extended for
+the colmap4d time axis. It will be linked here once published under the org.
+
+## Versioning
+
+Two **independent** version axes:
+
+| axis | where | meaning |
+|------|-------|---------|
+| **Package version** | `pyproject.toml` (`1.0.1`) | the Python implementation — bumps for any code change (bug fixes, new converters, API tweaks). |
+| **Spec version** | `spec/` title + `time_meta.colmap4d_spec` (`1.0`) | the on-disk **protocol** — bumps only on a protocol change. |
+
+They move at different rates: the package can release many times against one frozen spec.
+**This package (1.0.1) implements spec v1.0.** Protocol changes are logged in
+[`spec/CHANGELOG.md`](spec/CHANGELOG.md).
+
+## Development
+
+```bash
+pip install ruff pytest
+ruff check . && ruff format --check .
+pytest                     # runs the conformance suite
+```
+
+## License
+
+[Apache-2.0](LICENSE).