x4d-devkit 0.8.0__tar.gz → 0.9.0__tar.gz

{x4d_devkit-0.8.0/x4d_devkit.egg-info → x4d_devkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.8.0
+Version: 0.9.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.8.0 → x4d_devkit-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.8.0"
+version = "0.9.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.8.0 → x4d_devkit-0.9.0}/tests/test_coordinate_frames.py

@@ -331,7 +331,7 @@ class TestAnnotationsForSampleFrames:
         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="sensor frame"):
+        with pytest.raises(ValueError, match="ambiguous"):
             loader.annotations_for_sample("s-0", frame="sensor")
 
     def test_invalid_frame_raises(self, loader):

x4d_devkit-0.9.0/tests/test_v06_schema.py

@@ -0,0 +1,414 @@
+"""Tests for v0.6 schema additions: annotation_frame_id + per-sensor frame_id.
+
+Covers:
+    - SensorInfo.frame_id round-trip
+    - ClipMeta.annotation_frame_id round-trip
+    - ClipLoader.annotation_frame_id property (explicit + back-compat default)
+    - ClipLoader.frame_id_for_channel
+    - annotations_for_sample(frame=<arbitrary frame_id>)
+    - TransformChain.get_ego_from_frame_id
+    - validate_clip schema 0.6 strict checks
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from x4d_devkit import ClipLoader, validate_clip
+from x4d_devkit.core.models import ClipMeta, PointFormat, SensorInfo
+
+
+def _q_from_yaw(yaw: float) -> dict[str, float]:
+    return {"qx": 0.0, "qy": 0.0, "qz": math.sin(yaw / 2), "qw": math.cos(yaw / 2)}
+
+
+def _write_clip(
+    clip_dir: Path,
+    *,
+    schema_version: str,
+    annotation_frame_id: str | None,
+    sensors_meta: dict,
+    calibrated: list[dict],
+    samples: list[dict] | None = None,
+    sample_data: list[dict] | None = None,
+    annotations: list[dict] | None = None,
+) -> None:
+    clip_dir.mkdir(parents=True, exist_ok=True)
+    meta = {
+        "clip_id": "test-v06",
+        "schema_version": schema_version,
+        "session_id": "s",
+        "vehicle_id": "v",
+        "capture_time_utc": "2026-05-06T00:00:00Z",
+        "duration_s": 0.0,
+        "keyframe_count": len(samples or []),
+        "sweep_count": 0,
+        "sensors": sensors_meta,
+    }
+    if annotation_frame_id is not None:
+        meta["annotation_frame_id"] = annotation_frame_id
+    (clip_dir / "meta.json").write_text(json.dumps(meta))
+    (clip_dir / "calibrated_sensor.json").write_text(json.dumps(calibrated))
+    (clip_dir / "ego_pose.json").write_text(json.dumps([{
+        "ego_pose_token": "ep-0",
+        "timestamp_us": 0,
+        "translation": {"x": 0, "y": 0, "z": 0},
+        "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+    }]))
+    (clip_dir / "sample.json").write_text(json.dumps(samples or [{
+        "sample_token": "s-0", "timestamp_us": 0, "is_keyframe": True,
+        "prev": "", "next": "",
+    }]))
+    (clip_dir / "sample_data.json").write_text(json.dumps(sample_data or [{
+        "sample_data_token": "sd-0",
+        "sample_token": "s-0",
+        "channel": calibrated[0]["channel"],
+        "timestamp_us": 0,
+        "file_path": "samples/x/0.bin",
+        "ego_pose_token": "ep-0",
+        "calibrated_sensor_token": calibrated[0]["calibrated_sensor_token"],
+        "is_keyframe": True,
+        "width": None, "height": None,
+        "prev": "", "next": "",
+    }]))
+    (clip_dir / "annotation.json").write_text(json.dumps(annotations or []))
+    (clip_dir / "instance.json").write_text(json.dumps([]))
+
+
+# --- Model round-trip ---
+
+
+def test_sensor_info_frame_id_round_trip():
+    info = SensorInfo.from_dict({"modality": "lidar", "frame_id": "LIDAR_TOP"})
+    assert info.frame_id == "LIDAR_TOP"
+    assert info.to_dict()["frame_id"] == "LIDAR_TOP"
+
+
+def test_sensor_info_no_frame_id_omits_key_in_to_dict():
+    info = SensorInfo.from_dict({"modality": "camera"})
+    assert info.frame_id is None
+    assert "frame_id" not in info.to_dict()
+
+
+def test_clip_meta_annotation_frame_id_default_none():
+    meta = ClipMeta(
+        clip_id="x", schema_version="0.5", session_id="s", vehicle_id="v",
+        capture_time_utc="t", duration_s=0.0, num_keyframes=0, num_sweeps=0,
+        sensors={},
+    )
+    assert meta.annotation_frame_id is None
+
+
+# --- Loader: annotation_frame_id property ---
+
+
+def test_loader_annotation_frame_id_explicit(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="LIDAR_TOP",
+        sensors_meta={"LIDAR_TOP": {"modality": "lidar", "frame_id": "LIDAR_TOP",
+                                     "point_format": {"fields": ["x", "y", "z"],
+                                                      "types": ["float32"] * 3,
+                                                      "bytes_per_point": 12}}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "LIDAR_TOP",
+            "translation": {"x": 0, "y": 0, "z": 1.5},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    assert loader.annotation_frame_id == "LIDAR_TOP"
+
+
+def test_loader_annotation_frame_id_back_compat_default(tmp_path):
+    """Pre-v0.6 clip with no annotation_frame_id falls back to base_link."""
+    _write_clip(
+        tmp_path,
+        schema_version="0.5",
+        annotation_frame_id=None,
+        sensors_meta={"lidar": {"modality": "lidar"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    assert loader.annotation_frame_id == "base_link"
+
+
+def test_loader_frame_id_for_channel_explicit(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="base_link",
+        sensors_meta={"lidar": {"modality": "lidar", "frame_id": "base_link"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    assert loader.frame_id_for_channel("lidar") == "base_link"
+
+
+def test_loader_frame_id_for_channel_fallback_to_channel_name(tmp_path):
+    """Pre-v0.6 clip falls back to channel ≡ frame_id convention."""
+    _write_clip(
+        tmp_path,
+        schema_version="0.5",
+        annotation_frame_id=None,
+        sensors_meta={"LIDAR_TOP": {"modality": "lidar"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "LIDAR_TOP",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    assert loader.frame_id_for_channel("LIDAR_TOP") == "LIDAR_TOP"
+
+
+# --- Loader: annotations_for_sample with arbitrary frame_id ---
+
+
+def test_annotations_for_sample_in_storage_frame_no_op(tmp_path):
+    """Requesting the storage frame returns annotations unchanged."""
+    ann = {
+        "annotation_token": "a-0", "sample_token": "s-0", "instance_token": "i-0",
+        "category": "car",
+        "bbox_3d": {
+            "translation": {"x": 5.0, "y": 0.0, "z": 0.0},
+            "size": {"length": 4.0, "width": 2.0, "height": 1.5},
+            "rotation": _q_from_yaw(0.0),
+        },
+        "num_lidar_pts": 100, "visibility": "4", "velocity": None,
+        "attributes": [], "prev": "", "next": "", "score": None,
+    }
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="LIDAR_TOP",
+        sensors_meta={"LIDAR_TOP": {"modality": "lidar", "frame_id": "LIDAR_TOP",
+                                     "point_format": {"fields": ["x", "y", "z"],
+                                                      "types": ["float32"] * 3,
+                                                      "bytes_per_point": 12}}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "LIDAR_TOP",
+            "translation": {"x": 0, "y": 0, "z": 1.5},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+        annotations=[ann],
+    )
+    loader = ClipLoader(tmp_path)
+    [a] = loader.annotations_for_sample("s-0", frame="LIDAR_TOP")
+    np.testing.assert_allclose(a.translation, [5.0, 0.0, 0.0])
+
+
+def test_annotations_for_sample_lidar_top_to_base_link(tmp_path):
+    """Annotation in LIDAR_TOP with z-offset 1.5 → base_link adds 1.5 to z."""
+    ann = {
+        "annotation_token": "a-0", "sample_token": "s-0", "instance_token": "i-0",
+        "category": "car",
+        "bbox_3d": {
+            "translation": {"x": 5.0, "y": 0.0, "z": 0.0},
+            "size": {"length": 4.0, "width": 2.0, "height": 1.5},
+            "rotation": _q_from_yaw(0.0),
+        },
+        "num_lidar_pts": 100, "visibility": "4", "velocity": None,
+        "attributes": [], "prev": "", "next": "", "score": None,
+    }
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="LIDAR_TOP",
+        sensors_meta={"LIDAR_TOP": {"modality": "lidar", "frame_id": "LIDAR_TOP",
+                                     "point_format": {"fields": ["x", "y", "z"],
+                                                      "types": ["float32"] * 3,
+                                                      "bytes_per_point": 12}}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "LIDAR_TOP",
+            "translation": {"x": 0, "y": 0, "z": 1.5},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+        annotations=[ann],
+    )
+    loader = ClipLoader(tmp_path)
+    [a] = loader.annotations_for_sample("s-0", frame="base_link")
+    np.testing.assert_allclose(a.translation, [5.0, 0.0, 1.5])
+
+
+def test_annotations_for_sample_unknown_frame_id_raises(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="base_link",
+        sensors_meta={"lidar": {"modality": "lidar", "frame_id": "base_link"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+        annotations=[{
+            "annotation_token": "a-0", "sample_token": "s-0", "instance_token": "i-0",
+            "category": "car",
+            "bbox_3d": {"translation": {"x": 0, "y": 0, "z": 0},
+                        "size": {"length": 1, "width": 1, "height": 1},
+                        "rotation": _q_from_yaw(0.0)},
+            "num_lidar_pts": 0, "visibility": "", "velocity": None,
+            "attributes": [], "prev": "", "next": "", "score": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    with pytest.raises(ValueError, match="Invalid frame"):
+        loader.annotations_for_sample("s-0", frame="never_exists_frame")
+
+
+# --- TransformChain.get_ego_from_frame_id ---
+
+
+def test_transform_chain_ego_from_frame_id_base_link_is_identity(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="base_link",
+        sensors_meta={"lidar": {"modality": "lidar", "frame_id": "base_link"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    from x4d_devkit.core.transform import TransformChain
+    chain = TransformChain(loader)
+    T = chain.get_ego_from_frame_id("base_link")
+    np.testing.assert_allclose(T.translation, [0, 0, 0])
+    np.testing.assert_allclose(T.rotation, np.eye(3))
+
+
+def test_transform_chain_ego_from_frame_id_resolves_via_sensor_frame_id(tmp_path):
+    """When a sensor declares frame_id != channel, lookup uses frame_id."""
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="base_link",
+        sensors_meta={"recon_pcd": {"modality": "lidar", "frame_id": "camera-front"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "recon_pcd",
+            "translation": {"x": 1.0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    loader = ClipLoader(tmp_path)
+    from x4d_devkit.core.transform import TransformChain
+    chain = TransformChain(loader)
+    T = chain.get_ego_from_frame_id("camera-front")
+    np.testing.assert_allclose(T.translation, [1.0, 0, 0])
+
+
+# --- Validator: schema 0.6 strict checks ---
+
+
+def test_validate_v06_missing_annotation_frame_id_errors(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id=None,  # missing on purpose
+        sensors_meta={"lidar": {"modality": "lidar", "frame_id": "base_link"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    report = validate_clip(tmp_path)
+    assert any(i.check == "annotation_frame_id" for i in report.errors)
+
+
+def test_validate_v06_missing_sensor_frame_id_errors(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="base_link",
+        sensors_meta={"lidar": {"modality": "lidar"}},  # no frame_id
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    report = validate_clip(tmp_path)
+    assert any(i.check == "sensor_frame_id" for i in report.errors)
+
+
+def test_validate_v06_unresolvable_annotation_frame_errors(tmp_path):
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="non_existent_frame",
+        sensors_meta={"lidar": {"modality": "lidar", "frame_id": "base_link"}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "lidar",
+            "translation": {"x": 0, "y": 0, "z": 0},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+    )
+    report = validate_clip(tmp_path)
+    msgs = [i.message for i in report.errors if i.check == "annotation_frame_id"]
+    assert any("does not resolve" in m for m in msgs)
+
+
+def test_validate_v06_passes_with_lidar_top_annotation_frame(tmp_path):
+    """Scenario 1 (nuScenes-style): annotation_frame_id == sensor's own frame_id."""
+    ann = {
+        "annotation_token": "a-0", "sample_token": "s-0", "instance_token": "i-0",
+        "category": "car",
+        "bbox_3d": {"translation": {"x": 5, "y": 0, "z": 0},
+                    "size": {"length": 4, "width": 2, "height": 1.5},
+                    "rotation": _q_from_yaw(0.0)},
+        "num_lidar_pts": 50, "visibility": "4", "velocity": None,
+        "attributes": [], "prev": "", "next": "", "score": None,
+    }
+    _write_clip(
+        tmp_path,
+        schema_version="0.6",
+        annotation_frame_id="LIDAR_TOP",
+        sensors_meta={"LIDAR_TOP": {"modality": "lidar", "frame_id": "LIDAR_TOP",
+                                     "point_format": {"fields": ["x", "y", "z", "intensity", "t"],
+                                                      "types": ["float32"] * 5,
+                                                      "bytes_per_point": 20}}},
+        calibrated=[{
+            "calibrated_sensor_token": "cs-0", "channel": "LIDAR_TOP",
+            "translation": {"x": 0, "y": 0, "z": 1.5},
+            "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
+            "intrinsics": None, "distortion": None,
+        }],
+        annotations=[ann],
+    )
+    pcd_path = tmp_path / "samples/x/0.bin"
+    pcd_path.parent.mkdir(parents=True, exist_ok=True)
+    np.zeros(5, dtype=np.float32).tofile(pcd_path)
+
+    report = validate_clip(tmp_path)
+    schema_errors = [i for i in report.errors if i.check in ("annotation_frame_id", "sensor_frame_id")]
+    assert schema_errors == [], f"unexpected schema errors: {schema_errors}"

