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

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.6.0"
+version = "0.8.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/tests/test_box.py

@@ -0,0 +1,121 @@
+"""Unit tests for the Box detection dataclass."""
+
+import numpy as np
+import pytest
+
+from x4d_devkit.eval import Box
+
+
+class TestBoxConstruction:
+    def test_minimal_gt(self):
+        b = Box(
+            translation=[1.0, 2.0, 3.0],
+            size=[4.0, 2.0, 1.5],
+            rotation=[0.0, 0.0, 0.0, 1.0],
+            category="car",
+        )
+        assert b.translation.dtype == np.float64
+        assert b.translation.shape == (3,)
+        assert b.size.shape == (3,)
+        assert b.rotation.shape == (4,)
+        assert b.category == "car"
+        assert b.score is None
+        assert b.velocity is None
+        assert b.attributes == []
+
+    def test_prediction_with_score_and_velocity(self):
+        b = Box(
+            translation=np.array([10.0, 20.0, 1.0]),
+            size=np.array([4.5, 1.8, 1.5]),
+            rotation=np.array([0.0, 0.0, 0.0, 1.0]),
+            category="car",
+            score=0.85,
+            velocity=[1.0, 0.5, 0.0],
+            attributes=["vehicle.moving"],
+        )
+        assert b.score == 0.85
+        assert b.velocity.dtype == np.float64
+        assert b.velocity.tolist() == [1.0, 0.5, 0.0]
+        assert b.attributes == ["vehicle.moving"]
+
+    def test_frozen(self):
+        b = Box(
+            translation=[0, 0, 0], size=[1, 1, 1],
+            rotation=[0, 0, 0, 1], category="car",
+        )
+        with pytest.raises((AttributeError, Exception)):
+            b.category = "truck"
+
+    def test_rejects_wrong_translation_shape(self):
+        with pytest.raises(ValueError, match="translation"):
+            Box(translation=[1, 2], size=[1, 1, 1],
+                rotation=[0, 0, 0, 1], category="car")
+
+    def test_rejects_wrong_rotation_shape(self):
+        with pytest.raises(ValueError, match="rotation"):
+            Box(translation=[1, 2, 3], size=[1, 1, 1],
+                rotation=[0, 0, 0], category="car")
+
+    def test_rejects_wrong_size_shape(self):
+        with pytest.raises(ValueError, match="size"):
+            Box(translation=[1, 2, 3], size=[1, 1],
+                rotation=[0, 0, 0, 1], category="car")
+
+
+class TestFromXyzlwhyawVxvy:
+    def test_yaw_zero_gives_identity_quat(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [0, 0, 0, 4, 2, 1.5, 0.0, 0, 0], category="car", score=0.9,
+        )
+        assert b.rotation[0] == 0.0
+        assert b.rotation[1] == 0.0
+        assert b.rotation[2] == pytest.approx(0.0)
+        assert b.rotation[3] == pytest.approx(1.0)
+
+    def test_yaw_pi_half_gives_z_quat(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [0, 0, 0, 4, 2, 1.5, np.pi / 2, 0, 0], category="car",
+        )
+        assert b.rotation[2] == pytest.approx(np.sin(np.pi / 4))
+        assert b.rotation[3] == pytest.approx(np.cos(np.pi / 4))
+
+    def test_yaw_round_trip_via_quaternion_yaw(self):
+        from x4d_devkit.eval.metrics import quaternion_yaw
+
+        for yaw in [-2.5, -1.0, 0.0, 0.7, np.pi - 0.01]:
+            b = Box.from_xyzlwhyaw_vxvy(
+                [1, 2, 3, 4, 2, 1.5, yaw, 0, 0], category="car",
+            )
+            recovered = quaternion_yaw(b.rotation)
+            assert recovered == pytest.approx(yaw, abs=1e-6)
+
+    def test_velocity_lifts_to_3d(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [0, 0, 0, 4, 2, 1.5, 0, 1.5, -0.5], category="car",
+        )
+        assert b.velocity.shape == (3,)
+        assert b.velocity.tolist() == [1.5, -0.5, 0.0]
+
+    def test_translation_and_size_preserved(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [10, 20, 1, 4.5, 1.8, 1.5, 0.0, 0, 0], category="car",
+        )
+        assert b.translation.tolist() == [10.0, 20.0, 1.0]
+        assert b.size.tolist() == [4.5, 1.8, 1.5]
+
+    def test_rejects_wrong_shape(self):
+        with pytest.raises(ValueError, match="bbox must be shape"):
+            Box.from_xyzlwhyaw_vxvy([1, 2, 3], category="car")
+
+    def test_attributes_default_empty(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [0, 0, 0, 4, 2, 1.5, 0, 0, 0], category="car",
+        )
+        assert b.attributes == []
+
+    def test_attributes_passthrough(self):
+        b = Box.from_xyzlwhyaw_vxvy(
+            [0, 0, 0, 4, 2, 1.5, 0, 0, 0], category="car",
+            attributes=["vehicle.moving"],
+        )
+        assert b.attributes == ["vehicle.moving"]

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/tests/test_coordinate_frames.py

