Scene API

class py123d.api.SceneAPI

Base class for all scene APIs. The scene API provides access to all data modalities at in a scene.

Public Data Attributes:

log_metadata	The LogMetadata of the scene.
scene_metadata	The SceneMetadata of the scene.
dataset	The dataset name from the log metadata.
split	The data split name from the log metadata.
location	The location from the log metadata.
log_name	The log name from the log metadata.
scene_uuid	The UUID of the scene.
number_of_iterations	The number of iterations in the scene (includes current frame + future).
number_of_history_iterations	The number of history iterations in the scene.
available_camera_ids	List of available camera IDs.
available_camera_names	List of available camera names.
available_lidar_ids	List of available LidarID.
available_lidar_names	List of available Lidar names.

Public Methods:

get_scene_metadata()	Returns the SceneMetadata of the scene.
get_log_metadata()	Returns the LogMetadata of the scene.
get_timestamp_at_iteration(iteration)	Returns the Timestamp at a given iteration.
get_all_iteration_timestamps([include_history])	Returns all sync timestamps for the current scene.
get_scene_timestamp_boundaries([include_history])	Returns the first and last sync timestamps of the scene.
get_map_metadata()	Returns the MapMetadata of the scene, if available.
get_map_api()	Returns the MapAPI of the scene, if available.
get_all_modality_metadatas()	Returns all modality metadatas found in the log directory.
get_modality_metadata(modality_type[, ...])	Returns the metadata for a specific modality.
get_all_modality_timestamps(modality_type[, ...])	Returns all timestamps for a specific modality within the scene range.
get_modality_at_iteration(iteration, ...[, ...])	Returns the modality data at a given iteration, if available.
get_modality_at_timestamp(timestamp, ...[, ...])	Returns the modality data at a given timestamp, if available.
get_ego_state_se3_metadata()	Returns the EgoStateSE3Metadata of the ego vehicle, if available.
get_all_ego_state_se3_timestamps([...])	Returns all ego state timestamps within the current scene.
get_ego_state_se3_at_iteration(iteration)	Returns the EgoStateSE3 at a given iteration, if available.
get_ego_state_se3_at_timestamp(timestamp[, ...])	Returns the EgoStateSE3 at a given timestamp, if available.
get_box_detections_se3_metadata()	Returns the BoxDetectionsSE3Metadata of the scene, if available.
get_all_box_detections_se3_timestamps([...])	Returns all box detection timestamps within the current scene.
get_box_detections_se3_at_iteration(iteration)	Returns the BoxDetectionsSE3 at a given iteration, if available.
get_box_detections_se3_at_timestamp(timestamp)	Returns the BoxDetectionsSE3 at a given timestamp, if available.
get_traffic_light_detections_metadata()	Returns the TrafficLightDetectionsMetadata of the scene, if available.
get_all_traffic_light_detections_timestamps([...])	Returns all traffic light detection timestamps within the current scene.
get_traffic_light_detections_at_iteration(...)	Returns the TrafficLightDetections at a given iteration,
get_traffic_light_detections_at_timestamp(...)
get_camera_metadatas()	Returns per-camera metadata for all cameras in the scene.
get_all_camera_timestamps(camera_id[, ...])	Returns all camera timestamps within the current scene.
get_camera_at_iteration(iteration, camera_id)	Returns a Camera at a given iteration, if available.
get_camera_at_timestamp(timestamp, camera_id)	Returns a Camera at a given timestamp, if available.
get_lidar_metadatas()	Returns per-lidar metadata, if available.
get_all_lidar_timestamps(lidar_id[, ...])	Returns all lidar start timestamps within the current scene.
get_lidar_at_iteration(iteration, lidar_id)	Returns the Lidar of a given LidarID at a given iteration, if available.
get_lidar_at_timestamp(timestamp, lidar_id)	Returns the Lidar of a given LidarID at a given timestamp, if available.
get_all_custom_modality_metadatas()	Returns the metadata for all custom modalities in the scene, keyed by modality ID.
get_all_custom_modality_timestamps(modality_id)	Returns all custom modality timestamps within the current scene.
get_custom_modality_at_iteration(iteration, ...)	Returns the CustomModality with the given ID at a given iteration,
get_custom_modality_at_timestamp(timestamp, ...)	Returns the CustomModality with the given ID at a given timestamp,

