``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.
0.1.1 (2018-03-15)
------------------
* Second release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/bochent/pypcd2/",
"name": "pypcd2",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "pypcd2",
"author": "tongbochen",
"author_email": "bochen.tong@outlook.com",
"download_url": null,
"platform": null,
"description": "``pypcd``\n=========\n\nWhat?\n-----\n\nPure Python module to read and write point clouds stored in the\n`PCD file format <http://pointclouds.org/documentation/tutorials/pcd_file_format.php>`__,\nused by the `Point Cloud Library <http://pointclouds.org/>`__.\n\nWhy?\n----\n\nYou want to mess around with your point cloud data without writing C++\nand waiting hours for the template-heavy PCL code to compile.\n\nYou tried to get some of the Python bindings for PCL to compile\nand just gave up.\n\nHow does it work?\n-----------------\n\nIt parses the PCD header and loads the data (whether in ``ascii``,\n``binary`` or ``binary_compressed`` format) as a\n`Numpy <http://www.numpy.org>`__ structured array. It creates an\ninstance of the ``PointCloud``\nclass, containing the point cloud data as ``pc_data``, and\nsome convenience functions for I/O and metadata access.\nSee the comments in ``pypcd.py`` for some info on the point cloud\nstructure.\n\nExample\n-------\n\n.. code:: python\n\n import pypcd\n # also can read from file handles.\n pc = pypcd.PointCloud.from_path('foo.pcd')\n # pc.pc_data has the data as a structured array\n # pc.fields, pc.count, etc have the metadata\n\n # center the x field\n pc.pc_data['x'] -= pc.pc_data['x'].mean()\n\n # save as binary compressed\n pc.save_pcd('bar.pcd', compression='binary_compressed')\n\n\nHow to install\n--------------\n\n.. code:: bash\n\n pip install pypcd\n\nThat's it! You may want to install optional dependencies such as `pandas\n<https://pandas.pydata.org>`__.\n\nYou can also clone this repo and use setup.py. \n\n.. code:: bash\n\n git clone https://github.com/dimatura/pypcd\n\nNote that downloading data assets will\nrequire `git-lfs <https://git-lfs.github.com>`__.\n\n\nUsing with ROS\n---------------\n\nYou can also use this library with ROS ``sensor_msgs``, but it is *not* a dependency.\nYou don't need to install this package with catkin -- using `pip` should be fine --\nbut if you want to it is possible:\n\nSteps:\n\n.. code:: bash\n\n # you need to do this manually in this case\n pip install python-lzf\n cd your_workspace/src\n git clone https://github.com/dimatura/pypcd\n mv setup_ros.py setup.py\n catkin build pypcd\n source ../devel/setup.bash\n\n\nThen you can do something like this:\n\n.. code:: python\n\n import pypcd\n import rospy\n from sensor_msgs.msg import PointCloud2\n\n\n def cb(msg):\n pc = PointCloud.from_msg(msg)\n pc.save('foo.pcd', compression='binary_compressed')\n # maybe manipulate your pointcloud\n pc.pc_data['x'] *= -1\n outmsg = pc.to_msg()\n # you'll probably need to set the header\n outmsg.header = msg.header\n pub.publish(outmsg)\n\n # ...\n sub = rospy.Subscriber('incloud', PointCloud2)\n pub = rospy.Publisher('outcloud', PointCloud2, cb)\n rospy.init('pypcd_node')\n rospy.spin()\n\n\n\nIs it beautiful, production-ready code?\n---------------------------------------\n\nNo.\n\nWhat else can it do?\n--------------------\n\nThere's a bunch of functionality accumulated\nover time, much of it hackish and untested.\nIn no particular order,\n\n- Supports ``ascii``, ``binary`` and ``binary_compressed`` data.\n The latter requires the ``lzf`` module.\n- Decode and encode RGB into a single ``float32`` number. If\n you don't know what I'm talking about consider yourself lucky.\n- Point clouds to `pandas <https://pandas.pydata.org>`__ dataframes. \n This in particular is quite useful,\n since `pandas` is pretty powerful and makes various operations\n such as merging point clouds or manipulating values easy.\n Conceptually, data frames are a good match to the point cloud format, since\n many point clouds in reality have heterogeneous data types - e.g.\n `x`, `y` and `z` are float fields but `label` is an int.\n- Convert to and from `ROS <http://www.ros.org>`__ PointCloud2\n messages.\n Requires the ROS ``sensor_msgs`` package with Python bindings\n installed.\n This functionality uses code developed by Jon Binney under\n the BSD license, included as ``numpy_pc2.py``.\n\nWhat can't it do?\n-----------------\n\nThere's no synchronization between the metadata fields in\n``PointCloud``\nand the data in ``pc_data``. If you change the shape of ``pc_data``\nwithout updating the metadata fields you'll run into trouble.\n\nI've only used it for unorganized point cloud data\n(in PCD conventions, ``height=1``), not organized\ndata like what you get from RGBD.\nHowever, some things may still work.\n\nWhile padding and fields with count larger\nthan 1 seem to work, this is a somewhat\nad-hoc aspect of the PCD format, so be careful.\nIf you want to be safe, you're probably better off\nusing neither -- just name each component\nof your field something like ``FIELD_00``, ``FIELD_01``, etc.\n\nIt also can't run on Python 3, yet, but there's a PR to fix this\nthat might get pulled in the near future.\n\nIt's slow!\n----------\n\nTry using ``binary`` or ``binary_compressed``; using\nASCII is slow and takes up a lot of space, not to\nmention possibly inaccurate if you're not careful\nwith how you format your floats.\n\nI found a bug / I added a feature / I made your code cleaner\n------------------------------------------------------------\n\nThanks! You can submit a pull request. But honestly, I'm not too good\nat keeping up with my github :(\n\n\nTODO\n----\n\n- Better API for various operations.\n- Clean up, get rid of cruft.\n- Add a cli for common use cases like file type conversion.\n- Better support for structured point clouds, with tests.\n- Better testing.\n- Better docs. More examples.\n- More testing of padding\n- Improve handling of multicount fields\n- Better support for rgb nonsense\n- Export to ply?\n- Figure out if it's acceptable to use \"pointcloud\" as a single word.\n- Package data assets in pypi?\n\n\nCredits\n-------\n\nThe code for compressed point cloud data was informed by looking at\n`Matlab\nPCL <https://www.mathworks.com/matlabcentral/fileexchange/40382-matlab-to-point-cloud-library?requestedDomain=true>`__.\n\n@wkentaro for some minor changes.\n\nI used `cookiecutter <https://github.com/audreyr/cookiecutter>`__ to\nhelp with the packaging.\n\nThe code in ``numpy_pc2.py`` was developed by Jon Binney under\nthe BSD license for `ROS <http://www.ros.org>`__.\n\nI want to congratulate you / insult you\n---------------------------------------\n\nMy email is ``dimatura@cmu.edu``.\n\nCopyright (C) 2015-2017 Daniel Maturana\n\n\n=======\nHistory\n=======\n\n0.1.0 (2018-03-15)\n------------------\n\n* First release on PyPI.\n\n0.1.1 (2018-03-15)\n------------------\n\n* Second release on PyPI.\n\n\n",
"bugtrack_url": null,
"license": "BSD license",
"summary": "Read and write PCL .pcd files in python. Forked from https://github.com/dimatura/pypcd/",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/bochent/pypcd2/"
},
"split_keywords": [
"pypcd2"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1927a74dd41801ad9087249266a905dc81ec9a67f076caec3bb743a28a2c3717",
"md5": "261ef8582d7b3e5e0a4bbf1f42825154",
"sha256": "0cbd00fc4e6d6dcbed91d78fbc4ebf443497b0f48af880e9b81d29e0ef43b383"
},
"downloads": -1,
"filename": "pypcd2-0.2.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "261ef8582d7b3e5e0a4bbf1f42825154",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 27792,
"upload_time": "2025-08-16T07:53:59",
"upload_time_iso_8601": "2025-08-16T07:53:59.423393Z",
"url": "https://files.pythonhosted.org/packages/19/27/a74dd41801ad9087249266a905dc81ec9a67f076caec3bb743a28a2c3717/pypcd2-0.2.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 07:53:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bochent",
"github_project": "pypcd2",
"github_not_found": true,
"lcname": "pypcd2"
}
JSON
