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 .vynt 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 .vynt recording, either recorded from a sensor or downloaded:
  • car_parking-v1_0_0.vynt
  • people_walking-v1_0_0.vynt

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 field set)
python pcd_conversion_example.py --input recording.vynt --output-dir ./pcd_out

# 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

# Write a custom field set
python pcd_conversion_example.py --input recording.vynt --output-dir ./pcd_out \
    --fields x,y,z,doppler_mps,snr

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 x, y, z plus every non-geometry recorded field: doppler_mps, snr, calibrated_reflectance, timestamp_nanosecs, azimuth_idx, elevation_idx, drop_reason, combine_method, and user_data.

Pass --fields (or the fields keyword below) to write any other set of recorded fields, in your order — it just has to include one full geometry trio, either x/y/z or range_m/azimuth_rad/elevation_rad, so every PCD point has a position.

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. Each takes a keep_invalid_points flag (default False) to carry invalid points from a diagnostic-mode capture into the output:

from voyant_api.pcd_utils import frame_to_xyz_pcd, frame_to_xyzv_pcd, frame_to_pcd

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

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

# Default field set: x, y, z plus every non-geometry recorded field
pc = frame_to_pcd(frame)
pc.save("frame_standard.pcd")

# Custom field set, spherical geometry
pc = frame_to_pcd(frame, fields=["range_m", "azimuth_rad", "elevation_rad", "snr"])
pc.save("frame_spherical.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