LiDAR Module¶

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

Lidar¶

class mimic_data_api.lidar.Lidar(*, id, name, extrinsics, intrinsics, trajectory, lidar_pcds_data, min_cut_off_range, use_for_training=True)[source]¶

Bases: BaseModel

Complete LiDAR sensor representation.

This class encapsulates all information about a LiDAR sensor including its calibration, intrinsic parameters, trajectory, and captured point cloud data.

id¶

Unique identifier for the LiDAR within the sensor suite.

Type:: int

name¶

Human-readable name for the LiDAR (e.g., “top_lidar”, “front_lidar”).

Type:: str

extrinsics¶

4x4 transformation matrix from sensor frame to vehicle frame.

Type:: SensorExtrinsic

intrinsics¶

Internal LiDAR parameters (FOV, resolution, range, etc.).

Type:: LidarIntrinsics

trajectory¶

Time-series of LiDAR poses in world coordinates.

Type:: WorldTrajectory

lidar_pcds_data¶

List of captured point clouds with their metadata.

Type:: list of LidarPointCloudData

min_cut_off_range¶

Minimum range threshold for ego vehicle removal. Points closer than this distance are typically from the ego vehicle and should be filtered out.

Type:: float

use_for_training¶

Whether this LiDAR stream should be used for model training. Defaults to True. Set to False to exclude this stream.

Type:: bool

Note

The coordinate frame convention is: - X-axis: Forward - Y-axis: Left - Z-axis: Up (FLU convention)

Example

>>> lidar = Lidar(
...     id=0,
...     name="velodyne_top",
...     extrinsics=np.eye(4),
...     intrinsics=intrinsics,
...     trajectory=trajectory,
...     lidar_pcds_data=[pcd_data],
...     min_cut_off_range=2.0
... )

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.

id: int¶

name: str¶

extrinsics: SensorExtrinsic¶

intrinsics: LidarIntrinsics¶

trajectory: WorldTrajectory¶

lidar_pcds_data: list[LidarPointCloudData]¶

min_cut_off_range: float¶

use_for_training: StrictBool¶

validate_timestamps_for_solid_state()[source]¶

Validate timestamp requirements for solid-state LiDARs.

Returns:: The validated LiDAR instance.
Return type:: Lidar

property data: list[LidarPointCloudData]¶

Alias for accessing point cloud data.

Returns:: The list of captured point clouds.
Return type:: list of LidarPointCloudData

__eq__(other)[source]¶

Check equality with another Lidar.

Performs deep comparison of all LiDAR attributes including calibration parameters, trajectory, and point cloud data.

Parameters:: other (object) – The object to compare against.
Returns:: True if LiDARs are equal, False otherwise.
Return type:: bool

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

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¶

class mimic_data_api.lidar.LidarIntrinsics(*, lidar_type, rotation_type, vertical_fov, horizontal_fov, horizontal_resolution, vertical_resolution, max_range, min_range, horizontal_beam_divergence=None, vertical_beam_divergence=None)[source]¶

Bases: BaseModel

Internal parameters for a LiDAR sensor.

Defines the sensing characteristics of a LiDAR including field of view, resolution, range limits, and beam properties.

lidar_type¶

Technology type of the LiDAR sensor.

Type:: {“rotating”, “solid-state”}

rotation_type¶

Rotation direction for rotating LiDARs (top-down view). Required if lidar_type is “rotating”.

Type:: {“clockwise”, “counter-clockwise”} or None

vertical_fov¶

Vertical field of view in radians.

Type:: float

horizontal_fov¶

Horizontal field of view in radians. Typically 2π for rotating LiDARs.

Type:: float

horizontal_resolution¶

Horizontal angular resolution in radians per point (the angular step between adjacent azimuth samples), not points per radian. For example, a sensor with 3600 points over a full 360-degree rotation should set horizontal_resolution = 2 * np.pi / 3600, equivalently np.deg2rad(0.1). Every first-party converter (mimic-wod, mimic-nuscene, mimic-kitti360, mimic-osdar23) uses this convention.

Type:: float

vertical_resolution¶

Vertical resolution specification (uniform or per-channel).

Type:: VerticalResolution

max_range¶

Maximum detection range in meters.

Type:: float

min_range¶

Minimum detection range in meters.

Type:: float

horizontal_beam_divergence¶

Horizontal laser beam divergence in radians. Optional.

Type:: float or None

vertical_beam_divergence¶

Vertical laser beam divergence in radians. Optional.

Type:: float or None

Raises:: ValueError – If lidar_type is “rotating” but rotation_type is not specified.

Example

