ASAM OSI Utilities

A C++ and Python utility library for working with ASAM Open Simulation Interface (OSI) trace files in MCAP and other formats.

Quick Start

C++

# Clone with submodules
git clone https://github.com/lichtblick-suite/asam-osi-utilities.git
cd asam-osi-utilities
git submodule update --init --recursive

# Build (uses vcpkg preset — recommended)
make build cpp

# Build with tests
make build cpp tests

# Run tests
make test cpp

Note: First build takes 10-15 minutes as vcpkg compiles dependencies from source.

Power users can call cmake directly: cmake --preset vcpkg && cmake --build --preset vcpkg --parallel

Python

pip install asam-osi-utilities

Or from source:

# From the repository root
make setup          # creates venv + installs all dependencies
make test python    # run Python tests

Features

• Read/write OSI trace files in MCAP format with lz4/zstd compression
• Read/write single-channel binary (.osi) and text (.txth) trace files
• Convert between trace file formats
• Cross-platform: Linux, Windows, macOS
• C++ library with CMake/vcpkg integration
• Python SDK available on PyPI (pip install asam-osi-utilities)

Documentation

Document	Description
Overview	What is this library and OSI trace file formats
Building	Build instructions for all platforms
Development Guide	Short index for setup and workflow
Development Setup	Tooling and environment setup
Developer Workflow	Day-to-day commands
Contributing	How to contribute to this project
Examples	Example programs and their purpose
CI Pipeline	Continuous integration documentation
API Reference	C++ and Python API documentation

Examples

Both the C++ and Python SDKs ship with matching examples covering all supported formats (MCAP, binary .osi, text .txth), format conversion, and benchmarks.

C++	Python	Description
example_mcap_writer	example_mcap_writer.py	Write MCAP trace files with metadata and config constants
example_mcap_reader	example_mcap_reader.py	Read MCAP with metadata, topic filtering, and FilenameUtils
example_single_channel_binary_writer	example_single_channel_binary_writer.py	Write binary .osi files
example_single_channel_binary_reader	example_single_channel_binary_reader.py	Read binary .osi files
example_txth_writer	example_txth_writer.py	Write human-readable .txth files
example_txth_reader	example_txth_reader.py	Read .txth files
example_mcap_multi_channel_writer	example_mcap_multi_channel_writer.py	Multi-topic MCAP with mixed channels
convert_osi2mcap	convert_osi2mcap.py	Convert .osi → .mcap
convert_gt2sv	—	Convert GroundTruth → SensorView
—	example_reader_factory.py	Format auto-detection, timestamp utilities, and FilenameUtils
benchmark	benchmark.py	Throughput benchmark for all formats

See cpp/examples/README.md and python/examples/README.md for full details.

Requirements

C++

• C++17 compatible compiler
• CMake 3.16+
• vcpkg (recommended) or manual dependency installation

Python

• Python 3.10+
• pip install asam-osi-utilities

Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

License

This project is licensed under the Mozilla Public License 2.0.

Related Projects

• Open Simulation Interface - OSI standard
• MCAP - Open-source container file format