@@ -38,11 +38,14 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
         "sensors": {
             "LIDAR_TOP": {
                 "modality": "lidar",
-                "point_format": {"fields": ["x", "y", "z", "intensity"]}
+                "point_format": {
+                    "fields": ["x", "y", "z", "intensity"],
+                    "types": ["float32"] * 4,
+                    "bytes_per_point": 16,
+                },
             },
             "CAM_FRONT": {
                 "modality": "camera",
-                "point_format": None
             }
         }
     }))

x4d_devkit-0.8.0/tests/test_evaluate.py

@@ -0,0 +1,154 @@
+"""Unit tests for the in-memory evaluate() pure function."""
+
+import numpy as np
+import pytest
+
+from x4d_devkit.eval import (
+    Box,
+    DetectionConfig,
+    DetectionResult,
+    evaluate,
+    nusc_detection_config,
+)
+
+
+def _gt_box(x, y, z, category="car"):
+    return Box(
+        translation=[x, y, z], size=[4.0, 2.0, 1.5],
+        rotation=[0.0, 0.0, 0.0, 1.0], category=category,
+        velocity=[0.0, 0.0, 0.0], attributes=[],
+    )
+
+
+def _pred_box(x, y, z, score, category="car"):
+    return Box(
+        translation=[x, y, z], size=[4.0, 2.0, 1.5],
+        rotation=[0.0, 0.0, 0.0, 1.0], category=category,
+        score=score, velocity=[0.0, 0.0, 0.0], attributes=[],
+    )
+
+
+def _tiny_config(class_names=("car",)) -> DetectionConfig:
+    """Single-class config with NUSC-style thresholds, no traffic_cone/barrier
+    special cases hitting our class."""
+    cn = list(class_names)
+    return DetectionConfig(
+        class_names=cn,
+        dist_thresholds=[0.5, 1.0, 2.0, 4.0],
+        dist_th_tp=2.0,
+        min_recall=0.1,
+        min_precision=0.1,
+        max_boxes_per_sample=500,
+        class_range={c: 50.0 for c in cn},
+        category_map={},
+    )
+
+
+class TestEvaluatePerfect:
+    def test_perfect_single_class_single_sample(self):
+        cfg = _tiny_config()
+        gt = {"s1": [_gt_box(10, 20, 1)]}
+        pred = {"s1": [_pred_box(10, 20, 1, score=0.9)]}
+        result = evaluate(gt, pred, cfg)
+        assert isinstance(result, DetectionResult)
+        assert result.mean_ap == pytest.approx(1.0)
+        assert result.mean_dist_aps["car"] == pytest.approx(1.0)
+        assert result.label_tp_errors["car"]["trans_err"] < 1e-6
+        assert result.label_tp_errors["car"]["scale_err"] < 1e-6
+        assert result.nd_score > 0.9
+
+    def test_perfect_multi_sample(self):
+        cfg = _tiny_config()
+        gt = {f"s{i}": [_gt_box(10 + i, 0, 0)] for i in range(5)}
+        pred = {f"s{i}": [_pred_box(10 + i, 0, 0, score=0.9)] for i in range(5)}
+        result = evaluate(gt, pred, cfg)
+        assert result.mean_ap == pytest.approx(1.0)
+
+
+class TestEvaluateNoisy:
+    def test_translation_noise_increases_trans_err(self):
+        cfg = _tiny_config()
+        rng = np.random.default_rng(7)
+        gt = {f"s{i}": [_gt_box(10.0 * i, 0, 0)] for i in range(20)}
+        pred = {
+            f"s{i}": [_pred_box(10.0 * i + rng.normal(0, 0.5), 0, 0, score=0.9)]
+            for i in range(20)
+        }
+        result = evaluate(gt, pred, cfg)
+        assert result.label_tp_errors["car"]["trans_err"] > 0.1
+        assert result.label_tp_errors["car"]["trans_err"] < 2.0
+
+
+class TestEvaluateEmpty:
+    def test_empty_predictions_zero_ap(self):
+        cfg = _tiny_config()
+        gt = {"s1": [_gt_box(10, 20, 1)]}
+        pred = {"s1": []}
+        result = evaluate(gt, pred, cfg)
+        assert result.mean_ap == pytest.approx(0.0)
+
+    def test_no_gt_for_class_zero_ap(self):
+        cfg = _tiny_config()
+        gt = {"s1": []}
+        pred = {"s1": [_pred_box(10, 20, 1, score=0.9)]}
+        result = evaluate(gt, pred, cfg)
+        assert result.mean_ap == pytest.approx(0.0)
+
+    def test_pred_sample_missing_from_gt_treated_as_empty_gt(self):
+        cfg = _tiny_config()
+        gt = {"s1": [_gt_box(10, 20, 1)]}
+        pred = {"s2": [_pred_box(10, 20, 1, score=0.9)]}
+        result = evaluate(gt, pred, cfg)
+        assert result.mean_ap == pytest.approx(0.0)
+
+
+class TestEvaluateClassRangeFilter:
+    def test_filters_far_boxes(self):
+        cfg = _tiny_config()
+        cfg = DetectionConfig(
+            class_names=["car"],
+            dist_thresholds=cfg.dist_thresholds,
+            dist_th_tp=cfg.dist_th_tp,
+            min_recall=cfg.min_recall,
+            min_precision=cfg.min_precision,
+            max_boxes_per_sample=cfg.max_boxes_per_sample,
+            class_range={"car": 10.0},
+            category_map={},
+        )
+        gt = {"s1": [_gt_box(100, 0, 0), _gt_box(5, 0, 0)]}
+        pred = {"s1": [_pred_box(5, 0, 0, score=0.9)]}
+        result = evaluate(gt, pred, cfg)
+        # The far GT box is filtered out, near GT matches → AP = 1.0.
+        assert result.mean_ap == pytest.approx(1.0)
+
+
+class TestEvaluateMaxBoxesPerSample:
+    def test_low_score_predictions_dropped_when_capped(self):
+        cfg = DetectionConfig(
+            class_names=["car"],
+            dist_thresholds=[0.5, 1.0, 2.0, 4.0],
+            dist_th_tp=2.0,
+            min_recall=0.1, min_precision=0.1,
+            max_boxes_per_sample=1,
+            class_range={"car": 50.0},
+            category_map={},
+        )
+        gt = {"s1": [_gt_box(10, 0, 0)]}
+        pred = {"s1": [
+            _pred_box(40, 0, 0, score=0.95),  # high-score FP, kept by cap
+            _pred_box(10, 0, 0, score=0.10),  # low-score TP, dropped by cap
+        ]}
+        result = evaluate(gt, pred, cfg)
+        # The TP was dropped, only FP remains → mAP near 0.
+        assert result.mean_ap < 0.1
+
+
+class TestEvaluateMatchesDetectionEval:
+    """evaluate() is what DetectionEval.evaluate() delegates to — sanity-check
+    they produce identical numbers when fed equivalent inputs."""
+
+    def test_no_gt_no_pred_zero(self):
+        cfg = _tiny_config()
+        result = evaluate({}, {}, cfg)
+        assert result.mean_ap == 0.0
+        assert result.label_aps["car"]["0.5"] == 0.0

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/tests/test_matching.py

