x4d-devkit 0.11.1__tar.gz → 0.12.0__tar.gz

{x4d_devkit-0.11.1/x4d_devkit.egg-info → x4d_devkit-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.11.1
+Version: 0.12.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -65,22 +65,31 @@ for sample in loader.samples:
 
 ### Coordinate frame transforms
 
-Point clouds and annotations can be loaded in different coordinate frames:
+Frames are real frame_id strings: any node in the calibration tree (e.g.
+`"LIDAR_TOP"`, `"base_link"`, `"cam_front"`) plus the constant
+`"clip_world"` (the SLAM-anchored clip-local world). The legacy aliases
+`"sensor"`, `"ego"`, `"world"` are not accepted.
 
 ```python
+from x4d_devkit import ClipLoader
+from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID
+
 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
+pts_sensor = loader.load_point_cloud(sd)                                 # raw sensor (default)
+pts_ego    = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id) # sensor → ego
+pts_world  = loader.load_point_cloud(sd, frame=CLIP_WORLD_FRAME_ID)      # sensor → clip_world
+
+# Get annotations transformed to clip-local world
+anns_world = loader.annotations_for_sample(sample.token, frame=CLIP_WORLD_FRAME_ID)
 
-# Get annotations in ego frame (for training)
-anns_ego = loader.annotations_for_sample(sample.token, frame="ego")
+# Or to a specific sensor's frame
+anns_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")
 
-# Get the transform matrix directly
-T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+# Get the transform matrix directly (sd is required when clip_world is involved)
+T = loader.get_transform(loader.sensor_frame_id(sd), CLIP_WORLD_FRAME_ID, sd=sd)
 pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4
 ```
 

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/README.md

@@ -35,22 +35,31 @@ for sample in loader.samples:
 
 ### Coordinate frame transforms
 
-Point clouds and annotations can be loaded in different coordinate frames:
+Frames are real frame_id strings: any node in the calibration tree (e.g.
+`"LIDAR_TOP"`, `"base_link"`, `"cam_front"`) plus the constant
+`"clip_world"` (the SLAM-anchored clip-local world). The legacy aliases
+`"sensor"`, `"ego"`, `"world"` are not accepted.
 
 ```python
+from x4d_devkit import ClipLoader
+from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID
+
 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
+pts_sensor = loader.load_point_cloud(sd)                                 # raw sensor (default)
+pts_ego    = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id) # sensor → ego
+pts_world  = loader.load_point_cloud(sd, frame=CLIP_WORLD_FRAME_ID)      # sensor → clip_world
+
+# Get annotations transformed to clip-local world
+anns_world = loader.annotations_for_sample(sample.token, frame=CLIP_WORLD_FRAME_ID)
 
-# Get annotations in ego frame (for training)
-anns_ego = loader.annotations_for_sample(sample.token, frame="ego")
+# Or to a specific sensor's frame
+anns_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")
 
-# Get the transform matrix directly
-T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+# Get the transform matrix directly (sd is required when clip_world is involved)
+T = loader.get_transform(loader.sensor_frame_id(sd), CLIP_WORLD_FRAME_ID, sd=sd)
 pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4
 ```
 

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/pyproject.toml

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

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/tests/test_coordinate_frames.py

@@ -1,7 +1,12 @@
-"""Tests for ClipLoader coordinate frame support.
+"""Tests for ClipLoader coordinate frame support — frame-graph (post-magic-string) API.
 
-Unit tests use synthetic data (no nuScenes dependency).
-Integration tests require nuScenes mini data.
+The new contract: every frame is a real frame_id string (a node in the
+calibration tree) plus the constant ``"clip_world"`` for the SLAM-anchored
+clip-local world. The legacy magic strings ``"sensor"``, ``"ego"``, ``"world"``
+are rejected to remove the "did you mean my-actual-frame_id-string?" foot-gun.
+
+Unit tests use synthetic data (no nuScenes dependency). Integration tests
+require nuScenes mini data.
 """
 
 import json
@@ -12,8 +17,9 @@ 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
+
+
+CLIP_WORLD = "clip_world"
 
 
 # ---------------------------------------------------------------------------
@@ -157,7 +163,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
     pts.tofile(str(lidar_dir / "frame0.bin"))
     pts.tofile(str(lidar_dir / "frame1.bin"))
 
-    # -- annotation.json (v0.5: per-sample ego frame) --
+    # -- annotation.json (v0.5: per-sample ego frame; here ann_frame == base_link) --
     # s-0 ego at origin; s-1 ego at (10, 0, 0). Same world pos (5,3,0) and (10,3,0)
     # for the two frames maps to ego (5,3,0) and (0,3,0) respectively.
     (clip_dir / "annotation.json").write_text(json.dumps([
@@ -224,186 +230,220 @@ def loader(synthetic_clip):
 
 
 # ---------------------------------------------------------------------------
-# Unit tests: load_point_cloud with frame parameter
+# Frame-id helpers (the user-facing way to discover frame names)
+# ---------------------------------------------------------------------------
+
+class TestFrameIdHelpers:
+    def test_ego_pose_frame_id_exposes_ego_frame(self, loader):
+        # v0.2 fallback chain: meta.ego_pose_frame_id None → annotation_frame_id None → "base_link".
+        assert loader.ego_pose_frame_id == "base_link"
+
+    def test_annotation_frame_id_exposed(self, loader):
+        assert loader.annotation_frame_id == "base_link"
+
+    def test_sensor_frame_id_returns_channel_frame(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        # v0.2 has no per-sensor frame_id, falls back to channel name.
+        assert loader.sensor_frame_id(sd) == "LIDAR_TOP"
+
+    def test_clip_world_constant_is_string_literal(self):
+        # The spec pins this name. Any consumer can pass it as a regular frame.
+        from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID
+        assert CLIP_WORLD_FRAME_ID == "clip_world"
+
+
+# ---------------------------------------------------------------------------
+# load_point_cloud — explicit frame_id, no magic strings
 # ---------------------------------------------------------------------------
 
 class TestLoadPointCloudFrames:
-    def test_sensor_frame_default(self, loader):
-        """Default frame should return raw sensor coordinates."""
+    def test_no_frame_returns_raw_sensor(self, loader):
+        """Default (no frame=) returns the raw sensor data unchanged."""
         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."""
+    def test_frame_equal_to_sensor_frame_is_noop(self, loader):
+        """Passing the sensor's own frame_id matches the no-frame 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)
+        pts_explicit = loader.load_point_cloud(sd, frame=loader.sensor_frame_id(sd))
+        np.testing.assert_array_equal(pts_default, pts_explicit)
 
-    def test_ego_frame(self, loader):
-        """frame='ego' applies sensor-to-ego transform (z+1 for LIDAR_TOP)."""
+    def test_frame_equal_to_ego_applies_calibration(self, loader):
+        """frame=ego_pose_frame_id applies sensor-to-ego (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)
+        pts = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id)
         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."""
+    def test_frame_clip_world_first_ego(self, loader):
+        """frame='clip_world' for the first ego pose (at origin) ≡ 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")
+        pts_ego = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id)
+        pts_world = loader.load_point_cloud(sd, frame=CLIP_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."""
+    def test_frame_clip_world_second_ego(self, loader):
+        """frame='clip_world' for the second ego pose adds the 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)
+        pts = loader.load_point_cloud(sd, frame=CLIP_WORLD)
         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."""
+        """Non-xyz columns are passed through unchanged."""
         sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
-        pts = loader.load_point_cloud(sd, frame="world")
+        pts = loader.load_point_cloud(sd, frame=CLIP_WORLD)
         np.testing.assert_allclose(pts[:, 3], 0.5, atol=1e-6)
 
-    def test_invalid_frame_raises(self, loader):
+    def test_magic_string_world_rejected(self, loader):
+        """The legacy magic string 'world' must be rejected with a hint."""
         sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
-        with pytest.raises(ValueError, match="Invalid frame"):
-            loader.load_point_cloud(sd, frame="invalid")
+        with pytest.raises(ValueError, match=r"clip_world"):
+            loader.load_point_cloud(sd, frame="world")
+
+    def test_magic_string_ego_rejected(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(ValueError, match=r"ego_pose_frame_id"):
+            loader.load_point_cloud(sd, frame="ego")
+
+    def test_magic_string_sensor_rejected(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(ValueError, match=r"sensor_frame_id"):
+            loader.load_point_cloud(sd, frame="sensor")
+
+    def test_unknown_frame_id_raises_keyerror(self, loader):
+        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        with pytest.raises(KeyError, match=r"not_a_real_frame"):
+            loader.load_point_cloud(sd, frame="not_a_real_frame")
 
 
 # ---------------------------------------------------------------------------
-# Unit tests: annotations_for_sample with frame parameter
+# annotations_for_sample — explicit frame_id, no magic strings
 # ---------------------------------------------------------------------------
 
 class TestAnnotationsForSampleFrames:
-    def test_ego_frame_default(self, loader):
-        """Default frame should return annotations in per-sample ego coordinates (v0.5 native)."""
+    def test_no_frame_returns_native(self, loader):
+        """Default (no frame=) returns annotations in the stored frame, unchanged."""
         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_ego_frame_explicit(self, loader):
-        """Explicit frame='ego' should match default."""
+    def test_frame_equal_to_annotation_frame_is_noop(self, loader):
+        """Passing annotation_frame_id matches the no-frame default."""
         anns_default = loader.annotations_for_sample("s-0")
-        anns_ego = loader.annotations_for_sample("s-0", frame="ego")
-        assert len(anns_default) == len(anns_ego)
-        np.testing.assert_allclose(anns_default[0].translation, anns_ego[0].translation)
-
-    def test_world_frame_first_sample(self, loader):
-        """frame='world' for first sample (ego at origin): same as ego."""
-        anns = loader.annotations_for_sample("s-0", frame="world")
-        # ego at origin -> ego-to-world is identity
+        anns_explicit = loader.annotations_for_sample("s-0", frame=loader.annotation_frame_id)
+        np.testing.assert_allclose(anns_default[0].translation, anns_explicit[0].translation)
+
+    def test_frame_clip_world_first_sample(self, loader):
+        """frame='clip_world' on the first sample (ego at origin) ≡ stored ego."""
+        anns = loader.annotations_for_sample("s-0", frame=CLIP_WORLD)
         np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, 0.0], atol=1e-5)
 
-    def test_world_frame_second_sample(self, loader):
-        """frame='world' for second sample (ego at x=10): adds ego offset."""
-        anns = loader.annotations_for_sample("s-1", frame="world")
-        # ego frame (0,3,0), ego at (10,0,0) -> world (10,3,0)
+    def test_frame_clip_world_second_sample(self, loader):
+        """frame='clip_world' on the second sample (ego at x=10) shifts by ego offset."""
+        anns = loader.annotations_for_sample("s-1", frame=CLIP_WORLD)
         np.testing.assert_allclose(anns[0].translation, [10.0, 3.0, 0.0], atol=1e-5)
 
-    def test_ego_frame_velocity_unchanged(self, loader):
-        """Native (ego) frame: velocity returned as stored."""
-        anns = loader.annotations_for_sample("s-0", frame="ego")
+    def test_native_velocity_unchanged(self, loader):
+        anns = loader.annotations_for_sample("s-0")
         np.testing.assert_allclose(anns[0].velocity, [5.0, 0.0, 0.0], atol=1e-5)
 
-    def test_world_frame_preserves_other_fields(self, loader):
-        """Non-pose fields should be preserved across frame transforms."""
-        anns_ego = loader.annotations_for_sample("s-0", frame="ego")
-        anns_world = loader.annotations_for_sample("s-0", frame="world")
-        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_world_frame_returns_new_objects(self, loader):
-        """Transformed annotations should be new objects, not mutated originals."""
-        anns_ego = loader.annotations_for_sample("s-1", frame="ego")
-        anns_world = loader.annotations_for_sample("s-1", frame="world")
-        # Originals (ego, native) should be unmodified
-        np.testing.assert_allclose(anns_ego[0].translation, [0.0, 3.0, 0.0])
-        # World should be different
-        assert not np.allclose(anns_world[0].translation, anns_ego[0].translation, atol=0.1)
-
-    def test_sensor_frame_raises(self, loader):
-        with pytest.raises(ValueError, match="ambiguous"):
+    def test_clip_world_preserves_other_fields(self, loader):
+        anns_native = loader.annotations_for_sample("s-0")
+        anns_world = loader.annotations_for_sample("s-0", frame=CLIP_WORLD)
+        assert anns_native[0].token == anns_world[0].token
+        assert anns_native[0].category == anns_world[0].category
+        np.testing.assert_allclose(anns_native[0].size, anns_world[0].size)
+        assert anns_native[0].num_lidar_pts == anns_world[0].num_lidar_pts
+
+    def test_returns_new_objects(self, loader):
+        """Transformed annotations are new objects; originals untouched."""
+        anns_native = loader.annotations_for_sample("s-1")
+        anns_world = loader.annotations_for_sample("s-1", frame=CLIP_WORLD)
+        np.testing.assert_allclose(anns_native[0].translation, [0.0, 3.0, 0.0])
+        assert not np.allclose(anns_world[0].translation, anns_native[0].translation, atol=0.1)
+
+    def test_frame_sensor_id_transforms_to_that_sensor(self, loader):
+        """Passing a sensor's frame_id transforms annotations into that sensor's frame."""
+        # LIDAR_TOP is at (0,0,1) in ego frame. Annotation at ego (5,3,0) →
+        # LIDAR_TOP frame: subtract z=1 → (5,3,-1).
+        anns = loader.annotations_for_sample("s-0", frame="LIDAR_TOP")
+        np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, -1.0], atol=1e-5)
+
+    def test_magic_string_sensor_rejected(self, loader):
+        with pytest.raises(ValueError, match=r"sensor_frame_id"):
             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_magic_string_ego_rejected(self, loader):
+        with pytest.raises(ValueError, match=r"ego_pose_frame_id"):
+            loader.annotations_for_sample("s-0", frame="ego")
+
+    def test_magic_string_world_rejected(self, loader):
+        with pytest.raises(ValueError, match=r"clip_world"):
+            loader.annotations_for_sample("s-0", frame="world")
+
+    def test_unknown_frame_id_raises(self, loader):
+        with pytest.raises((KeyError, ValueError), match=r"not_a_real_frame"):
+            loader.annotations_for_sample("s-0", frame="not_a_real_frame")
 
     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") == []
+        assert loader.annotations_for_sample("nonexistent") == []
+        assert loader.annotations_for_sample("nonexistent", frame=CLIP_WORLD) == []
 
 
 # ---------------------------------------------------------------------------
-# Unit tests: get_transform
+# get_transform — frame_id × frame_id, sd carries dynamic context
 # ---------------------------------------------------------------------------
 
 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")
+        T = loader.get_transform("LIDAR_TOP", "LIDAR_TOP")
         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
+    def test_static_sensor_to_ego(self, loader):
+        # Static-only: no sd needed.
+        T = loader.get_transform("LIDAR_TOP", loader.ego_pose_frame_id)
         np.testing.assert_allclose(T.translation, [0.0, 0.0, 1.0], atol=1e-10)
 
-    def test_sensor_to_world(self, loader):
+    def test_static_sensor_to_sensor(self, loader):
+        # LIDAR_TOP at (0,0,1) and CAM_FRONT at (0.5,0,0.8) in ego frame.
+        # T_CAM_from_LIDAR = T_CAM_from_ego @ T_ego_from_LIDAR
+        #   = (-0.5, 0, -0.8) ∘ (0, 0, +1) = (-0.5, 0, +0.2)
+        T = loader.get_transform("LIDAR_TOP", "CAM_FRONT")
+        np.testing.assert_allclose(T.translation, [-0.5, 0.0, 0.2], atol=1e-10)
+
+    def test_dynamic_sensor_to_clip_world_requires_sd(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)
+        T = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
+        # sensor → ego (z+1) → world (x+10)  →  (10, 0, 1)
         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_clip_world_without_sd_raises(self, loader):
+        with pytest.raises(ValueError, match=r"clip_world"):
+            loader.get_transform("LIDAR_TOP", CLIP_WORLD)
 
-    def test_round_trip(self, loader):
-        """sensor→world→sensor should be identity."""
+    def test_round_trip_through_clip_world(self, loader):
         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)
+        T_fwd = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
+        T_rev = loader.get_transform(CLIP_WORLD, "LIDAR_TOP", sd=sd)
+        np.testing.assert_allclose((T_fwd @ T_rev).as_matrix, np.eye(4), atol=1e-10)
 
-    def test_all_six_combinations(self, loader):
-        """All from/to combinations should work without error."""
+    def test_magic_string_rejected(self, loader):
         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)
+        with pytest.raises(ValueError, match=r"clip_world"):
+            loader.get_transform("sensor", "world", sd=sd)
 
-    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_unknown_frame_id_raises_keyerror(self, loader):
+        with pytest.raises(KeyError, match=r"not_a_real_frame"):
+            loader.get_transform("LIDAR_TOP", "not_a_real_frame")
 
     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_sensor = loader.load_point_cloud(sd)
+        pts_world = loader.load_point_cloud(sd, frame=CLIP_WORLD)
+        T = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
         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)
 
@@ -434,25 +474,28 @@ def nuscenes_loader(tmp_path_factory):
 @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."""
