cloudanalyzer 0.3.0__tar.gz → 0.4.0__tar.gz

{cloudanalyzer-0.3.0 → cloudanalyzer-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudanalyzer
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI-first QA toolkit for point cloud, trajectory, and 3D perception outputs
 Author: rsasaki0109
 License-Expression: MIT
@@ -36,6 +36,10 @@ Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pkginfo>=1.12.0; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: twine>=6.0.0; extra == "dev"
+Provides-Extra: slam
+Requires-Dist: kiss-icp>=1.2.0; extra == "slam"
+Requires-Dist: kiss-slam>=0.0.2; extra == "slam"
+Requires-Dist: small_gicp>=1.0.0; extra == "slam"
 Dynamic: license-file
 
 # CloudAnalyzer

{cloudanalyzer-0.3.0 → cloudanalyzer-0.4.0}/ca/__init__.py

@@ -1,3 +1,3 @@
 """CloudAnalyzer - AI-friendly CLI tool for point cloud analysis."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

cloudanalyzer-0.4.0/ca/core/slam_run.py

@@ -0,0 +1,329 @@
+"""Stable contract for ``ca slam-run``: drive a LiDAR-odometry pipeline
+end-to-end on a sequence of input scans and produce the artifacts the rest of
+CloudAnalyzer's evaluation stack expects (estimated map PLY + TUM trajectory).
+
+The slice has two implementations under ``ca.experiments.slam_run``:
+
+- ``KissICPSlamDriver`` (adopted, also re-exported here): wraps the
+  ``kiss-icp`` package — a small, well-known scan-to-map LiDAR-odometry
+  registration pipeline. Picks up KITTI / Newer College sequences with
+  ``deskew`` enabled.
+- ``IdentityPassthroughSlamDriver``: a zero-motion sentinel that emits identity
+  poses and concatenates input frames as the "map". It is intentionally
+  bad — its only job is to prove the harness is wired and to provide a floor
+  for the slice's evaluator.
+
+The contract:
+
+- :class:`SlamRunRequest` carries the inputs you actually have (frame paths,
+  optional per-frame timestamps, driver knobs).
+- :class:`SlamRunResult` carries everything needed to feed the existing
+  ``ca run-evaluate`` pipeline plus enough metadata for ``ca check`` /
+  ``ca report-pr-comment``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+
+
+@dataclass(slots=True)
+class SlamRunRequest:
+    """Inputs to a single SLAM driver run."""
+
+    frame_paths: tuple[Path, ...]
+    """Per-frame scan paths in temporal order (``.pcd`` / ``.ply`` / ``.bin``)."""
+
+    timestamps_s: tuple[float, ...] | None = None
+    """Optional per-frame timestamps in seconds (length must equal frame_paths).
+    Used for the TUM trajectory output and for drivers that consume timing.
+    If omitted, drivers fall back to ``index * frame_period_s``."""
+
+    frame_period_s: float = 0.1
+    """Fallback timestamp spacing used when ``timestamps_s`` is None."""
+
+    max_range_m: float | None = None
+    """Drop scan points farther than this from the sensor before registration.
+    ``None`` keeps every point."""
+
+    voxel_size_m: float | None = None
+    """Driver-side voxel grid size for the local map. ``None`` uses the driver's
+    own default."""
+
+    deskew: bool = True
+    """Whether the driver should motion-deskew input frames (KISS-ICP default)."""
+
+    max_frames: int | None = None
+    """Optional cap on the number of frames consumed. ``None`` runs everything."""
+
+
+@dataclass(slots=True)
+class SlamRunResult:
+    """Outputs of a single SLAM driver run."""
+
+    driver: str
+    """Identifier of the driver that produced this result."""
+
+    poses: np.ndarray
+    """``(N, 4, 4)`` array of sensor-to-world poses, one per processed frame."""
+
+    timestamps_s: np.ndarray
+    """``(N,)`` array of pose timestamps in seconds."""
+
+    map_points: np.ndarray
+    """``(M, 3)`` accumulated map point cloud in the world frame."""
+
+    runtime_s: float
+    """Total wall-clock seconds spent inside the driver (frame iteration only)."""
+
+    frames_processed: int
+    """How many frames the driver consumed before producing the result."""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Driver-specific knobs / config snapshot. Echoed into the summary JSON
+    so a downstream baseline can prove two runs used the same settings."""
+
+
+@runtime_checkable
+class SlamRunDriver(Protocol):
+    """A SLAM driver consumes a request and returns the artifacts contract."""
+
+    name: str
+
+    def run(self, request: SlamRunRequest) -> SlamRunResult:  # pragma: no cover - Protocol
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers used by every driver (loading frames, writing artifacts).
+# ---------------------------------------------------------------------------
+
+
+def load_frame(path: Path) -> np.ndarray:
+    """Load one LiDAR scan as an ``(N, 3)`` float64 ndarray.
+
+    Supports:
+
+    - ``.bin``: KITTI Velodyne format (float32 quadruples, XYZI; intensity dropped).
+    - ``.pcd`` / ``.ply``: read through Open3D.
+    - ``.csv``: x,y,z columns (optionally with a header), parsed by ``ca.io``.
+
+    Empty scans are returned as ``(0, 3)`` so drivers can skip them without
+    raising.
+    """
+
+    suffix = path.suffix.lower()
+    if suffix == ".bin":
+        raw = np.fromfile(str(path), dtype=np.float32)
+        if raw.size == 0:
+            return np.empty((0, 3), dtype=np.float64)
+        if raw.size % 4 != 0:
+            raise ValueError(
+                f"KITTI .bin frame {path} has size {raw.size} not divisible by 4"
+            )
+        return raw.reshape(-1, 4)[:, :3].astype(np.float64, copy=False)
+    if suffix in {".pcd", ".ply", ".csv"}:
+        from ca.io import load_point_cloud
+
+        pcd = load_point_cloud(str(path))
+        pts = np.asarray(pcd.points, dtype=np.float64)
+        if pts.size == 0:
+            return np.empty((0, 3), dtype=np.float64)
+        return pts
+    raise ValueError(
+        f"Unsupported frame format '{suffix}'. Expected one of .bin .pcd .ply .csv"
+    )
+
+
+def discover_frame_paths(input_path: Path) -> list[Path]:
+    """Resolve ``--input`` to an ordered list of frame paths.
+
+    Accepts either:
+
+    - A directory: pick up ``*.bin``, ``*.pcd``, ``*.ply`` (in that priority
+      order, picking whichever extension dominates) and sort lexicographically.
+      KITTI Velodyne dumps use lex-sortable zero-padded filenames so this
+      matches frame order.
+    - A list file (``*.txt``): one path per line. Relative paths are resolved
+      against the list file's parent directory.
+    """
+
+    if input_path.is_file() and input_path.suffix.lower() == ".txt":
+        out: list[Path] = []
+        base = input_path.parent
+        for raw in input_path.read_text(encoding="utf-8").splitlines():
+            stripped = raw.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            candidate = Path(stripped)
+            if not candidate.is_absolute():
+                candidate = base / candidate
+            out.append(candidate)
+        if not out:
+            raise ValueError(f"Frame list {input_path} is empty")
+        return out
+
+    if not input_path.is_dir():
+        raise ValueError(
+            f"--input must be a directory of scans or a .txt list; got {input_path}"
+        )
+
+    for ext in (".bin", ".pcd", ".ply"):
+        hits = sorted(input_path.glob(f"*{ext}"))
+        if hits:
+            return hits
+    raise ValueError(
+        f"No .bin/.pcd/.ply scans found under {input_path}. "
+        "Pass a directory containing LiDAR sweeps or a frames-list.txt."
+    )
+
+
+def write_tum_trajectory(
+    path: Path, poses: np.ndarray, timestamps_s: np.ndarray
+) -> None:
+    """Dump poses to TUM format (``timestamp tx ty tz qx qy qz qw``).
+
+    Matches the format ``ca traj-evaluate`` already consumes.
+    """
+
+    if poses.ndim != 3 or poses.shape[1:] != (4, 4):
+        raise ValueError(f"poses must be (N, 4, 4); got {poses.shape}")
+    if timestamps_s.shape != (poses.shape[0],):
+        raise ValueError(
+            f"timestamps_s {timestamps_s.shape} must match poses {poses.shape[0]}"
+        )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    quats = _rotation_matrices_to_quaternions(poses[:, :3, :3])
+    with path.open("w", encoding="utf-8") as f:
+        f.write("# timestamp tx ty tz qx qy qz qw\n")
+        for t, pose, q in zip(timestamps_s, poses, quats):
+            tx, ty, tz = pose[:3, 3]
+            qx, qy, qz, qw = q
+            f.write(
+                f"{t:.6f} {tx:.6f} {ty:.6f} {tz:.6f} "
+                f"{qx:.6f} {qy:.6f} {qz:.6f} {qw:.6f}\n"
+            )
+
+
+def write_map_ply(path: Path, map_points: np.ndarray) -> None:
+    """Save the accumulated SLAM map as an Open3D-readable PLY."""
+
+    if map_points.ndim != 2 or map_points.shape[1] != 3:
+        raise ValueError(f"map_points must be (M, 3); got {map_points.shape}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    import open3d as o3d
+
+    pcd = o3d.geometry.PointCloud()
+    pcd.points = o3d.utility.Vector3dVector(
+        np.ascontiguousarray(map_points, dtype=np.float64)
+    )
+    o3d.io.write_point_cloud(str(path), pcd, write_ascii=False)
+
+
+def _rotation_matrices_to_quaternions(rotmats: np.ndarray) -> np.ndarray:
+    """Vectorized rotation-matrix → ``(qx, qy, qz, qw)`` quaternion.
+
+    Uses the standard Shepperd-style branchless trace selection so it works
+    cleanly even when most rotations are near-identity (the common case for
+    indoor LiDAR sweeps where motion is small per frame).
+    """
+
+    if rotmats.ndim != 3 or rotmats.shape[1:] != (3, 3):
+        raise ValueError(f"rotmats must be (N, 3, 3); got {rotmats.shape}")
+
+    n = rotmats.shape[0]
+    out = np.zeros((n, 4), dtype=np.float64)
+
+    m00 = rotmats[:, 0, 0]
+    m11 = rotmats[:, 1, 1]
+    m22 = rotmats[:, 2, 2]
+    trace = m00 + m11 + m22
+
+    # Branch on the largest diagonal entry to avoid numerical blowups.
+    case_w = trace > 0.0
+    case_x = (~case_w) & (m00 >= m11) & (m00 >= m22)
+    case_y = (~case_w) & (~case_x) & (m11 >= m22)
+    case_z = (~case_w) & (~case_x) & (~case_y)
+
+    if np.any(case_w):
+        idx = np.where(case_w)[0]
+        s = np.sqrt(trace[idx] + 1.0) * 2.0
+        qw = 0.25 * s
+        qx = (rotmats[idx, 2, 1] - rotmats[idx, 1, 2]) / s
+        qy = (rotmats[idx, 0, 2] - rotmats[idx, 2, 0]) / s
+        qz = (rotmats[idx, 1, 0] - rotmats[idx, 0, 1]) / s
+        out[idx, 0] = qx
+        out[idx, 1] = qy
+        out[idx, 2] = qz
+        out[idx, 3] = qw
+
+    if np.any(case_x):
+        idx = np.where(case_x)[0]
+        s = np.sqrt(1.0 + m00[idx] - m11[idx] - m22[idx]) * 2.0
+        out[idx, 0] = 0.25 * s
+        out[idx, 1] = (rotmats[idx, 0, 1] + rotmats[idx, 1, 0]) / s
+        out[idx, 2] = (rotmats[idx, 0, 2] + rotmats[idx, 2, 0]) / s
+        out[idx, 3] = (rotmats[idx, 2, 1] - rotmats[idx, 1, 2]) / s
+
+    if np.any(case_y):
+        idx = np.where(case_y)[0]
+        s = np.sqrt(1.0 + m11[idx] - m00[idx] - m22[idx]) * 2.0
+        out[idx, 0] = (rotmats[idx, 0, 1] + rotmats[idx, 1, 0]) / s
+        out[idx, 1] = 0.25 * s
+        out[idx, 2] = (rotmats[idx, 1, 2] + rotmats[idx, 2, 1]) / s
+        out[idx, 3] = (rotmats[idx, 0, 2] - rotmats[idx, 2, 0]) / s
+
+    if np.any(case_z):
+        idx = np.where(case_z)[0]
+        s = np.sqrt(1.0 + m22[idx] - m00[idx] - m11[idx]) * 2.0
+        out[idx, 0] = (rotmats[idx, 0, 2] + rotmats[idx, 2, 0]) / s
+        out[idx, 1] = (rotmats[idx, 1, 2] + rotmats[idx, 2, 1]) / s
+        out[idx, 2] = 0.25 * s
+        out[idx, 3] = (rotmats[idx, 1, 0] - rotmats[idx, 0, 1]) / s
+
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Adopted driver re-export. Concrete impl lives under ca.experiments.slam_run
+# so the slice's evaluator can still benchmark it against the sentinel; the
+# CLI imports from here so ``ca.core`` stays the only stable surface.
+# ---------------------------------------------------------------------------
+
+
+def _import_kiss_icp_driver() -> type[SlamRunDriver]:
+    from ca.experiments.slam_run.kiss_icp_driver import KissICPSlamDriver
+
+    return KissICPSlamDriver
+
+
+def make_default_driver() -> SlamRunDriver:
+    """Return the currently adopted SLAM driver instance (KISS-ICP)."""
+
+    cls = _import_kiss_icp_driver()
+    return cls()
+
+
+def run_slam(request: SlamRunRequest, driver: SlamRunDriver | None = None) -> SlamRunResult:
+    """Convenience entry point used by the CLI; delegates to the supplied
+    driver or to the adopted default."""
+
+    drv = driver or make_default_driver()
+    return drv.run(request)
+
+
+__all__ = [
+    "SlamRunRequest",
+    "SlamRunResult",
+    "SlamRunDriver",
+    "load_frame",
+    "discover_frame_paths",
+    "write_tum_trajectory",
+    "write_map_ply",
+    "make_default_driver",
+    "run_slam",
+]

{cloudanalyzer-0.3.0 → cloudanalyzer-0.4.0}/ca/experiments/process_docs.py

@@ -54,6 +54,12 @@ from ca.experiments.map_evaluate.evaluate import (
     render_interface_section as render_map_evaluate_interface_section,
     run_map_evaluate_experiment,
 )
+from ca.experiments.slam_run.evaluate import (
+    render_decision_section as render_slam_run_decision_section,
+    render_experiment_section as render_slam_run_experiment_section,
+    render_interface_section as render_slam_run_interface_section,
+    run_slam_run_experiment,
+)
 
 
 def build_experiment_reports(repetitions: int = 3) -> list[dict]:
@@ -68,6 +74,7 @@ def build_experiment_reports(repetitions: int = 3) -> list[dict]:
         run_check_baseline_evolution_experiment(repetitions=repetitions),
         run_ground_evaluate_experiment(repetitions=repetitions),
         run_map_evaluate_experiment(repetitions=repetitions),
+        run_slam_run_experiment(repetitions=1),
     ]
 
 
@@ -83,6 +90,7 @@ def render_experiments_markdown(reports: list[dict]) -> str:
         render_check_baseline_evolution_experiment_section(reports[5]),
         render_ground_evaluate_experiment_section(reports[6]),
         render_map_evaluate_experiment_section(reports[7]),
+        render_slam_run_experiment_section(reports[8]),
     ]
     return (
         "# Experiments\n\n"
@@ -104,6 +112,7 @@ def render_decisions_markdown(reports: list[dict]) -> str:
         render_check_baseline_evolution_decision_section(reports[5]),
         render_ground_evaluate_decision_section(reports[6]),
         render_map_evaluate_decision_section(reports[7]),
+        render_slam_run_decision_section(reports[8]),
     ]
     return "# Decisions\n\n" + "\n\n".join(sections) + "\n"
 
@@ -120,6 +129,7 @@ def render_interfaces_markdown(reports: list[dict]) -> str:
         render_check_baseline_evolution_interface_section(reports[5]),
         render_ground_evaluate_interface_section(reports[6]),
         render_map_evaluate_interface_section(reports[7]),
+        render_slam_run_interface_section(reports[8]),
     ]
     return (
         "# Interfaces\n\n"

cloudanalyzer-0.4.0/ca/experiments/slam_run/__init__.py

@@ -0,0 +1,46 @@
+"""Experimental SLAM drivers compared by the slam_run slice evaluator.
+
+Four drivers participate:
+
+- :class:`KissICPSlamDriver` — the adopted real driver, wrapping the
+  ``kiss-icp`` package. Also re-exported from ``ca.core.slam_run`` so the
+  CLI keeps depending only on core. Scan-to-map with constant-velocity
+  prediction and adaptive max-correspondence-distance.
+- :class:`KissSLAMSlamDriver` — wraps ``kiss-slam`` (KISS-ICP odometry +
+  pose-graph optimization + MapClosures loop closure). Same scan-to-map
+  inner loop as KISS-ICP with a PGO pass on top.
+- :class:`SmallGICPSlamDriver` — wraps ``small_gicp`` (PyPI MIT).
+  Scan-to-map VGICP using ``small_gicp.GaussianVoxelMap`` as the
+  registration target; map output is scan-stitched + voxel-downsampled
+  (the voxel map stores quantized centers and can't clear the Chamfer
+  threshold against a dense reference on its own).
+- :class:`IdentityPassthroughSlamDriver` — sentinel that returns identity
+  poses and concatenates input frames as the "map". It is intentionally
+  bad; its only job is to prove the harness runs and to set the floor for
+  ``evaluate.py``.
+"""
+
+from ca.experiments.slam_run.identity_passthrough import IdentityPassthroughSlamDriver
+from ca.experiments.slam_run.kiss_icp_driver import KissICPSlamDriver
+from ca.experiments.slam_run.kiss_slam_driver import KissSLAMSlamDriver
+from ca.experiments.slam_run.small_gicp_driver import SmallGICPSlamDriver
+
+
+def get_slam_run_drivers() -> list:
+    """Return the concrete drivers compared by the slice evaluator."""
+
+    return [
+        KissICPSlamDriver(),
+        KissSLAMSlamDriver(),
+        SmallGICPSlamDriver(),
+        IdentityPassthroughSlamDriver(),
+    ]
+
+
+__all__ = [
+    "IdentityPassthroughSlamDriver",
+    "KissICPSlamDriver",
+    "KissSLAMSlamDriver",
+    "SmallGICPSlamDriver",
+    "get_slam_run_drivers",
+]

cloudanalyzer-0.4.0/ca/experiments/slam_run/common.py

@@ -0,0 +1,244 @@
+"""Shared datasets for slam_run driver experiments.
+
+Each dataset case synthesizes a small set of LiDAR-style frames in a temp
+directory, defines the ground-truth sensor poses, and packages them into a
+:class:`SlamRunRequest`. The slice evaluator runs every concrete driver
+against every case and compares against the GT trajectory.
+
+The synthetic frames are tiny on purpose — the slice's job is to verify
+that the harness wires through, not to benchmark large maps. Real-scale
+benchmarking happens via ``ca slam-run`` + ``ca run-evaluate`` on the
+KITTI-mini / Newer-College-mini benchmark suites.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+from ca.core.slam_run import SlamRunRequest
+
+
+@dataclass(slots=True)
+class SlamRunDatasetCase:
+    """One comparable SLAM run for the slice's driver bake-off."""
+
+    name: str
+    description: str
+    build_request: Callable[[Path], SlamRunRequest]
+    """Closure that materializes synthetic frames under the given temp dir
+    and returns the request pointing at them."""
+
+    gt_poses: np.ndarray
+    """``(N, 4, 4)`` ground-truth sensor-to-world poses for ATE comparison."""
+
+    expected_kiss_icp_max_ate_m: float
+    """Pass condition for KISS-ICP on this case."""
+
+    keep_files: tuple[str, ...] = field(default_factory=tuple)
+    """Filenames the case promises to leave under the temp dir (helps tests
+    assert on driver outputs without re-running the synthesis)."""
+
+
+# ---------------------------------------------------------------------------
+# Synthetic frame builders
+# ---------------------------------------------------------------------------
+
+
+def _box_scene(seed: int, n_points: int = 1500) -> np.ndarray:
+    """Build a deterministic synthetic 'room' scene in the world frame.
+
+    Returns ``(n_points, 3)`` of points lying on the floor and four walls of
+    a 20 × 20 m room — enough structure for ICP to actually have something
+    to register against.
+    """
+
+    rng = np.random.default_rng(seed)
+    # Floor (z = 0)
+    floor = rng.uniform([-10, -10, -0.02], [10, 10, 0.02], size=(n_points // 2, 3))
+    # Four walls
+    rem = n_points - floor.shape[0]
+    per_wall = rem // 4
+    walls = []
+    for axis_pair in [(0, 1), (0, -1), (1, 1), (1, -1)]:
+        axis, sign = axis_pair
+        fixed = sign * 10.0
+        sweeping = rng.uniform(-10, 10, size=(per_wall, 1))
+        heights = rng.uniform(0.0, 3.0, size=(per_wall, 1))
+        if axis == 0:
+            pts = np.hstack(
+                [np.full((per_wall, 1), fixed), sweeping, heights]
+            )
+        else:
+            pts = np.hstack(
+                [sweeping, np.full((per_wall, 1), fixed), heights]
+            )
+        pts += rng.normal(0, 0.02, size=pts.shape)
+        walls.append(pts)
+    return np.vstack([floor, *walls]).astype(np.float64)
+
+
+def _pose(tx: float, ty: float, tz: float, yaw_rad: float = 0.0) -> np.ndarray:
+    """Build a 4×4 SE(3) pose with rotation about z (yaw) only."""
+    c, s = np.cos(yaw_rad), np.sin(yaw_rad)
+    pose = np.eye(4, dtype=np.float64)
+    pose[0, 0] = c
+    pose[0, 1] = -s
+    pose[1, 0] = s
+    pose[1, 1] = c
+    pose[0, 3] = tx
+    pose[1, 3] = ty
+    pose[2, 3] = tz
+    return pose
+
+
+def _write_pcd(path: Path, points: np.ndarray) -> None:
+    """Minimal ASCII PCD writer suitable for Open3D's reader."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    n = points.shape[0]
+    header = (
+        "# .PCD v.7 - Point Cloud Data file format\n"
+        "VERSION .7\n"
+        "FIELDS x y z\n"
+        "SIZE 4 4 4\n"
+        "TYPE F F F\n"
+        "COUNT 1 1 1\n"
+        f"WIDTH {n}\n"
+        "HEIGHT 1\n"
+        "VIEWPOINT 0 0 0 1 0 0 0\n"
+        f"POINTS {n}\n"
+        "DATA ascii\n"
+    )
+    with path.open("w", encoding="utf-8") as f:
+        f.write(header)
+        for x, y, z in points:
+            f.write(f"{x:.6f} {y:.6f} {z:.6f}\n")
+
+
+def _straight_line_dataset() -> SlamRunDatasetCase:
+    """6 sensor poses sliding forward along +x by 0.5 m / frame in a static room."""
+    n_frames = 6
+    scene = _box_scene(seed=11, n_points=1200)
+    gt_poses = np.stack(
+        [_pose(i * 0.5, 0.0, 0.0, yaw_rad=0.0) for i in range(n_frames)], axis=0
+    )
+
+    def build(tmp: Path) -> SlamRunRequest:
+        frame_dir = tmp / "straight"
+        frame_dir.mkdir(parents=True, exist_ok=True)
+        paths = []
+        for i, gt in enumerate(gt_poses):
+            sensor_to_world = gt
+            world_to_sensor = np.linalg.inv(sensor_to_world)
+            ones = np.ones((scene.shape[0], 1))
+            world_h = np.hstack([scene, ones])
+            sensor_pts = (world_to_sensor @ world_h.T).T[:, :3]
+            p = frame_dir / f"frame_{i:04d}.pcd"
+            _write_pcd(p, sensor_pts)
+            paths.append(p)
+        return SlamRunRequest(
+            frame_paths=tuple(paths),
+            timestamps_s=tuple(float(i) * 0.1 for i in range(n_frames)),
+            max_range_m=50.0,
+            voxel_size_m=0.5,
+            deskew=False,
+            max_frames=None,
+        )
+
+    return SlamRunDatasetCase(
+        name="straight_line_6frames",
+        description=(
+            "6 sensor poses sliding +0.5 m/frame along +x in a static 20×20 m room. "
+            "Identity-passthrough collapses every pose to origin; KISS-ICP should "
+            "recover the slide within a few cm."
+        ),
+        build_request=build,
+        gt_poses=gt_poses,
+        expected_kiss_icp_max_ate_m=0.20,
+        keep_files=tuple(f"frame_{i:04d}.pcd" for i in range(n_frames)),
+    )
+
+
+def _short_turn_dataset() -> SlamRunDatasetCase:
+    """4 poses tracing a quarter-turn: translate + yaw by 22.5° each step."""
+    n_frames = 4
+    scene = _box_scene(seed=23, n_points=1500)
+    gt_poses = np.stack(
+        [
+            _pose(0.3 * i, 0.1 * i, 0.0, yaw_rad=0.392 * i)  # ~22.5° per step
+            for i in range(n_frames)
+        ],
+        axis=0,
+    )
+
+    def build(tmp: Path) -> SlamRunRequest:
+        frame_dir = tmp / "turn"
+        frame_dir.mkdir(parents=True, exist_ok=True)
+        paths = []
+        for i, gt in enumerate(gt_poses):
+            world_to_sensor = np.linalg.inv(gt)
+            ones = np.ones((scene.shape[0], 1))
+            world_h = np.hstack([scene, ones])
+            sensor_pts = (world_to_sensor @ world_h.T).T[:, :3]
+            p = frame_dir / f"frame_{i:04d}.pcd"
+            _write_pcd(p, sensor_pts)
+            paths.append(p)
+        return SlamRunRequest(
+            frame_paths=tuple(paths),
+            timestamps_s=tuple(float(i) * 0.1 for i in range(n_frames)),
+            max_range_m=50.0,
+            voxel_size_m=0.5,
+            deskew=False,
+            max_frames=None,
+        )
+
+    return SlamRunDatasetCase(
+        name="short_turn_4frames",
+        description=(
+            "4 sensor poses tracing a short curve (~22.5° yaw + small translation "
+            "per step). Tests that the harness handles non-trivial rotation."
+        ),
+        build_request=build,
+        gt_poses=gt_poses,
+        expected_kiss_icp_max_ate_m=0.30,
+        keep_files=tuple(f"frame_{i:04d}.pcd" for i in range(n_frames)),
+    )
+
+
+def build_default_datasets() -> list[SlamRunDatasetCase]:
+    """Return the deterministic dataset suite the slice evaluator runs."""
+
+    return [_straight_line_dataset(), _short_turn_dataset()]
+
+
+def absolute_trajectory_error_m(
+    estimated_poses: np.ndarray, gt_poses: np.ndarray
+) -> float:
+    """RMS Euclidean distance between the translation components of two
+    pose sequences."""
+
+    if estimated_poses.shape[0] == 0 or gt_poses.shape[0] == 0:
+        return float("inf")
+    n = min(estimated_poses.shape[0], gt_poses.shape[0])
+    est_t = estimated_poses[:n, :3, 3]
+    gt_t = gt_poses[:n, :3, 3]
+    diffs = np.linalg.norm(est_t - gt_t, axis=1)
+    return float(np.sqrt(np.mean(diffs**2)))
+
+
+def make_temp_dir() -> tempfile.TemporaryDirectory:
+    """Helper used by the evaluator / tests to allocate a scratch dir."""
+
+    return tempfile.TemporaryDirectory(prefix="ca_slam_run_")
+
+
+__all__ = [
+    "SlamRunDatasetCase",
+    "build_default_datasets",
+    "absolute_trajectory_error_m",
+    "make_temp_dir",
+]