🚧 These docs are currently out of date. 🚧

They reflect the Meadowlark (Carbon dev kit) API and may not apply to Carbon systems.
Fully updated documentation will be published when Carbon Alpha ships in April 2026.

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.

1. Download and install CloudCompare from cloudcompare.org
2. Open CloudCompare and go to File → Open
3. In the file browser, change the filter dropdown from “All supported formats” to “All files (.)” — PCD files are hidden by default
4. 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