ouster.sdk.osf¶

Module contents¶

This module provides an API for working with OSF (Ouster Sensor Format) files. It includes tools for reading, writing, slicing, encoding, and modifying OSF files and their metadata.

Classes¶

class AsyncWriter(self, filename : str, info : collections.abc.Sequence [ ouster.sdk.core.SensorInfo ], fields_to_write : collections.abc.Sequence [ str ] = [], chunk_size : int = 0, encoder : ouster.sdk.osf.Encoder | None = None)
class Encoder(self, lidar_frame_encoder : LidarFrameEncoder)
class LidarFrameStream
class LidarSensor(self, arg : ouster.sdk.core.SensorInfo, /)
class OsfDropFrameError
class OsfFrameSetSource(self, file : str, ** kwargs)
class PngLidarFrameEncoder(self, compression_amount : int)
class Reader(self, file : str)
class Writer(self, file_name : str, chunk_size : int = 0)
class ZPngLidarFrameEncoder(self, compression_amount : int)

Functions¶

backup_osf_file_metablob(file : str, backup_file_name : str) → int
dump_metadata(file : str, full : bool = True) → str
osf_file_modify_metadata(file_name : str, new_metadata : collections.abc.Sequence [ ouster.sdk.core.SensorInfo ]) → int
restore_osf_file_metablob(file : str, backup_file_name : str) → int
slice_and_cast(* args, ** kwargs)

AsyncWriter¶

class AsyncWriter(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None)¶

Creates an AsyncWriter with specified chunk_size.

Default chunk_size is 2MB.

Parameters:

filename (str) – The filename to output to.
info (List[SensorInfo]) – The sensor info vector to use for a multi stream OSF file.
fields_to_write (List[str]) – The fields from frames to actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.
chunk_size (int) – The chunksize to use for the OSF file, this arg is optional.
encoder (Encoder) – an optional encoder instance, used to configure how writer encodes the OSF.

__enter__(self) → ouster.sdk.osf.AsyncWriter¶: Allow AsyncWriter to work within with blocks.

__exit__(self, exc_type: object | None, exc_value: object | None, traceback: object | None) → object¶: Allow AsyncWriter to work within with blocks.

__init__(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) → None¶

Creates an AsyncWriter with specified chunk_size.

Default chunk_size is 2MB.

Parameters:

filename (str) – The filename to output to.
info (List[SensorInfo]) – The sensor info vector to use for a multi stream OSF file.
fields_to_write (List[str]) – The fields from frames to actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.
chunk_size (int) – The chunksize to use for the OSF file, this arg is optional.
encoder (Encoder) – an optional encoder instance, used to configure how writer encodes the OSF.

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

close(self, fsync: bool = False) → None¶: Finish OSF file and flush everything to disk.

Encoder¶

class Encoder(self, lidar_frame_encoder: LidarFrameEncoder)¶

class Encoder(self, *, lidar_scan_encoder: LidarFrameEncoder)

Used by the Writer class to encode LidarFrames, depending on configuration.

__init__(self, lidar_frame_encoder: LidarFrameEncoder) → None¶
__init__(self, *, lidar_scan_encoder: LidarFrameEncoder) → None

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

LidarFrameStream¶

class LidarFrameStream¶

Stream of LidarFrame objects from a sensor.

type_id static property is a LidarFrameStream underlying metadata type identifier.

__annotations__ = {'meta': 'LidarFrameStreamMeta', 'type_id': 'str'}¶

__init__(*args, **kwargs)¶

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

property meta: LidarFrameStreamMeta¶: metadata entry to store LidarFrameStream metadata in an OSF file

type_id: str = 'ouster/v1/os_sensor/LidarScanStream'¶

LidarSensor¶

class LidarSensor(self, arg: ouster.sdk.core.SensorInfo, /)¶

class LidarSensor(self, metadata_json: str)

Ouster Lidar Sensor metadata with sensor intrinsics (i.e. SensorInfo/Metadata)

type_id static property is a LidarSensor metadata type identifier.

Overloaded function.

__init__(self, arg: ouster.sdk.core.SensorInfo, /) -> None

Create from SensorInfo object

__init__(self, metadata_json: str) -> None

Create from metadata_json string representation

__annotations__ = {'info': 'ouster.sdk.core.SensorInfo', 'metadata': 'str', 'type_id': 'str'}¶

__init__(self, arg: ouster.sdk.core.SensorInfo, /) → None¶