{x4d_devkit-0.8.0 → x4d_devkit-0.9.0}/x4d_devkit/core/loader.py

@@ -23,6 +23,12 @@ from x4d_devkit.core.transform import Transform, TransformChain, rotation_matrix
 
 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"}
 
 
 class SchemaVersionMismatch(ValueError):
@@ -58,14 +64,24 @@ class ClipLoader:
         loader = ClipLoader("/data/clips/my_clip")
         print(loader.meta.clip_id)
 
-        # Iterate samples and load point clouds
+        # Find lidar channels by modality — never hardcode "lidar" / "LIDAR_TOP".
+        # The directory/channel name is producer-defined: nuScenes-converted clips
+        # use "LIDAR_TOP", X-4D platform fused output uses "lidar", reconstruction
+        # pipelines may use any name. Always look up via meta.sensors.
+        lidar_channels = [
+            ch for ch, info in loader.meta.sensors.items()
+            if info.modality == "lidar"
+        ]
+
         for sample in loader.samples:
             for sd in loader.sample_data_for_sample(sample.token):
-                if "LIDAR" in sd.channel:
+                if sd.channel in lidar_channels:
                     pts = loader.load_point_cloud(sd, frame="ego")
 
-        # Get annotations in ego frame for training
-        anns = loader.annotations_for_sample(sample.token, frame="ego")
+        # Get annotations in their stored frame (loader.annotation_frame_id)
+        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")
     """
 
     def __init__(
@@ -137,6 +153,7 @@ class ClipLoader:
             num_keyframes=d["keyframe_count"],
             num_sweeps=d["sweep_count"],
             sensors=sensors,
+            annotation_frame_id=d.get("annotation_frame_id"),
         )
 
     def _load_calibrated_sensors(self) -> list[CalibratedSensor]:
@@ -263,6 +280,31 @@ class ClipLoader:
         """Shortcut for ``self.meta.schema_version`` — the X-4D format version this clip was written in."""
         return self._meta.schema_version
 
+    @property
+    def annotation_frame_id(self) -> str:
+        """The vehicle-local frame_id annotations are stored in.
+
+        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).
+        """
+        if self._meta.annotation_frame_id is not None:
+            return self._meta.annotation_frame_id
+        return "base_link"
+
+    def frame_id_for_channel(self, channel: str) -> str:
+        """Resolve the ROS frame_id of a sensor channel.
+
+        Looks up ``meta.sensors[channel].frame_id`` (v0.6+). Falls back to the
+        channel name itself for older clips, per the v0.4 ``channel ≡ frame_id``
+        convention.
+        """
+        info = self._meta.sensors.get(channel)
+        if info is not None and info.frame_id is not None:
+            return info.frame_id
+        return channel
+
     def require_schema_version(self, expected: "str | set[str]") -> None:
         """Raise ``SchemaVersionMismatch`` if the clip's schema_version isn't in ``expected``.
 
