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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.3.0"
+version = "0.5.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 → x4d_devkit-0.5.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,
         },
     ]))
 
@@ -150,7 +154,9 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
     pts.tofile(str(lidar_dir / "frame0.bin"))
     pts.tofile(str(lidar_dir / "frame1.bin"))
 
-    # -- annotation.json --
+    # -- annotation.json (v0.5: per-sample ego frame) --
+    # s-0 ego at origin; s-1 ego at (10, 0, 0). Same world pos (5,3,0) and (10,3,0)
+    # for the two frames maps to ego (5,3,0) and (0,3,0) respectively.
     (clip_dir / "annotation.json").write_text(json.dumps([
         {
             "annotation_token": "ann-0",
@@ -176,7 +182,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
             "instance_token": "inst-0",
             "category": "car",
             "bbox_3d": {
-                "translation": {"x": 10.0, "y": 3.0, "z": 0.0},
+                "translation": {"x": 0.0, "y": 3.0, "z": 0.0},
                 "size": {"length": 4.5, "width": 2.0, "height": 1.5},
                 "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
             },
@@ -273,54 +279,53 @@ class TestLoadPointCloudFrames:
 # ---------------------------------------------------------------------------
 
 class TestAnnotationsForSampleFrames:
-    def test_world_frame_default(self, loader):
-        """Default frame should return annotations in world coordinates."""
+    def test_ego_frame_default(self, loader):
+        """Default frame should return annotations in per-sample ego coordinates (v0.5 native)."""
         anns = loader.annotations_for_sample("s-0")
         assert len(anns) == 1
         np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, 0.0])
 
-    def test_world_frame_explicit(self, loader):
-        """Explicit frame='world' should match default."""
+    def test_ego_frame_explicit(self, loader):
+        """Explicit frame='ego' should match default."""
         anns_default = loader.annotations_for_sample("s-0")
-        anns_world = loader.annotations_for_sample("s-0", frame="world")
-        assert len(anns_default) == len(anns_world)
-        np.testing.assert_allclose(anns_default[0].translation, anns_world[0].translation)
+        anns_ego = loader.annotations_for_sample("s-0", frame="ego")
+        assert len(anns_default) == len(anns_ego)
+        np.testing.assert_allclose(anns_default[0].translation, anns_ego[0].translation)
 
-    def test_ego_frame_first_sample(self, loader):
-        """frame='ego' for first sample (ego at origin): same as world."""
-        anns = loader.annotations_for_sample("s-0", frame="ego")
-        # ego at origin -> world-to-ego is identity
+    def test_world_frame_first_sample(self, loader):
+        """frame='world' for first sample (ego at origin): same as ego."""
+        anns = loader.annotations_for_sample("s-0", frame="world")
+        # ego at origin -> ego-to-world is identity
         np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, 0.0], atol=1e-5)
 
-    def test_ego_frame_second_sample(self, loader):
-        """frame='ego' for second sample (ego at x=10): subtracts ego offset."""
-        anns = loader.annotations_for_sample("s-1", frame="ego")
-        # annotation at world (10,3,0), ego at (10,0,0) -> ego frame (0,3,0)
-        np.testing.assert_allclose(anns[0].translation, [0.0, 3.0, 0.0], atol=1e-5)
+    def test_world_frame_second_sample(self, loader):
+        """frame='world' for second sample (ego at x=10): adds ego offset."""
+        anns = loader.annotations_for_sample("s-1", frame="world")
+        # ego frame (0,3,0), ego at (10,0,0) -> world (10,3,0)
+        np.testing.assert_allclose(anns[0].translation, [10.0, 3.0, 0.0], atol=1e-5)
 
-    def test_ego_frame_velocity_rotated(self, loader):
-        """Velocity should be rotated (not translated) to ego frame."""
+    def test_ego_frame_velocity_unchanged(self, loader):
+        """Native (ego) frame: velocity returned as stored."""
         anns = loader.annotations_for_sample("s-0", frame="ego")
-        # ego rotation is identity, so velocity unchanged
         np.testing.assert_allclose(anns[0].velocity, [5.0, 0.0, 0.0], atol=1e-5)
 
-    def test_ego_frame_preserves_other_fields(self, loader):
-        """Non-pose fields should be preserved."""
-        anns_world = loader.annotations_for_sample("s-0", frame="world")
+    def test_world_frame_preserves_other_fields(self, loader):
+        """Non-pose fields should be preserved across frame transforms."""
         anns_ego = loader.annotations_for_sample("s-0", frame="ego")
