Core Types

Enumerations

class osi_utilities.tracefile._types.MessageType(*values)

Bases: Enum

OSI top-level message types. Mirrors C++ ReaderTopLevelMessage enum.

UNKNOWN = 0

GROUND_TRUTH = 1

SENSOR_DATA = 2

SENSOR_VIEW = 3

SENSOR_VIEW_CONFIGURATION = 4

HOST_VEHICLE_DATA = 5

TRAFFIC_COMMAND = 6

TRAFFIC_COMMAND_UPDATE = 7

TRAFFIC_UPDATE = 8

MOTION_REQUEST = 9

STREAMING_UPDATE = 10

class osi_utilities.tracefile._types.TraceFileFormat(*values)

Bases: Enum

Trace file format categories.

SINGLE_CHANNEL = 1

MULTI_CHANNEL = 2

Data Classes

class osi_utilities.tracefile._types.ReadResult(message, message_type, channel_name='')

Bases: object

Result of reading a single message from a trace file.

Parameters:

• message (Message)

• message_type (MessageType)

• channel_name (str)

message: Message

The deserialized protobuf message.

message_type: MessageType

The OSI message type.

channel_name: str = ''

The channel/topic name (MCAP only, empty for single-channel formats).

class osi_utilities.tracefile._types.ChannelSpecification(path, message_type=None, topic=None, metadata=<factory>)

Bases: object

Specification for an OSI channel within a trace file.

Adopted from PMSFIT’s OSIChannelSpecification with builder pattern.

Parameters:

• path (Path)

• message_type (str | None)

• topic (str | None)

• metadata (dict[str, str])

path: Path

Path to the trace file.

message_type: str | None = None

OSI message type name (e.g. “GroundTruth”).

topic: str | None = None

Channel topic name (MCAP only).

metadata: dict[str, str]

Additional channel metadata.

property trace_file_format: TraceFileFormat

Determine the trace file format from the file extension.

try_autodetect_message_type()

Attempt to detect message type from filename.

Returns True if detection succeeded and sets self.message_type.

Return type:

bool

autofill_topic()

Set topic to filename stem if not already set.

Return type:

None

exists()

Check if the file at path exists.

Return type:

bool

with_message_type(message_type)

Return a new ChannelSpecification with a different message type.

Parameters:

message_type (str)

Return type:

ChannelSpecification

with_topic(topic)

Return a new ChannelSpecification with a different topic.

Parameters:

topic (str)

Return type:

ChannelSpecification

with_trace_file_format(fmt)

Return a new ChannelSpecification with a different file extension.

Parameters:

fmt (TraceFileFormat)

Return type:

ChannelSpecification

Utility Functions

osi_utilities.tracefile._types.infer_message_type_from_filename(filename)

Infer message type from filename patterns.

Matches the C++ kFileNameMessageTypeMap 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._types.get_trace_file_format(path)

Determine the trace file format from the file extension.

Parameters:

path (Path)

Return type:

TraceFileFormat

osi_utilities.tracefile._types.parse_osi_trace_filename(filename)

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