Ex: PCD Conversion

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

This example demonstrates how to convert a Voyant recording into per-frame .pcd files for use with point cloud visualization tools. Conversion 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 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 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 convert to PCD fine; record your own file for the current Carbon format.

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.vynt --output-dir ./pcd_out

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

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

# Convert a specific range by sensor frame index
python pcd_conversion_example.py --input recording.vynt --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