+        anns_world = loader.annotations_for_sample("s-0", frame="world")
         assert anns_ego[0].token == anns_world[0].token
         assert anns_ego[0].category == anns_world[0].category
         np.testing.assert_allclose(anns_ego[0].size, anns_world[0].size)
         assert anns_ego[0].num_lidar_pts == anns_world[0].num_lidar_pts
 
-    def test_ego_frame_returns_new_objects(self, loader):
+    def test_world_frame_returns_new_objects(self, loader):
         """Transformed annotations should be new objects, not mutated originals."""
-        anns_world = loader.annotations_for_sample("s-1", frame="world")
         anns_ego = loader.annotations_for_sample("s-1", frame="ego")
-        # Originals should be unmodified
-        np.testing.assert_allclose(anns_world[0].translation, [10.0, 3.0, 0.0])
-        # Ego should be different
-        assert not np.allclose(anns_ego[0].translation, anns_world[0].translation, atol=0.1)
+        anns_world = loader.annotations_for_sample("s-1", frame="world")
+        # Originals (ego, native) should be unmodified
+        np.testing.assert_allclose(anns_ego[0].translation, [0.0, 3.0, 0.0])
+        # World should be different
+        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"):

{x4d_devkit-0.3.0 → x4d_devkit-0.5.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.3.0 → x4d_devkit-0.5.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.3.0 → x4d_devkit-0.5.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.3.0 → x4d_devkit-0.5.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
@@ -373,13 +380,36 @@ class NuScenesConverter:
             return None
         return {"vx": float(vel[0]), "vy": float(vel[1]), "vz": float(vel[2])}
 
+    def _get_lidar_ego_pose_for_sample(self, sample: dict) -> tuple[np.ndarray, list]:
+        """Return (R_global, t_global) of the LIDAR_TOP keyframe ego_pose for a sample.
+
+        v0.5 convention: the ego frame for an annotation = the ego_pose of the
+        sample's LiDAR keyframe sample_data.
+        """
+        lidar_sd_token = sample["data"].get("LIDAR_TOP")
+        if lidar_sd_token is None:
+            # Fallback to whichever target-channel sd has the earliest ts.
+            earliest_ts = None
+            earliest_ep = None
+            for channel, sd_token in sample["data"].items():
+                if channel not in TARGET_CHANNELS:
+                    continue
+                sd = self.nusc.get("sample_data", sd_token)
+                ep = self.nusc.get("ego_pose", sd["ego_pose_token"])
+                if earliest_ts is None or ep["timestamp"] < earliest_ts:
+                    earliest_ts = ep["timestamp"]
+                    earliest_ep = ep
+            ep = earliest_ep
+        else:
+            sd = self.nusc.get("sample_data", lidar_sd_token)
+            ep = self.nusc.get("ego_pose", sd["ego_pose_token"])
+        R = quat_to_rotation_matrix(ep["rotation"])
+        return R, ep["translation"]
+
     def _extract_annotations(
         self, scene: dict, clip_id: str
     ) -> tuple[list[dict], list[dict]]:
-        """Extract annotations and instances for the scene, in local coords."""
-        R_first, t_first = self._get_first_ego_pose_transform(scene)
-        R_inv, t_inv = invert_se3(R_first, t_first)
-
+        """Extract annotations and instances for the scene, in **per-sample ego frame** (v0.5)."""
         annotations: list[dict] = []
         instance_anns: dict[str, list[dict]] = {}
 
@@ -396,6 +426,10 @@ class NuScenesConverter:
             sample = self.nusc.get("sample", sample_token)
             new_sample_token = sample_token_map[sample_token]
 
+            # Per-sample ego_pose (LIDAR_TOP keyframe) — annotation frame.
+            R_ego_global, t_ego_global = self._get_lidar_ego_pose_for_sample(sample)
+            R_inv, t_inv = invert_se3(R_ego_global, t_ego_global)
+
             for ann_token in sample["anns"]:
                 ann = self.nusc.get("sample_annotation", ann_token)
                 nusc_instance_token = ann["instance_token"]
@@ -403,12 +437,13 @@ class NuScenesConverter:
                     self.nusc.get("instance", nusc_instance_token)["category_token"]
                 ]["name"]
 
+                # Global → ego (this sample's ego)
                 t_global = np.asarray(ann["translation"])
-                t_local = apply_se3(R_inv, t_inv, t_global)
+                t_ego = apply_se3(R_inv, t_inv, t_global)
 
                 R_ann_global = quat_to_rotation_matrix(ann["rotation"])
