Ex: Peak Dump

Dump the raw peak stream to CSV with C++.

This example demonstrates how to dump a Carbon sensor’s raw peak stream to a CSV file while the point cloud keeps streaming. The dump runs on its own writer thread, so point cloud processing is unaffected.

What You’ll Learn

• How to start and stop a peak dump on a live CarbonClient
• How the dump runs on a separate thread while frames keep flowing
• How to stop cleanly on a whole-frame boundary

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: peak_dump.cpp

Key Concepts

Starting the Dump

A dump only receives data while the pipeline is running, so wait for the first heartbeat before starting it. startPeakDump() takes an output path and an optional frame limit (0 = unbounded):

if (!client.waitForHeartbeat())
{
    std::cerr << "Timed out waiting for a sensor heartbeat." << std::endl;
    return 1;
}

if (!client.startPeakDump(output, maxFrames))
{
    std::cerr << "Failed to start peak dump (already running, or client stopped)." << std::endl;
    return 1;
}

Draining Frames During the Dump

Keep calling tryReceiveFrame() so the point cloud keeps flowing while the dump writes in the background. isPeakDumping() reports when the dump is still active:

while (client.isRunning() && client.isPeakDumping() && !CarbonClient::isTerminated())
{
    if (client.tryReceiveFrame())
    {
        std::cout << client.latestFrame() << std::endl;
    }
    std::this_thread::sleep_for(std::chrono::milliseconds(1));
}

Stopping Cleanly

stopPeakDump() asks the writer to finish on a whole frame; poll isPeakDumping() until it returns false.

Building and Running

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

# Dump peaks to a CSV (Ctrl+C to stop)
./bin/peak_dump peaks.csv

# Stop automatically after 100 frames
./bin/peak_dump peaks.csv --max-frames 100

# Add --sim to target a local carbon_simulator
./bin/peak_dump peaks.csv --sim

Expected Output

Peak dump started -> peaks.csv (Ctrl+C to stop early)
###############
Header{message type:2, device id:CAR-000, frame idx:41, ...}
...
Peak dump finished.

Next Steps

• Live Client — stream the point cloud on its own
• API Documentation — full CarbonClient reference