x4d-devkit 0.2.2__tar.gz → 0.3.0__tar.gz

{x4d_devkit-0.2.2/x4d_devkit.egg-info → x4d_devkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.2.2
+Version: 0.3.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.2.2 → x4d_devkit-0.3.0}/pyproject.toml

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

@@ -0,0 +1,134 @@
+import numpy as np
+import pytest
+
+from x4d_devkit.fusion import (
+    LIDAR_FUSED_DTYPE,
+    FusionSource,
+    fuse_pointclouds,
+)
+
+
+def _identity_pose():
+    m = np.eye(4, dtype=np.float64)
+    return m
+
+
+def test_fused_dtype_is_5_float32_fields():
+    assert LIDAR_FUSED_DTYPE.itemsize == 20
+    assert LIDAR_FUSED_DTYPE.names == ("x", "y", "z", "intensity", "t")
+    for name in LIDAR_FUSED_DTYPE.names:
+        assert LIDAR_FUSED_DTYPE.fields[name][0] == np.dtype("<f4")
+
+
+def test_single_lidar_identity_pose_no_per_point_ts():
+    pts = np.array(
+        [(1.0, 2.0, 3.0, 0.5),
+         (4.0, 5.0, 6.0, 0.9)],
+        dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4")],
+    )
+    out = fuse_pointclouds(
+        sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(), per_point_ts_field=None)],
+        frame_ref_time_us=0,
+    )
+    assert out.dtype == LIDAR_FUSED_DTYPE
+    assert out.shape == (2,)
+    np.testing.assert_array_equal(out["x"], [1.0, 4.0])
+    np.testing.assert_allclose(out["intensity"], [0.5, 0.9], rtol=1e-6)
+    np.testing.assert_array_equal(out["t"], [0.0, 0.0])
+
+
+def test_multi_lidar_concat_with_per_lidar_pose():
+    pts_a = np.array([(1.0, 0.0, 0.0, 0.1)],
+                     dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4")])
+    pts_b = np.array([(0.0, 1.0, 0.0, 0.2)],
+                     dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4")])
+    pose_b = np.eye(4, dtype=np.float64); pose_b[0, 3] = 5.0  # shift +5 in x
+    out = fuse_pointclouds(
+        sources=[
+            FusionSource(points=pts_a, lidar_to_ego=_identity_pose(), per_point_ts_field=None),
+            FusionSource(points=pts_b, lidar_to_ego=pose_b, per_point_ts_field=None),
+        ],
+        frame_ref_time_us=0,
+    )
+    assert out.shape == (2,)
+    np.testing.assert_allclose(out["x"], [1.0, 5.0])
+    np.testing.assert_allclose(out["y"], [0.0, 1.0])
+
+
+def test_per_point_ts_offset_is_seconds_relative_to_frame_ref():
+    # Points at +1ms and +2ms vs frame ref
+    pts = np.array(
+        [(1.0, 0.0, 0.0, 0.0, 1_000_000_000),
+         (2.0, 0.0, 0.0, 0.0, 1_000_001_000)],
+        dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4"), ("timestamp", "<u8")],
+    )
+    out = fuse_pointclouds(
+        sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(),
+                              per_point_ts_field="timestamp", per_point_ts_unit="ns")],
+        frame_ref_time_us=1_000_000,  # 1ms after epoch
+    )
+    np.testing.assert_allclose(out["t"], [0.0, 1e-6], atol=1e-9)
+
+
+def test_missing_intensity_raises():
+    pts = np.array([(1.0, 2.0, 3.0)],
+                   dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4")])
+    with pytest.raises(ValueError, match="intensity"):
+        fuse_pointclouds(
+            sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(), per_point_ts_field=None)],
+            frame_ref_time_us=0,
+        )
+
+
+def test_per_point_ts_offset_microseconds_unit():
+    # Points at +1ms vs frame ref, given in microseconds
+    pts = np.array(
+        [(1.0, 0.0, 0.0, 0.0, 1_000_000),
+         (2.0, 0.0, 0.0, 0.0, 1_001_000)],
+        dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4"), ("timestamp", "<u8")],
+    )
+    out = fuse_pointclouds(
+        sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(),
+                              per_point_ts_field="timestamp", per_point_ts_unit="us")],
+        frame_ref_time_us=1_000_000,
+    )
+    np.testing.assert_allclose(out["t"], [0.0, 1e-3], atol=1e-9)
+
+
+def test_unsupported_ts_unit_raises():
+    pts = np.array(
+        [(1.0, 0.0, 0.0, 0.0, 0)],
+        dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4"), ("timestamp", "<u8")],
+    )
+    with pytest.raises(ValueError, match="unsupported per_point_ts_unit"):
+        fuse_pointclouds(
+            sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(),
+                                  per_point_ts_field="timestamp", per_point_ts_unit="ms")],
+            frame_ref_time_us=0,
+        )
+
+
+def test_unstructured_array_raises():
+    pts = np.zeros((3, 4), dtype=np.float32)  # plain (N, 4) — not structured
+    with pytest.raises(ValueError, match="structured numpy array"):
+        fuse_pointclouds(
+            sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(), per_point_ts_field=None)],
+            frame_ref_time_us=0,
+        )
+
+
+def test_dtype_round_trip_via_tofile(tmp_path):
+    pts = np.array(
+        [(1.5, -2.5, 3.5, 0.25),
+         (10.0, 20.0, 30.0, 0.5)],
+        dtype=[("x", "<f4"), ("y", "<f4"), ("z", "<f4"), ("intensity", "<f4")],
+    )
+    out = fuse_pointclouds(
+        sources=[FusionSource(points=pts, lidar_to_ego=_identity_pose(), per_point_ts_field=None)],
+        frame_ref_time_us=0,
+    )
+    path = tmp_path / "test.bin"
+    out.tofile(str(path))
+    assert path.stat().st_size == 2 * 20  # 2 points * 20 bytes/point
+    roundtrip = np.fromfile(str(path), dtype=LIDAR_FUSED_DTYPE)
+    np.testing.assert_array_equal(roundtrip, out)

