colmap4d 1.0.1__py3-none-any.whl

colmap4d/__init__.py

@@ -0,0 +1,57 @@
+"""colmap4d — standard COLMAP sparse model + per-image and per-point timestamps.
+
+The zero-dependency time layer lives in :mod:`colmap4d.sidecar`. Base-model parsing
+(cameras/images/points3D) is delegated to pycolmap in :mod:`colmap4d.model` (optional
+dependency, not implemented yet).
+"""
+
+from __future__ import annotations
+
+from colmap4d.model import (
+    ModelView,
+    load_model_view,
+    read_base_model,
+    validate_full,
+)
+from colmap4d.sidecar import (
+    TIMELESS,
+    Sidecars,
+    is_temporally_unbounded,
+    load_sidecars,
+    read_points_t_bin,
+    read_points_t_txt,
+    read_time_meta,
+    read_times_bin,
+    read_times_txt,
+    rebase_to_seconds_f32,
+    write_points_t_bin,
+    write_points_t_txt,
+    write_time_meta,
+    write_times_bin,
+    write_times_txt,
+)
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "TIMELESS",
+    "ModelView",
+    "Sidecars",
+    "is_temporally_unbounded",
+    "load_model_view",
+    "load_sidecars",
+    "read_base_model",
+    "validate_full",
+    "rebase_to_seconds_f32",
+    "read_points_t_bin",
+    "read_points_t_txt",
+    "read_time_meta",
+    "read_times_bin",
+    "read_times_txt",
+    "write_points_t_bin",
+    "write_points_t_txt",
+    "write_time_meta",
+    "write_times_bin",
+    "write_times_txt",
+    "__version__",
+]

colmap4d/colmap_io.py

