Ex: Data Recording

Record live Carbon LiDAR data with C++.

This example demonstrates how to record live Carbon LiDAR data to disk, with support for automatic file splitting and recording limits.

What You’ll Learn

• How to configure and create a VoyantRecorder instance
• How to record frames from a live CarbonClient
• How to handle file splitting and recording limits
• How to finalize a recording cleanly on exit

Prerequisites

• Voyant SDK installed (see Installation)
• A Carbon sensor, or the bundled carbon_simulator running locally (pass --sim)

Example Code

View the complete example on GitHub: voyant_recorder_basic.cpp

Key Concepts

Recorder Configuration

The VoyantRecorderConfig struct controls all recording behavior. Only the output path is required — all limits are optional.

VoyantRecorderConfig config("test_recording/recording.vynt");

// Optional: split files after 50 frames or 20 MB, whichever comes first
config.framesPerFile = 50;
config.sizePerFileMb = 20;

// Optional: stop recording after 200 total frames
config.maxTotalFrames = 200;

VoyantRecorder recorder(config);

Recording Loop

Each call to recorder.recordFrame(frame) returns a RecordResult indicating what happened:

RecordResult result = recorder.recordFrame(frame);

switch (result)
{
    case RecordResult::Ok:       // Frame recorded, continue
    case RecordResult::Split:    // Frame recorded, new file started
    case RecordResult::Finished: // Limit reached, stop recording
    case RecordResult::Error:    // Something went wrong
}

Finalizing

Always call recorder.finalize() before exit to ensure all data is flushed and files are properly closed:

recorder.finalize();

Building and Running

# Build the examples
mkdir build && cd build
cmake ..
make

# Run against a real sensor
./bin/voyant_recorder_basic

# Or run against a local carbon_simulator
./bin/voyant_recorder_basic --sim

Expected Output

Starting Voyant recording example...
Listening for frames (press Ctrl+C to stop)...
Recorded 100 frames
Recorded 200 frames across 4 files

Finalizing recording...
Recording complete!

Next Steps

• Use Playback (C++) to read back your recording
• Use the Python PCD Conversion example to export frames to .pcd files for visualization