Actor Module
============

.. module:: mimic_data_api.actor

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

Actor
-----

.. autoclass:: Actor
   :members:
   :undoc-members:
   :show-inheritance:

   .. rubric:: Actor Categories

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

   .. list-table::
      :widths: 20 80
      :header-rows: 1

      * - 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").

ActorDimensions
---------------

.. autoclass:: ActorDimensions
   :members:
   :undoc-members:
   :show-inheritance:

   .. rubric:: Common Dimensions

   Typical dimensions for different actor types:

   .. list-table::
      :widths: 25 25 25 25
      :header-rows: 1

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

Usage Examples
--------------

Creating a dynamic vehicle:

.. code-block:: python

    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:

.. code-block:: python

    # 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:

.. code-block:: python

    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")]