x4d-devkit 0.1.0__tar.gz → 0.2.1__tar.gz

{x4d_devkit-0.1.0 → x4d_devkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.1.0
+Version: 0.2.1
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -57,13 +57,33 @@ pip install x4d-devkit[client]
 ```python
 from x4d_devkit import ClipLoader
 
-clip = ClipLoader("/path/to/clip")
-print(clip.meta)
+loader = ClipLoader("/path/to/clip")
+print(loader.meta)
 
-for sample in clip.samples:
-    # Access sensor data
-    for sd in clip.sample_data_by_sample(sample.token):
-        print(sd.channel, sd.filename)
+for sample in loader.samples:
+    for sd in loader.sample_data_for_sample(sample.token):
+        print(sd.channel, sd.file_path)
+```
+
+### Coordinate frame transforms
+
+Point clouds and annotations can be loaded in different coordinate frames:
+
+```python
+loader = ClipLoader("/path/to/clip")
+sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+
+# Load point cloud in different frames
+pts_sensor = loader.load_point_cloud(sd, frame="sensor")  # raw (default)
+pts_ego = loader.load_point_cloud(sd, frame="ego")        # sensor → ego
+pts_world = loader.load_point_cloud(sd, frame="world")    # sensor → world
+
+# Get annotations in ego frame (for training)
+anns_ego = loader.annotations_for_sample(sample.token, frame="ego")
+
+# Get the transform matrix directly
+T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4
 ```
 
 ### Validate a clip

{x4d_devkit-0.1.0 → x4d_devkit-0.2.1}/README.md

@@ -25,13 +25,33 @@ pip install x4d-devkit[client]
 ```python
 from x4d_devkit import ClipLoader
 
-clip = ClipLoader("/path/to/clip")
-print(clip.meta)
+loader = ClipLoader("/path/to/clip")
+print(loader.meta)
 
-for sample in clip.samples:
-    # Access sensor data
-    for sd in clip.sample_data_by_sample(sample.token):
-        print(sd.channel, sd.filename)
+for sample in loader.samples:
+    for sd in loader.sample_data_for_sample(sample.token):
+        print(sd.channel, sd.file_path)
+```
+
+### Coordinate frame transforms
+
+Point clouds and annotations can be loaded in different coordinate frames:
+
+```python
+loader = ClipLoader("/path/to/clip")
+sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+
+# Load point cloud in different frames
+pts_sensor = loader.load_point_cloud(sd, frame="sensor")  # raw (default)
+pts_ego = loader.load_point_cloud(sd, frame="ego")        # sensor → ego
+pts_world = loader.load_point_cloud(sd, frame="world")    # sensor → world
+
+# Get annotations in ego frame (for training)
+anns_ego = loader.annotations_for_sample(sample.token, frame="ego")
+
+# Get the transform matrix directly
+T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4
 ```
 
 ### Validate a clip

{x4d_devkit-0.1.0 → x4d_devkit-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.1.0"
+version = "0.2.1"
 description = "X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets"
 readme = "README.md"
 license = "Apache-2.0"

x4d_devkit-0.2.1/tests/test_coordinate_frames.py

@@ -0,0 +1,450 @@
+"""Tests for ClipLoader coordinate frame support.
+
+Unit tests use synthetic data (no nuScenes dependency).
+Integration tests require nuScenes mini data.
+"""
+
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from x4d_devkit.core.loader import ClipLoader
+from x4d_devkit.core.models import Annotation, SampleData
+from x4d_devkit.core.transform import Transform, rotation_matrix_to_quat
+
+
+# ---------------------------------------------------------------------------
+# Synthetic clip fixture
+# ---------------------------------------------------------------------------
+
+def _make_synthetic_clip(tmp_path: Path) -> Path:
+    """Create a minimal synthetic clip for unit testing."""
+    clip_dir = tmp_path / "synthetic_clip"
+    clip_dir.mkdir()
+
+    # -- meta.json --
+    (clip_dir / "meta.json").write_text(json.dumps({
+        "clip_id": "test-clip",
+        "schema_version": "0.4",
+        "session_id": "sess-001",
+        "vehicle_id": "veh-001",
+        "capture_time_utc": "2026-01-01T00:00:00Z",
+        "duration_s": 1.0,
+        "keyframe_count": 2,
+        "sweep_count": 0,
+        "sensors": {
+            "LIDAR_TOP": {
+                "modality": "lidar",
+                "point_format": {"fields": ["x", "y", "z", "intensity"]}
+            },
+            "CAM_FRONT": {
+                "modality": "camera",
+                "point_format": None
+            }
+        }
+    }))
+
+    # -- calibrated_sensor.json --
+    # LiDAR: translated 1m up (z=1), no rotation
+    # Camera: translated 0.5m forward (x=0.5), no rotation
+    (clip_dir / "calibrated_sensor.json").write_text(json.dumps([
+        {
+            "calibrated_sensor_token": "cs-lidar",
+            "channel": "LIDAR_TOP",
+            "translation": {"x": 0.0, "y": 0.0, "z": 1.0},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+            "camera_intrinsic": None,
+        },
+        {
+            "calibrated_sensor_token": "cs-cam",
+            "channel": "CAM_FRONT",
+            "translation": {"x": 0.5, "y": 0.0, "z": 0.8},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+            "camera_intrinsic": {"fx": 1000, "fy": 1000, "cx": 320, "cy": 240},
+        },
+    ]))
+
+    # -- ego_pose.json --
+    # Frame 0: ego at origin
+    # Frame 1: ego moved 10m forward (x=10)
+    (clip_dir / "ego_pose.json").write_text(json.dumps([
+        {
+            "ego_pose_token": "ep-0",
+            "timestamp_us": 1000000,
+            "translation": {"x": 0.0, "y": 0.0, "z": 0.0},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+        },
+        {
+            "ego_pose_token": "ep-1",
+            "timestamp_us": 1500000,
+            "translation": {"x": 10.0, "y": 0.0, "z": 0.0},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+        },
+    ]))
+
+    # -- sample.json --
+    (clip_dir / "sample.json").write_text(json.dumps([
+        {
+            "sample_token": "s-0",
+            "timestamp_us": 1000000,
+            "is_keyframe": True,
+            "prev": None,
+            "next": "s-1",
+        },
+        {
+            "sample_token": "s-1",
+            "timestamp_us": 1500000,
+            "is_keyframe": True,
+            "prev": "s-0",
+            "next": None,
+        },
+    ]))
+
+    # -- sample_data.json --
+    lidar_dir = clip_dir / "LIDAR_TOP"
+    lidar_dir.mkdir()
+
+    (clip_dir / "sample_data.json").write_text(json.dumps([
+        {
+            "sample_data_token": "sd-lidar-0",
+            "sample_token": "s-0",
+            "channel": "LIDAR_TOP",
+            "timestamp_us": 1000000,
+            "file_path": "LIDAR_TOP/frame0.bin",
+            "ego_pose_token": "ep-0",
+            "calibrated_sensor_token": "cs-lidar",
+            "is_keyframe": True,
+            "width": None,
+            "height": None,
+            "prev": None,
+            "next": "sd-lidar-1",
+        },
+        {
+            "sample_data_token": "sd-lidar-1",
+            "sample_token": "s-1",
+            "channel": "LIDAR_TOP",
+            "timestamp_us": 1500000,
+            "file_path": "LIDAR_TOP/frame1.bin",
+            "ego_pose_token": "ep-1",
+            "calibrated_sensor_token": "cs-lidar",
+            "is_keyframe": True,
+            "width": None,
+            "height": None,
+            "prev": "sd-lidar-0",
+            "next": None,
+        },
+    ]))
+
+    # -- point cloud binary files --
+    # 4 points at known positions: (1,0,0), (0,1,0), (0,0,1), (5,5,0)
+    # 4 fields: x, y, z, intensity
+    pts = np.array([
+        [1.0, 0.0, 0.0, 0.5],
+        [0.0, 1.0, 0.0, 0.5],
+        [0.0, 0.0, 1.0, 0.5],
+        [5.0, 5.0, 0.0, 0.5],
+    ], dtype=np.float32)
+    pts.tofile(str(lidar_dir / "frame0.bin"))
+    pts.tofile(str(lidar_dir / "frame1.bin"))
+
+    # -- annotation.json --
+    (clip_dir / "annotation.json").write_text(json.dumps([
+        {
+            "annotation_token": "ann-0",
+            "sample_token": "s-0",
+            "instance_token": "inst-0",
+            "category": "car",
+            "bbox_3d": {
+                "translation": {"x": 5.0, "y": 3.0, "z": 0.0},
+                "size": {"length": 4.5, "width": 2.0, "height": 1.5},
+                "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+            },
+            "num_lidar_pts": 100,
+            "visibility": "4",
+            "velocity": {"vx": 5.0, "vy": 0.0, "vz": 0.0},
+            "attributes": [],
+            "prev": None,
+            "next": "ann-1",
+            "score": None,
+        },
+        {
+            "annotation_token": "ann-1",
+            "sample_token": "s-1",
+            "instance_token": "inst-0",
+            "category": "car",
+            "bbox_3d": {
+                "translation": {"x": 10.0, "y": 3.0, "z": 0.0},
+                "size": {"length": 4.5, "width": 2.0, "height": 1.5},
+                "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+            },
+            "num_lidar_pts": 90,
+            "visibility": "4",
+            "velocity": {"vx": 5.0, "vy": 0.0, "vz": 0.0},
+            "attributes": [],
+            "prev": "ann-0",
+            "next": None,
+            "score": None,
+        },
+    ]))
+
+    # -- instance.json --
+    (clip_dir / "instance.json").write_text(json.dumps([
+        {
+            "instance_token": "inst-0",
+            "category": "car",
+            "num_annotations": 2,
+            "first_annotation_token": "ann-0",
+            "last_annotation_token": "ann-1",
+        },
+    ]))
+
+    return clip_dir
+
+
+@pytest.fixture(scope="module")
+def synthetic_clip(tmp_path_factory):
+    return _make_synthetic_clip(tmp_path_factory.mktemp("synth"))
+
+
+@pytest.fixture(scope="module")
+def loader(synthetic_clip):
+    return ClipLoader(synthetic_clip)
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: load_point_cloud with frame parameter
+# ---------------------------------------------------------------------------
+
+class TestLoadPointCloudFrames:
+    def test_sensor_frame_default(self, loader):
+        """Default frame should return raw sensor coordinates."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        pts = loader.load_point_cloud(sd)
+        assert pts.shape == (4, 4)
+        np.testing.assert_allclose(pts[0, :3], [1.0, 0.0, 0.0], atol=1e-6)
+
+    def test_sensor_frame_explicit(self, loader):
+        """Explicit frame='sensor' should match default."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        pts_default = loader.load_point_cloud(sd)
+        pts_sensor = loader.load_point_cloud(sd, frame="sensor")
+        np.testing.assert_array_equal(pts_default, pts_sensor)
+
+    def test_ego_frame(self, loader):
+        """frame='ego' applies sensor-to-ego transform (z+1 for LIDAR_TOP)."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        pts = loader.load_point_cloud(sd, frame="ego")
+        # LiDAR is at z=1 in ego frame, so sensor point (1,0,0) -> ego (1,0,1)
+        np.testing.assert_allclose(pts[0, :3], [1.0, 0.0, 1.0], atol=1e-5)
+        # sensor (0,0,1) -> ego (0,0,2)
+        np.testing.assert_allclose(pts[2, :3], [0.0, 0.0, 2.0], atol=1e-5)
+
+    def test_world_frame_first_ego(self, loader):
+        """frame='world' for first frame (ego at origin): same as ego frame."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]  # ep-0 at origin
+        pts_ego = loader.load_point_cloud(sd, frame="ego")
+        pts_world = loader.load_point_cloud(sd, frame="world")
+        np.testing.assert_allclose(pts_world[:, :3], pts_ego[:, :3], atol=1e-5)
+
+    def test_world_frame_second_ego(self, loader):
+        """frame='world' for second frame (ego at x=10): adds ego offset."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]  # ep-1 at x=10
+        pts = loader.load_point_cloud(sd, frame="world")
+        # sensor (1,0,0) -> ego (1,0,1) -> world (11,0,1)
+        np.testing.assert_allclose(pts[0, :3], [11.0, 0.0, 1.0], atol=1e-5)
+
+    def test_intensity_preserved(self, loader):
+        """Non-xyz columns should not be modified."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        pts = loader.load_point_cloud(sd, frame="world")
+        np.testing.assert_allclose(pts[:, 3], 0.5, atol=1e-6)
+
+    def test_invalid_frame_raises(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(ValueError, match="Invalid frame"):
+            loader.load_point_cloud(sd, frame="invalid")
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: annotations_for_sample with frame parameter
+# ---------------------------------------------------------------------------
+
+class TestAnnotationsForSampleFrames:
+    def test_world_frame_default(self, loader):
+        """Default frame should return annotations in world coordinates."""
+        anns = loader.annotations_for_sample("s-0")
+        assert len(anns) == 1
+        np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, 0.0])
+
+    def test_world_frame_explicit(self, loader):
+        """Explicit frame='world' should match default."""
+        anns_default = loader.annotations_for_sample("s-0")
+        anns_world = loader.annotations_for_sample("s-0", frame="world")
+        assert len(anns_default) == len(anns_world)
+        np.testing.assert_allclose(anns_default[0].translation, anns_world[0].translation)
+
+    def test_ego_frame_first_sample(self, loader):
+        """frame='ego' for first sample (ego at origin): same as world."""
+        anns = loader.annotations_for_sample("s-0", frame="ego")
+        # ego at origin -> world-to-ego is identity
+        np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, 0.0], atol=1e-5)
+
+    def test_ego_frame_second_sample(self, loader):
+        """frame='ego' for second sample (ego at x=10): subtracts ego offset."""
+        anns = loader.annotations_for_sample("s-1", frame="ego")
+        # annotation at world (10,3,0), ego at (10,0,0) -> ego frame (0,3,0)
+        np.testing.assert_allclose(anns[0].translation, [0.0, 3.0, 0.0], atol=1e-5)
+
+    def test_ego_frame_velocity_rotated(self, loader):
+        """Velocity should be rotated (not translated) to ego frame."""
+        anns = loader.annotations_for_sample("s-0", frame="ego")
+        # ego rotation is identity, so velocity unchanged
+        np.testing.assert_allclose(anns[0].velocity, [5.0, 0.0, 0.0], atol=1e-5)
+
+    def test_ego_frame_preserves_other_fields(self, loader):
+        """Non-pose fields should be preserved."""
+        anns_world = loader.annotations_for_sample("s-0", frame="world")
+        anns_ego = loader.annotations_for_sample("s-0", frame="ego")
+        assert anns_ego[0].token == anns_world[0].token
+        assert anns_ego[0].category == anns_world[0].category
+        np.testing.assert_allclose(anns_ego[0].size, anns_world[0].size)
+        assert anns_ego[0].num_lidar_pts == anns_world[0].num_lidar_pts
+
+    def test_ego_frame_returns_new_objects(self, loader):
+        """Transformed annotations should be new objects, not mutated originals."""
+        anns_world = loader.annotations_for_sample("s-1", frame="world")
+        anns_ego = loader.annotations_for_sample("s-1", frame="ego")
+        # Originals should be unmodified
+        np.testing.assert_allclose(anns_world[0].translation, [10.0, 3.0, 0.0])
+        # Ego should be different
+        assert not np.allclose(anns_ego[0].translation, anns_world[0].translation, atol=0.1)
+
+    def test_sensor_frame_raises(self, loader):
+        with pytest.raises(ValueError, match="sensor frame"):
+            loader.annotations_for_sample("s-0", frame="sensor")
+
+    def test_invalid_frame_raises(self, loader):
+        with pytest.raises(ValueError, match="Invalid frame"):
+            loader.annotations_for_sample("s-0", frame="invalid")
+
+    def test_empty_sample_returns_empty(self, loader):
+        """Non-existent sample returns empty list regardless of frame."""
+        assert loader.annotations_for_sample("nonexistent", frame="ego") == []
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: get_transform
+# ---------------------------------------------------------------------------
+
+class TestGetTransform:
+    def test_identity_same_frame(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        T = loader.get_transform(sd, from_frame="sensor", to_frame="sensor")
+        np.testing.assert_allclose(T.as_matrix, np.eye(4), atol=1e-10)
+
+    def test_sensor_to_ego(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        T = loader.get_transform(sd, from_frame="sensor", to_frame="ego")
+        # LiDAR at z=1
+        np.testing.assert_allclose(T.translation, [0.0, 0.0, 1.0], atol=1e-10)
+
+    def test_sensor_to_world(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]  # ego at x=10
+        T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+        # sensor to ego (z+1) then ego to world (x+10)
+        np.testing.assert_allclose(T.translation, [10.0, 0.0, 1.0], atol=1e-10)
+
+    def test_ego_to_world(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]
+        T = loader.get_transform(sd, from_frame="ego", to_frame="world")
+        np.testing.assert_allclose(T.translation, [10.0, 0.0, 0.0], atol=1e-10)
+
+    def test_round_trip(self, loader):
+        """sensor→world→sensor should be identity."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]
+        T_fwd = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+        T_rev = loader.get_transform(sd, from_frame="world", to_frame="sensor")
+        T_round = T_fwd @ T_rev
+        np.testing.assert_allclose(T_round.as_matrix, np.eye(4), atol=1e-10)
+
+    def test_all_six_combinations(self, loader):
+        """All from/to combinations should work without error."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        frames = ["sensor", "ego", "world"]
+        for f in frames:
+            for t in frames:
+                T = loader.get_transform(sd, from_frame=f, to_frame=t)
+                assert T.as_matrix.shape == (4, 4)
+
+    def test_invalid_from_frame_raises(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(ValueError, match="Invalid from_frame"):
+            loader.get_transform(sd, from_frame="bad", to_frame="ego")
+
+    def test_invalid_to_frame_raises(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(ValueError, match="Invalid to_frame"):
+            loader.get_transform(sd, from_frame="sensor", to_frame="bad")
+
+    def test_consistency_with_load_point_cloud(self, loader):
+        """get_transform result should match load_point_cloud frame output."""
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]
+        pts_sensor = loader.load_point_cloud(sd, frame="sensor")
+        pts_world = loader.load_point_cloud(sd, frame="world")
+
+        T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+        pts_manual = T.apply(pts_sensor[:, :3].astype(np.float64)).astype(np.float32)
+        np.testing.assert_allclose(pts_world[:, :3], pts_manual, atol=1e-5)
+
+
+# ---------------------------------------------------------------------------
+# Integration tests (nuScenes)
+# ---------------------------------------------------------------------------
+
+NUSCENES_DATAROOT = "/data/PublicDatasets/nuscenes"
+NUSCENES_AVAILABLE = os.path.isdir(os.path.join(NUSCENES_DATAROOT, "v1.0-mini"))
+
+
+@pytest.fixture(scope="module")
+def nuscenes_loader(tmp_path_factory):
+    if not NUSCENES_AVAILABLE:
+        pytest.skip("nuScenes data not found")
+    from x4d_devkit.converters.nuscenes import NuScenesConverter
+
+    out = tmp_path_factory.mktemp("frames_test")
+    conv = NuScenesConverter(
+        dataroot=NUSCENES_DATAROOT, version="v1.0-mini", output_dir=str(out),
+    )
+    scene = conv.nusc.scene[0]
+    clip_id = conv.convert_scene(scene["token"])
+    return ClipLoader(out / "clips" / clip_id)
+
+
+@pytest.mark.skipif(not NUSCENES_AVAILABLE, reason="nuScenes data not found")
+class TestCoordinateFramesIntegration:
+    def test_point_cloud_round_trip(self, nuscenes_loader):
+        """sensor→world→sensor should recover original points."""
+        sd = next(
+            s for s in nuscenes_loader.sample_data_for_channel("LIDAR_TOP") if s.is_keyframe
+        )
+        pts_sensor = nuscenes_loader.load_point_cloud(sd, frame="sensor")
+        T = nuscenes_loader.get_transform(sd, from_frame="world", to_frame="sensor")
+        pts_world = nuscenes_loader.load_point_cloud(sd, frame="world")
+        recovered = T.apply(pts_world[:, :3].astype(np.float64)).astype(np.float32)
+        np.testing.assert_allclose(recovered, pts_sensor[:, :3], atol=1e-4)
+
+    def test_ego_annotations_near_ego(self, nuscenes_loader):
+        """Ego-frame annotations should be centered around the ego vehicle."""
+        sample = nuscenes_loader.samples[0]
+        anns_world = nuscenes_loader.annotations_for_sample(sample.token, frame="world")
+        anns_ego = nuscenes_loader.annotations_for_sample(sample.token, frame="ego")
+        if not anns_world:
+            pytest.skip("No annotations in first sample")
+
+        # In ego frame, nearby objects should be within reasonable range
+        for ann in anns_ego:
+            dist = np.linalg.norm(ann.translation[:2])  # xy distance from ego
+            assert dist < 200, f"Annotation too far in ego frame: {dist}m"

{x4d_devkit-0.1.0 → x4d_devkit-0.2.1}/x4d_devkit/__init__.py

@@ -1,5 +1,6 @@
 """X-4D dataset format SDK."""
 
+from x4d_devkit.client import X4DClient
 from x4d_devkit.core import (
     Annotation,
     CalibratedSensor,
@@ -36,6 +37,7 @@ __all__ = [
     "Transform",
     "TransformChain",
     "ValidationReport",
+    "X4DClient",
     "generate_token",
     "nusc_detection_config",
     "validate_clip",

x4d_devkit-0.2.1/x4d_devkit/client/__init__.py

@@ -0,0 +1,13 @@
+from x4d_devkit.client.checkpoints import CheckpointsAPI
+from x4d_devkit.client.client import X4DClient
+from x4d_devkit.client.clips import ClipsAPI
+from x4d_devkit.client.projects import ProjectsAPI
+from x4d_devkit.client.test_sets import TestSetsAPI
+
+__all__ = [
+    "CheckpointsAPI",
+    "ClipsAPI",
+    "ProjectsAPI",
+    "TestSetsAPI",
+    "X4DClient",
+]

x4d_devkit-0.2.1/x4d_devkit/client/checkpoints.py

@@ -0,0 +1,64 @@
+"""Checkpoints API wrapper — training project registers its trained models
+so the platform's Model Compare view can run inference on them.
+
+This is the primary integration point between a training project and the
+platform: after every epoch the training CLI calls ``register(...)`` and
+the checkpoint immediately shows up in Compare's dropdown.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from x4d_devkit.client.client import X4DClient
+
+
+class CheckpointsAPI:
+    def __init__(self, client: "X4DClient"):
+        self._client = client
+
+    def register(
+        self,
+        project_id: int,
+        name: str,
+        service_id: str,
+        ckpt_uri: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict:
+        """Register a trained checkpoint for inference.
+
+        Idempotent on (project_id, service_id, ckpt_uri) — re-calling with
+        the same arguments updates name/metadata instead of creating a dup.
+
+        Args:
+            project_id: X-4D project the checkpoint belongs to.
+            name: Human-readable name, e.g. ``"exp_hg1_v1 · epoch 5"``.
+            service_id: The ``service_id`` of the training/inference service
+                that owns the checkpoint file (must be registered with the
+                platform, otherwise inference dispatch will 404).
+            ckpt_uri: Local path to the .pth file *on the service container*.
+                Remote/S3 URIs are not yet supported.
+            metadata: Arbitrary JSONB bag. By convention keys used by the
+                inference backend are ``cfg_file``, ``epoch``, ``is_best``,
+                ``training_task_id``.
+        """
+        return self._client.post(
+            "/checkpoints",
+            json={
+                "project_id": project_id,
+                "name": name,
+                "service_id": service_id,
+                "ckpt_uri": ckpt_uri,
+                "metadata": metadata or {},
+            },
+        )
+
+    def list(self, project_id: int) -> list[dict]:
+        resp = self._client.get(f"/projects/{project_id}/checkpoints")
+        return resp["items"]
+
+    def get(self, checkpoint_id: int) -> dict:
+        return self._client.get(f"/checkpoints/{checkpoint_id}")
+
+    def delete(self, checkpoint_id: int) -> None:
+        self._client.delete(f"/checkpoints/{checkpoint_id}")