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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.1.0"
+version = "0.2.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.2.0/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.0}/x4d_devkit/core/loader.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import json
+from dataclasses import replace
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import numpy as np
 
@@ -17,6 +18,10 @@ from x4d_devkit.core.models import (
     Annotation,
     Instance,
 )
+from x4d_devkit.core.transform import Transform, TransformChain, rotation_matrix_to_quat
+
+FrameType = Literal["sensor", "ego", "world"]
+_VALID_FRAMES = {"sensor", "ego", "world"}
 
 
 class ClipLoader:
@@ -237,23 +242,160 @@ class ClipLoader:
         """All sample_data records for a given sample (all channels at that timestamp)."""
         return self._sd_by_sample.get(sample_token, [])
 
-    def annotations_for_sample(self, sample_token: str) -> list[Annotation]:
-        """All annotations for a given sample."""
-        return self._ann_by_sample.get(sample_token, [])
-
-    def load_point_cloud(self, sd: SampleData) -> np.ndarray:
+    def annotations_for_sample(
+        self,
+        sample_token: str,
+        frame: FrameType = "world",
+    ) -> list[Annotation]:
+        """All annotations for a given sample.
+
+        Args:
+            sample_token: The sample token.
+            frame: Target coordinate frame.
+                - "world" (default): native annotation frame, no transform.
+                - "ego": transform from world to ego frame using the ego_pose
+                  of the LiDAR sample_data for this sample (or first sample_data
+                  if no LiDAR).
+
+        Returns:
+            List of Annotation objects in the requested frame.
+        """
+        if frame not in _VALID_FRAMES:
+            raise ValueError(f"Invalid frame '{frame}', must be one of {_VALID_FRAMES}")
+        if frame == "sensor":
+            raise ValueError("Annotations cannot be transformed to sensor frame")
+
+        anns = self._ann_by_sample.get(sample_token, [])
+        if frame == "world" or not anns:
+            return anns
+
+        # frame == "ego": need ego_pose for this sample
+        ego_from_world = self._get_ego_from_world_for_sample(sample_token)
+        return [self._transform_annotation(a, ego_from_world) for a in anns]
+
+    def load_point_cloud(
+        self,
+        sd: SampleData,
+        frame: FrameType = "sensor",
+    ) -> np.ndarray:
         """Load point cloud binary file as (N, C) float32 array.
 
-        Uses meta.sensors[channel].point_format to determine stride.
+        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.
+
+        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}")
+
         sensor_info = self._meta.sensors[sd.channel]
         pf = sensor_info["point_format"]
         num_fields = len(pf["fields"])
 
         path = self._clip_dir / sd.file_path
         raw = np.fromfile(str(path), dtype=np.float32)
-        return raw.reshape(-1, num_fields)
+        pts = raw.reshape(-1, num_fields)
+
+        if frame == "sensor":
+            return pts
+
+        T = self.get_transform(sd, from_frame="sensor", to_frame=frame)
+        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",
+    ) -> Transform:
+        """Get a Transform between coordinate frames for a given sample_data.
+
+        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").
+
+        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}")
+
+        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
 
     def load_image_path(self, sd: SampleData) -> Path:
         """Return the absolute path to the image file (does not load pixels)."""
         return self._clip_dir / sd.file_path
+
+    # --- Private helpers ---
+
+    def _get_transform_chain(self) -> TransformChain:
+        """Lazily initialize and return a TransformChain."""
+        if not hasattr(self, "_transform_chain"):
+            self._transform_chain = TransformChain(self)
+        return self._transform_chain
+
+    def _get_ego_from_world_for_sample(self, sample_token: str) -> Transform:
+        """Get the inverse ego_pose transform for a sample.
+
+        Uses the ego_pose from the LiDAR sample_data, or the first sample_data
+        if no LiDAR channel exists.
+        """
+        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
+        cs_map = {cs.channel: cs for cs in self._calibrated_sensors}
+        sd = 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).inverse
+
+    @staticmethod
+    def _transform_annotation(ann: Annotation, T: Transform) -> Annotation:
+        """Apply a rigid transform to an annotation's pose, returning a new Annotation."""
+        new_translation = T.apply(ann.translation)
+        new_rotation_mat = T.rotation @ Transform.from_quat(
+            [0, 0, 0], ann.rotation
+        ).rotation
+        new_quat = rotation_matrix_to_quat(new_rotation_mat)
+
+        new_velocity = None
+        if ann.velocity is not None:
+            new_velocity = T.rotation @ ann.velocity
+
+        return replace(
+            ann,
+            translation=new_translation,
+            rotation=np.array(new_quat),
+            velocity=new_velocity,
+        )

{x4d_devkit-0.1.0 → x4d_devkit-0.2.0}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.1.0 → x4d_devkit-0.2.0}/x4d_devkit.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 pyproject.toml
+tests/test_coordinate_frames.py
 tests/test_detection_eval.py
 tests/test_loader.py
 tests/test_matching.py