__init__(self, metadata_json: str) → None

Overloaded function.

__init__(self, arg: ouster.sdk.core.SensorInfo, /) -> None

Create from SensorInfo object

__init__(self, metadata_json: str) -> None

Create from metadata_json string representation

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

property info: ouster.sdk.core.SensorInfo¶: SensorInfo stored

property metadata: str¶: metadata_json string stored

type_id: str = 'ouster/v1/os_sensor/LidarSensor'¶

OsfDropFrameError¶

class OsfDropFrameError¶

__module__ = 'ouster.sdk.osf'¶

__weakref__¶: list of weak references to the object

OsfFrameSetSource¶

class OsfFrameSetSource(self, file: str, **kwargs)¶

__annotations__ = {'is_collated': 'bool'}¶

__init__(self, file: str, **kwargs) → None¶

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

property is_collated: bool¶: (self) -> bool

PngLidarFrameEncoder¶

class PngLidarFrameEncoder(self, compression_amount: int)¶

Used by the Writer class to encode LidarFrames using PNG compression.

__init__(self, compression_amount: int) → None¶

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

Reader¶

class Reader(self, file: str)¶

class Reader(self, file: str, error_handler: collections.abc.Callable[[ouster.sdk.core.Severity, str], None] | None = None)

Reader is a main entry point to get any info out of OSF file.

__annotations__ = {'end_ts': 'int', 'has_message_idx': 'bool', 'has_stream_info': 'bool', 'has_timestamp_idx': 'bool', 'meta_store': 'MetadataStore', 'metadata_id': 'str', 'size': 'int', 'start_ts': 'int', 'version': 'ouster.sdk.core.Version'}¶

__dict__ = mappingproxy({'__new__': <built-in method __new__ of nanobind.nb_type_0 object>, '__init__': <nanobind.nb_method object>, '__dict__': <attribute '__dict__' of 'ouster.sdk.osf.Reader' objects>, '__doc__': '\n Reader is a main entry point to get any info out of OSF file.\n ', '__module__': 'ouster.sdk.osf', 'metadata_id': <property object>, 'start_ts': <property object>, 'end_ts': <property object>, 'size': <property object>, 'version': <property object>, 'meta_store': <property object>, 'has_stream_info': <property object>, 'has_message_idx': <property object>, 'has_timestamp_idx': <property object>, 'messages': <nanobind.nb_method object>, 'ts_by_message_idx': <nanobind.nb_method object>, 'chunks': <nanobind.nb_method object>, '__annotations__': {'metadata_id': 'str', 'start_ts': 'int', 'end_ts': 'int', 'size': 'int', 'version': 'ouster.sdk.core.Version', 'meta_store': 'MetadataStore', 'has_stream_info': 'bool', 'has_message_idx': 'bool', 'has_timestamp_idx': 'bool'}})¶

__init__(self, file: str) → None¶
__init__(self, file: str, error_handler: collections.abc.Callable[[ouster.sdk.core.Severity, str], None] | None = None) → None

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

chunks(self) → collections.abc.Iterator[ouster.sdk.osf.ChunkRef]¶: Creates an iterator to reads chunks as they appear in a file.

property end_ts: int¶: End timestamp (ns) - the highest message timestamp present in the file

property has_message_idx: bool¶: Whether OSF contains the message counts that are needed for ts_by_message_idx() (message counts was added a bit later to the OSF core, so this function will be obsolete over time)

property has_stream_info: bool¶: Whether StreamingInfo metadata is available (i.e. reading messages by timestamp and streams can be performed)

property has_timestamp_idx: bool¶: Whether OSF contains the message timestamp index in the metadata necessary to quickly collate and jump to a specific message time.

messages(self) → collections.abc.Iterator[ouster.sdk.osf.MessageRef]¶

messages(self, start_ts: int, end_ts: int) → collections.abc.Iterator[ouster.sdk.osf.MessageRef]

messages(self, stream_ids: collections.abc.Sequence[int] = []) → collections.abc.Iterator[ouster.sdk.osf.MessageRef]

messages(self, stream_ids: collections.abc.Sequence[int], start_ts: int, end_ts: int) → collections.abc.Iterator[ouster.sdk.osf.MessageRef]

Overloaded function.

messages(self) -> collections.abc.Iterator[ouster.sdk.osf.MessageRef]

