Ex: PCD Conversion

Convert Voyant binary point cloud data to per-frame file with Python.

🚧 These docs are out of date as of May, 2026. 🚧

They reflect the Meadowlark (Carbon dev kit) API and may not apply to Carbon systems.

Questions? Reach out to us at: support@voyantphotonics.com

This example demonstrates how to convert a Voyant .bin recording into per-frame .pcd files for use with point cloud visualization tools.

Available from v0.4.5. Requires pip install voyant-api.

What You’ll Learn

How to export frames from a .bin recording to PCD format
How to control which frames are exported using frame index ranges
How to open PCD files in CloudCompare

Prerequisites

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Voyant .bin recording file, either recorded from a sensor or downloaded:
- car_parking-v0_2_2.bin
- people_walking-v0_2_2.bin

Example Code

View the complete example on GitHub: pcd_conversion_example.py

Key Concepts

Basic Conversion

By default, only the first 100 frames are exported to avoid accidentally filling disk on large recordings. Pass --max-frames 0 to convert all frames.

# Convert first 100 frames (default, standard 7 fields)
python pcd_conversion_example.py --input recording.bin --output-dir ./pcd_out

# Include all 11 extended fields
python pcd_conversion_example.py --input recording.bin --output-dir ./pcd_out --extended-format

# Convert all frames
python pcd_conversion_example.py --input recording.bin --output-dir ./pcd_out --max-frames 0

# Convert a specific range by sensor frame index
python pcd_conversion_example.py --input recording.bin --output-dir ./pcd_out \
    --min-frame-index 1000 --max-frame-index 1099

Output files are named frame_<frame_index>.pcd, e.g. frame_1042.pcd.

Note: Frame indices reflect sensor uptime — they do not start from zero per recording.

PCD Fields

By default, each .pcd file contains the standard 7 fields. Pass --extended-format to include all 11 fields.

Field	Default	Extended (`--extended-format`)
`x`, `y`, `z`	✓	✓
`radial_vel`	✓	✓
`snr_linear`	✓	✓
`nanosecs_since_frame`	✓	✓
`drop_reason`	✓	✓
`calibrated_reflectance`		✓
`noise_mean_estimate`		✓
`min_ramp_snr`		✓
`point_index`		✓

Using `pcd_utils` Directly

save_frame_to_pcd is a convenience wrapper. You can also use voyant_api.pcd_utils functions directly for more control on which fields are saved in your .pcd files:

from voyant_api.pcd_utils import frame_to_xyz_pcd, frame_to_xyzv_pcd, frame_to_pcd, frame_to_extended_pcd

# xyz only — smallest file, compatible with any PCD viewer
pc = frame_to_xyz_pcd(frame, valid_only=True)
pc.save("frame_xyz.pcd")

# xyz + radial velocity (Doppler) — great for quick visualization
pc = frame_to_xyzv_pcd(frame, valid_only=True)
pc.save("frame_xyzv.pcd")

# Standard 7 fields — default, good balance of size and information
pc = frame_to_pcd(frame, valid_only=True)
pc.save("frame_standard.pcd")

# All 11 fields — includes reflectance, noise, point index
pc = frame_to_extended_pcd(frame, valid_only=True)
pc.save("frame_extended.pcd")

Viewing PCD Files in CloudCompare

CloudCompare is a free, cross-platform tool for viewing and processing point clouds.

Download and install CloudCompare from cloudcompare.org
Open CloudCompare and go to File → Open
In the file browser, change the filter dropdown from “All supported formats” to “All files (.)” — PCD files are hidden by default
Select your .pcd file and click Open

Note: Your OS may show .pcd files with an image icon (Kodak Photo CD format uses the same extension). This is cosmetic — the files are standard PCD point clouds.

Other Viewers

Open3D (Python): import open3d as o3d; pcd = o3d.io.read_point_cloud("frame.pcd"); o3d.visualization.draw_geometries([pcd])
RViz — if you are working in a ROS environment
PCL tools — pcl_viewer frame.pcd

Expected Output

Converted 10 frames...
Converted 20 frames...
...
Done. Converted 100 frames to './pcd_out'

pcd_out/
├── frame_1020.pcd
├── frame_1021.pcd
├── frame_1022.pcd
...

Next Steps

Playback — process frames as pandas DataFrames instead
API Reference — full pcd_utils and pandas_utils documentation