@@ -4,21 +4,22 @@
 import numpy as np
 import pytest
 
+from x4d_devkit.eval import Box
 from x4d_devkit.eval.matching import MetricData, accumulate
 
 
 def _make_box(translation, size, rotation, category, score=None,
               velocity=None, attributes=None):
-    """Helper to create a dict that looks like what accumulate() expects."""
-    return {
-        "translation": np.asarray(translation, dtype=float),
-        "size": np.asarray(size, dtype=float),
-        "rotation": np.asarray(rotation, dtype=float),
-        "category": category,
-        "score": score,
-        "velocity": np.asarray(velocity, dtype=float) if velocity is not None else None,
-        "attributes": attributes or [],
-    }
+    """Helper to construct a Box matching what accumulate() expects."""
+    return Box(
+        translation=np.asarray(translation, dtype=float),
+        size=np.asarray(size, dtype=float),
+        rotation=np.asarray(rotation, dtype=float),
+        category=category,
+        score=score,
+        velocity=np.asarray(velocity, dtype=float) if velocity is not None else None,
+        attributes=attributes or [],
+    )
 
 
 class TestMetricData:

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/tests/test_models.py

@@ -9,6 +9,8 @@ from x4d_devkit.core.models import (
     SampleData,
     Annotation,
     Instance,
+    PointFormat,
+    SensorInfo,
 )
 
 