@@ -355,34 +397,74 @@ class ClipLoader:
     def annotations_for_sample(
         self,
         sample_token: str,
-        frame: FrameType = "ego",
+        frame: str = "ego",
     ) -> list[Annotation]:
-        """All annotations for a given sample.
+        """All annotations for a given sample, transformed to the requested frame.
 
         Args:
             sample_token: The sample token.
-            frame: Target coordinate frame.
-                - "ego" (default, v0.5 native): no transform — annotations are
-                  stored in the per-sample ego frame.
-                - "world": transform from ego to world using the ego_pose of
-                  the LiDAR sample_data for this sample (or first sample_data
-                  if no LiDAR).
+            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).
 
         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")
+            raise ValueError(
+                "frame='sensor' is ambiguous for annotations; pass an explicit "
+                "frame_id (e.g. 'LIDAR_TOP') or use 'ego' / 'base_link' / 'world'."
+            )
 
         anns = self._ann_by_sample.get(sample_token, [])
-        if frame == "ego" or not anns:
+        if not anns:
+            return anns
+
+        T = self._transform_for_annotation_target(sample_token, frame)
+        if T is None:
             return anns
+        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``.
 
-        # frame == "world": transform per-sample-ego → world via ego_pose.
-        world_from_ego = self._get_world_from_ego_for_sample(sample_token)
-        return [self._transform_annotation(a, world_from_ego) for a in anns]
+        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,

