Actor Module¶

The actor module provides data structures for representing objects in a driving scene, including vehicles, pedestrians, cyclists, and static objects.

Actor¶

class mimic_data_api.actor.Actor(*, id, name=None, dimensions, boxtype, original_boxtype=None, dynamic, trajectory, description=None, original_id=None, actor_accumulated_pcd_filepath=None, actor_accumulated_pcd=None, thumbnail_filepath=None, initial_splat_filepath=None, lidar_source=-1, base_folderpath=None)[source]¶

Bases: BaseModel

Representation of an actor (object) in a driving scene.

An actor represents any object of interest in the scene that is not the ego vehicle, including other vehicles, pedestrians, cyclists, traffic signs, and other static or dynamic objects.

id¶

Unique identifier for the actor within the scene.

Type:: int

name¶

Optional human-readable name for the actor.

Type:: str or None

dimensions¶

Physical dimensions (length, width, height) of the actor’s bounding box.

Type:: ActorDimensions

boxtype¶

Standardized category of the actor for cross-dataset compatibility.

Type:: {“pedestrian”, “bicycle”, “sign”, “vehicle”, “unknown”}

original_boxtype¶

Original category label from the source dataset. Useful when the source dataset provides more granular labels (e.g., “sedan”, “SUV”, “truck”).

Type:: str or None

dynamic¶

Movement flag. True if the actor moves during the scene, False if static.

Type:: bool

trajectory¶

Time-series of poses representing the actor’s position and orientation over time in world coordinates.

Type:: WorldTrajectory

description¶

Optional free-text description of the actor for annotation purposes.

Type:: str or None

original_id¶

Original actor ID from the source dataset. Useful for tracking actors across scene edits or for referencing back to the original data. Some datasets (e.g. Waymo’s key.laser_object_id) use string IDs.

Type:: int, str, or None

Note

The boxtype field uses a standardized set of categories for consistency across different datasets. Use original_boxtype to preserve the more detailed labels from the source dataset.

Example

>>> actor = Actor(
...     id=42,
...     name="Pedestrian_001",
...     dimensions=ActorDimensions(length=0.5, width=0.5, height=1.7),
...     boxtype="pedestrian",
...     dynamic=True,
...     trajectory=trajectory,  # WorldTrajectory instance
...     description="Pedestrian crossing at intersection"
... )

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.

Actor Categories

The boxtype field uses standardized categories for cross-dataset compatibility:

Category	Description
`vehicle`	Cars, trucks, buses, motorcycles, and other motorized vehicles
`pedestrian`	People walking, standing, or running
`bicycle`	Cyclists and bicycles
`sign`	Traffic signs, signals, and road markers
`unknown`	Unclassified or ambiguous objects

Use original_boxtype to preserve more granular labels from source datasets (e.g., “sedan”, “SUV”, “pickup_truck”).

id: int¶

name: str | None¶

dimensions: ActorDimensions¶

boxtype: Literal['pedestrian', 'bicycle', 'sign', 'vehicle', 'unknown']¶

original_boxtype: str | None¶

dynamic: bool¶

trajectory: WorldTrajectory¶

description: str | None¶

original_id: int | str | None¶

actor_accumulated_pcd_filepath: str | None¶

actor_accumulated_pcd: ColorizedPointCloud | None¶

thumbnail_filepath: str | None¶

initial_splat_filepath: str | None¶

lidar_source: int¶

base_folderpath: str | None¶

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

ActorDimensions¶

class mimic_data_api.actor.ActorDimensions(*, length, width, height)[source]¶

Bases: BaseModel

Physical dimensions of an actor in 3D space.

This class represents the bounding box dimensions of an actor, typically used for collision detection, visualization, and spatial reasoning in driving scenarios.

length¶

Length of the actor in meters (along the forward axis).

Type:: float

width¶

Width of the actor in meters (along the lateral axis).

Type:: float

height¶

Height of the actor in meters (along the vertical axis).

Type:: float

Example

>>> dims = ActorDimensions(length=4.5, width=1.8, height=1.5)
>>> print(f"Vehicle footprint: {dims.length}m x {dims.width}m")
Vehicle footprint: 4.5m x 1.8m

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.

Common Dimensions

Typical dimensions for different actor types:

Type	Length (m)	Width (m)	Height (m)
Sedan	4.5	1.8	1.5
SUV	4.8	1.9	1.7
Truck	5.5	2.0	2.0
Pedestrian	0.5	0.5	1.7
Bicycle	1.8	0.6	1.7
Sign	0.1	0.6	2.0

length: float¶

width: float¶

height: float¶

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

Usage Examples¶

Creating a dynamic vehicle:

from mimic_data_api import Actor, ActorDimensions, WorldTrajectory
import numpy as np

# Vehicle trajectory (moving forward at 10 m/s)
n_frames = 100
timestamps = np.linspace(0, 10, n_frames)

# Create translation matrices
poses = np.stack([np.eye(4)] * n_frames)
for i, t in enumerate(timestamps):
    poses[i, 0, 3] = 10.0 * t  # x = 10 * t (forward motion)

vehicle = Actor(
    id=1,
    name="sedan_001",
    dimensions=ActorDimensions(length=4.5, width=1.8, height=1.5),
    boxtype="vehicle",
    original_boxtype="sedan",
    dynamic=True,
    trajectory=WorldTrajectory(
        timestamps=timestamps,
        object2world=poses
    ),
    description="Blue sedan traveling eastbound"
)

Creating a static sign:

# Static actor has single-frame trajectory
stop_sign = Actor(
    id=100,
    name="stop_sign_001",
    dimensions=ActorDimensions(length=0.1, width=0.6, height=2.0),
    boxtype="sign",
    dynamic=False,
    trajectory=WorldTrajectory(
        timestamps=np.array([0.0]),
        object2world=np.eye(4).reshape(1, 4, 4)
    )
)

Filtering actors by type:

from mimic_data_api import Scene

scene = Scene.model_validate_json(open("scene.json").read())

# Get all vehicles
vehicles = [a for a in scene.actors if a.boxtype == "vehicle"]

# Get all dynamic actors
dynamic = [a for a in scene.actors if a.dynamic]

# Get pedestrians and cyclists (vulnerable road users)
vru = [a for a in scene.actors if a.boxtype in ("pedestrian", "bicycle")]