@@ -16,17 +18,21 @@ class TestClipMeta:
     def test_construction(self):
         meta = ClipMeta(
             clip_id="20180724_n015_scene-0061_000",
-            schema_version="0.1",
+            schema_version="0.5",
             session_id="n015-2018-07-24-11-22-45+0800",
             vehicle_id="n015",
             capture_time_utc="2018-07-24T00:00:00Z",
             duration_s=19.5,
             num_keyframes=39,
             num_sweeps=305,
-            sensors={"CAM_FRONT": {"modality": "camera", "resolution": [1600, 900]}},
+            sensors={
+                "CAM_FRONT": SensorInfo(modality="camera", resolution=(1600, 900)),
+            },
         )
         assert meta.clip_id == "20180724_n015_scene-0061_000"
         assert meta.num_keyframes == 39
+        assert meta.sensors["CAM_FRONT"].modality == "camera"
+        assert meta.sensors["CAM_FRONT"].resolution == (1600, 900)
 
     def test_frozen(self):
         meta = ClipMeta(
@@ -153,3 +159,74 @@ class TestInstance:
             first_annotation_token="a1", last_annotation_token="a5",
         )
         assert inst.num_annotations == 5
+
+
+class TestPointFormat:
+    def test_construction_normalises_to_tuples(self):
+        pf = PointFormat(
+            fields=["x", "y", "z", "intensity", "time"],
+            types=["float32"] * 5,
+            bytes_per_point=20,
+        )
+        assert isinstance(pf.fields, tuple)
+        assert isinstance(pf.types, tuple)
+        assert pf.num_fields == 5
+
+    def test_mismatched_lengths_rejected(self):
+        with pytest.raises(ValueError, match="must have equal length"):
+            PointFormat(fields=["x", "y", "z"], types=["float32", "float32"], bytes_per_point=12)
+
+    def test_round_trip_via_dict(self):
+        d = {
+            "fields": ["x", "y", "z", "intensity", "time"],
+            "types": ["float32"] * 5,
+            "bytes_per_point": 20,
+        }
+        pf = PointFormat.from_dict(d)
+        assert pf.to_dict() == d
+
+
+class TestSensorInfo:
+    def test_lidar_with_point_format(self):
+        d = {
+            "modality": "lidar",
+            "point_format": {
+                "fields": ["x", "y", "z", "intensity", "time"],
+                "types": ["float32"] * 5,
+                "bytes_per_point": 20,
+            },
+        }
+        si = SensorInfo.from_dict(d)
+        assert si.modality == "lidar"
+        assert si.point_format is not None
+        assert si.point_format.num_fields == 5
+        assert si.resolution is None
+        assert si.to_dict() == d
+
+    def test_camera_with_resolution(self):
+        d = {"modality": "camera", "resolution": [1600, 900]}
+        si = SensorInfo.from_dict(d)
+        assert si.modality == "camera"
+        assert si.point_format is None
+        assert si.resolution == (1600, 900)
+        assert si.to_dict() == d
+
+    def test_extras_round_trip(self):
+        """Unknown keys (e.g. producer-specific extras) survive a round-trip."""
+        d = {
+            "modality": "lidar",
+            "point_format": {
+                "fields": ["x", "y", "z"],
+                "types": ["float32", "float32", "float32"],
+                "bytes_per_point": 12,
+            },
+            "fused_from": ["lidar_top", "lidar_left"],
+        }
+        si = SensorInfo.from_dict(d)
+        assert si.extras == {"fused_from": ["lidar_top", "lidar_left"]}
+        out = si.to_dict()
+        assert out["fused_from"] == ["lidar_top", "lidar_left"]
+
+    def test_camera_no_point_format_in_dict(self):
+        si = SensorInfo.from_dict({"modality": "camera"})
+        assert si.point_format is None

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/x4d_devkit/__init__.py

