Using Converted MIMIC Data

The MIMIC SDK provides a typed Python interface to converted scene metadata. A conversion produces a scene.json file plus sensor data files referenced by that scene. The JSON describes the scene; it does not contain the image or point-cloud payloads themselves.

Install the SDK

For the current TestPyPI release, use a clean Python 3.10 environment. The complete install, including dataset converters and the Waymo runtime note, is in the Downloads and Getting Started guides. To install only the core packages:

uv venv --python 3.10 .venv
source .venv/bin/activate
uv pip install \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    qvyon-mimic-filesystem qvyon-mimic-data-api

Load and Inspect a Scene

Use Scene.model_validate_json to parse and validate the scene against the SDK models. This checks the structure and field types, but does not verify that referenced files exist or that measurements use the correct units.

from pathlib import Path

from mimic_data_api.scene import Scene

scene_path = Path("/data/converted/scene.json")
scene = Scene.model_validate_json(scene_path.read_text())

print(f"Cameras: {len(scene.ego_vehicle.sensors.cameras)}")
print(f"LiDARs: {len(scene.ego_vehicle.sensors.lidars)}")
print(f"Actors: {len(scene.actors)}")

Check Referenced Files

Sensor file paths in a scene are relative to the converted scene directory in the standard converter output. Check those paths before moving or packaging the output:

from pathlib import Path

from mimic_data_api.scene import Scene

scene_dir = Path("/data/converted")
scene = Scene.model_validate_json((scene_dir / "scene.json").read_text())

referenced_files = [
    *(image.filepath for camera in scene.ego_vehicle.sensors.cameras for image in camera.images_data),
    *(cloud.filepath for lidar in scene.ego_vehicle.sensors.lidars for cloud in lidar.lidar_pcds_data),
]
missing_files = [path for path in referenced_files if not (scene_dir / path).is_file()]

if missing_files:
    raise FileNotFoundError(f"Missing {len(missing_files)} sensor files: {missing_files[:5]}")

Run the MIMIC Data Validation checks before sharing converted data. For conversion setup and dataset-specific requirements, see the MIMIC Data Converter guide.