{x4d_devkit-0.8.0 → x4d_devkit-0.9.0}/x4d_devkit/core/models.py

@@ -72,6 +72,9 @@ class SensorInfo:
 
     Attributes:
         modality: ``"lidar"`` or ``"camera"``.
+        frame_id: ROS-style frame_id of this channel's stored data. Required by
+            v0.6 schema; ``None`` on older clips. For fused outputs the producer
+            should set this to the fusion target frame (e.g. ``"base_link"``).
         point_format: Binary point layout (LiDAR only; ``None`` for cameras).
         resolution: ``(width, height)`` in pixels (cameras only; ``None`` for LiDAR).
         extras: Any additional fields the producer wrote into the sensor dict.
@@ -79,6 +82,7 @@ class SensorInfo:
     """
 
     modality: str
+    frame_id: str | None = None
     point_format: PointFormat | None = None
     resolution: tuple[int, int] | None = None
     extras: dict[str, Any] = field(default_factory=dict)
@@ -86,14 +90,16 @@ class SensorInfo:
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> SensorInfo:
         modality = d["modality"]
+        frame_id = d.get("frame_id")
         pf_raw = d.get("point_format")
         point_format = PointFormat.from_dict(pf_raw) if pf_raw is not None else None
         res_raw = d.get("resolution")
         resolution = (int(res_raw[0]), int(res_raw[1])) if res_raw is not None else None
-        known = {"modality", "point_format", "resolution"}
+        known = {"modality", "frame_id", "point_format", "resolution"}
         extras = {k: v for k, v in d.items() if k not in known}
         return cls(
             modality=modality,
+            frame_id=frame_id,
             point_format=point_format,
             resolution=resolution,
             extras=extras,
@@ -101,6 +107,8 @@ class SensorInfo:
 
     def to_dict(self) -> dict[str, Any]:
         out: dict[str, Any] = {"modality": self.modality}
+        if self.frame_id is not None:
+            out["frame_id"] = self.frame_id
         if self.point_format is not None:
             out["point_format"] = self.point_format.to_dict()
         if self.resolution is not None:
@@ -125,6 +133,10 @@ class ClipMeta:
         sensors: Per-channel sensor metadata, keyed by channel name. Each
             value is a ``SensorInfo`` carrying modality + (for LiDAR) the
             binary ``PointFormat`` describing the .bin file layout.
+        annotation_frame_id: The ROS frame_id annotations are stored in.
+            Required by v0.6 schema. ``None`` on older clips (callers can
+            consult ``ClipLoader.annotation_frame_id`` for a back-compat
+            fallback that infers ``"base_link"`` for v0.5 clips).
     """
 
     clip_id: str