---

abstractmethod get_scene_metadata()

Returns the SceneMetadata of the scene.

Return type:

SceneMetadata

Returns:

The scene metadata.

abstractmethod get_log_metadata()

Returns the LogMetadata of the scene.

Return type:

LogMetadata

Returns:

The log metadata.

abstractmethod get_timestamp_at_iteration(iteration)

Returns the Timestamp at a given iteration.

Parameters:

iteration (int) – The iteration to get the timestamp for.

Return type:

Timestamp

Returns:

The timestamp at the given iteration.

abstractmethod get_all_iteration_timestamps(include_history=False)

Returns all sync timestamps for the current scene.

Parameters:

include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

List of timestamps, one per iteration in the scene.

abstractmethod get_scene_timestamp_boundaries(include_history=False)

Returns the first and last sync timestamps of the scene.

Parameters:

include_history (bool) – If True, extend the range to include history iterations.

Return type:

Tuple[Timestamp, Timestamp]

Returns:

Tuple of (first_timestamp, last_timestamp).

abstractmethod get_map_metadata()

Returns the MapMetadata of the scene, if available.

Return type:

Optional[MapMetadata]

Returns:

The map metadata, or None if not available.

abstractmethod get_map_api()

Returns the MapAPI of the scene, if available.

Return type:

Optional[MapAPI]

Returns:

The map API, or None if not available.

abstractmethod get_all_modality_metadatas()

Returns all modality metadatas found in the log directory.

Return type:

Dict[str, BaseModalityMetadata]

Returns:

Mapping of modality key to its metadata.

abstractmethod get_modality_metadata(modality_type, modality_id=None)

Returns the metadata for a specific modality.

Parameters:

• modality_type (Union[str, ModalityType]) – The type of the modality.

• modality_id (Union[str, SerialIntEnum, None]) – The ID of the modality, if applicable.

Return type:

Optional[BaseModalityMetadata]

Returns:

The modality metadata, or None if not found.

abstractmethod get_all_modality_timestamps(modality_type, modality_id=None, include_history=False)

Returns all timestamps for a specific modality within the scene range.

Parameters:

• modality_type (Union[str, ModalityType]) – The modality type as a string or ModalityType.

• modality_id (Union[str, SerialIntEnum, None]) – Optional modality id (e.g. sensor id).

• include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

List of timestamps, empty if the modality is not present.

abstractmethod get_modality_at_iteration(iteration, modality_type, modality_id=None, **kwargs)

Returns the modality data at a given iteration, if available.

Parameters:

• iteration (int) – The iteration to get the modality data for.

• modality_type (Union[str, ModalityType]) – The modality type as a string or ModalityType.

• modality_id (Union[str, SerialIntEnum, None]) – Optional modality id (e.g. sensor id).

Return type:

Optional[BaseModality]

Returns:

The modality data at the given iteration, or None if not available.

abstractmethod get_modality_at_timestamp(timestamp, modality_type, modality_id=None, criteria='exact', **kwargs)

Returns the modality data at a given timestamp, if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the modality data for, as a Timestamp object or integer microseconds.

• modality_type (Union[str, ModalityType]) – The modality type as a string or ModalityType.

• modality_id (Union[str, SerialIntEnum, None]) – Optional modality id (e.g. sensor id).

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

Return type:

Optional[BaseModality]

Returns:

The modality data at the given timestamp, or None if not available.

get_ego_state_se3_metadata()

Returns the EgoStateSE3Metadata of the ego vehicle, if available.

Return type:

