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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.2.2
+Version: 0.4.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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.2.2"
+version = "0.4.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.2.2 → x4d_devkit-0.4.0}/tests/test_coordinate_frames.py

@@ -56,14 +56,18 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
             "channel": "LIDAR_TOP",
             "translation": {"x": 0.0, "y": 0.0, "z": 1.0},
             "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
-            "camera_intrinsic": None,
+            "intrinsics": None,
+            "distortion": None,
         },
         {
             "calibrated_sensor_token": "cs-cam",
             "channel": "CAM_FRONT",
             "translation": {"x": 0.5, "y": 0.0, "z": 0.8},
             "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
-            "camera_intrinsic": {"fx": 1000, "fy": 1000, "cx": 320, "cy": 240},
+            "intrinsics": {"camera_model": "pinhole",
+                           "fx": 1000, "fy": 1000, "cx": 320, "cy": 240,
+                           "image_width": 640, "image_height": 480},
+            "distortion": None,
         },
     ]))
 

x4d_devkit-0.4.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.4.0}/tests/test_models.py

@@ -82,13 +82,17 @@ class TestSampleData:
 class TestCalibratedSensor:
     def test_construction(self):
         cs = CalibratedSensor(
-            token="cs1", channel="CAM_FRONT", modality="camera",
+            token="cs1", channel="cam_front", modality="camera",
             translation=np.zeros(3), rotation=np.array([0, 0, 0, 1.0]),
-            camera_intrinsic={"fx": 1266.4, "fy": 1266.4, "cx": 816.3, "cy": 491.5,
-                              "k1": 0.0, "k2": 0.0, "k3": 0.0, "p1": 0.0, "p2": 0.0},
+            intrinsics={"camera_model": "pinhole",
+                        "fx": 1266.4, "fy": 1266.4, "cx": 816.3, "cy": 491.5,
+                        "image_width": 1600, "image_height": 900},
+            distortion={"model": "plumb_bob",
+                        "k1": 0.0, "k2": 0.0, "k3": 0.0, "p1": 0.0, "p2": 0.0},
         )
         assert cs.modality == "camera"
-        assert cs.camera_intrinsic["fx"] == 1266.4
+        assert cs.intrinsics["fx"] == 1266.4
+        assert cs.distortion["model"] == "plumb_bob"
 
 
 class TestAnnotation:

{x4d_devkit-0.2.2 → x4d_devkit-0.4.0}/tests/test_nuscenes_converter.py

@@ -108,11 +108,10 @@ class TestIntrinsicConversion:
         assert result["fy"] == pytest.approx(1266.4)
         assert result["cx"] == pytest.approx(816.3)
         assert result["cy"] == pytest.approx(491.5)
-        assert result["k1"] == 0.0
-        assert result["k2"] == 0.0
-        assert result["k3"] == 0.0
-        assert result["p1"] == 0.0
-        assert result["p2"] == 0.0
+        assert result["camera_model"] == "pinhole"
+        # Image dimensions default to nuScenes standard 1600x900 when not given.
+        assert result["image_width"] == 1600
+        assert result["image_height"] == 900
 
     def test_empty_intrinsic(self):
         """nuScenes uses empty list for non-camera sensors."""
@@ -185,8 +184,10 @@ class TestNuScenesConverterExtraction:
         # Check named fields
         assert "x" in cam_front["translation"]
         assert "qx" in cam_front["rotation"]
-        assert cam_front["camera_intrinsic"] is not None
-        assert "fx" in cam_front["camera_intrinsic"]
+        assert cam_front["intrinsics"] is not None
+        assert "fx" in cam_front["intrinsics"]
+        assert cam_front["intrinsics"]["camera_model"] == "pinhole"
+        assert "child_frame" not in cam_front  # dropped in v0.4
 
     def test_ego_poses_local_coordinates(self, converter):
         scene = converter.nusc.scene[0]

{x4d_devkit-0.2.2 → x4d_devkit-0.4.0}/tests/test_validation.py

@@ -55,12 +55,12 @@ def valid_clip(tmp_path):
             [
                 {
                     "calibrated_sensor_token": "cs_lidar",
-                    "channel": "LIDAR_TOP",
+                    "channel": "lidar_top",
                     "parent_frame": "base_link",
-                    "child_frame": "lidar_top",
                     "translation": {"x": 0, "y": 0, "z": 1.8},
                     "rotation": {"qx": 0, "qy": 0, "qz": 0, "qw": 1},
-                    "camera_intrinsic": None,
+                    "intrinsics": None,
+                    "distortion": None,
                 }
             ]
         )

{x4d_devkit-0.2.2 → x4d_devkit-0.4.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.2.2 → x4d_devkit-0.4.0}/x4d_devkit/converters/nuscenes.py

