pypcd4

library1.4.3pypypi✓ verified 89d ago

A Python library for reading and writing PCL (Point Cloud Library) .pcd files, supporting ASCII, binary, and binary_compressed encodings. Current version: 1.4.3, requires Python >=3.8.2, released under MIT license on GitHub.

data serialization database

pip install pypcd4

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PYPCD4

pypcd4

datapythonv1.4.3

Install

5.5s avg

Import

708ms

Disk

99MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.716s · 99.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.5s · import 0.700s · 95MB

99MB installed

● package 99MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PointCloud

✓ from pypcd4 import PointCloud

Standard import path

PointCloud

✓ from pypcd4.point_cloud import PointCloud

Alternative import if using submodule directly

PointCloud

✓ import pypcd4; pypcd4.PointCloud

✗ from pypcd4 import PointCloud as PC

Aliasing is fine, but avoid confusing imports from older libraries like pypcd (without 4)

Create, save, and load a PCD point cloud

from pypcd4 import PointCloud import numpy as np # Create a simple point cloud pc = PointCloud.from_xyz_points(np.array([[0,0,0],[1,0,0],[0,1,0]], dtype=np.float32)) print(pc) # Save to file pc.save('example.pcd') # Load from file loaded = PointCloud.from_path('example.pcd') print(loaded.pc_data) # numpy structured array

Debug

Known issues

breakingBinary_compressed encoding changed in v1.3.0: save/load logic was fixed, which may break compatibility with files created by older versions (<=1.2.1). If you compress with v1.3.0+, older versions may not read them correctly.

fix

Re-save any existing binary_compressed PCD files after upgrading to 1.3.0+. If reading old files fails, re-save them in ASCII or binary uncompressed.

affects: >=1.3.0

deprecatedThe 'lzf' dependency changed in v1.4.0: 'python-lzf' was replaced with 'python-neo-lzf'. Install may break on older environments if 'python-neo-lzf' is not available for your platform (aarch64 fallback exists but can be problematic).

fix

Ensure your system supports python-neo-lzf. If installation fails, try pinning pypcd4<=1.3.0 or installing with --no-deps and manually adding python-lzf.

affects: >=1.4.0

gotchaPointCloud.pc_data is a numpy structured array, and field access uses column names (e.g., 'x', 'y', 'z', 'rgb'). Attempting to access by index on the structured array may produce unexpected results.

fix

Access fields by name: pc.pc_data['x'], pc.pc_data['y'], pc.pc_data['z']. For RGB, note that it's packed into a 32-bit integer; use pc.pc_data['rgb'] and unpack with view(np.uint8).

affects: all

gotchaWhen creating from lists using 'from_list', all PointCloud objects must share the same field names/types. Mixing different fields will raise a ValueError.

fix

Ensure all point clouds to merge have identical schema. Use PointCloud.fields to inspect before merging.

affects: >=1.2.0

gotchaSaving to a file with extension other than .pcd is allowed but may cause issues with other PCD readers. The library does not validate the extension.

fix

Always use .pcd extension for compatibility.

affects: all

Errors

Common errors & fixes

AttributeError: module 'pypcd4' has no attribute 'PointCloud'

Using wrong import path or installing older/conflicting package (e.g., pypcd instead of pypcd4).

fix

Install pypcd4 (pip install pypcd4) and import correctly: from pypcd4 import PointCloud

ModuleNotFoundError: No module named 'lzf'

Missing lzf dependency when using binary_compressed PCD format.

fix

Install pypcd4 with its dependencies: pip install pypcd4. For Python<3.8, you may need to manually install python-neo-lzf or python-lzf.

ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

Attempting to compare numpy arrays from pc_data in a boolean context, e.g., if pc.pc_data['x'] == 0:

fix

Use numpy element-wise comparison: pc.pc_data['x'][pc.pc_data['x'] == 0] or (pc.pc_data['x'] == 0).any()

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x...

Reading a PCD file with binary encoding as binary_compressed, or vice versa. The library auto-detects but can fail if file is malformed.

fix

Check the PCD file header to determine correct encoding. Use PointCloud.from_path(filename) for auto-detection.

Upgrade

Version history

1.4.3latest on PyPI · released Jan 7, 2026

Audit

Dependencies

numpyrequiredPointCloud data is stored as numpy arrays

python-neo-lzfrequiredHandles LZF decompression for binary_compressed PCD files

pydanticrequiredUsed for data validation and settings management

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/MapIV/pypcd4 ↗

packagehttps://pypi.org/project/pypcd4/ ↗

changeloghttps://github.com/MapIV/pypcd4/releases ↗