Optional[EgoStateSE3Metadata]

Returns:

The ego metadata, or None if not available.

get_all_ego_state_se3_timestamps(include_history=False)

Returns all ego state timestamps within the current scene.

Parameters:

include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All ego state timestamps in the scene, ordered by time.

get_ego_state_se3_at_iteration(iteration)

Returns the EgoStateSE3 at a given iteration, if available.

Parameters:

iteration (int) – The iteration to get the ego state for.

Return type:

Optional[EgoStateSE3]

Returns:

The ego state at the given iteration, or None if not available.

get_ego_state_se3_at_timestamp(timestamp, criteria='exact')

Returns the EgoStateSE3 at a given timestamp, if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the ego state for, as a Timestamp object or integer microseconds.

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

Return type:

Optional[EgoStateSE3]

Returns:

The ego state at the given timestamp, or None if not available.

get_box_detections_se3_metadata()

Returns the BoxDetectionsSE3Metadata of the scene, if available.

Return type:

Optional[BoxDetectionsSE3Metadata]

Returns:

The box detection metadata, or None if not available.

get_all_box_detections_se3_timestamps(include_history=False)

Returns all box detection timestamps within the current scene.

Parameters:

include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All box detection timestamps in the scene, ordered by time.

get_box_detections_se3_at_iteration(iteration)

Returns the BoxDetectionsSE3 at a given iteration, if available.

Parameters:

iteration (int) – The iteration to get the box detections for.

Return type:

Optional[BoxDetectionsSE3]

Returns:

The box detections at the given iteration, or None if not available.

get_box_detections_se3_at_timestamp(timestamp, criteria='exact')

Returns the BoxDetectionsSE3 at a given timestamp, if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the box detections for, as a Timestamp object or integer microseconds.

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

Return type:

Optional[BoxDetectionsSE3]

Returns:

The box detections at the given timestamp, or None if not available.

get_traffic_light_detections_metadata()

Returns the TrafficLightDetectionsMetadata of the scene, if available.

Return type:

Optional[TrafficLightDetectionsMetadata]

Returns:

The traffic light detection metadata, or None if not available.

get_all_traffic_light_detections_timestamps(include_history=False)

Returns all traffic light detection timestamps within the current scene.

Parameters:

include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All traffic light detection timestamps in the scene, ordered by time.

get_traffic_light_detections_at_iteration(iteration)

Returns the TrafficLightDetections at a given iteration,

if available.

Parameters:

iteration (int) – The iteration to get the traffic light detections for.

Return type:

Optional[TrafficLightDetections]

Returns:

The traffic light detections at the given iteration, or None if not available.

get_traffic_light_detections_at_timestamp(timestamp, criteria='exact')

Return type:

Optional[TrafficLightDetections]

Parameters:

• timestamp (Timestamp | int)

• criteria (Literal['exact', 'nearest', 'forward', 'backward'])

get_camera_metadatas()

Returns per-camera metadata for all cameras in the scene.

Return type:

Dict[CameraID, BaseCameraMetadata]

Returns:

A dictionary mapping camera IDs to their metadata.

get_all_camera_timestamps(camera_id, include_history=False)

Returns all camera timestamps within the current scene.

Parameters:

• camera_id (CameraID) – The camera ID.

• include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All camera timestamps in the scene, ordered by time.

get_camera_at_iteration(iteration, camera_id, scale=None)

Returns a Camera at a given iteration, if available.

Parameters:

• iteration (int) – The iteration to get the camera for.

• camera_id (CameraID) – The camera ID.

• scale (Optional[int]) – Optional downscale denominator, e.g. 2 for half size, 4 for quarter size.

Return type:

Optional[Camera]

Returns:

The camera, or None if not available.

get_camera_at_timestamp(timestamp, camera_id, criteria='exact', scale=None)

Returns a Camera at a given timestamp, if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the camera for, as a Timestamp object or integer microseconds.

• camera_id (CameraID) – The camera ID.

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

