x4d-devkit 0.1.0__py3-none-any.whl

x4d_devkit/converters/nuscenes.py

@@ -0,0 +1,715 @@
+"""NuScenes → X4D format converter.
+
+Requires: pip install x4d-devkit[converters]
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from x4d_devkit.core.token import generate_token
+
+# --- Field mapping helpers ---
+
+
+def quat_wxyz_to_named(q: list[float]) -> dict[str, float]:
+    """Convert nuScenes [w,x,y,z] quaternion to X4D {qx,qy,qz,qw}."""
+    return {"qx": q[1], "qy": q[2], "qz": q[3], "qw": q[0]}
+
+
+def translation_to_named(t: list[float]) -> dict[str, float]:
+    """Convert [x,y,z] array to {x,y,z} dict."""
+    return {"x": t[0], "y": t[1], "z": t[2]}
+
+
+def size_wlh_to_named(size: list[float]) -> dict[str, float]:
+    """Convert nuScenes [w,l,h] to X4D {length,width,height}."""
+    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."""
+    if not matrix:
+        return None
+    return {
+        "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,
+    }
+
+
+def build_clip_id(date_captured: str, vehicle: str, scene_name: str) -> str:
+    """Build X4D clip_id from nuScenes log metadata.
+
+    Format: {YYYYMMDD}_{vehicle}_{scene_name}_000
+    """
+    date_str = date_captured.replace("-", "")
+    return f"{date_str}_{vehicle}_{scene_name}_000"
+
+
+# --- SE3 transform helpers (converter uses [w,x,y,z] internally) ---
+
+from x4d_devkit.core.transform import (
+    quat_to_rotation_matrix as _quat_xyzw_to_matrix,
+    rotation_matrix_to_quat as _matrix_to_quat_xyzw,
+)
+
+
+def quat_to_rotation_matrix(q: list[float]) -> np.ndarray:
+    """Convert [w,x,y,z] quaternion to 3x3 rotation matrix.
+
+    Thin wrapper: converts nuScenes [w,x,y,z] to X4D [qx,qy,qz,qw].
+    """
+    w, x, y, z = q[0], q[1], q[2], q[3]
+    return _quat_xyzw_to_matrix(x, y, z, w)
+
+
+def rotation_matrix_to_quat(R: np.ndarray) -> list[float]:
+    """Convert 3x3 rotation matrix to [w,x,y,z] quaternion (nuScenes convention)."""
+    qx, qy, qz, qw = _matrix_to_quat_xyzw(R)
+    return [qw, qx, qy, qz]
+
+
+def apply_se3(
+    R: np.ndarray, t: list[float] | np.ndarray, point: np.ndarray
+) -> np.ndarray:
+    """Apply SE3 transform: p' = R @ p + t."""
+    return R @ point + np.asarray(t)
+
+
+def invert_se3(
+    R: np.ndarray, t: list[float] | np.ndarray
+) -> tuple[np.ndarray, np.ndarray]:
+    """Invert SE3 transform. Returns (R_inv, t_inv)."""
+    R_inv = R.T
+    t_inv = -R_inv @ np.asarray(t)
+    return R_inv, t_inv
+
+
+def compose_se3(
+    R1: np.ndarray,
+    t1: list[float] | np.ndarray,
+    R2: np.ndarray,
+    t2: list[float] | np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compose two SE3 transforms: T1 @ T2. Returns (R, t)."""
+    R = R1 @ R2
+    t = R1 @ np.asarray(t2) + np.asarray(t1)
+    return R, t
+
+
+# --- Target sensor channels (skip radar) ---
+
+TARGET_CHANNELS = {
+    "CAM_FRONT",
+    "CAM_FRONT_LEFT",
+    "CAM_FRONT_RIGHT",
+    "CAM_BACK",
+    "CAM_BACK_LEFT",
+    "CAM_BACK_RIGHT",
+    "LIDAR_TOP",
+}
+
+LIDAR_POINT_FORMAT = {
+    "fields": ["x", "y", "z", "intensity", "ring_index"],
+    "types": ["float32", "float32", "float32", "float32", "float32"],
+    "bytes_per_point": 20,
+}
+
+
+class NuScenesConverter:
+    """Convert nuScenes scenes to X4D clip format."""
+
+    def __init__(self, dataroot: str, version: str, output_dir: str) -> None:
+        from nuscenes.nuscenes import NuScenes
+
+        self.dataroot = Path(dataroot)
+        self.version = version
+        self.output_dir = Path(output_dir)
+        self.nusc = NuScenes(version=version, dataroot=str(dataroot), verbose=False)
+
+        # Build lookup tables
+        self._sensor_by_token = {s["token"]: s for s in self.nusc.sensor}
+        self._cs_by_token = {c["token"]: c for c in self.nusc.calibrated_sensor}
+        self._log_by_token = {lg["token"]: lg for lg in self.nusc.log}
+        self._category_by_token = {c["token"]: c for c in self.nusc.category}
+        self._attribute_by_token = {a["token"]: a for a in self.nusc.attribute}
+
+    def _get_channel(self, calibrated_sensor_token: str) -> str:
+        """Get sensor channel name from calibrated_sensor_token."""
+        cs = self._cs_by_token[calibrated_sensor_token]
+        return self._sensor_by_token[cs["sensor_token"]]["channel"]
+
+    def _extract_metadata(self, scene: dict) -> tuple[str, dict]:
+        """Extract clip metadata from a scene. Returns (clip_id, meta_dict)."""
+        log = self._log_by_token[scene["log_token"]]
+        clip_id = build_clip_id(
+            date_captured=log["date_captured"],
+            vehicle=log["vehicle"],
+            scene_name=scene["name"],
+        )
+
+        # Collect target sensors from first sample
+        sensors_dict: dict[str, dict] = {}
+        sample_token = scene["first_sample_token"]
+        first_sample = self.nusc.get("sample", sample_token)
+        for channel, sd_token in first_sample["data"].items():
+            if channel not in TARGET_CHANNELS:
+                continue
+            sd = self.nusc.get("sample_data", sd_token)
+            cs = self._cs_by_token[sd["calibrated_sensor_token"]]
+            sensor = self._sensor_by_token[cs["sensor_token"]]
+            if sensor["modality"] == "lidar":
+                sensors_dict[channel] = {
+                    "modality": "lidar",
+                    "point_format": LIDAR_POINT_FORMAT,
+                }
+            elif sensor["modality"] == "camera":
+                sensors_dict[channel] = {
+                    "modality": "camera",
+                    "resolution": [sd["width"], sd["height"]],
+                }
+
+        # Count keyframes
+        keyframe_count = scene["nbr_samples"]
+
+        # Count sweeps
+        sweep_count = 0
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            for channel, sd_token in sample["data"].items():
+                if channel not in TARGET_CHANNELS:
+                    continue
+                sd = self.nusc.get("sample_data", sd_token)
+                cur = sd["next"]
+                while cur:
+                    next_sd = self.nusc.get("sample_data", cur)
+                    if next_sd["is_key_frame"]:
+                        break
+                    sweep_count += 1
+                    cur = next_sd["next"]
+            sample_token = sample["next"]
+
+        # Compute duration
+        first_sample = self.nusc.get("sample", scene["first_sample_token"])
+        last_sample = self.nusc.get("sample", scene["last_sample_token"])
+        duration_s = (last_sample["timestamp"] - first_sample["timestamp"]) / 1e6
+
+        meta = {
+            "clip_id": clip_id,
+            "session_id": log["logfile"],
+            "vehicle_id": log["vehicle"],
+            "capture_time_utc": f"{log['date_captured']}T00:00:00Z",
+            "duration_s": round(duration_s, 1),
+            "keyframe_count": keyframe_count,
+            "sweep_count": sweep_count,
+            "sensors": sensors_dict,
+            "route_tag": None,
+            "weather": None,
+            "time_of_day": None,
+            "scene_tags": [log.get("location", "unknown")],
+            "schema_version": "0.1",
+        }
+        return clip_id, meta
+
+    def _extract_calibrated_sensors(
+        self, scene: dict, clip_id: str
+    ) -> list[dict]:
+        """Extract calibrated sensor records for target channels."""
+        first_sample = self.nusc.get("sample", scene["first_sample_token"])
+        records = []
+        for channel, sd_token in first_sample["data"].items():
+            if channel not in TARGET_CHANNELS:
+                continue
+            sd = self.nusc.get("sample_data", sd_token)
+            cs = self._cs_by_token[sd["calibrated_sensor_token"]]
+            sensor = self._sensor_by_token[cs["sensor_token"]]
+
+            parent_frame = "base_link"
+            child_frame = channel.lower()
+
+            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,
+                }
+            )
+        return records
+
+    def _get_first_ego_pose_transform(self, scene: dict) -> tuple[np.ndarray, list]:
+        """Get the SE3 transform of the first keyframe's ego_pose (for localizing).
+
+        Uses the ego_pose with the earliest timestamp among all target-channel
+        keyframe sensor-data records in the first sample, so that the earliest
+        keyframe ego_pose maps exactly to the local origin.
+        """
+        first_sample = self.nusc.get("sample", scene["first_sample_token"])
+        earliest_ts = None
+        earliest_ep = None
+        for channel, sd_token in first_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
+        R = quat_to_rotation_matrix(earliest_ep["rotation"])
+        return R, earliest_ep["translation"]
+
+    def _extract_ego_poses(
+        self, scene: dict, clip_id: str
+    ) -> list[dict]:
+        """Extract all ego_poses for the scene (keyframe + sweep), in local coords."""
+        R_first, t_first = self._get_first_ego_pose_transform(scene)
+        R_inv, t_inv = invert_se3(R_first, t_first)
+
+        seen_ep_tokens: set[str] = set()
+        records: list[dict] = []
+
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            for channel, sd_token in sample["data"].items():
+                if channel not in TARGET_CHANNELS:
+                    continue
+                cur_sd_token = sd_token
+                while cur_sd_token:
+                    sd = self.nusc.get("sample_data", cur_sd_token)
+                    ep_token = sd["ego_pose_token"]
+                    if ep_token not in seen_ep_tokens:
+                        seen_ep_tokens.add(ep_token)
+                        ep = self.nusc.get("ego_pose", ep_token)
+                        R_global = quat_to_rotation_matrix(ep["rotation"])
+                        t_global = np.asarray(ep["translation"])
+
+                        R_local, t_local = compose_se3(R_inv, t_inv, R_global, t_global)
+                        q_local = rotation_matrix_to_quat(R_local)
+
+                        records.append(
+                            {
+                                "ego_pose_token": generate_token(
+                                    clip_id, f"ego:{ep['timestamp']}"
+                                ),
+                                "timestamp_us": ep["timestamp"],
+                                "translation": translation_to_named(t_local.tolist()),
+                                "rotation": quat_wxyz_to_named(q_local),
+                                "_original_token": ep_token,
+                                "_is_keyframe": sd["is_key_frame"],
+                            }
+                        )
+
+                    next_sd_token = sd["next"]
+                    if next_sd_token:
+                        next_sd = self.nusc.get("sample_data", next_sd_token)
+                        if next_sd["is_key_frame"]:
+                            break
+                    cur_sd_token = next_sd_token
+
+            sample_token = sample["next"]
+
+        return records
+
+    def _compute_velocity(self, ann_token: str) -> dict[str, float] | None:
+        """Compute velocity using centered difference (matches nuScenes box_velocity).
+
+        Returns {"vx": ..., "vy": ..., "vz": ...} in GLOBAL coordinates, or None.
+        """
+        ann = self.nusc.get("sample_annotation", ann_token)
+        has_prev = ann["prev"] != ""
+        has_next = ann["next"] != ""
+
+        if not has_prev and not has_next:
+            return None
+
+        if has_prev:
+            first = self.nusc.get("sample_annotation", ann["prev"])
+        else:
+            first = ann
+
+        if has_next:
+            last = self.nusc.get("sample_annotation", ann["next"])
+        else:
+            last = ann
+
+        pos_last = np.asarray(last["translation"])
+        pos_first = np.asarray(first["translation"])
+        pos_diff = pos_last - pos_first
+
+        time_last = 1e-6 * self.nusc.get("sample", last["sample_token"])["timestamp"]
+        time_first = 1e-6 * self.nusc.get("sample", first["sample_token"])["timestamp"]
+        time_diff = time_last - time_first
+
+        max_time_diff = 1.5
+        if has_next and has_prev:
+            max_time_diff *= 2
+
+        if time_diff > max_time_diff or time_diff == 0:
+            return None
+
+        vel = pos_diff / time_diff
+        if np.any(np.isnan(vel)):
+            return None
+        return {"vx": float(vel[0]), "vy": float(vel[1]), "vz": float(vel[2])}
+
+    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)
+
+        annotations: list[dict] = []
+        instance_anns: dict[str, list[dict]] = {}
+
+        sample_token_map: dict[str, str] = {}
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            new_token = generate_token(clip_id, str(sample["timestamp"]))
+            sample_token_map[sample_token] = new_token
+            sample_token = sample["next"]
+
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            new_sample_token = sample_token_map[sample_token]
+
+            for ann_token in sample["anns"]:
+                ann = self.nusc.get("sample_annotation", ann_token)
+                nusc_instance_token = ann["instance_token"]
+                category = self._category_by_token[
+                    self.nusc.get("instance", nusc_instance_token)["category_token"]
+                ]["name"]
+
+                t_global = np.asarray(ann["translation"])
+                t_local = 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)
+
+                attributes = [
+                    self._attribute_by_token[at]["name"]
+                    for at in ann["attribute_tokens"]
+                ]
+
+                visibility = (
+                    int(ann["visibility_token"]) if ann["visibility_token"] else None
+                )
+
+                # Compute velocity in global coords, then rotate to local
+                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])}
+                else:
+                    velocity = None
+
+                ann_record = {
+                    "sample_token": new_sample_token,
+                    "category": category,
+                    "bbox_3d": {
+                        "translation": translation_to_named(t_local.tolist()),
+                        "size": size_wlh_to_named(ann["size"]),
+                        "rotation": quat_wxyz_to_named(q_ann_local),
+                    },
+                    "num_lidar_pts": ann["num_lidar_pts"],
+                    "visibility": visibility,
+                    "velocity": velocity,
+                    "attributes": attributes,
+                    "prev": None,
+                    "next": None,
+                    "_nusc_instance_token": nusc_instance_token,
+                    "_nusc_ann_token": ann_token,
+                    "_timestamp_us": sample["timestamp"],
+                }
+
+                if nusc_instance_token not in instance_anns:
+                    instance_anns[nusc_instance_token] = []
+                instance_anns[nusc_instance_token].append(ann_record)
+                annotations.append(ann_record)
+
+            sample_token = sample["next"]
+
+        # Pass 2: Generate tokens and build prev/next chains
+        instances: list[dict] = []
+        for nusc_inst_token, anns in instance_anns.items():
+            anns.sort(key=lambda a: a["_timestamp_us"])
+            category = anns[0]["category"]
+            first_ts = anns[0]["_timestamp_us"]
+            inst_token = generate_token(clip_id, f"inst:{category}:{first_ts}")
+
+            ann_tokens = []
+            for ann in anns:
+                ann["instance_token"] = inst_token
+                ann["annotation_token"] = generate_token(
+                    clip_id, f"ann:{ann['sample_token']}:{inst_token}"
+                )
+                ann_tokens.append(ann["annotation_token"])
+
+            for i, ann in enumerate(anns):
+                ann["prev"] = ann_tokens[i - 1] if i > 0 else None
+                ann["next"] = ann_tokens[i + 1] if i < len(anns) - 1 else None
+
+            instances.append(
+                {
+                    "instance_token": inst_token,
+                    "category": category,
+                    "num_annotations": len(anns),
+                    "first_annotation_token": ann_tokens[0],
+                    "last_annotation_token": ann_tokens[-1],
+                }
+            )
+
+        for ann in annotations:
+            del ann["_nusc_instance_token"]
+            del ann["_nusc_ann_token"]
+            del ann["_timestamp_us"]
+
+        return annotations, instances
+
+    def _extract_samples(
+        self, scene: dict, clip_id: str
+    ) -> list[dict]:
+        """Extract sample (keyframe-only) records for the scene."""
+        records: list[dict] = []
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            records.append(
+                {
+                    "sample_token": generate_token(clip_id, str(sample["timestamp"])),
+                    "clip_id": clip_id,
+                    "timestamp_us": sample["timestamp"],
+                    "is_keyframe": True,
+                    "prev": None,
+                    "next": None,
+                    "_nusc_token": sample_token,
+                }
+            )
+            sample_token = sample["next"]
+
+        # Build prev/next chain
+        for i in range(len(records)):
+            if i > 0:
+                records[i]["prev"] = records[i - 1]["sample_token"]
+            if i < len(records) - 1:
+                records[i]["next"] = records[i + 1]["sample_token"]
+
+        return records
+
+    def _extract_sample_data(
+        self,
+        scene: dict,
+        clip_id: str,
+        ep_old_to_new: dict[str, str],
+    ) -> list[dict]:
+        """Extract all sample_data (keyframe + sweep) for target channels."""
+        # Build sample token mapping
+        sample_token_map: dict[str, str] = {}
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            sample_token_map[sample_token] = generate_token(
+                clip_id, str(sample["timestamp"])
+            )
+            sample_token = sample["next"]
+
+        # Build cs token mapping
+        cs_token_map: dict[str, str] = {}
+        first_sample = self.nusc.get("sample", scene["first_sample_token"])
+        for channel, sd_token in first_sample["data"].items():
+            if channel not in TARGET_CHANNELS:
+                continue
+            sd = self.nusc.get("sample_data", sd_token)
+            cs_token_map[sd["calibrated_sensor_token"]] = generate_token(
+                clip_id, f"cs:{channel}"
+            )
+
+        # Collect all sample_data per channel, then build prev/next
+        per_channel: dict[str, list[dict]] = {}
+
+        sample_token = scene["first_sample_token"]
+        while sample_token:
+            sample = self.nusc.get("sample", sample_token)
+            new_sample_token = sample_token_map[sample_token]
+
+            for channel, sd_token in sample["data"].items():
+                if channel not in TARGET_CHANNELS:
+                    continue
+                if channel not in per_channel:
+                    per_channel[channel] = []
+
+                # Walk from this keyframe sd through sweeps to next keyframe
+                cur_sd_token = sd_token
+                while cur_sd_token:
+                    sd = self.nusc.get("sample_data", cur_sd_token)
+                    ch = self._get_channel(sd["calibrated_sensor_token"])
+                    if ch != channel:
+                        break
+
+                    is_kf = sd["is_key_frame"]
+                    ts = sd["timestamp"]
+                    prefix = "samples" if is_kf else "sweeps"
+                    ext = ".bin" if ch == "LIDAR_TOP" else ".jpg"
+                    file_path = f"{prefix}/{ch}/{ts}{ext}"
+
+                    per_channel[channel].append(
+                        {
+                            "sample_data_token": generate_token(
+                                clip_id, f"{ch}:{ts}"
+                            ),
+                            "sample_token": new_sample_token,
+                            "ego_pose_token": ep_old_to_new[sd["ego_pose_token"]],
+                            "calibrated_sensor_token": cs_token_map[
+                                sd["calibrated_sensor_token"]
+                            ],
+                            "channel": ch,
+                            "file_path": file_path,
+                            "timestamp_us": ts,
+                            "is_keyframe": is_kf,
+                            "width": sd["width"],
+                            "height": sd["height"],
+                            "prev": None,
+                            "next": None,
+                            "_nusc_filename": sd["filename"],
+                        }
+                    )
+
+                    next_sd_token = sd["next"]
+                    if next_sd_token:
+                        next_sd = self.nusc.get("sample_data", next_sd_token)
+                        if next_sd["is_key_frame"]:
+                            break
+                    cur_sd_token = next_sd_token
+
+            sample_token = sample["next"]
+
+        # Build per-channel prev/next chains and flatten
+        all_records: list[dict] = []
+        for channel, records in per_channel.items():
+            records.sort(key=lambda r: r["timestamp_us"])
+            for i in range(len(records)):
+                if i > 0:
+                    records[i]["prev"] = records[i - 1]["sample_data_token"]
+                if i < len(records) - 1:
+                    records[i]["next"] = records[i + 1]["sample_data_token"]
+            all_records.extend(records)
+
+        return all_records
+
+    def convert_scene(self, scene_token: str) -> str:
+        """Convert a single nuScenes scene to an X4D clip directory.
+
+        Returns the clip_id.
+        """
+        scene = self.nusc.get("scene", scene_token)
+
+        # 1. Extract metadata
+        clip_id, meta = self._extract_metadata(scene)
+        clip_dir = self.output_dir / "clips" / clip_id
+
+        # 2. Extract calibrated sensors
+        cs_records = self._extract_calibrated_sensors(scene, clip_id)
+
+        # 3. Extract ego poses (local coords)
+        ego_poses = self._extract_ego_poses(scene, clip_id)
+        ep_old_to_new = {ep["_original_token"]: ep["ego_pose_token"] for ep in ego_poses}
+
+        # 4. Extract samples (keyframe only)
+        samples = self._extract_samples(scene, clip_id)
+
+        # 5. Extract sample_data (keyframe + sweep)
+        sample_data_records = self._extract_sample_data(scene, clip_id, ep_old_to_new)
+
+        # 6. Extract annotations + instances
+        annotations, instances = self._extract_annotations(scene, clip_id)
+
+        # 7. Create directory structure
+        clip_dir.mkdir(parents=True, exist_ok=True)
+        for channel in TARGET_CHANNELS:
+            (clip_dir / "samples" / channel).mkdir(parents=True, exist_ok=True)
+            (clip_dir / "sweeps" / channel).mkdir(parents=True, exist_ok=True)
+
+        # 8. Copy sensor files
+        for sd in sample_data_records:
+            src = self.dataroot / sd["_nusc_filename"]
+            dst = clip_dir / sd["file_path"]
+            if src.is_file():
+                shutil.copy2(src, dst)
+
+        # 9. Clean internal fields before writing JSON
+        for ep in ego_poses:
+            del ep["_original_token"]
+            del ep["_is_keyframe"]
+        for sd in sample_data_records:
+            del sd["_nusc_filename"]
+        for s in samples:
+            del s["_nusc_token"]
+
+        # 10. Write JSON files
+        self._write_json(clip_dir / "meta.json", meta)
+        self._write_json(clip_dir / "calibrated_sensor.json", cs_records)
+        self._write_json(clip_dir / "ego_pose.json", ego_poses)
+        self._write_json(clip_dir / "sample.json", samples)
+        self._write_json(clip_dir / "sample_data.json", sample_data_records)
+        self._write_json(clip_dir / "annotation.json", annotations)
+        self._write_json(clip_dir / "instance.json", instances)
+
+        return clip_id
+
+    def convert(
+        self,
+        scenes: list[str] | None = None,
+        workers: int = 0,
+    ) -> list[str]:
+        """Convert nuScenes scenes to X4D clips.
+
+        Args:
+            scenes: List of scene names to convert (e.g. ["scene-0061"]).
+                    None converts all scenes.
+            workers: Not yet implemented. Reserved for future multiprocessing.
+
+        Returns:
+            List of clip_ids created.
+        """
+        target_scenes = self.nusc.scene
+        if scenes:
+            scene_names = set(scenes)
+            target_scenes = [s for s in target_scenes if s["name"] in scene_names]
+
+        clip_ids = []
+        for scene in target_scenes:
+            clip_id = self.convert_scene(scene["token"])
+            clip_ids.append(clip_id)
+
+        return clip_ids
+
+    @staticmethod
+    def _write_json(path: Path, data: Any) -> None:
+        """Write data to JSON file with consistent formatting."""
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)