@@ -136,6 +148,7 @@ class ClipMeta:
     num_keyframes: int
     num_sweeps: int
     sensors: dict[str, SensorInfo]
+    annotation_frame_id: str | None = None
 
 
 @dataclass(frozen=True)
@@ -245,27 +258,31 @@ class SampleData:
 
 @dataclass(frozen=True)
 class Annotation:
-    """A 3D bounding box annotation in **per-sample ego frame** (v0.5).
+    """A 3D bounding box annotation in the clip's vehicle-local annotation frame.
 
-    Annotations are natively stored in the ego frame of the sample they belong
-    to (the ego_pose of the sample's LiDAR keyframe). Use
-    ``ClipLoader.annotations_for_sample(..., frame="world")`` to transform to
-    the clip's local world frame when needed (rare — typically only for
-    cross-frame trajectory visualization).
+    Annotations are stored in whichever vehicle-local frame the producer
+    declared via ``meta.annotation_frame_id`` (v0.6+) — typically ``"base_link"``
+    for fused-lidar clips, ``"LIDAR_TOP"`` for nuScenes-style top-lidar clips,
+    or another sensor's frame_id. The frame is rigid relative to ``base_link``
+    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.
 
     Attributes:
         token: Unique annotation token.
         sample_token: Token of the sample this annotation belongs to.
         instance_token: Token of the tracked object instance.
         category: Object category string (e.g. "car", "pedestrian").