• scale (Optional[int]) – Optional downscale denominator, e.g. 2 for half size, 4 for quarter size.

Return type:

Optional[Camera]

Returns:

The camera, or None if not available.

get_lidar_metadatas()

Returns per-lidar metadata, if available.

Return type:

Dict[LidarID, LidarMetadata]

Returns:

The lidar metadatas, or None if not available.

get_all_lidar_timestamps(lidar_id, include_history=False)

Returns all lidar start timestamps within the current scene.

Parameters:

• lidar_id (LidarID) – The LidarID of the Lidar.

• include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All lidar start timestamps in the scene, ordered by time.

get_lidar_at_iteration(iteration, lidar_id)

Returns the Lidar of a given LidarID at a given iteration, if available.

Parameters:

• iteration (int) – The iteration to get the Lidar for.

• lidar_id (LidarID) – The LidarID of the Lidar.

Return type:

Optional[Lidar]

Returns:

The Lidar, or None if not available.

get_lidar_at_timestamp(timestamp, lidar_id, criteria='exact')

Returns the Lidar of a given LidarID at a given timestamp, if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the Lidar for, as a Timestamp object or integer microseconds.

• lidar_id (LidarID) – The LidarID of the Lidar.

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

Return type:

Optional[Lidar]

Returns:

The Lidar, or None if not available.

get_all_custom_modality_metadatas()

Returns the metadata for all custom modalities in the scene, keyed by modality ID.

Return type:

Dict[str, CustomModalityMetadata]

Returns:

A dictionary of custom modality metadata, keyed by modality ID.

get_all_custom_modality_timestamps(modality_id, include_history=False)

Returns all custom modality timestamps within the current scene.

Parameters:

• modality_id (str) – The ID of the custom modality.

• include_history (bool) – If True, include history iterations before the scene start.

Return type:

List[Timestamp]

Returns:

All custom modality timestamps in the scene, ordered by time.

get_custom_modality_at_iteration(iteration, modality_id)

Returns the CustomModality with the given ID at a given iteration,

if available.

Parameters:

• iteration (int) – The iteration to get the custom modality for.

• modality_id (str) – The ID of the custom modality (e.g. "route", "predictions").

Return type:

Optional[CustomModality]

Returns:

The custom modality, or None if not available.

get_custom_modality_at_timestamp(timestamp, modality_id, criteria='exact')

Returns the CustomModality with the given ID at a given timestamp,

if available.

Parameters:

• timestamp (Union[Timestamp, int]) – The timestamp to get the custom modality for, as a Timestamp object or integer microseconds.

• modality_id (str) – The ID of the custom modality (e.g. "route", "predictions").

• criteria (Literal['exact', 'nearest', 'forward', 'backward']) – Criteria for matching the timestamp if an exact match is not found. One of: - “exact”: Only return data if an exact timestamp match is found. - “nearest”: Return data from the nearest timestamp. - “forward”: Return data from the nearest timestamp that is greater than or equal to the requested timestamp. - “backward”: Return data from the nearest timestamp that is less than or equal to the requested timestamp.

Return type:

Optional[CustomModality]

Returns:

The custom modality, or None if not available.

property log_metadata: LogMetadata

The LogMetadata of the scene.

property scene_metadata: SceneMetadata

The SceneMetadata of the scene.

property dataset: str

The dataset name from the log metadata.

property split: str

The data split name from the log metadata.

property location: str | None

The location from the log metadata.

property log_name: str

The log name from the log metadata.

property scene_uuid: str

The UUID of the scene.

property number_of_iterations: int

The number of iterations in the scene (includes current frame + future).

property number_of_history_iterations: int

The number of history iterations in the scene.

property available_camera_ids: List[CameraID]

List of available camera IDs.

property available_camera_names: List[str]

List of available camera names.

property available_lidar_ids: List[LidarID]

List of available LidarID.

property available_lidar_names: List[str]

List of available Lidar names.