# 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](../downloads.html) and [Getting Started](README.md) guides.
To install only the core packages:

```bash
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.

```python
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:

```python
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](validation-guide.md) checks before sharing
converted data. For conversion setup and dataset-specific requirements, see
the [MIMIC Data Converter](conversion-guide.md) guide.