x4d-devkit 0.14.3

X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets

x4d-devkit

X-4D dataset format SDK for autonomous driving — load, validate, evaluate, and convert datasets.

Installation

pip install x4d-devkit

With optional dependencies:

# NuScenes format converter
pip install x4d-devkit[converters]

# Platform API client
pip install x4d-devkit[client]

Quick Start

Connect to an X-4D platform

The CLI can authenticate with a bearer token passed explicitly, through environment variables, or from the user config written by x4d login.

x4d --base-url http://host:8000 --api-key <token> projects list
x4d --base-url http://host:8000 --api-key <token> clips list --project-id 1
x4d --base-url http://host:8000 --api-key <token> clips download --clip-ids clip_a,clip_b --output /data/x4d/clips

export X4D_BASE_URL=http://host:8000
export X4D_API_KEY=<token>
x4d projects list
x4d clips list --project-name nuscenes-mini --has-archive true --format json
x4d clips download --project-name nuscenes-mini --output /data/x4d/nuscenes-mini/clips --workers 8

x4d --base-url http://host:8000 login --username <user> --password <password>

login stores base_url and the returned access token in ~/.config/x4d/config.toml. Archive downloads go through the platform file proxy and extract standard X4D clip directories; training containers do not need database or MinIO access.

Load a clip

from x4d_devkit import ClipLoader

loader = ClipLoader("/path/to/clip")
print(loader.meta)

for sample in loader.samples:
    for sd in loader.sample_data_for_sample(sample.token):
        print(sd.channel, sd.file_path)

Coordinate frame transforms

Frames are real frame_id strings: any node in the calibration tree (e.g. "LIDAR_TOP", "base_link", "cam_front") plus the constant "clip_world" (the SLAM-anchored clip-local world). The legacy aliases "sensor", "ego", "world" are not accepted.

from x4d_devkit import ClipLoader
from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID

loader = ClipLoader("/path/to/clip")
sd = loader.sample_data_for_channel("LIDAR_TOP")[0]

# Load point cloud in different frames
pts_sensor = loader.load_point_cloud(sd)                                 # raw sensor (default)
pts_ego    = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id) # sensor → ego
pts_world  = loader.load_point_cloud(sd, frame=CLIP_WORLD_FRAME_ID)      # sensor → clip_world

# Get annotations transformed to clip-local world
anns_world = loader.annotations_for_sample(sample.token, frame=CLIP_WORLD_FRAME_ID)

# Or to a specific sensor's frame
anns_lidar = loader.annotations_for_sample(sample.token, frame="LIDAR_TOP")

# Get the transform matrix directly (sd is required when clip_world is involved)
T = loader.get_transform(loader.sensor_frame_id(sd), CLIP_WORLD_FRAME_ID, sd=sd)
pts_world = T.apply(pts_sensor[:, :3])  # or use T.as_matrix for 4x4

Validate a clip

x4d validate /path/to/clip

from x4d_devkit import validate_clip

report = validate_clip("/path/to/clip")
print(report)

Detection evaluation

from x4d_devkit import DetectionEval, DetectionConfig

config = DetectionConfig(
    class_names=["car", "pedestrian", "bicycle"],
    dist_thresholds=[0.5, 1.0, 2.0, 4.0],
)
evaluator = DetectionEval(config, gt_clips=[...], pred_clips=[...])
result = evaluator.evaluate()
print(f"mAP: {result.mAP:.3f}, NDS: {result.NDS:.3f}")

Convert from NuScenes

from x4d_devkit.converters import NuScenesConverter

converter = NuScenesConverter("/path/to/nuscenes")
converter.convert_scene("scene-0001", output_dir="/path/to/output")

Modules

Module	Description
core	Data models, token generation, coordinate transforms, clip loader
eval	Detection evaluation (mAP, TP metrics, NDS)
converters	Format converters (NuScenes → X4D)
validation	Clip structure and data validation
client	X-4D platform API client

License

Apache License 2.0