-                R_ann_local = R_inv @ R_ann_global
-                q_ann_local = rotation_matrix_to_quat(R_ann_local)
+                R_ann_ego = R_inv @ R_ann_global
+                q_ann_ego = rotation_matrix_to_quat(R_ann_ego)
 
                 attributes = [
                     self._attribute_by_token[at]["name"]
@@ -419,12 +454,16 @@ class NuScenesConverter:
                     int(ann["visibility_token"]) if ann["visibility_token"] else None
                 )
 
-                # Compute velocity in global coords, then rotate to local
+                # Velocity: nuScenes computes globally; rotate into this sample's ego.
                 vel_global = self._compute_velocity(ann_token)
                 if vel_global is not None:
                     vel_vec = np.array([vel_global["vx"], vel_global["vy"], vel_global["vz"]])
-                    vel_local = R_inv @ vel_vec
-                    velocity = {"vx": float(vel_local[0]), "vy": float(vel_local[1]), "vz": float(vel_local[2])}
+                    vel_ego = R_inv @ vel_vec
+                    velocity = {
+                        "vx": float(vel_ego[0]),
+                        "vy": float(vel_ego[1]),
+                        "vz": float(vel_ego[2]),
+                    }
                 else:
                     velocity = None
 
@@ -432,9 +471,9 @@ class NuScenesConverter:
                     "sample_token": new_sample_token,
                     "category": category,
                     "bbox_3d": {
-                        "translation": translation_to_named(t_local.tolist()),
+                        "translation": translation_to_named(t_ego.tolist()),
                         "size": size_wlh_to_named(ann["size"]),
-                        "rotation": quat_wxyz_to_named(q_ann_local),
+                        "rotation": quat_wxyz_to_named(q_ann_ego),
                     },
                     "num_lidar_pts": ann["num_lidar_pts"],
                     "visibility": visibility,