>>> intrinsics = LidarIntrinsics(
...     lidar_type="rotating",
...     rotation_type="clockwise",
...     vertical_fov=0.7,  # ~40 degrees
...     horizontal_fov=2 * np.pi,  # 360 degrees
...     horizontal_resolution=0.002,
...     vertical_resolution=VerticalResolution(vertical_resolution=0.035),
...     max_range=120.0,
...     min_range=0.5,
...     horizontal_beam_divergence=0.003,
...     vertical_beam_divergence=0.003
... )

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.

lidar_type: LidarType¶

rotation_type: LidarRotationType | None¶

vertical_fov: float¶

horizontal_fov: float¶

horizontal_resolution: float¶

vertical_resolution: VerticalResolution¶

max_range: float¶

min_range: float¶

horizontal_beam_divergence: float | None¶

vertical_beam_divergence: float | None¶

validate_rotating_type()[source]¶

Validate that rotating LiDARs have a rotation type specified.

Returns:: The validated intrinsics instance.
Return type:: LidarIntrinsics
Raises:: ValueError – If lidar_type is “rotating” but rotation_type is None.

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

VerticalResolution¶

class mimic_data_api.lidar.VerticalResolution(*, vertical_resolution=None, elevation_channel_mapping=None)[source]¶

Bases: BaseModel

Vertical angular resolution specification for LiDAR sensors.

LiDAR sensors can specify vertical resolution in two ways: 1. A single uniform resolution value (radians per point, i.e. the angular

step between adjacent beams)

A per-channel elevation angle mapping (for sensors with discrete beam angles)

Exactly one of these must be provided.

vertical_resolution¶

Uniform vertical resolution in radians per point (angular step between adjacent beams), e.g. np.deg2rad(0.33) for a 0.33-degree step. Use this for sensors with continuous or uniform vertical spacing.

Type:: float or None

elevation_channel_mapping¶

Mapping from channel index (0 to N-1) to elevation angle in radians. Use this for sensors with discrete beam angles (e.g., Velodyne, Ouster).

Type:: dict[int, float] or None

Raises:: ValueError – If neither or both resolution specifications are provided.

Example

Uniform resolution:

>>> res = VerticalResolution(vertical_resolution=0.035)

Per-channel mapping (e.g., 4-beam LiDAR):

>>> res = VerticalResolution(
...     elevation_channel_mapping={
...         0: -0.26,  # -15 degrees
...         1: -0.09,  # -5 degrees
...         2: 0.09,   # +5 degrees
...         3: 0.26    # +15 degrees
...     }
... )

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.

Usage

Exactly one of vertical_resolution or elevation_channel_mapping must be provided:

# 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
    }
)

vertical_resolution: float | None¶

elevation_channel_mapping: dict[int, float] | None¶

only_one_of_vertical_resolution_or_elevation_channel_mapping()[source]¶

Validate that exactly one resolution specification is provided.

Returns:: The validated resolution instance.
Return type:: VerticalResolution
Raises:: ValueError – If neither or both specifications are provided.

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

LidarPointCloudData¶

class mimic_data_api.lidar.LidarPointCloudData(*, filepath, lidar_pcd=None, timestamp, egomotion_compensated, has_missing_points)[source]¶

Bases: BaseModel

Metadata and optional point cloud data for a single LiDAR scan.

This class stores information about individual point cloud captures, including file location, timestamp, and processing state.

filepath¶

Path to the point cloud file (PLY format).

Type:: str

lidar_pcd¶

Optional in-memory point cloud data. Not serialized to JSON.

Type:: LidarPointCloud or None

timestamp¶

Timestamp in seconds corresponding to the middle of the scan. For rotating LiDARs, this is the midpoint of the 360° rotation.

Type:: float

egomotion_compensated¶

True if the point cloud has been motion-compensated (unrolled) to account for vehicle motion during the scan.

Type:: bool

has_missing_points¶

True if the point cloud contains missing/invalid points (typically indicated by intensity = -1).

Type:: bool

Note

Point clouds should be stored in the sensor’s local coordinate frame (sensor referential), not world or vehicle coordinates.

Example

>>> pcd_data = LidarPointCloudData(
...     filepath="data/lidar/scan_000.ply",
...     timestamp=0.0,
...     egomotion_compensated=True,
...     has_missing_points=False
... )

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.

filepath: str¶

lidar_pcd: LidarPointCloud | None¶

timestamp: float¶

egomotion_compensated: bool¶

has_missing_points: bool¶

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

Type Aliases¶

mimic_data_api.lidar.LidarType¶

LiDAR sensor technology type.

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

mimic_data_api.lidar.LidarRotationType¶

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

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