JSON Schema Reference¶

This page documents the JSON schema for scene data serialization.

Overview¶

The MIMIC Data API uses Pydantic for JSON serialization, which automatically handles:

Type conversion (NumPy arrays to nested lists)
Validation on deserialization
Optional field handling

Serialization¶

Export a scene to JSON:

from mimic_data_api import Scene

# Pretty-printed JSON
json_str = scene.model_dump_json(indent=2)

# Compact JSON
json_str = scene.model_dump_json()

# Save to file
with open("scene.json", "w") as f:
    f.write(scene.model_dump_json(indent=2))

Deserialization¶

Load a scene from JSON:

from mimic_data_api import Scene

# From string
scene = Scene.model_validate_json(json_str)

# From file
with open("scene.json", "r") as f:
    scene = Scene.model_validate_json(f.read())

Schema Structure¶

Top-Level Scene¶

{
  "ego_vehicle": { ... },
  "actors": [ ... ]
}

EgoVehicle¶

{
  "trajectory": {
    "timestamps": [0.0, 0.1, 0.2, ...],
    "object2world": [
      [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]],
      ...
    ],
    "linear_velocity": null,
    "angular_velocity": null
  },
  "sensors": {
    "cameras": [ ... ],
    "lidars": [ ... ],
    "radars": [ ... ]
  }
}

Camera¶

{
  "id": 1,
  "name": "front_camera",
  "camera_model": "pinhole",
  "intrinsics": {
    "fx": 1000.0,
    "fy": 1000.0,
    "cx": 640.0,
    "cy": 360.0,
    "skew": 0.0,
    "height": 720.0,
    "width": 1280.0
  },
  "distortion_parameters": {
    "p1": 0.0,
    "p2": 0.0,
    "k1": 0.0,
    "k2": 0.0,
    "k3": 0.0,
    "k4": 0.0,
    "k5": null,
    "k6": null
  },
  "extrinsics": [
    [1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]
  ],
  "trajectory": { ... },
  "images_data": [
    {
      "filepath": "camera/00000000.png",
      "timestamp": 0.0,
      "undistorded": true,
      "rolling_shutter": {
        "readout_time": 0.0,
        "readout_direction": "global"
      }
    }
  ]
}

Lidar¶

{
  "id": 1,
  "name": "top_lidar",
  "extrinsics": [ ... ],
  "intrinsics": {
    "lidar_type": "rotating",
    "rotation_type": "clockwise",
    "vertical_fov": 0.785,
    "horizontal_fov": 6.283,
    "horizontal_resolution": 0.01,
    "vertical_resolution": {
      "vertical_resolution": 0.01,
      "elevation_channel_mapping": null
    },
    "max_range": 100.0,
    "min_range": 0.1,
    "horizontal_beam_divergence": null,
    "vertical_beam_divergence": null
  },
  "trajectory": { ... },
  "lidar_pcds_data": [
    {
      "filepath": "lidar/00000000.ply",
      "timestamp": 0.0,
      "egomotion_compensated": true,
      "has_missing_points": false
    }
  ],
  "min_cut_off_range": 1.5
}

Radar¶

{
  "id": 1,
  "name": "front_radar",
  "extrinsics": [ ... ],
  "intrinsics": {
    "range": 200.0,
    "azimuth_fov": 1.047,
    "elevation_fov": 0.524,
    "azimuth_resolution": [[0.0, 0.01], [0.524, 0.02]],
    "elevation_resolution": null,
    "min_speed_resolution": -50.0,
    "max_speed_resolution": 50.0
  },
  "trajectory": { ... },
  "radar_pcds_data": [
    {
      "filepath": "radar/00000000.ply",
      "timestamp": 0.0
    }
  ]
}

Actor¶

{
  "id": 1,
  "name": "Vehicle_001",
  "dimensions": {
    "length": 4.5,
    "width": 2.0,
    "height": 1.5
  },
  "boxtype": "vehicle",
  "original_boxtype": "sedan",
  "dynamic": true,
  "trajectory": { ... },
  "description": "A sedan traveling in the adjacent lane",
  "original_id": null
}

WorldTrajectory¶

{
  "timestamps": [0.0, 0.1, 0.2],
  "object2world": [
    [
      [1.0, 0.0, 0.0, 0.0],
      [0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0],
      [0.0, 0.0, 0.0, 1.0]
    ],
    [
      [1.0, 0.0, 0.0, 1.0],
      [0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0],
      [0.0, 0.0, 0.0, 1.0]
    ],
    [
      [1.0, 0.0, 0.0, 2.0],
      [0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0],
      [0.0, 0.0, 0.0, 1.0]
    ]
  ],
  "linear_velocity": null,
  "angular_velocity": null
}

Validation¶

The Data API validates JSON on deserialization:

from mimic_data_api import Scene
from pydantic import ValidationError

try:
    scene = Scene.model_validate_json(json_str)
except ValidationError as e:
    print(f"Validation failed: {e}")

Common validation errors:

Timestamp mismatch: Image timestamps must match trajectory timestamps
Missing required fields: All non-optional fields must be present
Type errors: Values must match expected types
Constraint violations: e.g., negative timestamps, invalid file extensions

Programmatic Schema Access¶

Get the JSON schema programmatically:

from mimic_data_api import Scene, Camera, Actor
import json

# Get full scene schema
schema = Scene.model_json_schema()
print(json.dumps(schema, indent=2))

# Get individual class schemas
camera_schema = Camera.model_json_schema()
actor_schema = Actor.model_json_schema()