@@ -15,19 +15,24 @@ from x4d_devkit.core import (
     ClipMeta,
     EgoPose,
     Instance,
+    PointFormat,
     Sample,
     SampleData,
     SchemaVersionMismatch,
+    SensorInfo,
     Transform,
     TransformChain,
     generate_token,
 )
 from x4d_devkit.eval import (
+    Box,
     DetectionConfig,
     DetectionEval,
     DetectionResult,
+    boxes_from_clip,
     calc_ap,
     calc_tp,
+    evaluate,
     nusc_detection_config,
 )
 from x4d_devkit.validation import validate_clip, ValidationReport
@@ -36,6 +41,7 @@ from x4d_devkit.fusion import LIDAR_FUSED_DTYPE, FusionSource, fuse_pointclouds
 __all__ = [
     "__version__",
     "Annotation",
+    "Box",
     "CalibratedSensor",
     "LIDAR_FUSED_DTYPE",
     "FusionSource",
@@ -47,15 +53,19 @@ __all__ = [
     "DetectionResult",
     "EgoPose",
     "Instance",
+    "PointFormat",
     "Sample",
     "SampleData",
     "SchemaVersionMismatch",
+    "SensorInfo",
     "Transform",
     "TransformChain",
     "ValidationReport",
     "X4DClient",
+    "boxes_from_clip",
     "calc_ap",
     "calc_tp",
+    "evaluate",
     "generate_token",
     "nusc_detection_config",
     "validate_clip",

{x4d_devkit-0.6.0 → x4d_devkit-0.8.0}/x4d_devkit/core/__init__.py

@@ -7,8 +7,10 @@ from x4d_devkit.core.models import (
     ClipMeta,
     EgoPose,
     Instance,
+    PointFormat,
     Sample,
     SampleData,
+    SensorInfo,
 )
 from x4d_devkit.core.token import generate_token
 from x4d_devkit.core.transform import Transform, TransformChain
@@ -20,9 +22,11 @@ __all__ = [
     "ClipMeta",
     "EgoPose",
     "Instance",
+    "PointFormat",
     "Sample",
     "SampleData",
     "SchemaVersionMismatch",
+    "SensorInfo",
     "Transform",
     "TransformChain",
     "generate_token",

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

@@ -17,6 +17,7 @@ from x4d_devkit.core.models import (
     SampleData,
     Annotation,
     Instance,
+    SensorInfo,
 )
 from x4d_devkit.core.transform import Transform, TransformChain, rotation_matrix_to_quat
 
@@ -122,6 +123,10 @@ class ClipLoader:
 
     def _load_meta(self) -> ClipMeta:
         d = self._read_json("meta.json")
+        sensors = {
+            channel: SensorInfo.from_dict(raw)
+            for channel, raw in (d.get("sensors") or {}).items()
+        }
         return ClipMeta(
             clip_id=d["clip_id"],
             schema_version=d["schema_version"],
@@ -131,7 +136,7 @@ class ClipLoader:
             duration_s=d["duration_s"],
             num_keyframes=d["keyframe_count"],
             num_sweeps=d["sweep_count"],
-            sensors=d["sensors"],
+            sensors=sensors,
         )
 
     def _load_calibrated_sensors(self) -> list[CalibratedSensor]:
@@ -400,8 +405,12 @@ class ClipLoader:
             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"])
+        if sensor_info.point_format is None:
+            raise ValueError(
+                f"channel '{sd.channel}' has no point_format in meta.json — "
+                f"cannot load as a point cloud (modality={sensor_info.modality})"
+            )
+        num_fields = sensor_info.point_format.num_fields
 
         path = self._clip_dir / sd.file_path
         raw = np.fromfile(str(path), dtype=np.float32)