Creates an iterator to read messages in default STREAMING layout.
messages(self, start_ts: int, end_ts: int) -> collections.abc.Iterator[ouster.sdk.osf.MessageRef]

Read messages in [start_ts, end_ts] timestamp range (inclusive)
messages(self, stream_ids: collections.abc.Sequence[int] = []) -> collections.abc.Iterator[ouster.sdk.osf.MessageRef]

Read messages from only specified [<stream_ids>] list
messages(self, stream_ids: collections.abc.Sequence[int], start_ts: int, end_ts: int) -> collections.abc.Iterator[ouster.sdk.osf.MessageRef]

Read messages in [start_ts, end_ts] timestamp range (inclusive) of a specified <stream_ids> list

property meta_store: MetadataStore¶: Returns the metadata store that gives an access to all metadata entries in the file.

property metadata_id: str¶: Data id string

property size: int¶: Size of the OSF file in bytes

property start_ts: int¶: Start timestamp (ns) - the lowest message timestamp present in the file

ts_by_message_idx(self, stream_id: int, message_idx: int) → object¶

Find the timestamp of the message by its index and stream_id.

Requires the OSF with message_counts inside, i.e. has_message_idx() is True, otherwise return value is always None.

property version: ouster.sdk.core.Version¶: Version of OSF file format in the file

Writer¶

class Writer(self, file_name: str, chunk_size: int = 0)¶

class Writer(self, filename: str, info: ouster.sdk.core.SensorInfo, fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None)

class Writer(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None)

Simple writer interface for OSF file

All jobs are done with MetadataStore for adding metadata entries and stream interfaces that encodes messages and passes them to internal chunks writer.

Overloaded function.

__init__(self, file_name: str, chunk_size: int = 0) -> None

Creates a Writer with specified chunk_size.

Default chunk_size is 2 MB.
__init__(self, filename: str, info: ouster.sdk.core.SensorInfo, fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) -> None

Creates a Writer with deafault STREAMING layout chunks writer.

Using default chunk_size of 2MB.

Args:
filename (str): The filename to output to. info (SensorInfo): The sensor info vector to use for a multi stream OSF

file.

chunk_size (int): The chunk size in bytes to use for the OSF file. This arg
is optional, and if not provided the default value of 2MB is used. If the current chunk being written exceeds the chunk_size, a new chunk will be started on the next call to save. This allows an application to tune the number of messages (e.g. lidar frames) per chunk, which affects the granularity of the message index stored in the StreamingInfo in the file metadata. A smaller chunk_size means more messages are indexed and a larger number of index entries. A more granular index allows for more precise seeking at the slight expense of a larger file.

fields_to_write (List[str]): The fields from frames to
actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.
__init__(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) -> None

Creates a Writer with specified chunk_size.

Default chunk_size is 2MB.

Args: filename (str): The filename to output to. info (List[SensorInfo]): The sensor info vector to use for a

multi stream OSF file.

fields_to_write (List[str]): The fields from frames to
actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.

chunk_size (int): The chunksize to use for the OSF file, this arg
is optional.

__annotations__ = {'meta_store': 'MetadataStore'}¶

__enter__(self) → ouster.sdk.osf.Writer¶: Allow Writer to work within with blocks.

__exit__(self, exc_type: object | None, exc_value: object | None, traceback: object | None) → object¶: Allow Writer to work within with blocks.

__init__(self, file_name: str, chunk_size: int = 0) → None¶

__init__(self, filename: str, info: ouster.sdk.core.SensorInfo, fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) → None

__init__(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) → None

Overloaded function.

__init__(self, file_name: str, chunk_size: int = 0) -> None

Creates a Writer with specified chunk_size.

Default chunk_size is 2 MB.
__init__(self, filename: str, info: ouster.sdk.core.SensorInfo, fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) -> None

Creates a Writer with deafault STREAMING layout chunks writer.

Using default chunk_size of 2MB.

Args:
filename (str): The filename to output to. info (SensorInfo): The sensor info vector to use for a multi stream OSF

file.

chunk_size (int): The chunk size in bytes to use for the OSF file. This arg
is optional, and if not provided the default value of 2MB is used. If the current chunk being written exceeds the chunk_size, a new chunk will be started on the next call to save. This allows an application to tune the number of messages (e.g. lidar frames) per chunk, which affects the granularity of the message index stored in the StreamingInfo in the file metadata. A smaller chunk_size means more messages are indexed and a larger number of index entries. A more granular index allows for more precise seeking at the slight expense of a larger file.

