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

{x4d_devkit-0.5.0/x4d_devkit.egg-info → x4d_devkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.5.0
+Version: 0.6.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -20,14 +20,12 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.24
+Requires-Dist: httpx>=0.27
 Provides-Extra: converters
 Requires-Dist: nuscenes-devkit>=1.1.0; extra == "converters"
-Provides-Extra: client
-Requires-Dist: httpx>=0.27; extra == "client"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: httpx>=0.27; extra == "dev"
 Dynamic: license-file
 
 # x4d-devkit

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.5.0"
+version = "0.6.0"
 description = "X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets"
 readme = "README.md"
 license = "Apache-2.0"
@@ -24,12 +24,11 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
-dependencies = ["numpy>=1.24"]
+dependencies = ["numpy>=1.24", "httpx>=0.27"]
 
 [project.optional-dependencies]
 converters = ["nuscenes-devkit>=1.1.0"]
-client = ["httpx>=0.27"]
-dev = ["pytest>=7.0", "pytest-cov", "httpx>=0.27"]
+dev = ["pytest>=7.0", "pytest-cov"]
 
 [project.urls]
 Homepage = "https://github.com/windzu/x4d-devkit"

x4d_devkit-0.6.0/tests/test_v06_api_additions.py

@@ -0,0 +1,162 @@
+"""Unit tests for v0.6.0 API additions.
+
+Covers:
+    - x4d_devkit.__version__
+    - ClipLoader.schema_version property + require_schema_version + constructor kwarg
+    - SchemaVersionMismatch exception
+    - calc_ap / calc_tp public re-exports (and underscore aliases still work)
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+import x4d_devkit
+from x4d_devkit import (
+    ClipLoader,
+    SchemaVersionMismatch,
+    calc_ap,
+    calc_tp,
+)
+from x4d_devkit.eval.matching import MetricData
+
+
+def _write_minimal_clip(clip_dir: Path, schema_version: str) -> None:
+    """Write the minimum JSON files ClipLoader.__init__ needs to succeed."""
+    clip_dir.mkdir(parents=True, exist_ok=True)
+    meta = {
+        "clip_id": "20260504_test_001",
+        "schema_version": schema_version,
+        "session_id": "20260504_test",
+        "vehicle_id": "test",
+        "capture_time_utc": "2026-05-04T00:00:00Z",
+        "duration_s": 0.0,
+        "keyframe_count": 0,
+        "sweep_count": 0,
+        "sensors": [],
+    }
+    (clip_dir / "meta.json").write_text(json.dumps(meta))
+    for empty in (
+        "calibrated_sensor.json",
+        "ego_pose.json",
+        "sample.json",
+        "sample_data.json",
+        "annotation.json",
+        "instance.json",
+    ):
+        (clip_dir / empty).write_text("[]")
+
+
+def test_package_has_version_attribute():
+    """__version__ is a non-empty string matching expected shape."""
+    assert isinstance(x4d_devkit.__version__, str)
+    assert x4d_devkit.__version__  # non-empty
+    # Either a real version (e.g. "0.6.0", "0.6.0.post1") or the editable fallback.
+    assert "." in x4d_devkit.__version__ or x4d_devkit.__version__.startswith("0.0.0")
+
+
+def test_loader_schema_version_property(tmp_path):
+    _write_minimal_clip(tmp_path, "0.5")
+    loader = ClipLoader(tmp_path)
+    assert loader.schema_version == "0.5"
+    assert loader.schema_version == loader.meta.schema_version
+
+
+def test_loader_require_schema_version_match(tmp_path):
+    _write_minimal_clip(tmp_path, "0.5")
+    loader = ClipLoader(tmp_path)
+    loader.require_schema_version("0.5")  # no raise
+
+
+def test_loader_require_schema_version_mismatch(tmp_path):
+    _write_minimal_clip(tmp_path, "0.4")
+    loader = ClipLoader(tmp_path)
+    with pytest.raises(SchemaVersionMismatch) as exc:
+        loader.require_schema_version("0.5")
+    assert exc.value.actual == "0.4"
+    assert exc.value.expected == "0.5"
+    assert "0.4" in str(exc.value) and "0.5" in str(exc.value)
+
+
+def test_loader_require_schema_version_set(tmp_path):
+    _write_minimal_clip(tmp_path, "0.4")
+    loader = ClipLoader(tmp_path)
+    loader.require_schema_version({"0.4", "0.5"})  # no raise
+    with pytest.raises(SchemaVersionMismatch):
+        loader.require_schema_version({"0.5", "0.6"})
+
+
+def test_loader_constructor_strict_check_match(tmp_path):
+    _write_minimal_clip(tmp_path, "0.5")
+    ClipLoader(tmp_path, expected_schema_version="0.5")  # no raise
+
+
+def test_loader_constructor_strict_check_mismatch(tmp_path):
+    _write_minimal_clip(tmp_path, "0.4")
+    with pytest.raises(SchemaVersionMismatch):
+        ClipLoader(tmp_path, expected_schema_version="0.5")
+
+
+def test_loader_constructor_strict_check_set(tmp_path):
+    _write_minimal_clip(tmp_path, "0.5")
+    ClipLoader(tmp_path, expected_schema_version={"0.4", "0.5"})  # no raise
+    _write_minimal_clip(tmp_path, "0.3")
+    with pytest.raises(SchemaVersionMismatch):
+        ClipLoader(tmp_path, expected_schema_version={"0.4", "0.5"})
+
+
+def _md_with_precision(prec: np.ndarray) -> MetricData:
+    """Build a MetricData with just enough fields for calc_ap / calc_tp."""
+    n = len(prec)
+    md = MetricData(
+        recall=np.linspace(0, 1, n),
+        precision=prec,
+        confidence=np.linspace(1, 0, n),
+        trans_err=np.zeros(n),
+        vel_err=np.zeros(n),
+        scale_err=np.zeros(n),
+        orient_err=np.zeros(n),
+        attr_err=np.zeros(n),
+    )
+    return md
+
+
+def test_calc_ap_public_export():
+    """calc_ap is importable from x4d_devkit and x4d_devkit.eval, returns expected value."""
+    from x4d_devkit.eval import calc_ap as eval_calc_ap
+
+    assert eval_calc_ap is calc_ap
+
+    # Constant precision = 1.0 across recall, min_recall=0, min_precision=0 → AP=1.0
+    md = _md_with_precision(np.ones(101))
+    ap = calc_ap(md, min_recall=0.0, min_precision=0.0)
+    assert ap == pytest.approx(1.0)
+
+    # Constant 0 precision → AP=0.0
+    md = _md_with_precision(np.zeros(101))
+    ap = calc_ap(md, min_recall=0.0, min_precision=0.0)
+    assert ap == pytest.approx(0.0)
+
+
+def test_calc_tp_public_export():
+    """calc_tp is importable and returns mean of metric in valid recall range."""
+    from x4d_devkit.eval import calc_tp as eval_calc_tp
+
+    assert eval_calc_tp is calc_tp
+
+    md = _md_with_precision(np.ones(101))
+    md.trans_err[:] = 0.5
+    # min_recall=0 → first_ind=1; max_recall_ind defaults; mean over [1..max] of 0.5 = 0.5
+    tp = calc_tp(md, min_recall=0.0, metric_name="trans_err")
+    assert tp == pytest.approx(0.5)
+
+
+def test_underscore_aliases_still_work():
+    """Old _calc_ap / _calc_tp names remain importable (deprecated alias)."""
+    from x4d_devkit.eval.detection import _calc_ap, _calc_tp
+
+    assert _calc_ap is calc_ap
+    assert _calc_tp is calc_tp

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

@@ -1,5 +1,12 @@
 """X-4D dataset format SDK."""
 
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("x4d-devkit")
+except PackageNotFoundError:  # source checkout without installed metadata
+    __version__ = "0.0.0+unknown"
+
 from x4d_devkit.client import X4DClient
 from x4d_devkit.core import (
     Annotation,
@@ -10,6 +17,7 @@ from x4d_devkit.core import (
     Instance,
     Sample,
     SampleData,
+    SchemaVersionMismatch,
     Transform,
     TransformChain,
     generate_token,
@@ -18,12 +26,15 @@ from x4d_devkit.eval import (
     DetectionConfig,
     DetectionEval,
     DetectionResult,
+    calc_ap,
+    calc_tp,
     nusc_detection_config,
 )
 from x4d_devkit.validation import validate_clip, ValidationReport
 from x4d_devkit.fusion import LIDAR_FUSED_DTYPE, FusionSource, fuse_pointclouds  # noqa: E402,F401
 
 __all__ = [
+    "__version__",
     "Annotation",
     "CalibratedSensor",
     "LIDAR_FUSED_DTYPE",
@@ -38,10 +49,13 @@ __all__ = [
     "Instance",
     "Sample",
     "SampleData",
+    "SchemaVersionMismatch",
     "Transform",
     "TransformChain",
     "ValidationReport",
     "X4DClient",
+    "calc_ap",
+    "calc_tp",
     "generate_token",
     "nusc_detection_config",
     "validate_clip",

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

@@ -1,6 +1,6 @@
 """Core layer: data models, clip loader, transforms."""
 
-from x4d_devkit.core.loader import ClipLoader
+from x4d_devkit.core.loader import ClipLoader, SchemaVersionMismatch
 from x4d_devkit.core.models import (
     Annotation,
     CalibratedSensor,
@@ -22,6 +22,7 @@ __all__ = [
     "Instance",
     "Sample",
     "SampleData",
+    "SchemaVersionMismatch",
     "Transform",
     "TransformChain",
     "generate_token",

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

@@ -24,6 +24,24 @@ FrameType = Literal["sensor", "ego", "world"]
 _VALID_FRAMES = {"sensor", "ego", "world"}
 
 
+class SchemaVersionMismatch(ValueError):
+    """Raised when a clip's ``meta.schema_version`` doesn't match the consumer's expectations.
+
+    Attributes:
+        actual: the version found in ``meta.json``.
+        expected: the version (or set of versions) the consumer required.
+    """
+
+    def __init__(self, actual: str, expected: "str | set[str]") -> None:
+        self.actual = actual
+        self.expected = expected
+        if isinstance(expected, str):
+            msg = f"clip schema_version is {actual!r}, expected {expected!r}"
+        else:
+            msg = f"clip schema_version is {actual!r}, expected one of {sorted(expected)!r}"
+        super().__init__(msg)
+
+
 class ClipLoader:
     """Load and index an X4D clip directory.
 
@@ -49,11 +67,18 @@ class ClipLoader:
         anns = loader.annotations_for_sample(sample.token, frame="ego")
     """
 
-    def __init__(self, clip_dir: str | Path) -> None:
+    def __init__(
+        self,
+        clip_dir: str | Path,
+        *,
+        expected_schema_version: "str | set[str] | None" = None,
+    ) -> None:
         self._clip_dir = Path(clip_dir)
 
         # Load and parse all JSON
         self._meta = self._load_meta()
+        if expected_schema_version is not None:
+            self.require_schema_version(expected_schema_version)
         self._calibrated_sensors = self._load_calibrated_sensors()
         self._ego_poses = self._load_ego_poses()
         self._samples = self._load_samples()
@@ -228,6 +253,31 @@ class ClipLoader:
         """Clip metadata (from meta.json)."""
         return self._meta
 
+    @property
+    def schema_version(self) -> str:
+        """Shortcut for ``self.meta.schema_version`` — the X-4D format version this clip was written in."""
+        return self._meta.schema_version
+
+    def require_schema_version(self, expected: "str | set[str]") -> None:
+        """Raise ``SchemaVersionMismatch`` if the clip's schema_version isn't in ``expected``.
+
+        Args:
+            expected: a single version string (e.g. ``"0.5"``) or a set of accepted
+                versions (e.g. ``{"0.4", "0.5"}``).
+
+        Example::
+
+            loader = ClipLoader(path)
+            loader.require_schema_version("0.5")  # raises if not 0.5
+        """
+        actual = self._meta.schema_version
+        if isinstance(expected, str):
+            if actual != expected:
+                raise SchemaVersionMismatch(actual, expected)
+        else:
+            if actual not in expected:
+                raise SchemaVersionMismatch(actual, set(expected))
+
     @property
     def samples(self) -> list[Sample]:
         """All samples, sorted by timestamp."""

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0}/x4d_devkit/eval/__init__.py

@@ -4,6 +4,8 @@ from x4d_devkit.eval.detection import (
     DetectionConfig,
     DetectionEval,
     DetectionResult,
+    calc_ap,
+    calc_tp,
     detzero_detection_config,
     nusc_detection_config,
 )
@@ -12,6 +14,8 @@ __all__ = [
     "DetectionConfig",
     "DetectionEval",
     "DetectionResult",
+    "calc_ap",
+    "calc_tp",
     "detzero_detection_config",
     "nusc_detection_config",
 ]

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0}/x4d_devkit/eval/detection.py

@@ -197,7 +197,7 @@ class DetectionResult:
     tp_scores: dict[str, float]
 
 
-def _calc_ap(md: MetricData, min_recall: float, min_precision: float) -> float:
+def calc_ap(md: MetricData, min_recall: float, min_precision: float) -> float:
     """Calculate Average Precision from MetricData."""
     prec = np.copy(md.precision)
     prec = prec[round(100 * min_recall) + 1:]
@@ -208,7 +208,7 @@ def _calc_ap(md: MetricData, min_recall: float, min_precision: float) -> float:
     return float(np.mean(prec) / (1.0 - min_precision))
 
 
-def _calc_tp(md: MetricData, min_recall: float, metric_name: str) -> float:
+def calc_tp(md: MetricData, min_recall: float, metric_name: str) -> float:
     """Calculate mean TP metric between min_recall and max_recall."""
     first_ind = round(100 * min_recall) + 1
     last_ind = md.max_recall_ind
@@ -218,6 +218,11 @@ def _calc_tp(md: MetricData, min_recall: float, metric_name: str) -> float:
     return float(np.nanmean(metric_arr[first_ind:last_ind + 1]))
 
 
+# Deprecated aliases — removed in 0.7.0. Use calc_ap / calc_tp.
+_calc_ap = calc_ap
+_calc_tp = calc_tp
+
+
 def _extract_boxes(
     clip: ClipLoader,
     config: DetectionConfig,
@@ -339,7 +344,7 @@ class DetectionEval:
             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)
+                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())))
@@ -360,7 +365,7 @@ class DetectionEval:
                 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)
+                    label_tp_errors[class_name][metric_name] = calc_tp(md, cfg.min_recall, metric_name)
 
         tp_errors = {}
         for metric_name in TP_METRICS:

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0/x4d_devkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.5.0
+Version: 0.6.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -20,14 +20,12 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.24
+Requires-Dist: httpx>=0.27
 Provides-Extra: converters
 Requires-Dist: nuscenes-devkit>=1.1.0; extra == "converters"
-Provides-Extra: client
-Requires-Dist: httpx>=0.27; extra == "client"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: httpx>=0.27; extra == "dev"
 Dynamic: license-file
 
 # x4d-devkit

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0}/x4d_devkit.egg-info/SOURCES.txt

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

{x4d_devkit-0.5.0 → x4d_devkit-0.6.0}/x4d_devkit.egg-info/requires.txt

@@ -1,6 +1,4 @@
 numpy>=1.24
-
-[client]
 httpx>=0.27
 
 [converters]
@@ -9,4 +7,3 @@ nuscenes-devkit>=1.1.0
 [dev]
 pytest>=7.0
 pytest-cov
-httpx>=0.27