@@ -0,0 +1,261 @@
+"""Zero-dependency reader/writer for the COLMAP base model (cameras/images/points3D).
+
+This is the pure-Python fallback so ``import colmap4d`` can read a timestamped model with no
+compiled dependency. pycolmap remains the *preferred* backend where installed (it is
+authoritative and also understands the 3.12 rigs/frames binary variants); this reader targets
+the classic cameras/images/points3D text and binary layouts, which cover the vast majority of
+models in the wild and every model colmap4d itself writes.
+
+Binary layout follows COLMAP's ``reconstruction_io`` (little-endian, count-prefixed):
+    cameras.bin  : u64 count, then [u32 id, i32 model_id, u64 w, u64 h, f64 params[k]]
+    images.bin   : u64 count, then [u32 id, f64 qw qx qy qz, f64 tx ty tz, u32 cam_id,
+                   name\\0, u64 n2d, [f64 x, f64 y, u64 point3D_id] * n2d]
+    points3D.bin : u64 count, then [u64 id, f64 x y z, u8 r g b, f64 error,
+                   u64 track_len, [u32 image_id, u32 point2D_idx] * track_len]
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# COLMAP camera model id <-> name and parameter counts.
+_MODEL_ID_TO_NAME = {
+    0: "SIMPLE_PINHOLE",
+    1: "PINHOLE",
+    2: "SIMPLE_RADIAL",
+    3: "RADIAL",
+    4: "OPENCV",
+    5: "OPENCV_FISHEYE",
+    6: "FULL_OPENCV",
+    7: "FOV",
+    8: "SIMPLE_RADIAL_FISHEYE",
+    9: "RADIAL_FISHEYE",
+    10: "THIN_PRISM_FISHEYE",
+}
+_MODEL_NAME_TO_ID = {v: k for k, v in _MODEL_ID_TO_NAME.items()}
+_MODEL_NUM_PARAMS = {0: 3, 1: 4, 2: 4, 3: 5, 4: 8, 5: 8, 6: 12, 7: 5, 8: 4, 9: 5, 10: 12}
+
+# COLMAP's sentinel for "this 2D point has no 3D point".
+INVALID_POINT3D_ID = 18446744073709551615
+
+
+@dataclass
+class Camera:
+    id: int
+    model: str
+    width: int
+    height: int
+    params: list[float]
+
+
+@dataclass
+class Image:
+    id: int
+    name: str
+    camera_id: int
+    qvec: list[float]  # [qw, qx, qy, qz]
+    tvec: list[float]  # [tx, ty, tz]
+    xys: list[tuple[float, float]] = field(default_factory=list)
+    point3D_ids: list[int] = field(default_factory=list)  # INVALID_POINT3D_ID where none
+
+
+@dataclass
+class Point3D:
+    id: int
+    xyz: list[float]
+    rgb: list[int]
+    error: float
+    track: list[tuple[int, int]]  # (image_id, point2D_idx)
+
+
+@dataclass
+class BaseModel:
+    cameras: dict[int, Camera] = field(default_factory=dict)
+    images: dict[int, Image] = field(default_factory=dict)
+    points3D: dict[int, Point3D] = field(default_factory=dict)
+
+    def image_ids(self) -> set[int]:
+        return set(self.images)
+
+    def point_ids(self) -> set[int]:
+        return set(self.points3D)
+
+
+# --------------------------------------------------------------------------- #
+# binary helpers
+# --------------------------------------------------------------------------- #
+def _r(f, fmt: str):
+    s = struct.Struct("<" + fmt)
+    return s.unpack(f.read(s.size))
+
+
+def _w(f, fmt: str, *vals) -> None:
+    f.write(struct.pack("<" + fmt, *vals))
+
+
+# --------------------------------------------------------------------------- #
+# text parsing helpers
+# --------------------------------------------------------------------------- #
+def _data_lines(path: str | Path) -> list[str]:
+    out = []
+    with open(path, encoding="utf-8") as fh:
+        for raw in fh:
+            line = raw.strip()
+            if line and not line.startswith("#"):
+                out.append(line)
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# cameras
+# --------------------------------------------------------------------------- #
+def read_cameras_txt(path: str | Path) -> dict[int, Camera]:
+    cams = {}
+    for line in _data_lines(path):
+        p = line.split()
+        cid = int(p[0])
+        cams[cid] = Camera(cid, p[1], int(p[2]), int(p[3]), [float(x) for x in p[4:]])
+    return cams
+
+
+def read_cameras_bin(path: str | Path) -> dict[int, Camera]:
+    cams = {}
+    with open(path, "rb") as f:
+        (n,) = _r(f, "Q")
+        for _ in range(n):
+            cid, model_id, w, h = _r(f, "IiQQ")
+            k = _MODEL_NUM_PARAMS[model_id]
+            params = list(_r(f, f"{k}d"))
+            cams[cid] = Camera(cid, _MODEL_ID_TO_NAME[model_id], w, h, params)
+    return cams
+
+
+def write_cameras_bin(path: str | Path, cams: dict[int, Camera]) -> None:
+    with open(path, "wb") as f:
+        _w(f, "Q", len(cams))
+        for cid in sorted(cams):
+            c = cams[cid]
+            _w(f, "IiQQ", cid, _MODEL_NAME_TO_ID[c.model], c.width, c.height)
+            _w(f, f"{len(c.params)}d", *c.params)
+
+
+# --------------------------------------------------------------------------- #
+# images
+# --------------------------------------------------------------------------- #
+def read_images_txt(path: str | Path) -> dict[int, Image]:
+    lines = _data_lines(path)
+    images = {}
+    for i in range(0, len(lines), 2):
+        head = lines[i].split()
+        iid = int(head[0])
+        qvec = [float(x) for x in head[1:5]]
+        tvec = [float(x) for x in head[5:8]]
+        cam_id = int(head[8])
+        name = head[9]
+        xys, ids = [], []
+        pts = lines[i + 1].split() if i + 1 < len(lines) else []
+        for j in range(0, len(pts), 3):
+            xys.append((float(pts[j]), float(pts[j + 1])))
+            pid = int(pts[j + 2])
+            ids.append(INVALID_POINT3D_ID if pid < 0 else pid)
+        images[iid] = Image(iid, name, cam_id, qvec, tvec, xys, ids)
+    return images
+
+
+def read_images_bin(path: str | Path) -> dict[int, Image]:
+    images = {}
+    with open(path, "rb") as f:
+        (n,) = _r(f, "Q")
+        for _ in range(n):
+            iid, qw, qx, qy, qz, tx, ty, tz, cam_id = _r(f, "IdddddddI")
+            name = bytearray()
+            while (ch := f.read(1)) not in (b"\x00", b""):
+                name += ch
+            (n2d,) = _r(f, "Q")
+            xys, ids = [], []
+            for _ in range(n2d):
+                x, y, pid = _r(f, "ddQ")
+                xys.append((x, y))
+                ids.append(pid)
+            images[iid] = Image(
+                iid, name.decode("utf-8"), cam_id, [qw, qx, qy, qz], [tx, ty, tz], xys, ids
+            )
+    return images
+
+
+def write_images_bin(path: str | Path, images: dict[int, Image]) -> None:
+    with open(path, "wb") as f:
+        _w(f, "Q", len(images))
+        for iid in sorted(images):
+            im = images[iid]
+            _w(f, "Iddddddd", iid, *im.qvec, *im.tvec)
+            _w(f, "I", im.camera_id)
+            f.write(im.name.encode("utf-8") + b"\x00")
+            _w(f, "Q", len(im.xys))
+            for (x, y), pid in zip(im.xys, im.point3D_ids):
+                _w(f, "ddQ", x, y, pid)
+
+
+# --------------------------------------------------------------------------- #
+# points3D
+# --------------------------------------------------------------------------- #
+def read_points3D_txt(path: str | Path) -> dict[int, Point3D]:
+    pts = {}
+    for line in _data_lines(path):
+        p = line.split()
+        pid = int(p[0])
+        xyz = [float(x) for x in p[1:4]]
+        rgb = [int(x) for x in p[4:7]]
+        error = float(p[7])
+        rest = p[8:]
+        track = [(int(rest[k]), int(rest[k + 1])) for k in range(0, len(rest), 2)]
+        pts[pid] = Point3D(pid, xyz, rgb, error, track)
+    return pts
+
+
+def read_points3D_bin(path: str | Path) -> dict[int, Point3D]:
+    pts = {}
+    with open(path, "rb") as f:
+        (n,) = _r(f, "Q")
+        for _ in range(n):
+            pid, x, y, z, r, g, b, error, tl = _r(f, "QdddBBBdQ")
+            track = [tuple(_r(f, "II")) for _ in range(tl)]
+            pts[pid] = Point3D(pid, [x, y, z], [r, g, b], error, track)
+    return pts
+
+
+def write_points3D_bin(path: str | Path, pts: dict[int, Point3D]) -> None:
+    with open(path, "wb") as f:
+        _w(f, "Q", len(pts))
+        for pid in sorted(pts):
+            p = pts[pid]
+            _w(f, "QdddBBBdQ", pid, *p.xyz, *p.rgb, p.error, len(p.track))
+            for img_id, idx in p.track:
+                _w(f, "II", img_id, idx)
+
+
+# --------------------------------------------------------------------------- #
+# whole model
+# --------------------------------------------------------------------------- #
+def read_model(model_dir: str | Path) -> BaseModel:
+    """Read cameras/images/points3D from a COLMAP model dir. Binary is preferred over text
+    when both are present (matching COLMAP)."""
+    d = Path(model_dir)
+
+    def pick(stem: str):
+        if (d / f"{stem}.bin").exists():
+            return d / f"{stem}.bin", "bin"
+        if (d / f"{stem}.txt").exists():
+            return d / f"{stem}.txt", "txt"
+        raise FileNotFoundError(f"no {stem}.bin or {stem}.txt in {d}")
+
+    cpath, ck = pick("cameras")
+    ipath, ik = pick("images")
+    ppath, pk = pick("points3D")
+    return BaseModel(
+        cameras=read_cameras_bin(cpath) if ck == "bin" else read_cameras_txt(cpath),
+        images=read_images_bin(ipath) if ik == "bin" else read_images_txt(ipath),
+        points3D=read_points3D_bin(ppath) if pk == "bin" else read_points3D_txt(ppath),
+    )

colmap4d/convert/__init__.py

@@ -0,0 +1,18 @@
+"""Converters into colmap4d — the format's "writer" side.
+
+One importer per stock data layout, turning already-existing data into colmap4d so the
+format's data "exists" in the world:
+
+    per_frame_colmap  -- N per-frame COLMAP dirs -> one colmap4d model   (IMPLEMENTED)
+    nerfstudio        -- transforms.json (time field), bidirectional     (planned)
+    neu3d / dynerf    -- first-frame COLMAP + video frame indices         (planned)
+    hypernerf / nerfies                                                   (planned)
+
+Each importer emits standard COLMAP files plus the three time sidecars.
+"""
+
+from __future__ import annotations
+
+from colmap4d.convert.per_frame_colmap import convert_per_frame_colmap
+
+__all__ = ["convert_per_frame_colmap"]

colmap4d/convert/per_frame_colmap.py

@@ -0,0 +1,233 @@
+"""Convert a per-frame COLMAP capture into a single colmap4d model.
+
+Input: an ordered list of per-frame COLMAP sparse models (``colmap_0/…``, ``colmap_1/…``),
+each an independent reconstruction of the *same rig at one time instant*. Output: one standard
+COLMAP model + colmap4d sidecars, where each image and point carries that frame's timestamp.
+
+Design choices (each traces to a white-paper principle; the contentious one is flagged):
+
+* **Points: per-frame independent, NO cross-frame dedup (default).** White paper §3.3: a
+  per-frame import honestly samples a persistent structure as one point *per frame*. Every
+  frame's points are kept and remapped to globally-unique ids; each gets its frame's time.
+  Cross-frame dedup would fabricate correspondences COLMAP never computed and collapse the
+  honest samples into a "conclusion" — it violates "store observations, not conclusions"
+  (§2). Per the author (white paper Q3/§3.3, OPEN-6 settled), cross-frame dedup is a derived
+  view / downstream optimization and is **out of scope for v1**: ``dedup_points=True`` stays
+  reserved and is refused.
+
+* **Cameras: per-frame independent, remapped (lossless).** Real captures reassign COLMAP
+  ``CAMERA_ID`` per frame (one frame may share a single intrinsic across all physical cameras,
+  another may give each its own), so intrinsics are kept as-is per frame rather than reconciled.
+  The stable physical-camera identity is the **image name**, preserved as ``frame_XXXX/<name>``
+  and surfaced in ``time_meta.devices`` keyed by name.
+
+* **Timestamps: frame instant.** All images in one frame share the frame's time, so every
+  point's per-track-centroid time is exactly that instant (II.1 degenerates cleanly). Real
+  timestamps are used when supplied; otherwise synthesized as ``frame_index * frame_interval_ns``
+  and marked synthetic in ``time_meta`` (clock_domain ``synthetic_frame_index``).
+
+Reads base models via pycolmap (optional dependency); writes COLMAP text + text sidecars.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+from colmap4d import model, sidecar
+
+# 30 fps default when no real timestamps are provided.
+DEFAULT_FRAME_INTERVAL_NS = 33_333_333
+
+
+@dataclass
+class ConversionResult:
+    out_dir: Path
+    num_frames: int
+    num_cameras: int
+    num_images: int
+    num_points: int
+    frame_interval_ns: int
+    synthetic_times: bool
+
+
+def _fmt(x: float) -> str:
+    return f"{x:.12g}"
+
+
+def _write_cameras_txt(path: Path, cams: list[tuple]) -> None:
+    lines = ["# CAMERA_ID, MODEL, WIDTH, HEIGHT, PARAMS[]\n", f"# Number of cameras: {len(cams)}\n"]
+    for cid, model_name, w, h, params in cams:
+        lines.append(f"{cid} {model_name} {w} {h} " + " ".join(_fmt(p) for p in params) + "\n")
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def _write_images_txt(path: Path, images: dict, obs: dict) -> None:
+    lines = [
+        "# IMAGE_ID, QW, QX, QY, QZ, TX, TY, TZ, CAMERA_ID, NAME\n",
+        "#   POINTS2D[] as (X, Y, POINT3D_ID)\n",
+        f"# Number of images: {len(images)}\n",
+    ]
+    for iid in sorted(images):
+        im = images[iid]
+        lines.append(
+            f"{iid} {_fmt(im['qw'])} {_fmt(im['qx'])} {_fmt(im['qy'])} {_fmt(im['qz'])} "
+            f"{_fmt(im['tx'])} {_fmt(im['ty'])} {_fmt(im['tz'])} {im['cam']} {im['name']}\n"
+        )
+        pts = obs.get(iid, [])
+        lines.append(" ".join(f"{_fmt(x)} {_fmt(y)} {pid}" for x, y, pid in pts) + "\n")
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def _write_points3d_txt(path: Path, points: dict) -> None:
+    lines = [
+        "# POINT3D_ID, X, Y, Z, R, G, B, ERROR, TRACK[] as (IMAGE_ID, POINT2D_IDX)\n",
+        f"# Number of points: {len(points)}\n",
+    ]
+    for pid in sorted(points):
+        p = points[pid]
+        x, y, z = p["xyz"]
+        r, g, b = p["rgb"]
+        track = " ".join(f"{iid} {idx}" for iid, idx in p["track"])
+        head = f"{pid} {_fmt(x)} {_fmt(y)} {_fmt(z)} {r} {g} {b} {_fmt(p['error'])}"
+        lines.append(f"{head} {track}\n")
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def convert_per_frame_colmap(
+    frame_dirs: list[str | Path],
+    out_dir: str | Path,
+    *,
+    frame_times_ns: list[int] | None = None,
+    frame_interval_ns: int = DEFAULT_FRAME_INTERVAL_NS,
+    dedup_points: bool = False,
+) -> ConversionResult:
+    """Merge ``frame_dirs`` (ordered per-frame COLMAP models) into a colmap4d model at ``out_dir``.
+
+    ``frame_times_ns`` gives an explicit timestamp per frame; when omitted, timestamps are
+    synthesized as ``index * frame_interval_ns`` and flagged synthetic in ``time_meta``.
+    """
+    if dedup_points:
+        raise NotImplementedError(
+            "cross-frame point dedup is out of scope for v1 (OPEN-6, settled per white paper "
+            "Q3/§3.3): per-frame imports keep independent xyzt samples; dedup is a derived "
+            "view / downstream optimization. dedup_points is reserved and refused."
+        )
+    frame_dirs = [Path(d) for d in frame_dirs]
+    if frame_times_ns is not None and len(frame_times_ns) != len(frame_dirs):
+        raise ValueError("frame_times_ns must match frame_dirs length")
+
+    cam_map: dict[tuple[int, int], int] = {}
+    img_map: dict[tuple[int, int], int] = {}
+    new_cameras: list[tuple] = []
+    new_images: dict[int, dict] = {}
+    new_points: dict[int, dict] = {}
+    obs: dict[int, list] = defaultdict(list)
+    times: dict[int, int] = {}
+    points_t: dict[int, int] = {}
+    name_to_camids: dict[str, set[int]] = defaultdict(set)
+    camid_to_names: dict[int, set[str]] = defaultdict(set)
+
+    next_cam = next_img = next_pt = 1
+    for f, d in enumerate(frame_dirs):
+        rec = model.read_reconstruction(d)
+        t = frame_times_ns[f] if frame_times_ns is not None else f * frame_interval_ns
+
+        for cid, cam in rec.cameras.items():
+            cam_map[(f, int(cid))] = next_cam
+            new_cameras.append(
+                (next_cam, cam.model.name, cam.width, cam.height, [float(p) for p in cam.params])
+            )
+            next_cam += 1
+
+        for iid, im in rec.images.items():
+            new_img = next_img
+            next_img += 1
+            img_map[(f, int(iid))] = new_img
+            cfw = im.cam_from_world()
+            q = cfw.rotation.quat  # [x, y, z, w]
+            tr = cfw.translation
+            new_cam = cam_map[(f, int(im.camera_id))]
+            stem = Path(im.name).stem
+            new_images[new_img] = {
+                "qw": float(q[3]),
+                "qx": float(q[0]),
+                "qy": float(q[1]),
+                "qz": float(q[2]),
+                "tx": float(tr[0]),
+                "ty": float(tr[1]),
+                "tz": float(tr[2]),
+                "cam": new_cam,
+                "name": f"frame_{f:04d}/{im.name}",
+            }
+            times[new_img] = t
+            name_to_camids[stem].add(new_cam)
+            camid_to_names[new_cam].add(stem)
+
+        for pt in rec.points3D.values():
+            new_pt = next_pt
+            next_pt += 1
+            track = []
+            for el in pt.track.elements:
+                new_img = img_map[(f, int(el.image_id))]
+                xy = rec.images[el.image_id].points2D[el.point2D_idx].xy
+                idx = len(obs[new_img])
+                obs[new_img].append((float(xy[0]), float(xy[1]), new_pt))
+                track.append((new_img, idx))
+            new_points[new_pt] = {
+                "xyz": [float(v) for v in pt.xyz],
+                "rgb": [int(v) for v in pt.color],
+                "error": float(pt.error),
+                "track": track,
+            }
+            points_t[new_pt] = t
+
+    # Device provenance: one device per physical camera name; attach camera_ids only where a
+    # global CAMERA_ID maps unambiguously to a single name (keeps validate's uniqueness rule).
+    devices = {}
+    for stem in sorted(name_to_camids):
+        exclusive = sorted(c for c in name_to_camids[stem] if len(camid_to_names[c]) == 1)
+        dev = {"note": "physical camera identified by image name across frames"}
+        if exclusive:
+            dev["camera_ids"] = exclusive
+        devices[stem] = dev
+
+    synthetic = frame_times_ns is None
+    ts_note = "synthetic (frame_index * frame_interval_ns)" if synthetic else "provided"
+    pt_policy = "frame_instant; per-frame independent points, no cross-frame dedup"
+    # Synthetic timestamps are uniform frame_index * interval — the degenerate case of a
+    # software-clocked capture where the real per-image offsets were not recorded.
+    time_meta = {
+        "colmap4d_spec": "1.0",
+        "time_convention": "mid_exposure",
+        "time_unit": "ns",
+        "clock_domain": "synthetic_uniform" if synthetic else "provided",
+        "devices": devices,
+        "conversion": {
+            "source": "per_frame_colmap",
+            "num_frames": len(frame_dirs),
+            "frame_interval_ns": frame_interval_ns,
+            "timestamps": ts_note,
+            "point_time_policy": pt_policy,
+        },
+    }
+
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    _write_cameras_txt(out / "cameras.txt", new_cameras)
+    _write_images_txt(out / "images.txt", new_images, obs)
+    _write_points3d_txt(out / "points3D.txt", new_points)
+    sidecar.write_times_txt(out / sidecar.TIMES_TXT, times)
+    sidecar.write_points_t_txt(out / sidecar.POINTS_T_TXT, points_t)
+    sidecar.write_time_meta(out / sidecar.TIME_META_JSON, time_meta)
+
+    return ConversionResult(
+        out_dir=out,
+        num_frames=len(frame_dirs),
+        num_cameras=len(new_cameras),
+        num_images=len(new_images),
+        num_points=len(new_points),
+        frame_interval_ns=frame_interval_ns,
+        synthetic_times=synthetic,
+    )

colmap4d/groups.py

@@ -0,0 +1,14 @@
+"""Derived pseudo-frame grouping. (PLACEHOLDER)
+
+Intent (not implemented in WP0): ``group_by_time(times, eps_ns)`` clusters images
+whose timestamps fall within eps_ns into pseudo-frames, and optional read/write of a
+`groups.txt` derived view. Per spec Part III, grouping is a DERIVED view: the source
+of truth is always ``times`` + a chosen epsilon, recomputable on demand. groups.txt is
+never required and never authoritative.
+"""
+
+from __future__ import annotations
+
+
+def group_by_time(times: dict[int, int], eps_ns: int) -> list[list[int]]:  # noqa: ARG001
+    raise NotImplementedError("colmap4d.groups is a WP0 placeholder.")