-        translation: (3,) float64 array — box center [x, y, z] in this sample's ego frame.
+        translation: (3,) float64 array — box center [x, y, z] in the
+            annotation frame at this sample's timestamp.
         size: (3,) float64 array — box dimensions [length, width, height] in meters.
         rotation: (4,) float64 array — box orientation as quaternion [qx, qy, qz, qw],
-            relative to this sample's ego frame.
+            relative to the annotation frame.
         num_lidar_pts: Number of LiDAR points inside this box (real-counted, ≥ 0).
         visibility: Visibility level as string ("1" to "4", or "" if unknown).
-        velocity: (3,) float64 array — velocity [vx, vy, vz] in m/s, **ego frame**
-            (forward = +x, left = +y), or None.
+        velocity: (3,) float64 array — velocity [vx, vy, vz] in m/s, in the
+            annotation frame (forward = +x, left = +y), or None.
         attributes: List of attribute strings (e.g. ["vehicle.moving"]).
         prev: Token of previous annotation of same instance, or "" if first.
         next: Token of next annotation of same instance, or "" if last.

{x4d_devkit-0.8.0 → x4d_devkit-0.9.0}/x4d_devkit/core/transform.py

@@ -191,6 +191,14 @@ class TransformChain:
     def __init__(self, loader: ClipLoader) -> None:
         self._loader = loader
         self._cs_by_channel = {cs.channel: cs for cs in loader.calibrated_sensors}
