Ex: Playback

Play back recorded point cloud data with Python.

This example demonstrates how to play back a Voyant recording and process frames using pandas DataFrames. Playback is sensor-agnostic — it reads any Voyant recording, regardless of which sensor produced it.

Requires pip install voyant-api.

What You’ll Learn

How to open and iterate over a .bin recording in Python
How to convert frames to pandas DataFrames using voyant_api.pandas_utils
How to control playback rate and looping

Prerequisites

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Voyant recording (.vynt or .bin), either recorded from a sensor or downloaded:
- car_parking-v0_2_2.bin
- people_walking-v0_2_2.bin
Note: These sample files are older Carbon recordings in the v0_2_2 proto format. They still play back fine; record your own file for the current Carbon format.

Example Code

View the complete example on GitHub: playback_example.py

Key Concepts

Opening a Recording

VoyantPlayback supports Python’s context manager and iterator protocols:

from voyant_api import VoyantPlayback
from voyant_api.pandas_utils import frame_to_dataframe

with VoyantPlayback(filter_points=True) as playback:
    playback.open("my_recording.vynt")

    for frame in playback:
        if frame is None:
            break

        df = frame_to_dataframe(frame)
        print(df.head())

DataFrame Columns

frame_to_dataframe() returns a DataFrame with 7 columns:

Column	Type	Description
`x`	float32	X position (meters)
`y`	float32	Y position (meters)
`z`	float32	Z position (meters)
`radial_vel`	float32	Doppler velocity (m/s)
`snr_linear`	float32	Signal-to-noise ratio
`nanosecs_since_frame`	float32	Timestamp within frame
`drop_reason`	float32	Point validity code

For all extended fields (reflectance, noise, etc.) use frame_to_extended_dataframe() instead.

Command Line Options

python playback_example.py --input my_recording.vynt

# Keep invalid points
python playback_example.py --input my_recording.vynt --keep-invalid-points

# Loop continuously
python playback_example.py --input my_recording.vynt --loopback

Expected Output

#############
VoyantFrame(frame_index=20, n_points=15850, n_valid=15850, timestamp=1742330842.722)
            x         y         z  radial_vel  snr_linear  nanosecs_since_frame  drop_reason
0    5.820130  0.193966  0.000000    1.229850   12.323400                   0.0          1.0
1    5.812000  0.192000  0.010000    1.198000   11.980000               16384.0          1.0
...

Next Steps

PCD Conversion — export frames to .pcd files for visualization in CloudCompare or Open3D
Recorder — record live data to create your own .bin files