Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/io/include/pcl/io/pcd_io.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2011, Willow Garage, Inc.
00006  *
00007  *  All rights reserved.
00008  *
00009  *  Redistribution and use in source and binary forms, with or without
00010  *  modification, are permitted provided that the following conditions
00011  *  are met:
00012  *
00013  *   * Redistributions of source code must retain the above copyright
00014  *     notice, this list of conditions and the following disclaimer.
00015  *   * Redistributions in binary form must reproduce the above
00016  *     copyright notice, this list of conditions and the following
00017  *     disclaimer in the documentation and/or other materials provided
00018  *     with the distribution.
00019  *   * Neither the name of the copyright holder(s) nor the names of its
00020  *     contributors may be used to endorse or promote products derived
00021  *     from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00027  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034  *  POSSIBILITY OF SUCH DAMAGE.
00035  *
00036  * $Id$
00037  *
00038  */
00039 
00040 #ifndef PCL_IO_PCD_IO_H_
00041 #define PCL_IO_PCD_IO_H_
00042 
00043 #include <pcl/point_cloud.h>
00044 #include <pcl/io/file_io.h>
00045 
00046 namespace pcl
00047 {
00048   /** \brief Point Cloud Data (PCD) file format reader.
00049     * \author Radu B. Rusu
00050     * \ingroup io
00051     */
00052   class PCL_EXPORTS PCDReader : public FileReader
00053   {
00054     public:
00055       /** Empty constructor */
00056       PCDReader () : FileReader () {}
00057       /** Empty destructor */
00058       ~PCDReader () {}
00059 
00060       /** \brief Various PCD file versions.
00061         *
00062         * PCD_V6 represents PCD files with version 0.6, which contain the following fields:
00063         *   - lines beginning with # are treated as comments
00064         *   - FIELDS ...
00065         *   - SIZE ...
00066         *   - TYPE ...
00067         *   - COUNT ...
00068         *   - WIDTH ...
00069         *   - HEIGHT ...
00070         *   - POINTS ...
00071         *   - DATA ascii/binary
00072         * 
00073         * Everything that follows \b DATA is intepreted as data points and
00074         * will be read accordingly.
00075         *
00076         * PCD_V7 represents PCD files with version 0.7 and has an important
00077         * addon: it adds sensor origin/orientation (aka viewpoint) information
00078         * to a dataset through the use of a new header field:
00079         *   - VIEWPOINT tx ty tz qw qx qy qz
00080         */
00081       enum
00082       {
00083         PCD_V6 = 0,
00084         PCD_V7 = 1
00085       };
00086 
00087       /** \brief Read a point cloud data header from a PCD file. 
00088         *
00089         * Load only the meta information (number of points, their types, etc),
00090         * and not the points themselves, from a given PCD file. Useful for fast
00091         * evaluation of the underlying data structure.
00092         *
00093         * \attention The PCD data is \b always stored in ROW major format! The
00094         * read/write PCD methods will detect column major input and automatically convert it.
00095         *
00096         * \param[in] file_name the name of the file to load
00097         * \param[out] cloud the resultant point cloud dataset (only the header will be filled)
00098         * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
00099         * \param[out] orientation the sensor acquisition orientation (only for > PCD_V7 - identity if not present)
00100         * \param[out] pcd_version the PCD version of the file (i.e., PCD_V6, PCD_V7)
00101         * \param[out] data_type the type of data (0 = ASCII, 1 = Binary, 2 = Binary compressed) 
00102         * \param[out] data_idx the offset of cloud data within the file
00103         * \param[in] offset the offset of where to expect the PCD Header in the
00104         * file (optional parameter). One usage example for setting the offset
00105         * parameter is for reading data from a TAR "archive containing multiple
00106         * PCD files: TAR files always add a 512 byte header in front of the
00107         * actual file, so set the offset to the next byte after the header
00108         * (e.g., 513).
00109         *
00110         * \return
00111         *  * < 0 (-1) on error
00112         *  * == 0 on success
00113         */
00114       int 
00115       readHeader (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
00116                   Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version,
00117                   int &data_type, unsigned int &data_idx, const int offset = 0);
00118 
00119 
00120       /** \brief Read a point cloud data header from a PCD file. 
00121         *
00122         * Load only the meta information (number of points, their types, etc),
00123         * and not the points themselves, from a given PCD file. Useful for fast
00124         * evaluation of the underlying data structure.
00125         *
00126         * \attention The PCD data is \b always stored in ROW major format! The
00127         * read/write PCD methods will detect column major input and automatically convert it.
00128         *
00129         * \param[in] file_name the name of the file to load
00130         * \param[out] cloud the resultant point cloud dataset (only the header will be filled)
00131         * \param[in] offset the offset of where to expect the PCD Header in the
00132         * file (optional parameter). One usage example for setting the offset
00133         * parameter is for reading data from a TAR "archive containing multiple
00134         * PCD files: TAR files always add a 512 byte header in front of the
00135         * actual file, so set the offset to the next byte after the header
00136         * (e.g., 513).
00137         *
00138         * \return
00139         *  * < 0 (-1) on error
00140         *  * == 0 on success
00141         */
00142       int 
00143       readHeader (const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset = 0);
00144 
00145       /** \brief Read a point cloud data from a PCD file and store it into a pcl/PCLPointCloud2.
00146         * \param[in] file_name the name of the file containing the actual PointCloud data
00147         * \param[out] cloud the resultant PointCloud message read from disk
00148         * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
00149         * \param[out] orientation the sensor acquisition orientation (only for > PCD_V7 - identity if not present)
00150         * \param[out] pcd_version the PCD version of the file (either PCD_V6 or PCD_V7)
00151         * \param[in] offset the offset of where to expect the PCD Header in the
00152         * file (optional parameter). One usage example for setting the offset
00153         * parameter is for reading data from a TAR "archive containing multiple
00154         * PCD files: TAR files always add a 512 byte header in front of the
00155         * actual file, so set the offset to the next byte after the header
00156         * (e.g., 513).
00157         *
00158         * \return
00159         *  * < 0 (-1) on error
00160         *  * == 0 on success
00161         */
00162       int 
00163       read (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
00164             Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version, const int offset = 0);
00165 
00166       /** \brief Read a point cloud data from a PCD (PCD_V6) and store it into a pcl/PCLPointCloud2.
00167         * 
00168         * \note This function is provided for backwards compatibility only and
00169         * it can only read PCD_V6 files correctly, as pcl::PCLPointCloud2
00170         * does not contain a sensor origin/orientation. Reading any file 
00171         * > PCD_V6 will generate a warning. 
00172         *
00173         * \param[in] file_name the name of the file containing the actual PointCloud data
00174         * \param[out] cloud the resultant PointCloud message read from disk
00175         * \param[in] offset the offset of where to expect the PCD Header in the
00176         * file (optional parameter). One usage example for setting the offset
00177         * parameter is for reading data from a TAR "archive containing multiple
00178         * PCD files: TAR files always add a 512 byte header in front of the
00179         * actual file, so set the offset to the next byte after the header
00180         * (e.g., 513).
00181         *
00182         * \return
00183         *  * < 0 (-1) on error
00184         *  * == 0 on success
00185         */
00186       int 
00187       read (const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset = 0);
00188 
00189       /** \brief Read a point cloud data from any PCD file, and convert it to the given template format.
00190         * \param[in] file_name the name of the file containing the actual PointCloud data
00191         * \param[out] cloud the resultant PointCloud message read from disk
00192         * \param[in] offset the offset of where to expect the PCD Header in the
00193         * file (optional parameter). One usage example for setting the offset
00194         * parameter is for reading data from a TAR "archive containing multiple
00195         * PCD files: TAR files always add a 512 byte header in front of the
00196         * actual file, so set the offset to the next byte after the header
00197         * (e.g., 513).
00198         *
00199         * \return
00200         *  * < 0 (-1) on error
00201         *  * == 0 on success
00202         */
00203       template<typename PointT> int
00204       read (const std::string &file_name, pcl::PointCloud<PointT> &cloud, const int offset = 0)
00205       {
00206         pcl::PCLPointCloud2 blob;
00207         int pcd_version;
00208         int res = read (file_name, blob, cloud.sensor_origin_, cloud.sensor_orientation_, 
00209                         pcd_version, offset);
00210 
00211         // If no error, convert the data
00212         if (res == 0)
00213           pcl::fromPCLPointCloud2 (blob, cloud);
00214         return (res);
00215       }
00216 
00217       EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00218   };
00219 
00220   /** \brief Point Cloud Data (PCD) file format writer.
00221     * \author Radu Bogdan Rusu
00222     * \ingroup io
00223     */
00224   class PCL_EXPORTS PCDWriter : public FileWriter
00225   {
00226     public:
00227       PCDWriter() : FileWriter(), map_synchronization_(false) {}
00228       ~PCDWriter() {}
00229 
00230       /** \brief Set whether mmap() synchornization via msync() is desired before munmap() calls. 
00231         * Setting this to true could prevent NFS data loss (see
00232         * http://www.pcl-developers.org/PCD-IO-consistency-on-NFS-msync-needed-td4885942.html).
00233         * Default: false
00234         * \note This option should be used by advanced users only!
00235         * \note Please note that using msync() on certain systems can reduce the I/O performance by up to 80%!
00236         * \param[in] sync set to true if msync() should be called before munmap()
00237         */
00238       void
00239       setMapSynchronization (bool sync)
00240       {
00241         map_synchronization_ = sync;
00242       }
00243 
00244       /** \brief Generate the header of a PCD file format
00245         * \param[in] cloud the point cloud data message
00246         * \param[in] origin the sensor acquisition origin
00247         * \param[in] orientation the sensor acquisition orientation
00248         */
00249       std::string
00250       generateHeaderBinary (const pcl::PCLPointCloud2 &cloud,
00251                             const Eigen::Vector4f &origin, 
00252                             const Eigen::Quaternionf &orientation);
00253 
00254       /** \brief Generate the header of a BINARY_COMPRESSED PCD file format
00255         * \param[in] cloud the point cloud data message
00256         * \param[in] origin the sensor acquisition origin
00257         * \param[in] orientation the sensor acquisition orientation
00258         */
00259       std::string
00260       generateHeaderBinaryCompressed (const pcl::PCLPointCloud2 &cloud,
00261                                       const Eigen::Vector4f &origin, 
00262                                       const Eigen::Quaternionf &orientation);
00263 
00264       /** \brief Generate the header of a PCD file format
00265         * \param[in] cloud the point cloud data message
00266         * \param[in] origin the sensor acquisition origin
00267         * \param[in] orientation the sensor acquisition orientation
00268         */
00269       std::string
00270       generateHeaderASCII (const pcl::PCLPointCloud2 &cloud,
00271                            const Eigen::Vector4f &origin, 
00272                            const Eigen::Quaternionf &orientation);
00273 
00274       /** \brief Generate the header of a PCD file format
00275         * \param[in] cloud the point cloud data message
00276         * \param[in] nr_points if given, use this to fill in WIDTH, HEIGHT (=1), and POINTS in the header
00277         * By default, nr_points is set to INTMAX, and the data in the header is used instead.
00278         */
00279       template <typename PointT> static std::string
00280       generateHeader (const pcl::PointCloud<PointT> &cloud, 
00281                       const int nr_points = std::numeric_limits<int>::max ());
00282 
00283       /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
00284         * \param[in] file_name the output file name
00285         * \param[in] cloud the point cloud data message
00286         * \param[in] origin the sensor acquisition origin
00287         * \param[in] orientation the sensor acquisition orientation
00288         * \param[in] precision the specified output numeric stream precision (default: 8)
00289         *
00290         * Caution: PointCloud structures containing an RGB field have
00291         * traditionally used packed float values to store RGB data. Storing a
00292         * float as ASCII can introduce variations to the smallest bits, and
00293         * thus significantly alter the data. This is a known issue, and the fix
00294         * involves switching RGB data to be stored as a packed integer in
00295         * future versions of PCL.
00296         *
00297         * As an intermediary solution, precision 8 is used, which guarantees lossless storage for RGB.
00298         */
00299       int 
00300       writeASCII (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
00301                   const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00302                   const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
00303                   const int precision = 8);
00304 
00305       /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
00306         * \param[in] file_name the output file name
00307         * \param[in] cloud the point cloud data message
00308         * \param[in] origin the sensor acquisition origin
00309         * \param[in] orientation the sensor acquisition orientation
00310         */
00311       int 
00312       writeBinary (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
00313                    const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00314                    const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
00315 
00316       /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY_COMPRESSED format
00317         * \param[in] file_name the output file name
00318         * \param[in] cloud the point cloud data message
00319         * \param[in] origin the sensor acquisition origin
00320         * \param[in] orientation the sensor acquisition orientation
00321         */
00322       int 
00323       writeBinaryCompressed (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
00324                              const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00325                              const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
00326 
00327       /** \brief Save point cloud data to a PCD file containing n-D points
00328         * \param[in] file_name the output file name
00329         * \param[in] cloud the point cloud data message
00330         * \param[in] origin the sensor acquisition origin
00331         * \param[in] orientation the sensor acquisition orientation
00332         * \param[in] binary set to true if the file is to be written in a binary
00333         * PCD format, false (default) for ASCII
00334         *
00335         * Caution: PointCloud structures containing an RGB field have
00336         * traditionally used packed float values to store RGB data. Storing a
00337         * float as ASCII can introduce variations to the smallest bits, and
00338         * thus significantly alter the data. This is a known issue, and the fix
00339         * involves switching RGB data to be stored as a packed integer in
00340         * future versions of PCL.
00341         *
00342         * As an intermediary solution, precision 8 is used, which guarantees lossless storage for RGB.
00343         */
00344       inline int
00345       write (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
00346              const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00347              const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
00348              const bool binary = false)
00349       {
00350         if (binary)
00351           return (writeBinary (file_name, cloud, origin, orientation));
00352         else
00353           return (writeASCII (file_name, cloud, origin, orientation, 8));
00354       }
00355 
00356       /** \brief Save point cloud data to a PCD file containing n-D points
00357         * \param[in] file_name the output file name
00358         * \param[in] cloud the point cloud data message (boost shared pointer)
00359         * \param[in] binary set to true if the file is to be written in a binary PCD format, 
00360         * false (default) for ASCII
00361         * \param[in] origin the sensor acquisition origin
00362         * \param[in] orientation the sensor acquisition orientation
00363         *
00364         * Caution: PointCloud structures containing an RGB field have
00365         * traditionally used packed float values to store RGB data. Storing a
00366         * float as ASCII can introduce variations to the smallest bits, and
00367         * thus significantly alter the data. This is a known issue, and the fix
00368         * involves switching RGB data to be stored as a packed integer in
00369         * future versions of PCL.
00370         */
00371       inline int
00372       write (const std::string &file_name, const pcl::PCLPointCloud2::ConstPtr &cloud,
00373              const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00374              const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
00375              const bool binary = false)
00376       {
00377         return (write (file_name, *cloud, origin, orientation, binary));
00378       }
00379 
00380       /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
00381         * \param[in] file_name the output file name
00382         * \param[in] cloud the point cloud data message
00383         */
00384       template <typename PointT> int 
00385       writeBinary (const std::string &file_name, 
00386                    const pcl::PointCloud<PointT> &cloud);
00387 
00388       /** \brief Save point cloud data to a binary comprssed PCD file
00389         * \param[in] file_name the output file name
00390         * \param[in] cloud the point cloud data message
00391         */
00392       template <typename PointT> int 
00393       writeBinaryCompressed (const std::string &file_name, 
00394                              const pcl::PointCloud<PointT> &cloud);
00395 
00396       /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
00397         * \param[in] file_name the output file name
00398         * \param[in] cloud the point cloud data message
00399         * \param[in] indices the set of point indices that we want written to disk
00400         */
00401       template <typename PointT> int 
00402       writeBinary (const std::string &file_name, 
00403                    const pcl::PointCloud<PointT> &cloud, 
00404                    const std::vector<int> &indices);
00405 
00406       /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
00407         * \param[in] file_name the output file name
00408         * \param[in] cloud the point cloud data message
00409         * \param[in] precision the specified output numeric stream precision (default: 8)
00410         */
00411       template <typename PointT> int 
00412       writeASCII (const std::string &file_name, 
00413                   const pcl::PointCloud<PointT> &cloud,
00414                   const int precision = 8);
00415 
00416        /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
00417         * \param[in] file_name the output file name
00418         * \param[in] cloud the point cloud data message
00419         * \param[in] indices the set of point indices that we want written to disk
00420         * \param[in] precision the specified output numeric stream precision (default: 8)
00421         */
00422       template <typename PointT> int 
00423       writeASCII (const std::string &file_name, 
00424                   const pcl::PointCloud<PointT> &cloud,
00425                   const std::vector<int> &indices,
00426                   const int precision = 8);
00427 
00428       /** \brief Save point cloud data to a PCD file containing n-D points
00429         * \param[in] file_name the output file name
00430         * \param[in] cloud the pcl::PointCloud data
00431         * \param[in] binary set to true if the file is to be written in a binary
00432         * PCD format, false (default) for ASCII
00433         *
00434         * Caution: PointCloud structures containing an RGB field have
00435         * traditionally used packed float values to store RGB data. Storing a
00436         * float as ASCII can introduce variations to the smallest bits, and
00437         * thus significantly alter the data. This is a known issue, and the fix
00438         * involves switching RGB data to be stored as a packed integer in
00439         * future versions of PCL.
00440         */
00441       template<typename PointT> inline int
00442       write (const std::string &file_name, 
00443              const pcl::PointCloud<PointT> &cloud, 
00444              const bool binary = false)
00445       {
00446         if (binary)
00447           return (writeBinary<PointT> (file_name, cloud));
00448         else
00449           return (writeASCII<PointT> (file_name, cloud));
00450       }
00451 
00452       /** \brief Save point cloud data to a PCD file containing n-D points
00453         * \param[in] file_name the output file name
00454         * \param[in] cloud the pcl::PointCloud data
00455         * \param[in] indices the set of point indices that we want written to disk
00456         * \param[in] binary set to true if the file is to be written in a binary
00457         * PCD format, false (default) for ASCII
00458         *
00459         * Caution: PointCloud structures containing an RGB field have
00460         * traditionally used packed float values to store RGB data. Storing a
00461         * float as ASCII can introduce variations to the smallest bits, and
00462         * thus significantly alter the data. This is a known issue, and the fix
00463         * involves switching RGB data to be stored as a packed integer in
00464         * future versions of PCL.
00465         */
00466       template<typename PointT> inline int
00467       write (const std::string &file_name, 
00468              const pcl::PointCloud<PointT> &cloud, 
00469              const std::vector<int> &indices,
00470              bool binary = false)
00471       {
00472         if (binary)
00473           return (writeBinary<PointT> (file_name, cloud, indices));
00474         else
00475           return (writeASCII<PointT> (file_name, cloud, indices));
00476       }
00477 
00478     protected:
00479       /** \brief Set permissions for file locking (Boost 1.49+).
00480         * \param[in] file_name the file name to set permission for file locking
00481         * \param[in,out] lock the file lock
00482         */
00483       void
00484       setLockingPermissions (const std::string &file_name,
00485                              boost::interprocess::file_lock &lock);
00486 
00487       /** \brief Reset permissions for file locking (Boost 1.49+).
00488         * \param[in] file_name the file name to reset permission for file locking
00489         * \param[in,out] lock the file lock
00490         */
00491       void
00492       resetLockingPermissions (const std::string &file_name,
00493                                boost::interprocess::file_lock &lock);
00494 
00495     private:
00496       /** \brief Set to true if msync() should be called before munmap(). Prevents data loss on NFS systems. */
00497       bool map_synchronization_;
00498   };
00499 
00500   namespace io
00501   {
00502     /** \brief Load a PCD v.6 file into a templated PointCloud type.
00503       * 
00504       * Any PCD files > v.6 will generate a warning as a
00505       * pcl/PCLPointCloud2 message cannot hold the sensor origin.
00506       *
00507       * \param[in] file_name the name of the file to load
00508       * \param[out] cloud the resultant templated point cloud
00509       * \ingroup io
00510       */
00511     inline int 
00512     loadPCDFile (const std::string &file_name, pcl::PCLPointCloud2 &cloud)
00513     {
00514       pcl::PCDReader p;
00515       return (p.read (file_name, cloud));
00516     }
00517 
00518     /** \brief Load any PCD file into a templated PointCloud type.
00519       * \param[in] file_name the name of the file to load
00520       * \param[out] cloud the resultant templated point cloud
00521       * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
00522       * \param[out] orientation the sensor acquisition orientation (only for >
00523       * PCD_V7 - identity if not present)
00524       * \ingroup io
00525       */
00526     inline int 
00527     loadPCDFile (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
00528                  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation)
00529     {
00530       pcl::PCDReader p;
00531       int pcd_version;
00532       return (p.read (file_name, cloud, origin, orientation, pcd_version));
00533     }
00534 
00535     /** \brief Load any PCD file into a templated PointCloud type
00536       * \param[in] file_name the name of the file to load
00537       * \param[out] cloud the resultant templated point cloud
00538       * \ingroup io
00539       */
00540     template<typename PointT> inline int
00541     loadPCDFile (const std::string &file_name, pcl::PointCloud<PointT> &cloud)
00542     {
00543       pcl::PCDReader p;
00544       return (p.read (file_name, cloud));
00545     }
00546 
00547     /** \brief Save point cloud data to a PCD file containing n-D points
00548       * \param[in] file_name the output file name
00549       * \param[in] cloud the point cloud data message
00550       * \param[in] origin the sensor acquisition origin
00551       * \param[in] orientation the sensor acquisition orientation
00552       * \param[in] binary_mode true for binary mode, false (default) for ASCII
00553       *
00554       * Caution: PointCloud structures containing an RGB field have
00555       * traditionally used packed float values to store RGB data. Storing a
00556       * float as ASCII can introduce variations to the smallest bits, and
00557       * thus significantly alter the data. This is a known issue, and the fix
00558       * involves switching RGB data to be stored as a packed integer in
00559       * future versions of PCL.
00560       * \ingroup io
00561       */
00562     inline int 
00563     savePCDFile (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
00564                  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (), 
00565                  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
00566                  const bool binary_mode = false)
00567     {
00568       PCDWriter w;
00569       return (w.write (file_name, cloud, origin, orientation, binary_mode));
00570     }
00571 
00572     /** \brief Templated version for saving point cloud data to a PCD file
00573       * containing a specific given cloud format
00574       * \param[in] file_name the output file name
00575       * \param[in] cloud the point cloud data message
00576       * \param[in] binary_mode true for binary mode, false (default) for ASCII
00577       *
00578       * Caution: PointCloud structures containing an RGB field have
00579       * traditionally used packed float values to store RGB data. Storing a
00580       * float as ASCII can introduce variations to the smallest bits, and
00581       * thus significantly alter the data. This is a known issue, and the fix
00582       * involves switching RGB data to be stored as a packed integer in
00583       * future versions of PCL.
00584       * \ingroup io
00585       */
00586     template<typename PointT> inline int
00587     savePCDFile (const std::string &file_name, const pcl::PointCloud<PointT> &cloud, bool binary_mode = false)
00588     {
00589       PCDWriter w;
00590       return (w.write<PointT> (file_name, cloud, binary_mode));
00591     }
00592 
00593     /** 
00594       * \brief Templated version for saving point cloud data to a PCD file
00595       * containing a specific given cloud format.
00596       *
00597       *      This version is to retain backwards compatibility.
00598       * \param[in] file_name the output file name
00599       * \param[in] cloud the point cloud data message
00600       *
00601       * Caution: PointCloud structures containing an RGB field have
00602       * traditionally used packed float values to store RGB data. Storing a
00603       * float as ASCII can introduce variations to the smallest bits, and
00604       * thus significantly alter the data. This is a known issue, and the fix
00605       * involves switching RGB data to be stored as a packed integer in
00606       * future versions of PCL.
00607       * \ingroup io
00608       */
00609     template<typename PointT> inline int
00610     savePCDFileASCII (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
00611     {
00612       PCDWriter w;
00613       return (w.write<PointT> (file_name, cloud, false));
00614     }
00615 
00616     /** 
00617       * \brief Templated version for saving point cloud data to a PCD file
00618       * containing a specific given cloud format. The resulting file will be an uncompressed binary.
00619       *
00620       *      This version is to retain backwards compatibility.
00621       * \param[in] file_name the output file name
00622       * \param[in] cloud the point cloud data message
00623       * \ingroup io
00624       */
00625     template<typename PointT> inline int
00626     savePCDFileBinary (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
00627     {
00628       PCDWriter w;
00629       return (w.write<PointT> (file_name, cloud, true));
00630     }
00631 
00632     /** 
00633       * \brief Templated version for saving point cloud data to a PCD file
00634       * containing a specific given cloud format
00635       *
00636       * \param[in] file_name the output file name
00637       * \param[in] cloud the point cloud data message
00638       * \param[in] indices the set of indices to save
00639       * \param[in] binary_mode true for binary mode, false (default) for ASCII
00640       *
00641       * Caution: PointCloud structures containing an RGB field have
00642       * traditionally used packed float values to store RGB data. Storing a
00643       * float as ASCII can introduce variations to the smallest bits, and
00644       * thus significantly alter the data. This is a known issue, and the fix
00645       * involves switching RGB data to be stored as a packed integer in
00646       * future versions of PCL.
00647       * \ingroup io
00648       */
00649     template<typename PointT> int
00650     savePCDFile (const std::string &file_name, 
00651                  const pcl::PointCloud<PointT> &cloud,
00652                  const std::vector<int> &indices, 
00653                  const bool binary_mode = false)
00654     {
00655       // Save the data
00656       PCDWriter w;
00657       return (w.write<PointT> (file_name, cloud, indices, binary_mode));
00658     }
00659 
00660 
00661     /**
00662       * \brief Templated version for saving point cloud data to a PCD file
00663       * containing a specific given cloud format. This method will write a compressed binary file.
00664       *
00665       *      This version is to retain backwards compatibility.
00666       * \param[in] file_name the output file name
00667       * \param[in] cloud the point cloud data message
00668       * \ingroup io
00669       */
00670     template<typename PointT> inline int
00671     savePCDFileBinaryCompressed (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
00672     {
00673       PCDWriter w;
00674       return (w.writeBinaryCompressed<PointT> (file_name, cloud));
00675     }
00676 
00677   }
00678 }
00679 
00680 #include <pcl/io/impl/pcd_io.hpp>
00681 
00682 #endif  //#ifndef PCL_IO_PCD_IO_H_