LiDAR Module
============

.. module:: mimic_data_api.lidar

The lidar module provides data structures for representing LiDAR (Light Detection
and Ranging) sensors, including rotating and solid-state types.

Lidar
-----

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

.. note::

   ``Lidar.trajectory.object2world`` contains LiDAR-to-world poses. It is
   formed by composing the matching vehicle-to-world pose with
   ``Lidar.extrinsics`` (LiDAR-to-vehicle); it is not the raw ego trajectory.

.. important::

   ``use_for_training`` is a strict boolean and defaults to ``True``. Use
   ``False`` to exclude a LiDAR stream from training. ``None``/``null`` is not
   valid.

LidarIntrinsics
---------------

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

VerticalResolution
------------------

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

   .. rubric:: Usage

   Exactly one of ``vertical_resolution`` or ``elevation_channel_mapping`` must be provided:

   .. code-block:: python

       # Option 1: Uniform resolution
       res = VerticalResolution(vertical_resolution=0.035)

       # Option 2: Per-channel mapping (e.g., 64-beam LiDAR)
       res = VerticalResolution(
           elevation_channel_mapping={
               0: -0.436,   # -25 degrees
               1: -0.419,
               # ... more channels
               63: 0.262    # +15 degrees
           }
       )

LidarPointCloudData
-------------------

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

Type Aliases
------------

.. data:: LidarType

   LiDAR sensor technology type.

   - ``"rotating"``: Mechanical spinning LiDAR with 360° horizontal coverage
   - ``"solid-state"``: Non-mechanical LiDAR with limited horizontal FOV

.. data:: LidarRotationType

   Rotation direction for mechanical LiDAR sensors (top-down view).

   - ``"clockwise"``: Rotates clockwise
   - ``"counter-clockwise"``: Rotates counter-clockwise