Metadata-Version: 1.1
Name: pypcd
Version: 0.1.1
Summary: Read and write PCL .pcd files in python.
Home-page: https://github.com/dimatura/pypcd
Author: Daniel Maturana
Author-email: dimatura@gmail.com
License: BSD license
Description-Content-Type: UNKNOWN
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.
        
Keywords: pypcd
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Multimedia :: Graphics :: Capture
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
