x4d-devkit 0.1.0__py3-none-any.whl

x4d_devkit/core/__init__.py

@@ -0,0 +1,28 @@
+"""Core layer: data models, clip loader, transforms."""
+
+from x4d_devkit.core.loader import ClipLoader
+from x4d_devkit.core.models import (
+    Annotation,
+    CalibratedSensor,
+    ClipMeta,
+    EgoPose,
+    Instance,
+    Sample,
+    SampleData,
+)
+from x4d_devkit.core.token import generate_token
+from x4d_devkit.core.transform import Transform, TransformChain
+
+__all__ = [
+    "Annotation",
+    "CalibratedSensor",
+    "ClipLoader",
+    "ClipMeta",
+    "EgoPose",
+    "Instance",
+    "Sample",
+    "SampleData",
+    "Transform",
+    "TransformChain",
+    "generate_token",
+]

x4d_devkit/core/loader.py

@@ -0,0 +1,259 @@
+"""ClipLoader: load an X4D clip directory into typed dataclasses."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from x4d_devkit.core.models import (
+    ClipMeta,
+    CalibratedSensor,
+    EgoPose,
+    Sample,
+    SampleData,
+    Annotation,
+    Instance,
+)
+
+
+class ClipLoader:
+    """Load and index an X4D clip directory.
+
+    Eagerly parses all JSON metadata into frozen dataclasses.
+    Binary sensor data (point clouds, images) is loaded on demand.
+    """
+
+    def __init__(self, clip_dir: str | Path) -> None:
+        self._clip_dir = Path(clip_dir)
+
+        # Load and parse all JSON
+        self._meta = self._load_meta()
+        self._calibrated_sensors = self._load_calibrated_sensors()
+        self._ego_poses = self._load_ego_poses()
+        self._samples = self._load_samples()
+        self._sample_data = self._load_sample_data()
+        self._annotations = self._load_annotations()
+        self._instances = self._load_instances()
+
+        # Build global token → object index
+        self._token_index: dict[str, Any] = {}
+        for cs in self._calibrated_sensors:
+            self._token_index[cs.token] = cs
+        for ep in self._ego_poses:
+            self._token_index[ep.token] = ep
+        for s in self._samples:
+            self._token_index[s.token] = s
+        for sd in self._sample_data:
+            self._token_index[sd.token] = sd
+        for a in self._annotations:
+            self._token_index[a.token] = a
+        for i in self._instances:
+            self._token_index[i.token] = i
+
+        # Build auxiliary indices
+        self._sd_by_channel: dict[str, list[SampleData]] = {}
+        for sd in self._sample_data:
+            self._sd_by_channel.setdefault(sd.channel, []).append(sd)
+        for ch in self._sd_by_channel:
+            self._sd_by_channel[ch].sort(key=lambda sd: sd.timestamp_us)
+
+        self._sd_by_sample: dict[str, list[SampleData]] = {}
+        for sd in self._sample_data:
+            self._sd_by_sample.setdefault(sd.sample_token, []).append(sd)
+
+        self._ann_by_sample: dict[str, list[Annotation]] = {}
+        for a in self._annotations:
+            self._ann_by_sample.setdefault(a.sample_token, []).append(a)
+
+    def _read_json(self, name: str) -> Any:
+        with open(self._clip_dir / name) as f:
+            return json.load(f)
+
+    def _load_meta(self) -> ClipMeta:
+        d = self._read_json("meta.json")
+        return ClipMeta(
+            clip_id=d["clip_id"],
+            schema_version=d["schema_version"],
+            session_id=d["session_id"],
+            vehicle_id=d["vehicle_id"],
+            capture_time_utc=d["capture_time_utc"],
+            duration_s=d["duration_s"],
+            num_keyframes=d["keyframe_count"],
+            num_sweeps=d["sweep_count"],
+            sensors=d["sensors"],
+        )
+
+    def _load_calibrated_sensors(self) -> list[CalibratedSensor]:
+        records = self._read_json("calibrated_sensor.json")
+        result = []
+        for r in records:
+            t = r["translation"]
+            q = r["rotation"]
+            result.append(CalibratedSensor(
+                token=r["calibrated_sensor_token"],
+                channel=r["channel"],
+                modality="lidar" if r["camera_intrinsic"] is None else "camera",
+                translation=[t["x"], t["y"], t["z"]],
+                rotation=[q["qx"], q["qy"], q["qz"], q["qw"]],
+                camera_intrinsic=r["camera_intrinsic"],
+            ))
+        return result
+
+    def _load_ego_poses(self) -> list[EgoPose]:
+        records = self._read_json("ego_pose.json")
+        result = []
+        for r in records:
+            t = r["translation"]
+            q = r["rotation"]
+            result.append(EgoPose(
+                token=r["ego_pose_token"],
+                timestamp_us=r["timestamp_us"],
+                translation=[t["x"], t["y"], t["z"]],
+                rotation=[q["qx"], q["qy"], q["qz"], q["qw"]],
+            ))
+        result.sort(key=lambda ep: ep.timestamp_us)
+        return result
+
+    def _load_samples(self) -> list[Sample]:
+        records = self._read_json("sample.json")
+        result = []
+        for r in records:
+            result.append(Sample(
+                token=r["sample_token"],
+                timestamp_us=r["timestamp_us"],
+                is_keyframe=r["is_keyframe"],
+                prev=r["prev"] or "",
+                next=r["next"] or "",
+            ))
+        result.sort(key=lambda s: s.timestamp_us)
+        return result
+
+    def _load_sample_data(self) -> list[SampleData]:
+        records = self._read_json("sample_data.json")
+        result = []
+        for r in records:
+            result.append(SampleData(
+                token=r["sample_data_token"],
+                sample_token=r["sample_token"],
+                channel=r["channel"],
+                timestamp_us=r["timestamp_us"],
+                file_path=r["file_path"],
+                ego_pose_token=r["ego_pose_token"],
+                calibrated_sensor_token=r["calibrated_sensor_token"],
+                is_keyframe=r["is_keyframe"],
+                width=r.get("width"),
+                height=r.get("height"),
+                prev=r["prev"] or "",
+                next=r["next"] or "",
+            ))
+        return result
+
+    def _load_annotations(self) -> list[Annotation]:
+        records = self._read_json("annotation.json")
+        result = []
+        for r in records:
+            bbox = r["bbox_3d"]
+            t = bbox["translation"]
+            s = bbox["size"]
+            q = bbox["rotation"]
+            vel = r.get("velocity")
+            result.append(Annotation(
+                token=r["annotation_token"],
+                sample_token=r["sample_token"],
+                instance_token=r["instance_token"],
+                category=r["category"],
+                translation=[t["x"], t["y"], t["z"]],
+                size=[s["length"], s["width"], s["height"]],
+                rotation=[q["qx"], q["qy"], q["qz"], q["qw"]],
+                num_lidar_pts=r["num_lidar_pts"],
+                visibility=str(r["visibility"]) if r["visibility"] is not None else "",
+                velocity=[vel["vx"], vel["vy"], vel["vz"]] if vel else None,
+                attributes=r.get("attributes", []),
+                prev=r["prev"] or "",
+                next=r["next"] or "",
+                score=r.get("score"),
+            ))
+        return result
+
+    def _load_instances(self) -> list[Instance]:
+        records = self._read_json("instance.json")
+        return [
+            Instance(
+                token=r["instance_token"],
+                category=r["category"],
+                num_annotations=r["num_annotations"],
+                first_annotation_token=r["first_annotation_token"],
+                last_annotation_token=r["last_annotation_token"],
+            )
+            for r in records
+        ]
+
+    # --- Public API ---
+
+    @property
+    def clip_dir(self) -> Path:
+        return self._clip_dir
+
+    @property
+    def meta(self) -> ClipMeta:
+        return self._meta
+
+    @property
+    def samples(self) -> list[Sample]:
+        return self._samples
+
+    @property
+    def sample_data(self) -> list[SampleData]:
+        return self._sample_data
+
+    @property
+    def ego_poses(self) -> list[EgoPose]:
+        return self._ego_poses
+
+    @property
+    def calibrated_sensors(self) -> list[CalibratedSensor]:
+        return self._calibrated_sensors
+
+    @property
+    def annotations(self) -> list[Annotation]:
+        return self._annotations
+
+    @property
+    def instances(self) -> list[Instance]:
+        return self._instances
+
+    def get(self, token: str) -> Any:
+        """O(1) lookup by token across all entity types. Raises KeyError if not found."""
+        return self._token_index[token]
+
+    def sample_data_for_channel(self, channel: str) -> list[SampleData]:
+        """All sample_data for a channel, sorted by timestamp."""
+        return self._sd_by_channel.get(channel, [])
+
+    def sample_data_for_sample(self, sample_token: str) -> list[SampleData]:
+        """All sample_data records for a given sample (all channels at that timestamp)."""
+        return self._sd_by_sample.get(sample_token, [])
+
+    def annotations_for_sample(self, sample_token: str) -> list[Annotation]:
+        """All annotations for a given sample."""
+        return self._ann_by_sample.get(sample_token, [])
+
+    def load_point_cloud(self, sd: SampleData) -> np.ndarray:
+        """Load point cloud binary file as (N, C) float32 array.
+
+        Uses meta.sensors[channel].point_format to determine stride.
+        """
+        sensor_info = self._meta.sensors[sd.channel]
+        pf = sensor_info["point_format"]
+        num_fields = len(pf["fields"])
+
+        path = self._clip_dir / sd.file_path
+        raw = np.fromfile(str(path), dtype=np.float32)
+        return raw.reshape(-1, num_fields)
+
+    def load_image_path(self, sd: SampleData) -> Path:
+        """Return the absolute path to the image file (does not load pixels)."""
+        return self._clip_dir / sd.file_path

x4d_devkit/core/models.py

@@ -0,0 +1,106 @@
+"""Frozen dataclass models for X4D dataset entities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ClipMeta:
+    clip_id: str
+    schema_version: str
+    session_id: str
+    vehicle_id: str
+    capture_time_utc: str
+    duration_s: float
+    num_keyframes: int
+    num_sweeps: int
+    sensors: dict[str, dict[str, Any]]
+
+
+@dataclass(frozen=True)
+class CalibratedSensor:
+    token: str
+    channel: str
+    modality: str
+    translation: np.ndarray
+    rotation: np.ndarray
+    camera_intrinsic: dict[str, float] | None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "translation", np.asarray(self.translation, dtype=np.float64))
+        object.__setattr__(self, "rotation", np.asarray(self.rotation, dtype=np.float64))
+
+
+@dataclass(frozen=True)
+class EgoPose:
+    token: str
+    timestamp_us: int
+    translation: np.ndarray
+    rotation: np.ndarray
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "translation", np.asarray(self.translation, dtype=np.float64))
+        object.__setattr__(self, "rotation", np.asarray(self.rotation, dtype=np.float64))
+
+
+@dataclass(frozen=True)
+class Sample:
+    token: str
+    timestamp_us: int
+    is_keyframe: bool
+    prev: str
+    next: str
+
+
+@dataclass(frozen=True)
+class SampleData:
+    token: str
+    sample_token: str
+    channel: str
+    timestamp_us: int
+    file_path: str
+    ego_pose_token: str
+    calibrated_sensor_token: str
+    is_keyframe: bool
+    width: int | None
+    height: int | None
+    prev: str
+    next: str
+
+
+@dataclass(frozen=True)
+class Annotation:
+    token: str
+    sample_token: str
+    instance_token: str
+    category: str
+    translation: np.ndarray
+    size: np.ndarray
+    rotation: np.ndarray
+    num_lidar_pts: int
+    visibility: str
+    velocity: np.ndarray | None
+    attributes: list[str]
+    prev: str
+    next: str
+    score: float | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "translation", np.asarray(self.translation, dtype=np.float64))
+        object.__setattr__(self, "size", np.asarray(self.size, dtype=np.float64))
+        object.__setattr__(self, "rotation", np.asarray(self.rotation, dtype=np.float64))
+        if self.velocity is not None:
+            object.__setattr__(self, "velocity", np.asarray(self.velocity, dtype=np.float64))
+
+
+@dataclass(frozen=True)
+class Instance:
+    token: str
+    category: str
+    num_annotations: int
+    first_annotation_token: str
+    last_annotation_token: str

