Scene Module¶

The scene module provides the top-level data structures for representing complete driving scenes.

Scene¶

class mimic_data_api.scene.Scene(*, ego_vehicle, actors, world_offset=None, background_pcd_paths=None, base_folderpath=None)[source]¶

Bases: BaseModel

Complete driving scene representation.

The Scene class is the top-level container for all data in a driving scenario. It includes the ego vehicle (with sensors and trajectory) and all detected/annotated actors in the environment.

This class serves as the primary interface for loading, saving, and manipulating scene data in the Data API.

ego_vehicle¶

The autonomous/recording vehicle with trajectory and sensors.

Type:: EgoVehicle

actors¶

List of all other objects (vehicles, pedestrians, cyclists, etc.) present in the scene.

Type:: list of Actor

world_offset¶

Constant (x, y, z) translation subtracted from every global object2world translation (e.g. world re-centering during preprocessing); add it back to recover the source world frame. None means no offset was applied.

Type:: list of float or None

Note

The scene data structure is designed for:

Serialization: Easy JSON export/import for data exchange
Simulation: Providing ground truth for rendering and replay
Analysis: Querying and filtering scene elements
Editing: Adding, removing, or modifying scene components

Example

Creating and serializing a scene:

>>> scene = Scene(
...     ego_vehicle=ego,
...     actors=[car_1, car_2, pedestrian_1]
... )
>>> # Serialize to JSON
>>> json_data = scene.model_dump_json(indent=2)
>>> # Load from JSON
>>> loaded_scene = Scene.model_validate_json(json_data)

Accessing scene components:

>>> # Get all camera data
>>> cameras = scene.ego_vehicle.sensors.cameras
>>> # Get all dynamic actors
>>> dynamic_actors = [a for a in scene.actors if a.dynamic]
>>> # Get ego trajectory timestamps
>>> timestamps = scene.ego_vehicle.trajectory.timestamps

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

ego_vehicle: EgoVehicle¶

actors: list[Actor]¶

world_offset: list[float] | None¶: (x, y, z) offset subtracted from global object2world translations; see class docstring.

background_pcd_paths: BackgroundPointCloudPaths | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

base_folderpath: str | None¶

EgoVehicle¶

class mimic_data_api.scene.EgoVehicle(*, trajectory, sensors)[source]¶

Bases: BaseModel

The autonomous or recording vehicle in the scene.

Represents the vehicle carrying the sensor suite, including its trajectory through the scene and all mounted sensors.

trajectory¶

Time-series of ego vehicle poses in world coordinates. Defines the vehicle’s position and orientation over time.

Type:: WorldTrajectory

sensors¶

Collection of all sensors mounted on the ego vehicle.

Type:: Sensors

Note

The ego vehicle’s trajectory defines the reference frame for sensor data alignment. All sensor extrinsics are defined relative to the vehicle body frame, and the trajectory transforms from body frame to world frame.

Coordinate conventions: - Vehicle Frame: X-forward, Y-left, Z-up (FLU) - World Frame: Typically ENU (East-North-Up) or local tangent plane

Example

>>> ego = EgoVehicle(
...     trajectory=WorldTrajectory(
...         timestamps=np.arange(0, 10, 0.1),
...         object2world=poses  # (100, 4, 4) array
...     ),
...     sensors=Sensors(cameras=[camera], lidars=[lidar])
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

trajectory: WorldTrajectory¶

sensors: Sensors¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Sensors¶

class mimic_data_api.scene.Sensors(*, cameras, lidars, radars=None)[source]¶

Bases: BaseModel

Collection of sensors mounted on the ego vehicle.

This class aggregates all perception sensors attached to the ego vehicle, providing a unified interface for accessing camera, LiDAR, and radar data.

cameras¶

List of camera sensors. At least one camera is required.

Type:: list of Camera

lidars¶

List of LiDAR sensors. At least one LiDAR is required.

Type:: list of Lidar

radars¶

Optional list of radar sensors. None if no radars are present.

Type:: list of Radar or None

Note

Every scene must contain at least one camera and one LiDAR. Radar sensors remain optional.

Example

>>> sensors = Sensors(
...     cameras=[front_cam, rear_cam, left_cam, right_cam],
...     lidars=[top_lidar, front_lidar],
...     radars=[front_radar, rear_radar]
... )
>>> print(f"Number of cameras: {len(sensors.cameras)}")
Number of cameras: 4

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cameras: list[Camera]¶

lidars: list[Lidar]¶

radars: list[Radar] | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].