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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.8.0
+Version: 0.11.1
 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.11.1}/pyproject.toml

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

{x4d_devkit-0.8.0 → x4d_devkit-0.11.1}/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.11.1/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}"