+        # Map ROS frame_id → channel: prefer explicit meta.sensors[ch].frame_id
+        # (v0.6+); fall back to channel-name equality for older clips.
+        self._channel_by_frame_id: dict[str, str] = {}
+        for ch, info in loader.meta.sensors.items():
+            fid = info.frame_id if info.frame_id is not None else ch
+            self._channel_by_frame_id[fid] = ch
+        for ch in self._cs_by_channel:
+            self._channel_by_frame_id.setdefault(ch, ch)
 
     def get_ego_from_sensor(self, channel: str) -> Transform:
         """Get the static sensor-to-ego transform for a channel.
@@ -206,6 +214,33 @@ class TransformChain:
         cs = self._cs_by_channel[channel]
         return Transform.from_quat(cs.translation, cs.rotation)
 
+    def get_ego_from_frame_id(self, frame_id: str) -> Transform:
+        """Get the static frame_id-to-ego transform.
+
+        Resolves ``frame_id`` to the calibrated channel that declares it
+        (via ``meta.sensors[ch].frame_id``, falling back to channel-name
+        equality for older clips). For ``frame_id == "base_link"`` this is
+        the identity transform.
+
+        Args:
+            frame_id: ROS frame_id (e.g. ``"LIDAR_TOP"``, ``"camera-front"``).
+
+        Returns:
+            Transform from the named frame to the ego (base_link) frame.
+
+        Raises:
+            KeyError: if no sensor declares ``frame_id``.
+        """
+        if frame_id == "base_link":
+            return Transform.identity()
+        ch = self._channel_by_frame_id.get(frame_id)
+        if ch is None:
+            raise KeyError(
+                f"frame_id {frame_id!r} not found in calibration tree "
+                f"(known: {sorted(self._channel_by_frame_id)})"
+            )
+        return self.get_ego_from_sensor(ch)
+
     def get_world_from_ego(self, ego_pose_token: str) -> Transform:
         """Get the ego-to-world transform for a specific ego pose.
 

{x4d_devkit-0.8.0 → x4d_devkit-0.9.0}/x4d_devkit/validation/validator.py

@@ -101,6 +101,57 @@ def validate_clip(clip_dir: str | Path) -> ValidationReport:
     if "meta.json" in jsons:
         clip_id = jsons["meta.json"].get("clip_id", clip_id)
 
+    # Schema v0.6: explicit annotation_frame_id + per-sensor frame_id, both
+    # resolving against calibrated_sensor.json.
+    if "meta.json" in jsons:
+        meta = jsons["meta.json"]
+        sv = str(meta.get("schema_version", ""))
+        if sv == "0.6":
+            cs_records = jsons.get("calibrated_sensor.json", []) or []
+            cs_channels = {r.get("channel") for r in cs_records if r.get("channel")}
+            calib_frame_ids = set(cs_channels) | {"base_link"}
+            sensors = (meta.get("sensors") or {})
+            sensor_frame_ids: set[str] = set()
+            for ch, info in sensors.items():
+                fid = (info or {}).get("frame_id") if isinstance(info, dict) else None
+                if not fid:
+                    issues.append(
+                        ValidationIssue(
+                            "sensor_frame_id",
+                            "error",
+                            f"sensors[{ch!r}].frame_id is required in schema 0.6",
+                        )
+                    )
+                    continue
+                sensor_frame_ids.add(fid)
+                if ch not in cs_channels:
+                    issues.append(
+                        ValidationIssue(
+                            "sensor_frame_id",
+                            "error",
+                            f"sensors[{ch!r}] has no matching calibrated_sensor record",
+                        )
+                    )
+            calib_frame_ids |= sensor_frame_ids
+            ann_fid = meta.get("annotation_frame_id")
+            if not ann_fid:
+                issues.append(
+                    ValidationIssue(
+                        "annotation_frame_id",
+                        "error",
+                        "meta.annotation_frame_id is required in schema 0.6",
+                    )
+                )
+            elif ann_fid not in calib_frame_ids:
+                issues.append(
+                    ValidationIssue(
+                        "annotation_frame_id",
+                        "error",
+                        f"annotation_frame_id={ann_fid!r} does not resolve in calibration tree "
+                        f"(known: {sorted(calib_frame_ids)})",
+                    )
+                )
+
     # If we can't parse essential files, return early
     if "sample.json" not in jsons or "sample_data.json" not in jsons:
         return ValidationReport(clip_id=clip_id, issues=issues)

{x4d_devkit-0.8.0 → x4d_devkit-0.9.0/x4d_devkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.8.0
+Version: 0.9.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.8.0 → x4d_devkit-0.9.0}/x4d_devkit.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ tests/test_token.py
 tests/test_transform.py
 tests/test_transform_chain.py
 tests/test_v06_api_additions.py
+tests/test_v06_schema.py
 tests/test_validation.py
 x4d_devkit/__init__.py
 x4d_devkit/cli.py