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

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

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

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

@@ -25,11 +25,14 @@ from x4d_devkit.core import (
     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
@@ -38,6 +41,7 @@ from x4d_devkit.fusion import LIDAR_FUSED_DTYPE, FusionSource, fuse_pointclouds
 __all__ = [
     "__version__",
     "Annotation",
+    "Box",
     "CalibratedSensor",
     "LIDAR_FUSED_DTYPE",
     "FusionSource",
@@ -58,8 +62,10 @@ __all__ = [
     "TransformChain",
     "ValidationReport",
     "X4DClient",
+    "boxes_from_clip",
     "calc_ap",
     "calc_tp",
+    "evaluate",
     "generate_token",
     "nusc_detection_config",
     "validate_clip",

{x4d_devkit-0.7.0 → x4d_devkit-0.8.0}/x4d_devkit/eval/__init__.py

@@ -1,5 +1,7 @@
 """Evaluation layer for X4D dataset."""
 
+from x4d_devkit.eval.api import boxes_from_clip, evaluate
+from x4d_devkit.eval.box import Box
 from x4d_devkit.eval.detection import (
     DetectionConfig,
     DetectionEval,
@@ -11,11 +13,14 @@ from x4d_devkit.eval.detection import (
 )
 
 __all__ = [
+    "Box",
     "DetectionConfig",
     "DetectionEval",
     "DetectionResult",
+    "boxes_from_clip",
     "calc_ap",
     "calc_tp",
     "detzero_detection_config",
+    "evaluate",
     "nusc_detection_config",
 ]

x4d_devkit-0.8.0/x4d_devkit/eval/api.py

@@ -0,0 +1,205 @@
+"""Pure-function detection evaluation API.
+
+`evaluate(gt, pred, config)` consumes in-memory ``dict[str, list[Box]]``
+without requiring on-disk clip directories — designed for the metric
+callback hot path of training pipelines. Use ``boxes_from_clip(loader,
+config)`` to build the dicts from a ``ClipLoader`` (replicating the
+behaviour previously hidden inside ``DetectionEval._extract_boxes``).
+
+The two-step split is intentional: extraction (which applies the
+config's ``category_map`` and ``class_range``) is decoupled from
+evaluation (per-class accumulate → AP → TP errors → NDS), so training
+code that already has predictions in memory never has to round-trip
+through disk.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from x4d_devkit.eval.box import Box
+from x4d_devkit.eval.matching import MetricData, accumulate
+
+if TYPE_CHECKING:
+    from x4d_devkit.core.loader import ClipLoader
+    from x4d_devkit.eval.detection import DetectionConfig, DetectionResult
+
+
+TP_METRICS = ["trans_err", "scale_err", "orient_err", "vel_err", "attr_err"]
+
+
+def _filter_for_eval(
+    boxes: dict[str, list[Box]],
+    class_names: list[str],
+    class_range: dict[str, float],
+    max_boxes: int | None = None,
+) -> dict[str, list[Box]]:
+    """Drop boxes whose category isn't in ``class_names`` or whose ego-frame
+    XY distance exceeds the per-class range. Optionally cap predictions per
+    sample (top-N by score)."""
+    class_names_set = set(class_names)
+    out: dict[str, list[Box]] = {}
+    for sample_token, sample_boxes in boxes.items():
+        kept = []
+        for b in sample_boxes:
+            if b.category not in class_names_set:
+                continue
+            r = class_range.get(b.category)
+            if r is not None:
+                if float(np.linalg.norm(b.translation[:2])) > r:
+                    continue
+            kept.append(b)
+        if max_boxes is not None and len(kept) > max_boxes:
+            kept.sort(key=lambda b: (b.score if b.score is not None else 0.0), reverse=True)
+            kept = kept[:max_boxes]
+        out[sample_token] = kept
+    return out
+
+
+def boxes_from_clip(
+    clip: ClipLoader,
+    config: DetectionConfig,
+    *,
+    apply_score_cap: bool = False,
+) -> dict[str, list[Box]]:
+    """Extract per-sample boxes from a ClipLoader, applying the config's
+    category mapping and class-range distance filter.
+
+    v0.5: annotations are already in per-sample ego frame, so the
+    distance filter is just ``||translation[:2]||`` — no ego_pose
+    subtraction.
+
+    Args:
+        clip: Source clip.
+        config: Provides ``category_map``, ``class_names``, ``class_range``,
+            and (when ``apply_score_cap=True``) ``max_boxes_per_sample``.
+        apply_score_cap: Set to True for *prediction* clips so the per-sample
+            top-K cap from ``config.max_boxes_per_sample`` is applied. GT
+            extraction leaves it False.
+
+    Returns:
+        ``{sample_token: [Box, ...]}`` keyed exactly as ``evaluate()`` expects.
+    """
+    from x4d_devkit.eval.detection import map_category
+
+    out: dict[str, list[Box]] = {}
+    cap = config.max_boxes_per_sample if apply_score_cap else None
+    for sample in clip.samples:
+        anns = clip.annotations_for_sample(sample.token)
+        kept: list[Box] = []
+        for ann in anns:
+            det_name = map_category(ann.category, config.category_map, config.class_names)
+            if det_name is None or det_name not in config.class_range:
+                continue
+            dist = float(np.linalg.norm(ann.translation[:2]))
+            if dist > config.class_range[det_name]:
+                continue
+            kept.append(Box(
+                translation=ann.translation,
+                size=ann.size,
+                rotation=ann.rotation,
+                category=det_name,
+                score=ann.score,
+                velocity=ann.velocity,
+                attributes=list(ann.attributes),
+            ))
+        if cap is not None and len(kept) > cap:
+            kept.sort(key=lambda b: (b.score if b.score is not None else 0.0), reverse=True)
+            kept = kept[:cap]
+        out[sample.token] = kept
+    return out
+
+
+def evaluate(
+    gt: dict[str, list[Box]],
+    pred: dict[str, list[Box]],
+    config: DetectionConfig,
+) -> DetectionResult:
+    """Run detection evaluation on in-memory boxes.
+
+    The training-pipeline entry point: feed dicts of ``Box`` instances
+    keyed by sample_token, get back the same ``DetectionResult`` that
+    ``DetectionEval.evaluate()`` produces. No disk I/O, no ClipLoader
+    requirement.
+
+    The function applies ``config.class_range`` distance filtering and the
+    ``config.max_boxes_per_sample`` cap on predictions, but does **not**
+    apply ``config.category_map`` — predictions are expected to already
+    carry final class names. Use ``boxes_from_clip()`` if you need the
+    mapping applied.
+
+    Args:
+        gt: ``{sample_token: [Box, ...]}`` for ground truth. Box.score
+            should be ``None``.
+        pred: ``{sample_token: [Box, ...]}`` for predictions. Box.score
+            must be a float.
+        config: Evaluation configuration.
+
+    Returns:
+        DetectionResult with mAP, NDS, per-class APs, and TP errors.
+    """
+    from x4d_devkit.eval.detection import DetectionResult, calc_ap, calc_tp
+
+    cfg = config
+    gt_f = _filter_for_eval(gt, cfg.class_names, cfg.class_range)
+    pred_f = _filter_for_eval(
+        pred, cfg.class_names, cfg.class_range, max_boxes=cfg.max_boxes_per_sample
+    )
+    for st in gt_f:
+        pred_f.setdefault(st, [])
+
+    metric_data: dict[str, dict[str, MetricData]] = {}
+    for class_name in cfg.class_names:
+        metric_data[class_name] = {}
+        for dist_th in cfg.dist_thresholds:
+            metric_data[class_name][str(dist_th)] = accumulate(
+                gt_f, pred_f, class_name, dist_th
+            )
+
+    label_aps: dict[str, dict[str, float]] = {}
+    for class_name in cfg.class_names:
+        label_aps[class_name] = {}
+        for dist_th in cfg.dist_thresholds:
+            md = metric_data[class_name][str(dist_th)]
+            label_aps[class_name][str(dist_th)] = calc_ap(md, cfg.min_recall, cfg.min_precision)
+
+    mean_dist_aps = {
+        cn: float(np.mean(list(label_aps[cn].values())))
+        for cn in cfg.class_names
+    }
+    all_ap_values = [ap for cn_aps in label_aps.values() for ap in cn_aps.values()]
+    mean_ap = float(np.mean(all_ap_values)) if all_ap_values else 0.0
+
+    label_tp_errors: dict[str, dict[str, float]] = {}
+    for class_name in cfg.class_names:
+        md = metric_data[class_name][str(cfg.dist_th_tp)]
+        label_tp_errors[class_name] = {}
+        for metric_name in TP_METRICS:
+            if class_name == "traffic_cone" and metric_name in ("attr_err", "vel_err", "orient_err"):
+                label_tp_errors[class_name][metric_name] = float("nan")
+            elif class_name == "barrier" and metric_name in ("attr_err", "vel_err"):
+                label_tp_errors[class_name][metric_name] = float("nan")
+            else:
+                label_tp_errors[class_name][metric_name] = calc_tp(md, cfg.min_recall, metric_name)
+
+    tp_errors = {}
+    for metric_name in TP_METRICS:
+        values = [label_tp_errors[cn][metric_name] for cn in cfg.class_names]
+        tp_errors[metric_name] = float(np.nanmean(values))
+
+    tp_scores = {m: max(0.0, 1.0 - tp_errors[m]) for m in TP_METRICS}
+    nd_score = (cfg.mean_ap_weight * mean_ap + sum(tp_scores.values())) / (
+        cfg.mean_ap_weight + len(tp_scores)
+    )
+
+    return DetectionResult(
+        mean_ap=mean_ap,
+        nd_score=nd_score,
+        label_aps=label_aps,
+        mean_dist_aps=mean_dist_aps,
+        tp_errors=tp_errors,
+        label_tp_errors=label_tp_errors,
+        tp_scores=tp_scores,
+    )

x4d_devkit-0.8.0/x4d_devkit/eval/box.py

@@ -0,0 +1,124 @@
+"""Typed 3D bounding box for detection evaluation.
+
+`Box` is the data shape that ``evaluate()`` and ``accumulate()`` consume.
+It mirrors the fields previously expected as a dict (``translation``,
+``size``, ``rotation``, ``category``, ``score``, ``velocity``,
+``attributes``) but with type checking, frozen semantics, and
+constructor helpers for common upstream LiDAR detection layouts.
+
+GT vs. prediction is distinguished by ``score`` — None for ground truth,
+float for predictions. ``sample_token`` is *not* a field on Box; it's
+the key of the outer ``dict[str, list[Box]]`` passed to ``evaluate``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Sequence
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Box:
+    """A 3D bounding box for detection evaluation.
+
+    Attributes:
+        translation: (3,) float64 — box center [x, y, z] in meters,
+            in **per-sample ego frame** (matching annotations v0.5).
+        size: (3,) float64 — [length, width, height] in meters.
+        rotation: (4,) float64 — box orientation as quaternion
+            [qx, qy, qz, qw]. Last-w convention (nuScenes-compatible).
+        category: Final detection class name (e.g. ``"car"``,
+            ``"Vehicle"``). Class mapping from raw hierarchical labels
+            (``"vehicle.car"`` → ``"car"``) is the caller's
+            responsibility — ``Box.category`` is consumed verbatim.
+        score: Detection confidence in [0, 1] for predictions, or
+            ``None`` for ground truth.
+        velocity: (3,) float64 [vx, vy, vz] in m/s in the same ego
+            frame, or ``None`` if velocity is unknown. ``vel_err``
+            (AVE) uses only the [:2] xy component.
+        attributes: List of attribute strings (e.g.
+            ``["vehicle.moving"]``). Empty list = no attributes.
+    """
+
+    translation: np.ndarray
+    size: np.ndarray
+    rotation: np.ndarray
+    category: str
+    score: float | None = None
+    velocity: np.ndarray | None = None
+    attributes: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        # Coerce array fields to float64 numpy arrays.
+        object.__setattr__(self, "translation", np.asarray(self.translation, dtype=np.float64))
+        object.__setattr__(self, "size", np.asarray(self.size, dtype=np.float64))
+        object.__setattr__(self, "rotation", np.asarray(self.rotation, dtype=np.float64))
+        if self.velocity is not None:
+            object.__setattr__(self, "velocity", np.asarray(self.velocity, dtype=np.float64))
+
+        if self.translation.shape != (3,):
+            raise ValueError(
+                f"Box.translation must be shape (3,), got {self.translation.shape}"
+            )
+        if self.size.shape != (3,):
+            raise ValueError(
+                f"Box.size must be shape (3,), got {self.size.shape}"
+            )
+        if self.rotation.shape != (4,):
+            raise ValueError(
+                f"Box.rotation must be shape (4,) [qx, qy, qz, qw], got {self.rotation.shape}"
+            )
+
+    @classmethod
+    def from_xyzlwhyaw_vxvy(
+        cls,
+        bbox: Sequence[float] | np.ndarray,
+        category: str,
+        score: float | None = None,
+        attributes: list[str] | None = None,
+    ) -> Box:
+        """Construct a Box from a 9-D LiDAR-frame array.
+
+        Layout: ``[x, y, z, l, w, h, yaw, vx, vy]``. This is the de-facto
+        encoding used by mmdetection3d's ``LiDARInstance3DBoxes`` (with
+        velocity head), OpenPCDet, and DetZero. The yaw is converted to a
+        quaternion ``[0, 0, sin(yaw/2), cos(yaw/2)]``; ``(vx, vy)`` is
+        wrapped into a ``(3,)`` velocity array with ``vz = 0``.
+
+        Use this in training-pipeline metric callbacks to convert per-batch
+        detector outputs directly to evaluation-ready boxes — instead of
+        passing ``rotation=[0, 0, 0, 1]`` placeholders that silently zero
+        out the orientation error (AOE) component.
+
+        Args:
+            bbox: 9-element array ``[x, y, z, l, w, h, yaw, vx, vy]``.
+            category: Final detection class name.
+            score: Detection confidence (predictions) or None (GT).
+            attributes: Optional attribute strings.
+
+        Returns:
+            A frozen Box.
+
+        Raises:
+            ValueError: If ``bbox`` is not 9-element.
+        """
+        b = np.asarray(bbox, dtype=np.float64)
+        if b.shape != (9,):
+            raise ValueError(
+                f"bbox must be shape (9,) [x, y, z, l, w, h, yaw, vx, vy], got {b.shape}"
+            )
+        x, y, z, l, w, h, yaw, vx, vy = b
+        half = 0.5 * float(yaw)
+        rotation = np.array([0.0, 0.0, np.sin(half), np.cos(half)], dtype=np.float64)
+        velocity = np.array([float(vx), float(vy), 0.0], dtype=np.float64)
+        return cls(
+            translation=np.array([x, y, z], dtype=np.float64),
+            size=np.array([l, w, h], dtype=np.float64),
+            rotation=rotation,
+            category=category,
+            score=score,
+            velocity=velocity,
+            attributes=list(attributes) if attributes is not None else [],
+        )

{x4d_devkit-0.7.0 → x4d_devkit-0.8.0}/x4d_devkit/eval/detection.py

@@ -17,8 +17,7 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
-from x4d_devkit.eval.matching import MetricData, accumulate
-from x4d_devkit.eval.metrics import center_distance
+from x4d_devkit.eval.matching import MetricData
 
 if TYPE_CHECKING:
     from x4d_devkit.core.loader import ClipLoader
@@ -223,50 +222,6 @@ _calc_ap = calc_ap
 _calc_tp = calc_tp
 
 
-def _extract_boxes(
-    clip: ClipLoader,
-    config: DetectionConfig,
-    max_boxes: int | None = None,
-) -> dict[str, list[dict]]:
-    """Extract annotation boxes grouped by sample_token, with distance filtering.
-
-    v0.5: annotations are in per-sample ego frame, so distance from ego is
-    simply ``||ann.translation[:2]||`` — no subtraction of ego_pose required.
-    """
-    category_map = config.category_map or {}
-    class_names = config.class_names
-    class_range = config.class_range
-
-    result: dict[str, list[dict]] = {}
-    for sample in clip.samples:
-        anns = clip.annotations_for_sample(sample.token)  # default = ego in v0.5
-        boxes = []
-        for ann in anns:
-            det_name = map_category(ann.category, category_map, class_names)
-            if det_name is None or det_name not in class_range:
-                continue
-            dist = float(np.linalg.norm(ann.translation[:2]))
-            if dist > class_range[det_name]:
-                continue
-            boxes.append({
-                "translation": ann.translation,
-                "size": ann.size,
-                "rotation": ann.rotation,
-                "category": det_name,
-                "score": ann.score,
-                "velocity": ann.velocity,
-                "attributes": ann.attributes,
-            })
-
-        if max_boxes is not None and len(boxes) > max_boxes:
-            boxes.sort(key=lambda b: b["score"] or 0, reverse=True)
-            boxes = boxes[:max_boxes]
-
-        result[sample.token] = boxes
-
-    return result
-
-
 class DetectionEval:
     """3D object detection evaluator.
 
@@ -306,82 +261,21 @@ class DetectionEval:
         Returns:
             DetectionResult with mAP, NDS, per-class APs, and TP errors.
         """
-        cfg = self._config
+        from x4d_devkit.eval.api import boxes_from_clip, evaluate as _evaluate
 
+        cfg = self._config
         gt_by_id = {c.meta.clip_id: c for c in self._gt_clips}
         pred_by_id = {c.meta.clip_id: c for c in self._pred_clips}
 
-        all_gt: dict[str, list[dict]] = {}
-        all_pred: dict[str, list[dict]] = {}
+        all_gt: dict[str, list] = {}
+        all_pred: dict[str, list] = {}
 
         for clip_id, gt_clip in gt_by_id.items():
-            gt_boxes = _extract_boxes(gt_clip, cfg)
-            for st, boxes in gt_boxes.items():
+            for st, boxes in boxes_from_clip(gt_clip, cfg).items():
                 all_gt[st] = boxes
-
             pred_clip = pred_by_id.get(clip_id)
             if pred_clip is not None:
-                pred_boxes = _extract_boxes(pred_clip, cfg, max_boxes=cfg.max_boxes_per_sample)
-                for st, boxes in pred_boxes.items():
+                for st, boxes in boxes_from_clip(pred_clip, cfg, apply_score_cap=True).items():
                     all_pred[st] = boxes
 
-        for st in all_gt:
-            if st not in all_pred:
-                all_pred[st] = []
-
-        # Accumulate per class per distance threshold
-        metric_data: dict[str, dict[str, MetricData]] = {}
-        for class_name in cfg.class_names:
-            metric_data[class_name] = {}
-            for dist_th in cfg.dist_thresholds:
-                metric_data[class_name][str(dist_th)] = accumulate(
-                    all_gt, all_pred, class_name, dist_th
-                )
-
-        # AP per class per threshold
-        label_aps: dict[str, dict[str, float]] = {}
-        for class_name in cfg.class_names:
-            label_aps[class_name] = {}
-            for dist_th in cfg.dist_thresholds:
-                md = metric_data[class_name][str(dist_th)]
-                label_aps[class_name][str(dist_th)] = calc_ap(md, cfg.min_recall, cfg.min_precision)
-
-        mean_dist_aps = {
-            cn: float(np.mean(list(label_aps[cn].values())))
-            for cn in cfg.class_names
-        }
-
-        all_ap_values = [ap for cn_aps in label_aps.values() for ap in cn_aps.values()]
-        mean_ap = float(np.mean(all_ap_values)) if all_ap_values else 0.0
-
-        # TP errors per class at dist_th_tp
-        label_tp_errors: dict[str, dict[str, float]] = {}
-        for class_name in cfg.class_names:
-            md = metric_data[class_name][str(cfg.dist_th_tp)]
-            label_tp_errors[class_name] = {}
-            for metric_name in TP_METRICS:
-                if class_name == "traffic_cone" and metric_name in ("attr_err", "vel_err", "orient_err"):
-                    label_tp_errors[class_name][metric_name] = float("nan")
-                elif class_name == "barrier" and metric_name in ("attr_err", "vel_err"):
-                    label_tp_errors[class_name][metric_name] = float("nan")
-                else:
-                    label_tp_errors[class_name][metric_name] = calc_tp(md, cfg.min_recall, metric_name)
-
-        tp_errors = {}
-        for metric_name in TP_METRICS:
-            values = [label_tp_errors[cn][metric_name] for cn in cfg.class_names]
-            tp_errors[metric_name] = float(np.nanmean(values))
-
-        tp_scores = {m: max(0.0, 1.0 - tp_errors[m]) for m in TP_METRICS}
-
-        nd_score = (cfg.mean_ap_weight * mean_ap + sum(tp_scores.values())) / (cfg.mean_ap_weight + len(tp_scores))
-
-        return DetectionResult(
-            mean_ap=mean_ap,
-            nd_score=nd_score,
-            label_aps=label_aps,
-            mean_dist_aps=mean_dist_aps,
-            tp_errors=tp_errors,
-            label_tp_errors=label_tp_errors,
-            tp_scores=tp_scores,
-        )
+        return _evaluate(all_gt, all_pred, cfg)

{x4d_devkit-0.7.0 → x4d_devkit-0.8.0}/x4d_devkit/eval/matching.py

@@ -7,12 +7,13 @@ from dataclasses import dataclass
 
 import numpy as np
 
+from x4d_devkit.eval.box import Box
 from x4d_devkit.eval.metrics import (
+    attr_acc,
     center_distance,
+    cummean,
     scale_iou,
     yaw_diff,
-    attr_acc,
-    cummean,
 )
 
 NELEM = 101  # Number of recall interpolation points
@@ -55,52 +56,49 @@ class MetricData:
 
 
 def accumulate(
-    gt_boxes: dict[str, list[dict]],
-    pred_boxes: dict[str, list[dict]],
+    gt_boxes: dict[str, list[Box]],
+    pred_boxes: dict[str, list[Box]],
     class_name: str,
     dist_th: float,
 ) -> MetricData:
     """Match predictions to ground truth and compute interpolated curves.
 
     Args:
-        gt_boxes: {sample_token: [box_dict, ...]} — all GT boxes across samples.
-        pred_boxes: {sample_token: [box_dict, ...]} — all pred boxes across samples.
-        class_name: Class to evaluate (e.g. "car").
+        gt_boxes: ``{sample_token: [Box, ...]}`` — all GT boxes across samples.
+        pred_boxes: ``{sample_token: [Box, ...]}`` — all pred boxes across samples.
+            Each prediction Box must have a non-None ``score``.
+        class_name: Class to evaluate (e.g. ``"car"``).
         dist_th: Center distance threshold for matching.
 
-    Each box_dict has: translation (3,), size (3,), rotation (4,) [qx,qy,qz,qw],
-    category (str), score (float, pred only), velocity (3,) or None, attributes (list[str]).
-
     Returns:
         MetricData with interpolated curves at 101 recall points.
     """
-    # Filter by class
-    gt_by_sample: dict[str, list[dict]] = {}
+    gt_by_sample: dict[str, list[Box]] = {}
     npos = 0
     for sample_token, boxes in gt_boxes.items():
-        class_boxes = [b for b in boxes if b["category"] == class_name]
+        class_boxes = [b for b in boxes if b.category == class_name]
         gt_by_sample[sample_token] = class_boxes
         npos += len(class_boxes)
 
-    pred_by_sample: dict[str, list[dict]] = {}
-    all_preds = []
+    pred_by_sample: dict[str, list[Box]] = {}
+    all_preds: list[tuple[float, str, int]] = []
     for sample_token, boxes in pred_boxes.items():
-        class_boxes = [b for b in boxes if b["category"] == class_name]
-        class_boxes.sort(key=lambda b: b["score"], reverse=True)
+        class_boxes = [b for b in boxes if b.category == class_name]
+        class_boxes.sort(key=lambda b: b.score, reverse=True)
         pred_by_sample[sample_token] = class_boxes
         for i, b in enumerate(class_boxes):
-            all_preds.append((b["score"], sample_token, i))
+            all_preds.append((float(b.score), sample_token, i))
 
     if npos == 0:
         return MetricData.no_predictions()
 
-    # Sort all predictions globally by score descending
     all_preds.sort(key=lambda x: x[0], reverse=True)
 
-    # Greedy matching
-    tp_list = []
-    conf_list = []
-    match_data = {k: [] for k in ["trans_err", "scale_err", "orient_err", "vel_err", "attr_err"]}
+    tp_list: list[int] = []
+    conf_list: list[float] = []
+    match_data: dict[str, list[float]] = {
+        k: [] for k in ("trans_err", "scale_err", "orient_err", "vel_err", "attr_err")
+    }
     matched_gt: dict[str, set[int]] = {st: set() for st in gt_by_sample}
 
     for score, sample_token, pred_idx in all_preds:
@@ -112,7 +110,7 @@ def accumulate(
         for gt_idx, gt in enumerate(gt_list):
             if gt_idx in matched_gt.get(sample_token, set()):
                 continue
-            d = center_distance(pred["translation"], gt["translation"])
+            d = center_distance(pred.translation, gt.translation)
             if d < min_dist:
                 min_dist = d
                 min_gt_idx = gt_idx
@@ -124,23 +122,22 @@ def accumulate(
         if is_tp:
             matched_gt[sample_token].add(min_gt_idx)
             gt = gt_list[min_gt_idx]
-            match_data["trans_err"].append(center_distance(pred["translation"], gt["translation"]))
-            match_data["scale_err"].append(1.0 - scale_iou(pred["size"], gt["size"]))
+            match_data["trans_err"].append(center_distance(pred.translation, gt.translation))
+            match_data["scale_err"].append(1.0 - scale_iou(pred.size, gt.size))
             period = np.pi if class_name == "barrier" else 2 * np.pi
-            match_data["orient_err"].append(yaw_diff(pred["rotation"], gt["rotation"], period=period))
-            if pred["velocity"] is not None and gt["velocity"] is not None:
+            match_data["orient_err"].append(yaw_diff(pred.rotation, gt.rotation, period=period))
+            if pred.velocity is not None and gt.velocity is not None:
                 vel_diff = float(np.linalg.norm(
-                    np.asarray(pred["velocity"])[:2] - np.asarray(gt["velocity"])[:2]
+                    pred.velocity[:2] - gt.velocity[:2]
                 ))
                 match_data["vel_err"].append(vel_diff)
             else:
                 match_data["vel_err"].append(float("nan"))
-            match_data["attr_err"].append(1.0 - attr_acc(gt["attributes"], pred["attributes"]))
+            match_data["attr_err"].append(1.0 - attr_acc(gt.attributes, pred.attributes))
         else:
             for key in match_data:
                 match_data[key].append(float("nan"))
 
-    # Compute precision / recall
     tp_arr = np.array(tp_list, dtype=float)
     conf_arr = np.array(conf_list, dtype=float)
     tp_cum = np.cumsum(tp_arr)
@@ -148,7 +145,6 @@ def accumulate(
     precision_raw = tp_cum / (tp_cum + fp_cum)
     recall_raw = tp_cum / npos
 
-    # Interpolate to NELEM recall points
     recall_interp = np.linspace(0, 1, NELEM)
     precision_interp = np.zeros(NELEM)
     confidence_interp = np.zeros(NELEM)
@@ -159,7 +155,6 @@ def accumulate(
             precision_interp[i] = precision_raw[mask].max()
             confidence_interp[i] = conf_arr[mask].min()
 
-    # Interpolate TP errors using cumulative mean
     tp_metric_interp = {}
     for key in match_data:
         raw = np.array(match_data[key], dtype=float)

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

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

@@ -1,8 +1,10 @@
 LICENSE
 README.md
 pyproject.toml
+tests/test_box.py
 tests/test_coordinate_frames.py
 tests/test_detection_eval.py
+tests/test_evaluate.py
 tests/test_fusion.py
 tests/test_loader.py
 tests/test_matching.py
@@ -37,6 +39,8 @@ x4d_devkit/core/models.py
 x4d_devkit/core/token.py
 x4d_devkit/core/transform.py
 x4d_devkit/eval/__init__.py
+x4d_devkit/eval/api.py
+x4d_devkit/eval/box.py
 x4d_devkit/eval/detection.py
 x4d_devkit/eval/matching.py
 x4d_devkit/eval/metrics.py