Metadata-Version: 2.2
Name: pypointcloud
Version: 0.1.0
Summary: Lightweight Python library for loading PCD (Point Cloud Data) files with arbitrary data fields and types directly into NumPy
Keywords: point cloud,data loader,PCD
Author-Email: Dominik Kulmer <dominik.kulmer@tum.de>
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Project-URL: Homepage, https://github.com/ga58lar/pypointcloud
Requires-Python: >=3.8
Requires-Dist: numpy>=1.21.0
Description-Content-Type: text/markdown

<div align="center">
  <h1> pyPointCloud </h1>
  <img src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black" />
  <img src="https://img.shields.io/badge/Windows-0078D6?st&logo=windows&logoColor=white" />
  <img src="https://img.shields.io/badge/mac%20os-000000?&logo=apple&logoColor=white" />
  
  [![PyPI](https://github.com/ga58lar/pypointcloud/actions/workflows/pypi.yml/badge.svg)](https://github.com/ga58lar/pypointcloud/actions/workflows/pypi.yml)

  <img src="docs/logo.svg" alt="pypointcloud" width="600" style="margin-bottom: 30px;">

**pyPointCloud** is a lightweight Python library for loading PCD (Point Cloud Data) files directly into NumPy arrays.  
It is designed to support **arbitrary data fields and data types**, while keeping a simple and predictable data layout.

</div>

<hr/>

<h2> Installation </h2>

```bash
pip install pypointcloud
```

<h2> Overview </h2>

There are several Python libraries capable of loading PCD files, including:

- **open3d** – Easy to use, but limited in supported data fields and types.
- **pyntcloud** – Supports arbitrary fields, but is relatively slow.
- **pypcd4** – Very fast, supports arbitrary fields, and is well maintained.  
  It loads PCDs into its own class and allows conversion to NumPy arrays.

**General recommendation:**  
For most use cases, **pypcd4** is the preferred solution due to its speed, simplicity, and maintenance status.

<h2> Why pyPointcloud? </h2>

`pyPointCloud` focuses on a slightly different design choice:

- Loads **x, y, z** coordinates into a dedicated `float32` NumPy array
- Stores **all other fields** in a separate dictionary
- Preserves **original data types** for non-coordinate fields

This contrasts with `pypcd4`, which uses its own class or combines all fields into a single `float64` NumPy array.

Our approach can be beneficial when:
- You want to preserve original data types
- You only need fast access to XYZ coordinates
- You want a minimal dependency, NumPy-first workflow


<h2> Benchmark </h2>

Depending on the exact use case and application goal, pyPointCloud can outperform other PCD loaders.  
Note that this is a limited benchmark, and for most general-purpose scenarios, `pypcd4` remains the recommended choice.

```bash
python3 benchmark/benchmark.py

Benchmarking PCD loaders with /dev_ws/benchmark/../example/ascii.pcd (100 iterations)
pyntcloud:    0.08244 seconds per cloud
pypcd4:       0.07953 seconds per cloud
pypointcloud: 0.01884 seconds per cloud

Benchmarking PCD loaders with /dev_ws/benchmark/../example/binary.pcd (100 iterations)
pyntcloud:    0.00345 seconds per cloud
pypcd4:       0.00184 seconds per cloud
pypointcloud: 0.00077 seconds per cloud

Benchmarking PCD loaders with /dev_ws/benchmark/../example/binary_compressed.pcd (100 iterations)
pyntcloud:    0.00307 seconds per cloud
pypcd4:       0.00122 seconds per cloud
pypointcloud: 0.00053 seconds per cloud
```

<h2> Example </h2>

[example.py](example/example.py) provides a reference implementation for the usage of this library.  
It shows how to load clouds, to access data, to modifies data and to move the data to `PyTorch`.

<h2> License </h2>

This project uses the [Apache-2.0 license](LICENSE).  
This package uses `lzf` to decompress binary-compressed PCDs, certain parts of the application are subject to the terms specified in their [license](include/pypointcloud/lzf/LICENSE).

<h2> Contact </h2>

Dominik Kulmer 
[![GitHub](https://i.sstatic.net/tskMh.png)](https://github.com/ga58lar)
[![Linkedin](https://i.sstatic.net/gVE0j.png)](https://www.linkedin.com/in/dominik-kulmer/)
[✉️](mailto:dominik.kulmer@tum.de)