{x4d_devkit-0.2.2 → x4d_devkit-0.3.0}/x4d_devkit/__init__.py

@@ -21,10 +21,14 @@ from x4d_devkit.eval import (
     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__ = [
     "Annotation",
     "CalibratedSensor",
+    "LIDAR_FUSED_DTYPE",
+    "FusionSource",
+    "fuse_pointclouds",
     "ClipLoader",
     "ClipMeta",
     "DetectionConfig",

x4d_devkit-0.3.0/x4d_devkit/fusion.py

@@ -0,0 +1,104 @@
+"""Lidar fusion to ego frame.
+
+Single-lidar and multi-lidar share one path: each source provides its points
+in lidar frame plus a 4x4 homogeneous lidar->ego transform. Output is a
+contiguous structured array with the canonical 5-field layout.
+
+Used by the X-4D ingestion pipeline to write `samples/lidar/<ts>.bin` and
+`sweeps/lidar/<ts>.bin`. Downstream consumers read with
+`np.fromfile(path, dtype=LIDAR_FUSED_DTYPE)`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+
+LIDAR_FUSED_DTYPE = np.dtype([
+    ("x", "<f4"),
+    ("y", "<f4"),
+    ("z", "<f4"),
+    ("intensity", "<f4"),
+    ("t", "<f4"),
+])
+
+
+@dataclass
+class FusionSource:
+    points: np.ndarray                   # structured array; must include x, y, z, intensity
+    lidar_to_ego: np.ndarray             # (4, 4) float64 homogeneous
+    per_point_ts_field: Optional[str] = None  # name of u64/i64 ts field, e.g. "timestamp"
+    per_point_ts_unit: str = "ns"        # "ns" | "us"
+
+
+def _intensity_field(names: tuple[str, ...]) -> str:
+    for n in names:
+        if "intensity" in n.lower():
+            return n
+    raise ValueError(
+        f"point cloud has no field with 'intensity' in its name (got {names!r}); "
+        "fusion refuses to silently zero-fill"
+    )
+
+
+def _transform_xyz(xyz: np.ndarray, T: np.ndarray) -> np.ndarray:
+    # xyz: (N, 3) float64; T: (4, 4) float64; returns (N, 3) float32
+    homog = np.empty((xyz.shape[0], 4), dtype=np.float64)
+    homog[:, :3] = xyz
+    homog[:, 3] = 1.0
+    out = homog @ T.T
+    return out[:, :3].astype(np.float32, copy=False)
+
+
+def fuse_pointclouds(sources: list[FusionSource], frame_ref_time_us: int) -> np.ndarray:
+    """Transform each source into ego frame and concat into the 5-field layout.
+
+    `frame_ref_time_us` is the synced frame timestamp; per-point `t` is computed
+    as `(point_ts - frame_ref) / 1e6` (seconds). When a source has no per-point
+    timestamp, `t` is filled with 0 (semantics: no motion-comp info available).
+    """
+    if not sources:
+        return np.empty((0,), dtype=LIDAR_FUSED_DTYPE)
+
+    chunks: list[np.ndarray] = []
+    for src in sources:
+        pts = src.points
+        if pts.dtype.names is None:
+            raise ValueError(
+                "FusionSource.points must be a structured numpy array with named fields"
+            )
+        names = pts.dtype.names
+        for required in ("x", "y", "z"):
+            if required not in names:
+                raise ValueError(f"source missing field {required!r}; got {names!r}")
+        intensity_name = _intensity_field(names)
+
+        xyz = np.column_stack([pts["x"], pts["y"], pts["z"]]).astype(np.float64, copy=False)
+        ego_xyz = _transform_xyz(xyz, np.asarray(src.lidar_to_ego, dtype=np.float64))
+
+        intensity = np.asarray(pts[intensity_name], dtype=np.float32)
+
+        if src.per_point_ts_field and src.per_point_ts_field in names:
+            raw_ts = np.asarray(pts[src.per_point_ts_field], dtype=np.int64)
+            if src.per_point_ts_unit == "ns":
+                ref_ns = int(frame_ref_time_us) * 1000
+                t = ((raw_ts - ref_ns).astype(np.float64) / 1e9).astype(np.float32)
+            elif src.per_point_ts_unit == "us":
+                ref_us = int(frame_ref_time_us)
+                t = ((raw_ts - ref_us).astype(np.float64) / 1e6).astype(np.float32)
+            else:
+                raise ValueError(f"unsupported per_point_ts_unit: {src.per_point_ts_unit}")
+        else:
+            t = np.zeros((ego_xyz.shape[0],), dtype=np.float32)
+
+        out = np.empty((ego_xyz.shape[0],), dtype=LIDAR_FUSED_DTYPE)
+        out["x"] = ego_xyz[:, 0]
+        out["y"] = ego_xyz[:, 1]
+        out["z"] = ego_xyz[:, 2]
+        out["intensity"] = intensity
+        out["t"] = t
+        chunks.append(out)
+
+    return np.concatenate(chunks, axis=0)

{x4d_devkit-0.2.2 → x4d_devkit-0.3.0/x4d_devkit.egg-info}/PKG-INFO

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

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 tests/test_coordinate_frames.py
 tests/test_detection_eval.py
+tests/test_fusion.py
 tests/test_loader.py
 tests/test_matching.py
 tests/test_metrics.py
@@ -14,6 +15,7 @@ tests/test_transform_chain.py
 tests/test_validation.py
 x4d_devkit/__init__.py
 x4d_devkit/cli.py
+x4d_devkit/fusion.py
 x4d_devkit.egg-info/PKG-INFO
 x4d_devkit.egg-info/SOURCES.txt
 x4d_devkit.egg-info/dependency_links.txt