Ex: Data Recording

Record live Carbon LiDAR data with Python.

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

Requires pip install voyant-api.

What You’ll Learn

How to create a VoyantRecorder instance in Python
How to record frames with file splitting options
How to handle recording limits and finalize cleanly

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: recorder_example.py

Key Concepts

Creating the Recorder

Construct a client (the frame source) and a recorder:

from voyant_api import CarbonClient, CarbonConfig, VoyantRecorder, RecordStatus, init_voyant_logging

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

recorder = VoyantRecorder(
    output_path="my_recording.vynt",
    timestamp_filename=True,    # Adds timestamp to filename automatically
    frames_per_file=None,       # Split after N frames (None = no limit)
    size_per_file_mb=None,      # Split after N MB (None = no limit)
    max_total_frames=None,      # Stop after N total frames (None = no limit)
)

Record in a loop; the context manager calls finalize() on exit:

with recorder:
    while client.is_running():
        frame = client.try_receive_frame()
        if frame is not None:
            status = recorder.record_frame(frame)
            if status == RecordStatus.STOP:
                break

RecordStatus

record_frame() returns a RecordStatus indicating what happened:

Status	Meaning
`RecordStatus.OK`	Frame recorded, continue
`RecordStatus.SPLIT`	Frame recorded, new file started
`RecordStatus.STOP`	Recording limit reached, stop

Command Line Options

python recorder_example.py --output my_recording.vynt

# Split files every 100 frames
python recorder_example.py --output my_recording.vynt --frames-per-file 100

# Stop after 10 minutes total
python recorder_example.py --output my_recording.vynt --max-total-duration 600

# Disable timestamp in filename
python recorder_example.py --output my_recording.vynt --no-timestamp-filename

Note: Python-based recording may struggle to keep up with high-frequency data streams. For reliable high-rate capture, use the native binary recorder tool.

Expected Output

Recording to 'my_recording.vynt'. Press Ctrl+C to stop.
Recorded 100 frames in 1 files...
Recorded 200 frames in 1 files...
^C
Ctrl+C detected. Finalizing recording...
Finalizing recording after 243 total frames
Recording finalized

Next Steps

Playback — replay your recording
PCD Conversion — export frames to .pcd for visualization