Skip to main content

Read and write PCL .pcd files in python.

Project description

``pypcd``
=========

What?
-----

Pure Python module to read and write point clouds stored in the
`PCD file format <http://pointclouds.org/documentation/tutorials/pcd_file_format.php>`__,
used by the `Point Cloud Library <http://pointclouds.org/>`__.

Why?
----

You want to mess around with your point cloud data without writing C++
and waiting hours for the template-heavy PCL code to compile.

You tried to get some of the Python bindings for PCL to compile
and just gave up.

How does it work?
-----------------

It parses the PCD header and loads the data (whether in ``ascii``,
``binary`` or ``binary_compressed`` format) as a
`Numpy <http://www.numpy.org>`__ structured array. It creates an
instance of the ``PointCloud``
class, containing the point cloud data as ``pc_data``, and
some convenience functions for I/O and metadata access.
See the comments in ``pypcd.py`` for some info on the point cloud
structure.

Example
-------

.. code:: python

import pypcd
# also can read from file handles.
pc = pypcd.PointCloud.from_path('foo.pcd')
# pc.pc_data has the data as a structured array
# pc.fields, pc.count, etc have the metadata

# center the x field
pc.pc_data['x'] -= pc.pc_data['x'].mean()

# save as binary compressed
pc.save_pcd('bar.pcd', compression='binary_compressed')


How to install
--------------

.. code:: bash

pip install pypcd

That's it! You may want to install optional dependencies such as `pandas
<https://pandas.pydata.org>`__.

You can also clone this repo and use setup.py.

.. code:: bash

git clone https://github.com/dimatura/pypcd

Note that downloading data assets will
require `git-lfs <https://git-lfs.github.com>`__.


Using with ROS
---------------

You can also use this library with ROS ``sensor_msgs``, but it is *not* a dependency.
You don't need to install this package with catkin -- using `pip` should be fine --
but if you want to it is possible:

Steps:

.. code:: bash
# you need to do this manually in this case
pip install python-lzf
cd your_workspace/src
git clone https://github.com/dimatura/pypcd
mv setup_ros.py setup.py
catkin build pypcd
source ../devel/setup.bash


Then you can do something like this:

.. code:: python

import pypcd
import rospy
from sensor_msgs.msg import PointCloud2


def cb(msg):
pc = PointCloud.from_msg(msg)
pc.save('foo.pcd', compression='binary_compressed')
# maybe manipulate your pointcloud
pc.pc_data['x'] *= -1
outmsg = pc.to_msg()
# you'll probably need to set the header
outmsg.header = msg.header
pub.publish(outmsg)

# ...
sub = rospy.Subscriber('incloud', PointCloud2)
pub = rospy.Publisher('outcloud', PointCloud2, cb)
rospy.init('pypcd_node')
rospy.spin()



Is it beautiful, production-ready code?
---------------------------------------

No.

What else can it do?
--------------------

There's a bunch of functionality accumulated
over time, much of it hackish and untested.
In no particular order,

- Supports ``ascii``, ``binary`` and ``binary_compressed`` data.
The latter requires the ``lzf`` module.
- Decode and encode RGB into a single ``float32`` number. If
you don't know what I'm talking about consider yourself lucky.
- Point clouds to `pandas <https://pandas.pydata.org>`__ dataframes.
This in particular is quite useful,
since `pandas` is pretty powerful and makes various operations
such as merging point clouds or manipulating values easy.
Conceptually, data frames are a good match to the point cloud format, since
many point clouds in reality have heterogeneous data types - e.g.
`x`, `y` and `z` are float fields but `label` is an int.
- Convert to and from `ROS <http://www.ros.org>`__ PointCloud2
messages.
Requires the ROS ``sensor_msgs`` package with Python bindings
installed.
This functionality uses code developed by Jon Binney under
the BSD license, included as ``numpy_pc2.py``.

What can't it do?
-----------------

There's no synchronization between the metadata fields in
``PointCloud``
and the data in ``pc_data``. If you change the shape of ``pc_data``
without updating the metadata fields you'll run into trouble.

I've only used it for unorganized point cloud data
(in PCD conventions, ``height=1``), not organized
data like what you get from RGBD.
However, some things may still work.

While padding and fields with count larger
than 1 seem to work, this is a somewhat
ad-hoc aspect of the PCD format, so be careful.
If you want to be safe, you're probably better off
using neither -- just name each component
of your field something like ``FIELD_00``, ``FIELD_01``, etc.

It also can't run on Python 3, yet, but there's a PR to fix this
that might get pulled in the near future.

It's slow!
----------

Try using ``binary`` or ``binary_compressed``; using
ASCII is slow and takes up a lot of space, not to
mention possibly inaccurate if you're not careful
with how you format your floats.

I found a bug / I added a feature / I made your code cleaner
------------------------------------------------------------

Thanks! You can submit a pull request. But honestly, I'm not too good
at keeping up with my github :(


TODO
----

- Better API for various operations.
- Clean up, get rid of cruft.
- Add a cli for common use cases like file type conversion.
- Better support for structured point clouds, with tests.
- Better testing.
- Better docs. More examples.
- More testing of padding
- Improve handling of multicount fields
- Better support for rgb nonsense
- Export to ply?
- Figure out if it's acceptable to use "pointcloud" as a single word.
- Package data assets in pypi?


Credits
-------

The code for compressed point cloud data was informed by looking at
`Matlab
PCL <https://www.mathworks.com/matlabcentral/fileexchange/40382-matlab-to-point-cloud-library?requestedDomain=true>`__.

@wkentaro for some minor changes.

I used `cookiecutter <https://github.com/audreyr/cookiecutter>`__ to
help with the packaging.

The code in ``numpy_pc2.py`` was developed by Jon Binney under
the BSD license for `ROS <http://www.ros.org>`__.

I want to congratulate you / insult you
---------------------------------------

My email is ``dimatura@cmu.edu``.

Copyright (C) 2015-2017 Daniel Maturana


=======
History
=======

0.1.0 (2018-03-15)
------------------

* First release on PyPI.


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pypcd-0.1.1.tar.gz (19.5 kB view hashes)

Uploaded Source

Built Distribution

pypcd-0.1.1-py2.py3-none-any.whl (22.1 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page