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:

.. code-block:: python

    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:

.. code-block:: python

    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
^^^^^^^^^^^^^^^

.. code-block:: json

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

EgoVehicle
^^^^^^^^^^

.. code-block:: json

    {
      "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
^^^^^^

.. code-block:: json

    {
      "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
^^^^^

.. code-block:: json

    {
      "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
^^^^^

.. code-block:: json

    {
      "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
^^^^^

.. code-block:: json

    {
      "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
^^^^^^^^^^^^^^^

.. code-block:: json

    {
      "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:

.. code-block:: python

    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:

.. code-block:: python

    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()