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

{x4d_devkit-0.4.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.4.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.4.0 → x4d_devkit-0.5.0}/pyproject.toml

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

@@ -154,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",
@@ -180,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},
             },
@@ -277,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.4.0 → x4d_devkit-0.5.0}/x4d_devkit/converters/nuscenes.py

@@ -380,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]] = {}
 
@@ -403,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"]
@@ -410,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"]
@@ -426,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
 
@@ -439,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.4.0 → x4d_devkit-0.5.0}/x4d_devkit/core/loader.py

@@ -250,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
@@ -297,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:
@@ -318,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,
@@ -422,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.
@@ -439,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.4.0 → x4d_devkit-0.5.0}/x4d_devkit/core/models.py

@@ -154,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.4.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.4.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.4.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.4.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