"""
Actor Module
============
This module defines the data structures for representing actors (objects) in a driving scene,
including vehicles, pedestrians, bicycles, signs, and other objects.
Classes
-------
ActorDimensions
Physical dimensions of an actor (length, width, height).
Actor
Complete actor representation including identity, type, dimensions, and trajectory.
Example
-------
Creating an actor with a trajectory::
import numpy as np
from mimic_data_api.actor import Actor, ActorDimensions
from mimic_data_api.trajectory_numpy import WorldTrajectory
actor = Actor(
id=1,
name="Car_001",
dimensions=ActorDimensions(length=4.5, width=1.8, height=1.5),
boxtype="vehicle",
original_boxtype="sedan",
dynamic=True,
trajectory=WorldTrajectory(
timestamps=np.array([0.0, 0.1, 0.2]),
object2world=np.stack([np.eye(4)] * 3)
),
description="A sedan traveling in the adjacent lane"
)
"""
from typing import Literal
from pydantic import BaseModel, Field
from mimic_data_api.unstructured.pointclouds import ColorizedPointCloud
from mimic_data_api.trajectory_numpy import WorldTrajectory
[docs]
class ActorDimensions(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.
Attributes
----------
length : float
Length of the actor in meters (along the forward axis).
width : float
Width of the actor in meters (along the lateral axis).
height : float
Height of the actor in meters (along the vertical axis).
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
"""
length: float = Field(description="Length of the actor in meters")
width: float = Field(description="Width of the actor in meters")
height: float = Field(description="Height of the actor in meters")
[docs]
class Actor(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.
Attributes
----------
id : int
Unique identifier for the actor within the scene.
name : str or None
Optional human-readable name for the actor.
dimensions : ActorDimensions
Physical dimensions (length, width, height) of the actor's bounding box.
boxtype : {"pedestrian", "bicycle", "sign", "vehicle", "unknown"}
Standardized category of the actor for cross-dataset compatibility.
original_boxtype : str or None
Original category label from the source dataset. Useful when the source
dataset provides more granular labels (e.g., "sedan", "SUV", "truck").
dynamic : bool
Movement flag. ``True`` if the actor moves during the scene,
``False`` if static.
trajectory : WorldTrajectory
Time-series of poses representing the actor's position and orientation
over time in world coordinates.
description : str or None
Optional free-text description of the actor for annotation purposes.
original_id : int, str, or None
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.
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"
... )
"""
id: int
name: str | None = None
dimensions: ActorDimensions
boxtype: Literal["pedestrian", "bicycle", "sign", "vehicle", "unknown"]
original_boxtype: str | None = Field(
default=None,
description="Original boxtype from the source dataset, if available. Can be helpful when original dataset has more complete set of labels.",
)
dynamic: bool = Field(
description="False if actor is static (not moving), True if static"
)
trajectory: WorldTrajectory
description: str | None = None
original_id: int | str | None = Field(
description="Original actor id from the dataset. Useful when identifying across scene edits. "
"Accepts str for datasets with non-integer IDs (e.g. Waymo's key.laser_object_id).",
default=None,
)
actor_accumulated_pcd_filepath: str | None = Field(default=None)
actor_accumulated_pcd: ColorizedPointCloud | None = Field(
default=None, exclude=True
)
thumbnail_filepath: str | None = Field(default=None)
initial_splat_filepath: str | None = Field(default=None)
lidar_source: int = Field(
default=-1,
description=(
"ID of another actor to use as the lidar source for this actor. "
"-1 means the source is selected automatically at runtime."
),
)
base_folderpath: str | None = Field(
default=None,
exclude=True,
description=(
"Path where the scene.json file is loaded from. "
"This is helpful for resolving relative paths from unstructured data."
),
)