+        """sensor → clip_world → sensor recovers 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)
+        pts_sensor = nuscenes_loader.load_point_cloud(sd)
+        pts_world = nuscenes_loader.load_point_cloud(sd, frame=CLIP_WORLD)
+        T_back = nuscenes_loader.get_transform(CLIP_WORLD, "LIDAR_TOP", sd=sd)
+        recovered = T_back.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:
+        anns_native = nuscenes_loader.annotations_for_sample(sample.token)
+        anns_world = nuscenes_loader.annotations_for_sample(sample.token, frame=CLIP_WORLD)
+        if not anns_native:
             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"
+        for ann in anns_native:
+            dist = np.linalg.norm(ann.translation[:2])
+            assert dist < 200, f"Annotation too far in native frame: {dist}m"
+        # World frame should differ for at least one annotation (ego usually not at origin).
+        diffs = [
+            np.linalg.norm(an.translation - aw.translation)
+            for an, aw in zip(anns_native, anns_world)
+        ]
+        assert max(diffs) > 0  # at minimum, different positions

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/tests/test_v06_schema.py

@@ -274,7 +274,7 @@ def test_annotations_for_sample_unknown_frame_id_raises(tmp_path):
         }],
     )
     loader = ClipLoader(tmp_path)
-    with pytest.raises(ValueError, match="Invalid frame"):
+    with pytest.raises(KeyError, match="never_exists_frame"):
         loader.annotations_for_sample("s-0", frame="never_exists_frame")
 
 

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/x4d_devkit/core/loader.py

@@ -1,11 +1,20 @@
-"""ClipLoader: load an X4D clip directory into typed dataclasses."""
+"""ClipLoader: load an X4D clip directory into typed dataclasses.
+
+Coordinate frames in this loader are *real frame_id strings only* — every
+frame is either a node in the clip's calibration tree (e.g. ``"LIDAR_TOP"``,
+``"base_link"``, ``"cam_front"``) or the constant ``"clip_world"`` for the
+SLAM-anchored clip-local world. The legacy magic aliases ``"sensor"``,
+``"ego"``, ``"world"`` are no longer accepted; use the helpers
+:meth:`ClipLoader.sensor_frame_id`, :attr:`ClipLoader.ego_pose_frame_id`,
+and :data:`CLIP_WORLD_FRAME_ID` instead.
+"""
 
 from __future__ import annotations
 
 import json
 from dataclasses import replace
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any
 
 import numpy as np
 
@@ -21,14 +30,34 @@ from x4d_devkit.core.models import (
 )
 from x4d_devkit.core.transform import Transform, TransformChain, rotation_matrix_to_quat
 
-FrameType = Literal["sensor", "ego", "world"]
-_VALID_FRAMES = {"sensor", "ego", "world"}
-# In annotation/transform APIs the user may pass the literal aliases above
-# OR any frame_id string that resolves in the calibration tree. We resolve
-# "ego" and "base_link" to the ego (vehicle body) frame; "world" composes
-# with ego_pose; any other string is treated as a sensor frame_id and looked
-# up via the calibration tree.
-_EGO_ALIASES = {"ego", "base_link"}
+
+CLIP_WORLD_FRAME_ID = "clip_world"
+"""The constant frame_id of the SLAM-anchored clip-local world.
+
+Defined by the X-4D dataset spec (v0.8+). Not a node in
+``calibrated_sensor.json``; it is the dynamic edge wired through
+``ego_pose.json`` (``ego_pose[t]: clip_world ← ego_pose_frame_id``).
+"""
+
+_MAGIC_FRAME_REPLACEMENTS = {
+    "sensor": "loader.sensor_frame_id(sd)  (e.g. 'LIDAR_TOP')",
+    "ego":    "loader.ego_pose_frame_id    (e.g. 'base_link')",
+    "world":  f"the constant {CLIP_WORLD_FRAME_ID!r}  "
+              "(also exported as x4d_devkit.core.loader.CLIP_WORLD_FRAME_ID)",
+}
+
+
+def _reject_magic_frame(frame: str) -> None:
+    """Reject the legacy magic aliases ('sensor' / 'ego' / 'world') with a hint."""
+    if frame in _MAGIC_FRAME_REPLACEMENTS:
+        replacements = "; ".join(
+            f"{alias!r} → {hint}" for alias, hint in _MAGIC_FRAME_REPLACEMENTS.items()
+        )
+        raise ValueError(
+            f"frame {frame!r} is not a valid frame_id — the legacy magic aliases "
+            f"'sensor', 'ego', 'world' were removed. Use real frame_ids instead: "
+            f"{replacements}."
+        )
 
 
 class SchemaVersionMismatch(ValueError):
@@ -76,12 +105,13 @@ class ClipLoader:
         for sample in loader.samples:
             for sd in loader.sample_data_for_sample(sample.token):
                 if sd.channel in lidar_channels:
-                    pts = loader.load_point_cloud(sd, frame="ego")
+                    pts = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id)
 
-        # Get annotations in their stored frame (loader.annotation_frame_id)
+        # Annotations in their stored frame:
         anns = loader.annotations_for_sample(sample.token)
-        # Or transform to a specific frame_id from the calibration tree
-        anns_in_top_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")
+        # Or transform to clip-local world / a specific sensor frame:
+        anns_world = loader.annotations_for_sample(sample.token, frame=CLIP_WORLD_FRAME_ID)
+        anns_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")
     """
 
     def __init__(
@@ -288,8 +318,7 @@ class ClipLoader:
 
         Returns ``meta.annotation_frame_id`` if explicitly set (v0.6+ clips).
         Pre-v0.6 clips fall back to ``"base_link"`` — the per-sample ego frame
-        all earlier loader code already assumed (``annotations_for_sample(frame="ego")``
-        was a no-op transform).
+        all earlier loader code already assumed.
         """
         if self._meta.annotation_frame_id is not None:
             return self._meta.annotation_frame_id
@@ -319,6 +348,15 @@ class ClipLoader:
             return info.frame_id
         return channel
 
+    def sensor_frame_id(self, sd: SampleData) -> str:
+        """ROS frame_id of the sensor that produced ``sd``.
+
+        Sugar for ``frame_id_for_channel(sd.channel)`` — the canonical way to
+        get the source frame_id for a piece of sample_data when calling
+        :meth:`load_point_cloud` / :meth:`get_transform`.
+        """
+        return self.frame_id_for_channel(sd.channel)
+
     def require_schema_version(self, expected: "str | set[str]") -> None:
         """Raise ``SchemaVersionMismatch`` if the clip's schema_version isn't in ``expected``.
 
@@ -361,7 +399,7 @@ class ClipLoader:
 
     @property
     def annotations(self) -> list[Annotation]:
-        """All annotations in their **native frame** (ego since v0.5; world for v0.4 clips).
+        """All annotations in their **native frame** (``annotation_frame_id``).
 
         Use ``annotations_for_sample(token, frame=...)`` to request a specific frame.
         """
@@ -411,94 +449,54 @@ class ClipLoader:
     def annotations_for_sample(
         self,
         sample_token: str,
-        frame: str = "ego",
+        frame: str | None = None,
     ) -> list[Annotation]:
-        """All annotations for a given sample, transformed to the requested frame.
+        """All annotations for a given sample, optionally transformed to ``frame``.
 
         Args:
             sample_token: The sample token.
-            frame: Target coordinate frame. Accepted values:
-                - ``"ego"`` / ``"base_link"`` (default): vehicle body frame.
-                - ``"world"``: clip-local world frame (composes with ego_pose).
-                - any sensor's ROS frame_id present in the calibration tree
-                  (e.g. ``"LIDAR_TOP"``, ``"camera-front"``).
-                - ``"sensor"`` is rejected (ambiguous — no single sensor implied).
+            frame: Target frame_id. ``None`` (default) returns annotations in
+                their stored frame (``loader.annotation_frame_id``). Any other
+                value must be a real frame_id in the calibration tree, or the
+                constant :data:`CLIP_WORLD_FRAME_ID`. The legacy magic aliases
+                ``"sensor"``/``"ego"``/``"world"`` raise ``ValueError``.
 
         Returns:
             List of Annotation objects in the requested frame.
         """
-        if frame == "sensor":
-            raise ValueError(
-                "frame='sensor' is ambiguous for annotations; pass an explicit "
-                "frame_id (e.g. 'LIDAR_TOP') or use 'ego' / 'base_link' / 'world'."
-            )
+        if frame is not None:
+            _reject_magic_frame(frame)
 
         anns = self._ann_by_sample.get(sample_token, [])
-        if not anns:
+        if not anns or frame is None or frame == self.annotation_frame_id:
             return anns
 
-        T = self._transform_for_annotation_target(sample_token, frame)
-        if T is None:
-            return anns
+        sd = None
+        if frame == CLIP_WORLD_FRAME_ID:
+            sd = self._representative_sd_for_sample(sample_token)
+        T = self.get_transform(self.annotation_frame_id, frame, sd=sd)
         return [self._transform_annotation(a, T) for a in anns]
 
-    def _transform_for_annotation_target(
-        self, sample_token: str, target_frame: str
-    ) -> Transform | None:
-        """Build the transform from the clip's annotation frame to ``target_frame``.
-
-        Returns ``None`` when the requested frame matches the storage frame
-        (no transform needed).
-        """
-        ann_frame = self.annotation_frame_id  # e.g. "base_link" or "LIDAR_TOP"
-        if target_frame == ann_frame:
-            return None
-        if target_frame in _EGO_ALIASES and ann_frame in _EGO_ALIASES:
-            return None
-
-        chain = self._get_transform_chain()
-        # T(ego ← annotation_frame): identity if annotation frame is ego/base_link;
-        # else look up the sensor whose frame_id == ann_frame.
-        if ann_frame in _EGO_ALIASES:
-            ego_from_ann = Transform.identity()
-        else:
-            ego_from_ann = chain.get_ego_from_frame_id(ann_frame)
-
-        # T(target ← ego)
-        if target_frame in _EGO_ALIASES:
-            target_from_ego = Transform.identity()
-        elif target_frame == "world":
-            target_from_ego = self._get_world_from_ego_for_sample(sample_token)
-        else:
-            try:
-                ego_from_target = chain.get_ego_from_frame_id(target_frame)
-            except KeyError as e:
-                raise ValueError(
-                    f"Invalid frame {target_frame!r} for annotations: {e}"
-                ) from None
-            target_from_ego = ego_from_target.inverse
-
-        return target_from_ego @ ego_from_ann
-
     def load_point_cloud(
         self,
         sd: SampleData,
-        frame: FrameType = "sensor",
+        frame: str | None = None,
     ) -> np.ndarray:
         """Load point cloud binary file as (N, C) float32 array.
 
         Args:
             sd: The SampleData record for the point cloud.
-            frame: Target coordinate frame.
-                - "sensor" (default): raw sensor frame.
-                - "ego": sensor → ego via calibrated_sensor extrinsics.
-                - "world": sensor → ego → world via extrinsics + ego_pose.
+            frame: Target frame_id. ``None`` (default) returns raw sensor
+                coordinates. Any other value must be a real frame_id in the
+                calibration tree, or :data:`CLIP_WORLD_FRAME_ID`. The legacy
+                magic aliases ``"sensor"``/``"ego"``/``"world"`` raise
+                ``ValueError``.
 
         Returns:
             Point cloud as (N, C) float32 array with xyz in the requested frame.
         """
-        if frame not in _VALID_FRAMES:
-            raise ValueError(f"Invalid frame '{frame}', must be one of {_VALID_FRAMES}")
+        if frame is not None:
+            _reject_magic_frame(frame)
 
         sensor_info = self._meta.sensors[sd.channel]
         if sensor_info.point_format is None:
@@ -512,53 +510,49 @@ class ClipLoader:
         raw = np.fromfile(str(path), dtype=np.float32)
         pts = raw.reshape(-1, num_fields)
 
-        if frame == "sensor":
+        src_frame = self.sensor_frame_id(sd)
+        if frame is None or frame == src_frame:
             return pts
 
-        T = self.get_transform(sd, from_frame="sensor", to_frame=frame)
+        T = self.get_transform(src_frame, frame, sd=sd)
         pts[:, :3] = T.apply(pts[:, :3].astype(np.float64)).astype(np.float32)
         return pts
 
     def get_transform(
         self,
-        sd: SampleData,
-        from_frame: FrameType = "sensor",
-        to_frame: FrameType = "world",
+        from_frame: str,
+        to_frame: str,
+        *,
+        sd: SampleData | None = None,
     ) -> Transform:
-        """Get a Transform between coordinate frames for a given sample_data.
+        """Build the SE(3) transform ``to_frame ← from_frame``.
+
+        Both arguments are real frame_id strings (calibration-tree nodes or
+        :data:`CLIP_WORLD_FRAME_ID`). When either side is ``CLIP_WORLD_FRAME_ID``
+        the transform is dynamic and ``sd`` (or another ego_pose-bearing
+        SampleData) must be supplied to fix the timestamp.
 
         Args:
-            sd: The SampleData record (provides channel and ego_pose_token).
-            from_frame: Source frame ("sensor", "ego", or "world").
-            to_frame: Target frame ("sensor", "ego", or "world").
+            from_frame: Source frame_id.
+            to_frame: Destination frame_id.
+            sd: SampleData fixing the ego_pose for ``CLIP_WORLD_FRAME_ID``;
+                omit when both frames are static (in the calibration tree).
 
         Returns:
-            Transform object. Use T.apply(points) or T.as_matrix for the 4x4 matrix.
-        """
-        if from_frame not in _VALID_FRAMES:
-            raise ValueError(f"Invalid from_frame '{from_frame}', must be one of {_VALID_FRAMES}")
-        if to_frame not in _VALID_FRAMES:
-            raise ValueError(f"Invalid to_frame '{to_frame}', must be one of {_VALID_FRAMES}")
+            Transform such that ``p_to = T.apply(p_from)``.
 
+        Raises:
+            ValueError: if a magic alias is passed, or ``CLIP_WORLD_FRAME_ID``
+                is requested without ``sd``.
+            KeyError: if a frame_id is not in the calibration tree.
+        """
+        _reject_magic_frame(from_frame)
+        _reject_magic_frame(to_frame)
         if from_frame == to_frame:
             return Transform.identity()
-
-        chain = self._get_transform_chain()
-        ego_from_sensor = chain.get_ego_from_sensor(sd.channel)
-        world_from_ego = chain.get_world_from_ego(sd.ego_pose_token)
-
-        if from_frame == "sensor" and to_frame == "ego":
-            return ego_from_sensor
-        elif from_frame == "sensor" and to_frame == "world":
-            return world_from_ego @ ego_from_sensor
-        elif from_frame == "ego" and to_frame == "world":
-            return world_from_ego
-        elif from_frame == "ego" and to_frame == "sensor":
-            return ego_from_sensor.inverse
-        elif from_frame == "world" and to_frame == "ego":
-            return world_from_ego.inverse
-        else:  # world -> sensor
-            return (world_from_ego @ ego_from_sensor).inverse
+        T_root_from_src = self._root_from_frame(from_frame, sd=sd)
+        T_root_from_dst = self._root_from_frame(to_frame, sd=sd)
+        return T_root_from_dst.inverse @ T_root_from_src
 
     def load_image_path(self, sd: SampleData) -> Path:
         """Get the absolute path to an image file.
@@ -581,24 +575,42 @@ class ClipLoader:
             self._transform_chain = TransformChain(self)
         return self._transform_chain
 
-    def _get_world_from_ego_for_sample(self, sample_token: str) -> Transform:
-        """Get the world_from_ego transform for a sample.
+    def _root_from_frame(
+        self, frame_id: str, *, sd: SampleData | None = None,
+    ) -> Transform:
+        """Transform from ``frame_id`` to the calibration tree root.
 
-        Uses the ego_pose from the LiDAR sample_data, or the first sample_data
-        if no LiDAR channel exists.
+        For :data:`CLIP_WORLD_FRAME_ID` the result is dynamic (depends on
+        ``sd.ego_pose_token``); for any other frame it is the static walk
+        through ``calibrated_sensor.json``.
         """
+        chain = self._get_transform_chain()
+        if frame_id != CLIP_WORLD_FRAME_ID:
+            return chain.get_root_from_frame_id(frame_id)
+        if sd is None:
+            raise ValueError(
+                f"frame {CLIP_WORLD_FRAME_ID!r} is dynamic — pass sd=<SampleData> "
+                f"so the transform can be evaluated at the correct ego_pose."
+            )
+        ego_fid = self.ego_pose_frame_id
+        T_root_from_ego = chain.get_root_from_frame_id(ego_fid)
+        T_world_from_ego = chain.get_world_from_ego(sd.ego_pose_token)
+        # T_root_from_world = T_root_from_ego @ T_world_from_ego.inverse
+        return T_root_from_ego @ T_world_from_ego.inverse
+
+    def _representative_sd_for_sample(self, sample_token: str) -> SampleData:
+        """Pick a representative SampleData (preferring lidar) for a sample."""
         sds = self._sd_by_sample.get(sample_token, [])
         if not sds:
-            raise ValueError(f"No sample_data found for sample {sample_token}")
-
-        # Prefer LiDAR sample_data for the ego_pose
+            raise ValueError(
+                f"sample {sample_token!r} has no sample_data — cannot resolve "
+                f"{CLIP_WORLD_FRAME_ID!r}."
+            )
         cs_map = {cs.channel: cs for cs in self._calibrated_sensors}
-        sd = next(
+        return next(
             (s for s in sds if cs_map.get(s.channel) and cs_map[s.channel].modality == "lidar"),
             sds[0],
         )
-        chain = self._get_transform_chain()
-        return chain.get_world_from_ego(sd.ego_pose_token)
 
     @staticmethod
     def _transform_annotation(ann: Annotation, T: Transform) -> Annotation:

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0}/x4d_devkit/core/models.py

@@ -275,7 +275,7 @@ class Annotation:
     via calibration, so per-sample timing is determined by ``sample_token``.
     For v0.5 clips without an explicit field, the convention is per-sample ego
     frame (== ``base_link``). Use ``ClipLoader.annotations_for_sample(..., frame=...)``
-    to transform to ``"world"`` or any other frame_id in the calibration tree.
+    to transform to ``"clip_world"`` or any other frame_id in the calibration tree.
 
     Attributes:
         token: Unique annotation token.

{x4d_devkit-0.11.1 → x4d_devkit-0.12.0/x4d_devkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.11.1
+Version: 0.12.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -65,22 +65,31 @@ for sample in loader.samples:
 
 ### Coordinate frame transforms
 
-Point clouds and annotations can be loaded in different coordinate frames:
+Frames are real frame_id strings: any node in the calibration tree (e.g.
+`"LIDAR_TOP"`, `"base_link"`, `"cam_front"`) plus the constant
+`"clip_world"` (the SLAM-anchored clip-local world). The legacy aliases
+`"sensor"`, `"ego"`, `"world"` are not accepted.
 
 ```python
+from x4d_devkit import ClipLoader
+from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID
+
 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
+pts_sensor = loader.load_point_cloud(sd)                                 # raw sensor (default)
+pts_ego    = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id) # sensor → ego
+pts_world  = loader.load_point_cloud(sd, frame=CLIP_WORLD_FRAME_ID)      # sensor → clip_world
+
+# Get annotations transformed to clip-local world
+anns_world = loader.annotations_for_sample(sample.token, frame=CLIP_WORLD_FRAME_ID)
 
-# Get annotations in ego frame (for training)
-anns_ego = loader.annotations_for_sample(sample.token, frame="ego")
+# Or to a specific sensor's frame
+anns_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")
 
-# Get the transform matrix directly
-T = loader.get_transform(sd, from_frame="sensor", to_frame="world")
+# Get the transform matrix directly (sd is required when clip_world is involved)
+T = loader.get_transform(loader.sensor_frame_id(sd), CLIP_WORLD_FRAME_ID, sd=sd)
 pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4
 ```