{x4d_devkit-0.3.0 → x4d_devkit-0.5.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
 
@@ -248,7 +250,10 @@ class ClipLoader:
 
     @property
     def annotations(self) -> list[Annotation]:
-        """All annotations in world frame."""
+        """All annotations in their **native frame** (ego since v0.5; world for v0.4 clips).
+
+        Use ``annotations_for_sample(token, frame=...)`` to request a specific frame.
+        """
         return self._annotations
 
     @property
@@ -295,16 +300,17 @@ class ClipLoader:
     def annotations_for_sample(
         self,
         sample_token: str,
-        frame: FrameType = "world",
+        frame: FrameType = "ego",
     ) -> list[Annotation]:
         """All annotations for a given sample.
 
         Args:
             sample_token: The sample token.
             frame: Target coordinate frame.
-                - "world" (default): native annotation frame, no transform.
-                - "ego": transform from world to ego frame using the ego_pose
-                  of the LiDAR sample_data for this sample (or first sample_data
+                - "ego" (default, v0.5 native): no transform — annotations are
+                  stored in the per-sample ego frame.
+                - "world": transform from ego to world using the ego_pose of
+                  the LiDAR sample_data for this sample (or first sample_data
                   if no LiDAR).
 
         Returns:
@@ -316,12 +322,12 @@ class ClipLoader:
             raise ValueError("Annotations cannot be transformed to sensor frame")
 
         anns = self._ann_by_sample.get(sample_token, [])
-        if frame == "world" or not anns:
+        if frame == "ego" or not anns:
             return anns
 
-        # frame == "ego": need ego_pose for this sample
-        ego_from_world = self._get_ego_from_world_for_sample(sample_token)
-        return [self._transform_annotation(a, ego_from_world) for a in anns]
+        # frame == "world": transform per-sample-ego → world via ego_pose.
+        world_from_ego = self._get_world_from_ego_for_sample(sample_token)
+        return [self._transform_annotation(a, world_from_ego) for a in anns]
 
     def load_point_cloud(
         self,
@@ -420,8 +426,8 @@ class ClipLoader:
             self._transform_chain = TransformChain(self)
         return self._transform_chain
 
-    def _get_ego_from_world_for_sample(self, sample_token: str) -> Transform:
-        """Get the inverse ego_pose transform for a sample.
+    def _get_world_from_ego_for_sample(self, sample_token: str) -> Transform:
+        """Get the world_from_ego transform for a sample.
 
         Uses the ego_pose from the LiDAR sample_data, or the first sample_data
         if no LiDAR channel exists.
@@ -437,7 +443,7 @@ class ClipLoader:
             sds[0],
         )
         chain = self._get_transform_chain()
-        return chain.get_world_from_ego(sd.ego_pose_token).inverse
+        return chain.get_world_from_ego(sd.ego_pose_token)
 
     @staticmethod
     def _transform_annotation(ann: Annotation, T: Transform) -> Annotation:

{x4d_devkit-0.3.0 → x4d_devkit-0.5.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))
@@ -150,23 +154,27 @@ class SampleData:
 
 @dataclass(frozen=True)
 class Annotation:
-    """A 3D bounding box annotation in world frame.
+    """A 3D bounding box annotation in **per-sample ego frame** (v0.5).
 
-    Annotations are natively stored in the clip's local world frame
-    (first ego pose ≈ origin). Use ``ClipLoader.annotations_for_sample(..., frame="ego")``
-    to transform to ego frame.
+    Annotations are natively stored in the ego frame of the sample they belong
+    to (the ego_pose of the sample's LiDAR keyframe). Use
+    ``ClipLoader.annotations_for_sample(..., frame="world")`` to transform to
+    the clip's local world frame when needed (rare — typically only for
+    cross-frame trajectory visualization).
 
     Attributes:
         token: Unique annotation token.
         sample_token: Token of the sample this annotation belongs to.
         instance_token: Token of the tracked object instance.
         category: Object category string (e.g. "car", "pedestrian").
-        translation: (3,) float64 array — box center [x, y, z] in world frame.
+        translation: (3,) float64 array — box center [x, y, z] in this sample's ego frame.
         size: (3,) float64 array — box dimensions [length, width, height] in meters.
-        rotation: (4,) float64 array — box orientation as quaternion [qx, qy, qz, qw].
-        num_lidar_pts: Number of LiDAR points inside this box.
+        rotation: (4,) float64 array — box orientation as quaternion [qx, qy, qz, qw],
+            relative to this sample's ego frame.
+        num_lidar_pts: Number of LiDAR points inside this box (real-counted, ≥ 0).
         visibility: Visibility level as string ("1" to "4", or "" if unknown).
-        velocity: (3,) float64 array — velocity [vx, vy, vz] in m/s, or None.
+        velocity: (3,) float64 array — velocity [vx, vy, vz] in m/s, **ego frame**
+            (forward = +x, left = +y), or None.
         attributes: List of attribute strings (e.g. ["vehicle.moving"]).
         prev: Token of previous annotation of same instance, or "" if first.
         next: Token of next annotation of same instance, or "" if last.

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

@@ -223,33 +223,26 @@ def _extract_boxes(
     config: DetectionConfig,
     max_boxes: int | None = None,
 ) -> dict[str, list[dict]]:
-    """Extract annotation boxes grouped by sample_token, with distance filtering."""
-    ep_by_token = {ep.token: ep for ep in clip.ego_poses}
+    """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
 
-    # Map sample_token → ego position (for distance filtering)
-    sample_ego_pos: dict[str, np.ndarray] = {}
-    for sd in clip.sample_data:
-        if sd.sample_token not in sample_ego_pos and sd.is_keyframe:
-            ep = ep_by_token.get(sd.ego_pose_token)
-            if ep is not None:
-                sample_ego_pos[sd.sample_token] = ep.translation
-
     result: dict[str, list[dict]] = {}
     for sample in clip.samples:
-        ego_pos = sample_ego_pos.get(sample.token)
-        anns = clip.annotations_for_sample(sample.token)
+        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
-            if ego_pos is not None:
-                dist = float(np.linalg.norm(ann.translation[:2] - ego_pos[:2]))
-                if dist > class_range[det_name]:
-                    continue
+            dist = float(np.linalg.norm(ann.translation[:2]))
+            if dist > class_range[det_name]:
+                continue
             boxes.append({
                 "translation": ann.translation,
                 "size": ann.size,

{x4d_devkit-0.3.0 → x4d_devkit-0.5.0}/x4d_devkit/validation/validator.py

@@ -218,6 +218,19 @@ def validate_clip(clip_dir: str | Path) -> ValidationReport:
                 )
                 break
 
+        # num_lidar_pts must be a non-negative integer (v0.5+: real-computed,
+        # 0 means "no points in box", not a default placeholder).
+        npts = ann.get("num_lidar_pts")
+        if not isinstance(npts, int) or isinstance(npts, bool) or npts < 0:
+            issues.append(
+                ValidationIssue(
+                    "annotation_num_lidar_pts",
+                    "error",
+                    f"Invalid num_lidar_pts={npts!r} (must be int >= 0)",
+                    ann.get("annotation_token", ""),
+                )
+            )
+
         # Sample token reference
         if ann.get("sample_token") not in sample_tokens:
             issues.append(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.3.0
+Version: 0.5.0
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0