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

{x4d_devkit-0.7.0 → x4d_devkit-0.9.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.7.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.9.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.7.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_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.7.0 → x4d_devkit-0.9.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: