Core Types¶

Enumerations¶

class osi_utilities._types.MessageType(*values)[source]¶

Bases: str, Enum

OSI top-level message types.

UNKNOWN = 'Unknown'¶

GROUND_TRUTH = 'GroundTruth'¶

SENSOR_DATA = 'SensorData'¶

SENSOR_VIEW = 'SensorView'¶

SENSOR_VIEW_CONFIGURATION = 'SensorViewConfiguration'¶

HOST_VEHICLE_DATA = 'HostVehicleData'¶

TRAFFIC_COMMAND = 'TrafficCommand'¶

TRAFFIC_COMMAND_UPDATE = 'TrafficCommandUpdate'¶

TRAFFIC_UPDATE = 'TrafficUpdate'¶

MOTION_REQUEST = 'MotionRequest'¶

STREAMING_UPDATE = 'StreamingUpdate'¶

class osi_utilities._types.TraceFileFormat(*values)[source]¶

Bases: Enum

Trace file format categories.

SINGLE_CHANNEL = 1¶

MULTI_CHANNEL = 2¶

Data Classes¶

class osi_utilities._types.ReadResult(message, message_type, channel_name='', status=ReadStatus.OK, error_message='')[source]¶

Bases: object

Result of reading a single message from a trace file.

Parameters:

message (Message | None)
message_type (MessageType)
channel_name (str)
status (ReadStatus)
error_message (str)

message: Message | None¶

message_type: MessageType¶

channel_name: str = ''¶

status: ReadStatus = 'ok'¶

error_message: str = ''¶

class osi_utilities.api.types.ChannelSpecification(path, message_type=None, topic=None, metadata=<factory>)[source]¶

Bases: object

Immutable specification for an OSI channel within a trace file.

Parameters:

path (Path)
message_type (MessageType | str | None)
topic (str | None)
metadata (Mapping[str, str])

path: Path¶: Path to the trace file.

message_type: MessageType | str | None = None¶: OSI message type (normalized to MessageType if provided).

topic: str | None = None¶: Channel topic name (MCAP only).

metadata: Mapping[str, str]¶: Additional channel metadata.

property trace_file_format: TraceFileFormat¶: Determine the trace file format from the file extension.

property autodetected_message_type: MessageType | None¶: Best-effort inferred message type from filename, without mutating this instance.

with_autodetected_message_type()[source]¶

Return a specification with auto-detected message type when possible.

If message_type is already set or cannot be inferred, returns self unchanged.

Return type:: ChannelSpecification

with_autofilled_topic()[source]¶

Return a specification with topic set to filename stem if missing.

Return type:: ChannelSpecification

exists()[source]¶

Check if the file at path exists.

Return type:: bool

with_message_type(message_type)[source]¶

Return a new ChannelSpecification with a different message type.

Parameters:: message_type (MessageType | str)
Return type:: ChannelSpecification

with_topic(topic)[source]¶

Return a new ChannelSpecification with a different topic.

Parameters:: topic (str)
Return type:: ChannelSpecification

with_path(path)[source]¶

Return a new ChannelSpecification with a different path.

Parameters:: path (Path | str)
Return type:: ChannelSpecification

with_metadata(metadata)[source]¶

Return a new ChannelSpecification with replaced metadata.

Parameters:: metadata (Mapping[str, str])
Return type:: ChannelSpecification

with_metadata_updates(updates)[source]¶

Return a new ChannelSpecification with metadata updated by key.

Parameters:: updates (Mapping[str, str])
Return type:: ChannelSpecification

with_metadata_entry(key, value)[source]¶

Return a new ChannelSpecification with one metadata key updated.

Parameters:

key (str)
value (str)

Return type:

ChannelSpecification

with_trace_file_format(format)[source]¶

Return a new ChannelSpecification with a different file extension.

Parameters:: format (TraceFileFormat)
Return type:: ChannelSpecification

Utility Functions¶

osi_utilities.filename.infer_message_type_from_filename(filename)[source]¶

Infer message type from filename patterns.

Matches the underscore-delimited patterns (e.g. _gt_) and also supports the common convention where the type code appears at the end of the stem before the extension (e.g. trace_gt.osi, output_sv.mcap).

Parameters:: filename (str)
Return type:: MessageType

osi_utilities.tracefile.format.get_trace_file_format(path)[source]¶

Determine the trace file format from the file extension.

Parameters:: path (Path)
Return type:: TraceFileFormat

osi_utilities.filename.parse_osi_trace_filename(filename)[source]¶

Parse an OSI trace filename according to OSI naming convention 2.2.6.2.

Format: <timestamp>_<type>_<osi-version>_<protobuf-version>_<number-of-frames>_<custom-trace-name>.osi

Returns a dict with parsed fields, or empty dict if parsing fails.

Parameters:: filename (str)
Return type:: dict