Ex: Peak Dump

Dump the raw peak stream to CSV with Python.

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.

Requires pip install voyant-api.

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

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Carbon sensor, or the bundled carbon_simulator running locally

Example Code

View the complete example on GitHub: peak_dump_example.py

Key Concepts

Starting the Dump

A dump only receives data while the pipeline is running, so wait for the first heartbeat before starting it. start_peak_dump() takes an output path plus optional max_frames / max_peaks limits and an add_timestamp flag:

from voyant_api import CarbonClient, CarbonConfig, init_voyant_logging

init_voyant_logging()
client = CarbonClient(CarbonConfig())
client.start()

client.wait_for_heartbeat()
client.start_peak_dump("peaks.csv", max_frames=100)

Draining Frames During the Dump

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

while client.is_running() and client.is_peak_dumping():
    frame = client.try_receive_frame()
    if frame is not None:
        print(frame)
    else:
        time.sleep(0.001)

Stopping Cleanly

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

Command Line Options

python peak_dump_example.py --help

# Dump peaks to a CSV (Ctrl+C to stop)
python peak_dump_example.py peaks.csv

# Stop automatically after 100 frames, timestamp the filename
python peak_dump_example.py peaks.csv --max-frames 100 --add-timestamp

Expected Output

CarbonClient started.
Peak dump started → peaks.csv (Ctrl+C to stop early)
Frame 1: VoyantFrame(frame_index=41, n_points=23040, ...)
...
Peak dump finished after 100 frames.

Next Steps

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