x4d_devkit/core/token.py

@@ -0,0 +1,26 @@
+"""Deterministic token generation for X4D dataset format.
+
+All tokens are md5(clip_id + ":" + discriminator), truncated to 16 hex chars.
+"""
+
+import hashlib
+
+
+def generate_token(clip_id: str, discriminator: str) -> str:
+    """Generate a deterministic 16-char hex token.
+
+    Args:
+        clip_id: The clip identifier (e.g. "20180724_n015_scene-0061_000").
+        discriminator: Type-specific suffix. Convention:
+            - sample:            str(timestamp_us)
+            - sample_data:       f"{channel}:{timestamp_us}"
+            - ego_pose:          f"ego:{timestamp_us}"
+            - calibrated_sensor: f"cs:{channel}"
+            - annotation:        f"ann:{sample_token}:{instance_token}"
+            - instance:          f"inst:{category}:{first_timestamp_us}"
+
+    Returns:
+        16-character lowercase hex string.
+    """
+    raw = f"{clip_id}:{discriminator}"
+    return hashlib.md5(raw.encode()).hexdigest()[:16]

x4d_devkit/core/transform.py

@@ -0,0 +1,159 @@
+"""SE3 transform utilities for X4D coordinate systems.
+
+Quaternion convention: [qx, qy, qz, qw] (X4D standard).
+Transform naming convention: dst_from_src (e.g. world_from_ego).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+def quat_to_rotation_matrix(qx: float, qy: float, qz: float, qw: float) -> np.ndarray:
+    """Convert [qx,qy,qz,qw] quaternion to 3x3 rotation matrix.
+
+    Normalizes the quaternion before conversion.
+    """
+    q = np.array([qx, qy, qz, qw], dtype=float)
+    q = q / np.linalg.norm(q)
+    x, y, z, w = q
+    return np.array(
+        [
+            [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
+            [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
+            [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
+        ]
+    )
+
+
+def rotation_matrix_to_quat(R: np.ndarray) -> tuple[float, float, float, float]:
+    """Convert 3x3 rotation matrix to (qx, qy, qz, qw) tuple."""
+    trace = R[0, 0] + R[1, 1] + R[2, 2]
+    if trace > 0:
+        s = 0.5 / np.sqrt(trace + 1.0)
+        w = 0.25 / s
+        x = (R[2, 1] - R[1, 2]) * s
+        y = (R[0, 2] - R[2, 0]) * s
+        z = (R[1, 0] - R[0, 1]) * s
+    elif R[0, 0] > R[1, 1] and R[0, 0] > R[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + R[0, 0] - R[1, 1] - R[2, 2])
+        w = (R[2, 1] - R[1, 2]) / s
+        x = 0.25 * s
+        y = (R[0, 1] + R[1, 0]) / s
+        z = (R[0, 2] + R[2, 0]) / s
+    elif R[1, 1] > R[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + R[1, 1] - R[0, 0] - R[2, 2])
+        w = (R[0, 2] - R[2, 0]) / s
+        x = (R[0, 1] + R[1, 0]) / s
+        y = 0.25 * s
+        z = (R[1, 2] + R[2, 1]) / s
+    else:
+        s = 2.0 * np.sqrt(1.0 + R[2, 2] - R[0, 0] - R[1, 1])
+        w = (R[1, 0] - R[0, 1]) / s
+        x = (R[0, 2] + R[2, 0]) / s
+        y = (R[1, 2] + R[2, 1]) / s
+        z = 0.25 * s
+    return (float(x), float(y), float(z), float(w))
+
+
+@dataclass(frozen=True)
+class Transform:
+    """SE3 rigid-body transform.
+
+    Naming convention: variable name should read as dst_from_src.
+    Example: world_from_ego = Transform(...) means p_world = T @ p_ego.
+    """
+
+    rotation: np.ndarray     # (3, 3) rotation matrix
+    translation: np.ndarray  # (3,)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "rotation", np.asarray(self.rotation, dtype=float))
+        object.__setattr__(self, "translation", np.asarray(self.translation, dtype=float))
+
+    @classmethod
+    def identity(cls) -> Transform:
+        return cls(rotation=np.eye(3), translation=np.zeros(3))
+
+    @classmethod
+    def from_quat(
+        cls,
+        translation: np.ndarray | list[float],
+        quat: np.ndarray | list[float],
+    ) -> Transform:
+        """Construct from translation (3,) and quaternion [qx, qy, qz, qw]."""
+        q = np.asarray(quat, dtype=float)
+        R = quat_to_rotation_matrix(q[0], q[1], q[2], q[3])
+        return cls(rotation=R, translation=np.asarray(translation, dtype=float))
+
+    @property
+    def inverse(self) -> Transform:
+        R_inv = self.rotation.T
+        t_inv = -R_inv @ self.translation
+        return Transform(rotation=R_inv, translation=t_inv)
+
+    def __matmul__(self, other: Transform) -> Transform:
+        """Compose transforms: (A @ B).apply(p) == A.apply(B.apply(p))."""
+        R = self.rotation @ other.rotation
+        t = self.rotation @ other.translation + self.translation
+        return Transform(rotation=R, translation=t)
+
+    def apply(self, points: np.ndarray) -> np.ndarray:
+        """Transform points (N, 3) or (3,) -> same shape."""
+        return (self.rotation @ points.T).T + self.translation
+
+    @property
+    def as_matrix(self) -> np.ndarray:
+        """Return (4, 4) homogeneous transformation matrix."""
+        M = np.eye(4)
+        M[:3, :3] = self.rotation
+        M[:3, 3] = self.translation
+        return M
+
+    @property
+    def quat(self) -> np.ndarray:
+        """Return quaternion as [qx, qy, qz, qw]."""
+        return np.array(rotation_matrix_to_quat(self.rotation))
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from x4d_devkit.core.loader import ClipLoader
+    from x4d_devkit.core.models import SampleData
+
+
+class TransformChain:
+    """Build coordinate transform chains from a loaded clip.
+
+    Composes sensor → ego → world transforms using calibration
+    and ego_pose data from ClipLoader.
+    """
+
+    def __init__(self, loader: ClipLoader) -> None:
+        self._loader = loader
+        self._cs_by_channel = {cs.channel: cs for cs in loader.calibrated_sensors}
+
+    def get_ego_from_sensor(self, channel: str) -> Transform:
+        """Get the static sensor-to-ego (base_link) transform for a channel."""
+        cs = self._cs_by_channel[channel]
+        return Transform.from_quat(cs.translation, cs.rotation)
+
+    def get_world_from_ego(self, ego_pose_token: str) -> Transform:
+        """Get the ego-to-world transform for a specific ego_pose."""
+        ep = self._loader.get(ego_pose_token)
+        return Transform.from_quat(ep.translation, ep.rotation)
+
+    def get_world_from_sensor(self, sd: SampleData) -> Transform:
+        """Get the full sensor-to-world transform for a sample_data record."""
+        return self.get_world_from_ego(sd.ego_pose_token) @ self.get_ego_from_sensor(sd.channel)
+
+    def transform_points_to_world(self, points: np.ndarray, sd: SampleData) -> np.ndarray:
+        """Transform points (N, 3) from sensor coordinates to world coordinates."""
+        return self.get_world_from_sensor(sd).apply(points)
+
+    def transform_points_to_sensor(self, points: np.ndarray, sd: SampleData) -> np.ndarray:
+        """Transform points (N, 3) from world coordinates to sensor coordinates."""
+        return self.get_world_from_sensor(sd).inverse.apply(points)

x4d_devkit/eval/__init__.py

@@ -0,0 +1,17 @@
+"""Evaluation layer for X4D dataset."""
+
+from x4d_devkit.eval.detection import (
+    DetectionConfig,
+    DetectionEval,
+    DetectionResult,
+    detzero_detection_config,
+    nusc_detection_config,
+)
+
+__all__ = [
+    "DetectionConfig",
+    "DetectionEval",
+    "DetectionResult",
+    "detzero_detection_config",
+    "nusc_detection_config",
+]