@@ -32,20 +32,26 @@ def size_wlh_to_named(size: list[float]) -> dict[str, float]:
     return {"length": size[1], "width": size[0], "height": size[2]}
 
 
-def intrinsic_matrix_to_named(matrix: list[list[float]]) -> dict[str, float] | None:
-    """Convert 3x3 intrinsic matrix to X4D named fields. Returns None for empty."""
+def intrinsic_matrix_to_named(
+    matrix: list[list[float]],
+    image_width: int | None = None,
+    image_height: int | None = None,
+) -> dict[str, float] | None:
+    """Convert 3x3 intrinsic matrix to X4D v0.4 intrinsics dict. Returns None for empty.
+
+    nuScenes does not record image dimensions per-sensor; they default to the
+    standard 1600x900 used by the dataset when not provided.
+    """
     if not matrix:
         return None
     return {
+        "camera_model": "pinhole",
         "fx": matrix[0][0],
         "fy": matrix[1][1],
         "cx": matrix[0][2],
         "cy": matrix[1][2],
-        "k1": 0.0,
-        "k2": 0.0,
-        "k3": 0.0,
-        "p1": 0.0,
-        "p2": 0.0,
+        "image_width": int(image_width) if image_width is not None else 1600,
+        "image_height": int(image_height) if image_height is not None else 900,
     }
 
 
@@ -238,21 +244,22 @@ class NuScenesConverter:
             sensor = self._sensor_by_token[cs["sensor_token"]]
 
             parent_frame = "base_link"
-            child_frame = channel.lower()
+
+            intrinsics = (
+                intrinsic_matrix_to_named(cs["camera_intrinsic"])
+                if sensor["modality"] == "camera"
+                else None
+            )
 
             records.append(
                 {
                     "calibrated_sensor_token": generate_token(clip_id, f"cs:{channel}"),
                     "channel": channel,
                     "parent_frame": parent_frame,
-                    "child_frame": child_frame,
                     "translation": translation_to_named(cs["translation"]),
                     "rotation": quat_wxyz_to_named(cs["rotation"]),
-                    "camera_intrinsic": intrinsic_matrix_to_named(
-                        cs["camera_intrinsic"]
-                    )
-                    if sensor["modality"] == "camera"
-                    else None,
+                    "intrinsics": intrinsics,
+                    "distortion": None,
                 }
             )
         return records

{x4d_devkit-0.2.2 → x4d_devkit-0.4.0}/x4d_devkit/core/loader.py

@@ -115,13 +115,15 @@ class ClipLoader:
         for r in records:
             t = r["translation"]
             q = r["rotation"]
+            intr = r.get("intrinsics")
             result.append(CalibratedSensor(
                 token=r["calibrated_sensor_token"],
                 channel=r["channel"],
-                modality="lidar" if r["camera_intrinsic"] is None else "camera",
+                modality="camera" if intr is not None else "lidar",
                 translation=[t["x"], t["y"], t["z"]],
                 rotation=[q["qx"], q["qy"], q["qz"], q["qw"]],
-                camera_intrinsic=r["camera_intrinsic"],
+                intrinsics=intr,
+                distortion=r.get("distortion"),
             ))
         return result
 

{x4d_devkit-0.2.2 → x4d_devkit-0.4.0}/x4d_devkit/core/models.py

@@ -53,11 +53,14 @@ class CalibratedSensor:
 
     Attributes:
         token: Unique token for this calibrated sensor record.
-        channel: Sensor channel name (e.g. "LIDAR_TOP", "CAM_FRONT").
+        channel: Sensor channel name — equals the ROS frame_id of the sensor
+            (e.g. "lidar_top", "cam_front_left").
         modality: "lidar" or "camera".
         translation: (3,) float64 array — sensor position in ego frame [x, y, z] meters.
         rotation: (4,) float64 array — sensor orientation as quaternion [qx, qy, qz, qw].
-        camera_intrinsic: Camera intrinsic parameters (fx, fy, cx, cy), or None for LiDAR.
+        intrinsics: Full camera intrinsics dict (camera_model, fx, fy, cx, cy,
+            image_width, image_height) or None for LiDAR.
+        distortion: Distortion model dict (model + coefficients) or None.
     """
 
     token: str
@@ -65,7 +68,8 @@ class CalibratedSensor:
     modality: str
     translation: np.ndarray
     rotation: np.ndarray
-    camera_intrinsic: dict[str, float] | None
+    intrinsics: dict | None
+    distortion: dict | None
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "translation", np.asarray(self.translation, dtype=np.float64))

x4d_devkit-0.4.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.4.0/x4d_devkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.2.2
+Version: 0.4.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.4.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