MCAPTraceFileChannel

class MCAPTraceFileChannel

OSI channel helper for integration with external MCAP writers.

This class provides OSI-compliant channel registration and message writing capabilities for use with an externally-managed mcap::McapWriter. Use this when you have your own MCAP writer that handles multiple topic types (both OSI and non-OSI) and you want to leverage this library’s OSI schema/metadata handling.

Unlike MCAPTraceFileWriter which owns the file and MCAP writer, this class operates on a caller-provided McapWriter reference. The caller is responsible for the writer’s lifecycle (open/close) and for writing the required OSI file metadata (via PrepareRequiredFileMetadata()) before writing any messages.

Example usage:

std::ofstream file("mixed.mcap", std::ios::binary);
mcap::McapWriter writer;
writer.open(file, mcap::McapWriterOptions("protobuf"));

// Add OSI file metadata (required by OSI spec)
writer.write(osi3::MCAPTraceFileChannel::PrepareRequiredFileMetadata());

// Create channel helper
osi3::MCAPTraceFileChannel osi_channels(writer);
osi_channels.AddChannel("ground_truth", osi3::GroundTruth::descriptor());

// Write OSI messages
osi3::GroundTruth gt;
osi_channels.WriteMessage(gt, "ground_truth");

// You can also write non-OSI messages directly to writer
writer.close();

Note

Thread Safety: Not thread-safe. External synchronization required for concurrent access.

Note

Lifetime: The provided McapWriter must outlive this object.

Public Functions

explicit MCAPTraceFileChannel(mcap::McapWriter &writer)

Constructs a channel helper attached to an external MCAP writer.

Parameters:

writer – Reference to an open McapWriter (caller-owned, must outlive this object)

MCAPTraceFileChannel(const MCAPTraceFileChannel&) = delete

Deleted copy constructor.

MCAPTraceFileChannel &operator=(const MCAPTraceFileChannel&) = delete

Deleted copy assignment operator.

MCAPTraceFileChannel(MCAPTraceFileChannel&&) = delete

Deleted move constructor.

MCAPTraceFileChannel &operator=(MCAPTraceFileChannel&&) = delete

Deleted move assignment operator.

template<typename T>
bool WriteMessage(const T &top_level_message, const std::string &topic)

Writes a protobuf message to the file.

Warning

Caller must write OSI file metadata (via PrepareRequiredFileMetadata()) to the McapWriter before calling this method. Without it the resulting file is non-compliant.

Template Parameters:

T – Type of the OSI protobuf message (must have timestamp() method)

Parameters:

• top_level_message – The message to write

• topic – Topic name (must match a previously added channel)

Returns:

true if successful, false otherwise

uint16_t AddChannel(const std::string &topic, const google::protobuf::Descriptor *descriptor, std::unordered_map<std::string, std::string> channel_metadata = {})

Adds a new OSI channel to the MCAP file.

Registers the schema (if not already registered) and creates a channel with OSI-compliant metadata (osi_version, protobuf_version).

Parameters:

• topic – Name of the channel/topic

• descriptor – Protobuf descriptor for the OSI message type

• channel_metadata – Additional metadata for the channel (passed by value; OSI metadata is added in-place)

Throws:

std::runtime_error – if topic already exists with a different message type

Returns:

Channel ID for the newly created channel

Public Static Functions

static mcap::Metadata PrepareRequiredFileMetadata()

Prepares the required (by OSI spec) metadata for the MCAP trace file.

Call this and write the result to your McapWriter before writing OSI messages. This is the same metadata that MCAPTraceFileWriter adds automatically.

Returns:

mcap::Metadata Object containing the necessary metadata for OSI compliance

static std::string GetCurrentTimeAsString()

Helper function that returns the current time as a formatted string.

Returns:

Current timestamp as string in OSI-specification format