fields_to_write (List[str]): The fields from frames to
actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.
__init__(self, filename: str, info: collections.abc.Sequence[ouster.sdk.core.SensorInfo], fields_to_write: collections.abc.Sequence[str] = [], chunk_size: int = 0, encoder: ouster.sdk.osf.Encoder | None = None) -> None

Creates a Writer with specified chunk_size.

Default chunk_size is 2MB.

Args: filename (str): The filename to output to. info (List[SensorInfo]): The sensor info vector to use for a

multi stream OSF file.

fields_to_write (List[str]): The fields from frames to
actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.

chunk_size (int): The chunksize to use for the OSF file, this arg
is optional.

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

add_metadata(self, m: object) → int¶: Add metadata entry to a file

add_sensor(self, info: ouster.sdk.core.SensorInfo, fields_to_write: collections.abc.Sequence[str] = []) → int¶

Add a sensor to the OSF file.

Parameters:

info (SensorInfo) – Sensor to add.
fields_to_write (List[str]) – The fields from frames to actually save into the OSF. If not provided uses the fields from the first saved lidar frame for each stream. This parameter is optional.

Returns (int):: The stream index to use to write frames to this sensor.

close(self, fsync: bool = False) → None¶: Finish OSF file and flush everything to disk.

filename(self) → str¶

Return the osf file name.

Returns (str):: The OSF filename.

is_closed(self) → bool¶

Return the closed status of the writer.

Returns (bool):: The closed status of the writer.

property meta_store: MetadataStore¶: Returns the metadata store that gives an access to all metadata entries in the file.

metadata_id(self) → str¶

Return the metadata identifier string.

Returns (str):: The OSF metadata identifier string.

save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: ndarray[dtype=uint8], type: str) → None¶

save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: bytes, type: str) → None

save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: collections.abc.Sequence[int], type: str) → None

Overloaded function.

save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: ndarray[dtype=uint8], type: str) -> None

Low-level save message routine.

Directly saves the message buffer with id and ts (ns) without any further checks.
save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: bytes, type: str) -> None

Low-level save message routine.

Directly saves the message buffer with id and ts (ns) without any further checks.
save_message(self, stream_id: int, receive_ts: int, sensor_ts: int, buffer: collections.abc.Sequence[int], type: str) -> None

Low-level save message routine.

Directly saves the message buffer (from a Python list) with id and ts (ns).

sensor_info(self) → list[ouster.sdk.core.SensorInfo]¶

Return the sensor info list.

Returns (List[SensorInfo]):: The sensor info list.

set_metadata_id(self, arg: str, /) → None¶: Set the metadata identifier string.

ZPngLidarFrameEncoder¶

class ZPngLidarFrameEncoder(self, compression_amount: int)¶

Used by the Writer class to encode LidarFrames using ZPNG compression.

__annotations__ = {}¶

__init__(self, compression_amount: int) → None¶

__module__ = 'ouster.sdk.osf'¶

__new__(**kwargs)¶

backup_osf_file_metablob¶

backup_osf_file_metablob(file: str, backup_file_name: str) → int¶

Backup the metadata blob in an OSF file.

File:: OSF file path (v1/v2)
Backup_file_name:: Backup path

dump_metadata¶

dump_metadata(file: str, full: bool = True) → str¶

Dump OSF metadata/session info in JSON format. (aka osf-metadata)

File:: OSF file path
Returns:: JSON formatted string of OSF metadata + header info

osf_file_modify_metadata¶

osf_file_modify_metadata(file_name: str, new_metadata: collections.abc.Sequence[ouster.sdk.core.SensorInfo]) → int¶

Modify an OSF files sensor_info metadata.

File_name:: The OSF file to modify.
New_metadata:: Array containing sensor infos to write to the file.
Returns:: The number of the bytes written to the OSF file.

restore_osf_file_metablob¶

restore_osf_file_metablob(file: str, backup_file_name: str) → int¶

Restore an OSF metadata blob from a backup file.

File:: OSF file path (v1/v2)
Backup_file_name:: The backup to use

slice_and_cast¶

slice_and_cast(*args, **kwargs)¶

slice_and_cast(lidar_frame: ouster.sdk.core.LidarFrame, field_types: collections.abc.Mapping[str, object]) → ouster.sdk.core.LidarFrame

Copies LidarFrame with new field types

Parameters:

args (Any)
kwargs (Any)

Return type:

Any