Point Cloud Library (PCL)  1.14.1-dev
pcd_io.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2011, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of the copyright holder(s) nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  * $Id$
37  *
38  */
39 
40 #pragma once
41 
42 #include <pcl/memory.h>
43 #include <pcl/pcl_macros.h>
44 #include <pcl/point_cloud.h>
45 #include <pcl/io/file_io.h>
46 #include <boost/interprocess/sync/file_lock.hpp> // for file_lock
47 
48 namespace pcl
49 {
50  /** \brief Point Cloud Data (PCD) file format reader.
51  * \author Radu B. Rusu
52  * \ingroup io
53  */
55  {
56  public:
57  /** Empty constructor */
58  PCDReader () = default;
59  /** Empty destructor */
60  ~PCDReader () override = default;
61 
62  /** \brief Various PCD file versions.
63  *
64  * PCD_V6 represents PCD files with version 0.6, which contain the following fields:
65  * - lines beginning with # are treated as comments
66  * - FIELDS ...
67  * - SIZE ...
68  * - TYPE ...
69  * - COUNT ...
70  * - WIDTH ...
71  * - HEIGHT ...
72  * - POINTS ...
73  * - DATA ascii/binary
74  *
75  * Everything that follows \b DATA is interpreted as data points and
76  * will be read accordingly.
77  *
78  * PCD_V7 represents PCD files with version 0.7 and has an important
79  * addon: it adds sensor origin/orientation (aka viewpoint) information
80  * to a dataset through the use of a new header field:
81  * - VIEWPOINT tx ty tz qw qx qy qz
82  */
83  enum
84  {
85  PCD_V6 = 0,
86  PCD_V7 = 1
87  };
88 
89  /** \brief Read a point cloud data header from a PCD-formatted, binary istream.
90  *
91  * Load only the meta information (number of points, their types, etc),
92  * and not the points themselves, from a given PCD stream. Useful for fast
93  * evaluation of the underlying data structure.
94  *
95  * \attention The PCD data is \b always stored in ROW major format! The
96  * read/write PCD methods will detect column major input and automatically convert it.
97  *
98  * \param[in] binary_istream a std::istream with openmode set to std::ios::binary.
99  * \param[out] cloud the resultant point cloud dataset (only these
100  * members will be filled: width, height, point_step,
101  * row_step, fields[]; data is resized but not written)
102  * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
103  * \param[out] orientation the sensor acquisition orientation (only for > PCD_V7 - identity if not present)
104  * \param[out] pcd_version the PCD version of the file (i.e., PCD_V6, PCD_V7)
105  * \param[out] data_type the type of data (0 = ASCII, 1 = Binary, 2 = Binary compressed)
106  * \param[out] data_idx the offset of cloud data within the file
107  *
108  * \return
109  * * < 0 (-1) on error
110  * * == 0 on success
111  */
112  int
113  readHeader (std::istream &binary_istream, pcl::PCLPointCloud2 &cloud,
114  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version,
115  int &data_type, unsigned int &data_idx);
116 
117  /** \brief Read a point cloud data header from a PCD file.
118  *
119  * Load only the meta information (number of points, their types, etc),
120  * and not the points themselves, from a given PCD file. Useful for fast
121  * evaluation of the underlying data structure.
122  *
123  * \attention The PCD data is \b always stored in ROW major format! The
124  * read/write PCD methods will detect column major input and automatically convert it.
125  *
126  * \param[in] file_name the name of the file to load
127  * \param[out] cloud the resultant point cloud dataset (only these
128  * members will be filled: width, height, point_step,
129  * row_step, fields[]; data is resized but not written)
130  * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
131  * \param[out] orientation the sensor acquisition orientation (only for > PCD_V7 - identity if not present)
132  * \param[out] pcd_version the PCD version of the file (i.e., PCD_V6, PCD_V7)
133  * \param[out] data_type the type of data (0 = ASCII, 1 = Binary, 2 = Binary compressed)
134  * \param[out] data_idx the offset of cloud data within the file
135  * \param[in] offset the offset of where to expect the PCD Header in the
136  * file (optional parameter). One usage example for setting the offset
137  * parameter is for reading data from a TAR "archive containing multiple
138  * PCD files: TAR files always add a 512 byte header in front of the
139  * actual file, so set the offset to the next byte after the header
140  * (e.g., 513).
141  *
142  * \return
143  * * < 0 (-1) on error
144  * * == 0 on success
145  */
146  int
147  readHeader (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
148  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version,
149  int &data_type, unsigned int &data_idx, const int offset = 0) override;
150 
151 
152  /** \brief Read a point cloud data header from a PCD file.
153  *
154  * Load only the meta information (number of points, their types, etc),
155  * and not the points themselves, from a given PCD file. Useful for fast
156  * evaluation of the underlying data structure.
157  *
158  * \attention The PCD data is \b always stored in ROW major format! The
159  * read/write PCD methods will detect column major input and automatically convert it.
160  *
161  * \param[in] file_name the name of the file to load
162  * \param[out] cloud the resultant point cloud dataset (only these
163  * members will be filled: width, height, point_step,
164  * row_step, fields[]; data is resized but not written)
165  * \param[in] offset the offset of where to expect the PCD Header in the
166  * file (optional parameter). One usage example for setting the offset
167  * parameter is for reading data from a TAR "archive containing multiple
168  * PCD files: TAR files always add a 512 byte header in front of the
169  * actual file, so set the offset to the next byte after the header
170  * (e.g., 513).
171  *
172  * \return
173  * * < 0 (-1) on error
174  * * == 0 on success
175  */
176  int
177  readHeader (const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset = 0);
178 
179  /** \brief Read the point cloud data (body) from a PCD stream.
180  *
181  * Reads the cloud points from a text-formatted stream. For use after
182  * readHeader(), when the resulting data_type == 0.
183  *
184  * \attention This assumes the stream has been seeked to the position
185  * indicated by the data_idx result of readHeader().
186  *
187  * \param[in] stream the stream from which to read the body.
188  * \param[out] cloud the resultant point cloud dataset to be filled.
189  * \param[in] pcd_version the PCD version of the stream (from readHeader()).
190  *
191  * \return
192  * * < 0 (-1) on error
193  * * == 0 on success
194  */
195  int
196  readBodyASCII (std::istream &stream, pcl::PCLPointCloud2 &cloud, int pcd_version);
197 
198  /** \brief Read the point cloud data (body) from a block of memory.
199  *
200  * Reads the cloud points from a binary-formatted memory block. For use
201  * after readHeader(), when the resulting data_type is nonzero.
202  *
203  * \param[in] data the memory location from which to read the body.
204  * \param[out] cloud the resultant point cloud dataset to be filled.
205  * \param[in] pcd_version the PCD version of the stream (from readHeader()).
206  * \param[in] compressed indicates whether the PCD block contains compressed
207  * data. This should be true if the data_type returned by readHeader() == 2.
208  * \param[in] data_idx the offset of the body, as reported by readHeader().
209  *
210  * \return
211  * * < 0 (-1) on error
212  * * == 0 on success
213  */
214  int
215  readBodyBinary (const unsigned char *data, pcl::PCLPointCloud2 &cloud,
216  int pcd_version, bool compressed, unsigned int data_idx);
217 
218  /** \brief Read a point cloud data from a PCD file and store it into a pcl/PCLPointCloud2.
219  * \param[in] file_name the name of the file containing the actual PointCloud data
220  * \param[out] cloud the resultant PointCloud message read from disk
221  * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
222  * \param[out] orientation the sensor acquisition orientation (only for > PCD_V7 - identity if not present)
223  * \param[out] pcd_version the PCD version of the file (either PCD_V6 or PCD_V7)
224  * \param[in] offset the offset of where to expect the PCD Header in the
225  * file (optional parameter). One usage example for setting the offset
226  * parameter is for reading data from a TAR "archive containing multiple
227  * PCD files: TAR files always add a 512 byte header in front of the
228  * actual file, so set the offset to the next byte after the header
229  * (e.g., 513).
230  *
231  * \return
232  * * < 0 (-1) on error
233  * * == 0 on success
234  */
235  int
236  read (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
237  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version, const int offset = 0) override;
238 
239  /** \brief Read a point cloud data from a PCD (PCD_V6) and store it into a pcl/PCLPointCloud2.
240  *
241  * \note This function is provided for backwards compatibility only and
242  * it can only read PCD_V6 files correctly, as pcl::PCLPointCloud2
243  * does not contain a sensor origin/orientation. Reading any file
244  * > PCD_V6 will generate a warning.
245  *
246  * \param[in] file_name the name of the file containing the actual PointCloud data
247  * \param[out] cloud the resultant PointCloud message read from disk
248  * \param[in] offset the offset of where to expect the PCD Header in the
249  * file (optional parameter). One usage example for setting the offset
250  * parameter is for reading data from a TAR "archive containing multiple
251  * PCD files: TAR files always add a 512 byte header in front of the
252  * actual file, so set the offset to the next byte after the header
253  * (e.g., 513).
254  *
255  * \return
256  * * < 0 (-1) on error
257  * * == 0 on success
258  */
259  int
260  read (const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset = 0);
261 
262  /** \brief Read a point cloud data from any PCD file, and convert it to the given template format.
263  * \param[in] file_name the name of the file containing the actual PointCloud data
264  * \param[out] cloud the resultant PointCloud message read from disk
265  * \param[in] offset the offset of where to expect the PCD Header in the
266  * file (optional parameter). One usage example for setting the offset
267  * parameter is for reading data from a TAR "archive containing multiple
268  * PCD files: TAR files always add a 512 byte header in front of the
269  * actual file, so set the offset to the next byte after the header
270  * (e.g., 513).
271  *
272  * \return
273  * * < 0 (-1) on error
274  * * == 0 on success
275  */
276  template<typename PointT> int
277  read (const std::string &file_name, pcl::PointCloud<PointT> &cloud, const int offset = 0)
278  {
279  pcl::PCLPointCloud2 blob;
280  int pcd_version;
281  int res = read (file_name, blob, cloud.sensor_origin_, cloud.sensor_orientation_,
282  pcd_version, offset);
283 
284  // If no error, convert the data
285  if (res == 0)
286  pcl::fromPCLPointCloud2 (blob, cloud);
287 
288  return (res);
289  }
290 
292  };
293 
294  /** \brief Point Cloud Data (PCD) file format writer.
295  * \author Radu Bogdan Rusu
296  * \ingroup io
297  */
299  {
300  public:
301  PCDWriter() = default;
302  ~PCDWriter() override = default;
303 
304  /** \brief Set whether mmap() synchornization via msync() is desired before munmap() calls.
305  * Setting this to true could prevent NFS data loss (see
306  * http://www.pcl-developers.org/PCD-IO-consistency-on-NFS-msync-needed-td4885942.html).
307  * Default: false
308  * \note This option should be used by advanced users only!
309  * \note Please note that using msync() on certain systems can reduce the I/O performance by up to 80%!
310  * \param[in] sync set to true if msync() should be called before munmap()
311  */
312  void
314  {
315  map_synchronization_ = sync;
316  }
317 
318  /** \brief Generate the header of a PCD file format
319  * \param[in] cloud the point cloud data message
320  * \param[in] origin the sensor acquisition origin
321  * \param[in] orientation the sensor acquisition orientation
322  */
323  std::string
325  const Eigen::Vector4f &origin,
326  const Eigen::Quaternionf &orientation);
327 
328  /** \brief Generate the header of a BINARY_COMPRESSED PCD file format
329  * \param[out] os the stream into which to write the header
330  * \param[in] cloud the point cloud data message
331  * \param[in] origin the sensor acquisition origin
332  * \param[in] orientation the sensor acquisition orientation
333  *
334  * \return
335  * * < 0 (-1) on error
336  * * == 0 on success
337  */
338  int
340  const pcl::PCLPointCloud2 &cloud,
341  const Eigen::Vector4f &origin,
342  const Eigen::Quaternionf &orientation);
343 
344  /** \brief Generate the header of a BINARY_COMPRESSED PCD file format
345  * \param[in] cloud the point cloud data message
346  * \param[in] origin the sensor acquisition origin
347  * \param[in] orientation the sensor acquisition orientation
348  */
349  std::string
351  const Eigen::Vector4f &origin,
352  const Eigen::Quaternionf &orientation);
353 
354  /** \brief Generate the header of a PCD file format
355  * \param[in] cloud the point cloud data message
356  * \param[in] origin the sensor acquisition origin
357  * \param[in] orientation the sensor acquisition orientation
358  */
359  std::string
361  const Eigen::Vector4f &origin,
362  const Eigen::Quaternionf &orientation);
363 
364  /** \brief Generate the header of a PCD file format
365  * \param[in] cloud the point cloud data message
366  * \param[in] nr_points if given, use this to fill in WIDTH, HEIGHT (=1), and POINTS in the header
367  * By default, nr_points is set to INTMAX, and the data in the header is used instead.
368  */
369  template <typename PointT> static std::string
370  generateHeader (const pcl::PointCloud<PointT> &cloud,
371  const int nr_points = std::numeric_limits<int>::max ());
372 
373  /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
374  * \param[in] file_name the output file name
375  * \param[in] cloud the point cloud data message
376  * \param[in] origin the sensor acquisition origin
377  * \param[in] orientation the sensor acquisition orientation
378  * \param[in] precision the specified output numeric stream precision (default: 8)
379  *
380  * Caution: PointCloud structures containing an RGB field have
381  * traditionally used packed float values to store RGB data. Storing a
382  * float as ASCII can introduce variations to the smallest bits, and
383  * thus significantly alter the data. This is a known issue, and the fix
384  * involves switching RGB data to be stored as a packed integer in
385  * future versions of PCL.
386  *
387  * As an intermediary solution, precision 8 is used, which guarantees lossless storage for RGB.
388  */
389  int
390  writeASCII (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
391  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
392  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
393  const int precision = 8);
394 
395  /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
396  * \param[in] file_name the output file name
397  * \param[in] cloud the point cloud data message
398  * \param[in] origin the sensor acquisition origin
399  * \param[in] orientation the sensor acquisition orientation
400  */
401  int
402  writeBinary (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
403  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
404  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
405 
406  /** \brief Save point cloud data to a std::ostream containing n-D points, in BINARY format
407  * \param[out] os the stream into which to write the data
408  * \param[in] cloud the point cloud data message
409  * \param[in] origin the sensor acquisition origin
410  * \param[in] orientation the sensor acquisition orientation
411  */
412  int
413  writeBinary (std::ostream &os, const pcl::PCLPointCloud2 &cloud,
414  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
415  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
416 
417  /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY_COMPRESSED format
418  * \param[in] file_name the output file name
419  * \param[in] cloud the point cloud data message
420  * \param[in] origin the sensor acquisition origin
421  * \param[in] orientation the sensor acquisition orientation
422  * \return
423  * (-1) for a general error
424  * (-2) if the input cloud is too large for the file format
425  * 0 on success
426  */
427  int
428  writeBinaryCompressed (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
429  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
430  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
431 
432  /** \brief Save point cloud data to a std::ostream containing n-D points, in BINARY_COMPRESSED format
433  * \param[out] os the stream into which to write the data
434  * \param[in] cloud the point cloud data message
435  * \param[in] origin the sensor acquisition origin
436  * \param[in] orientation the sensor acquisition orientation
437  * \return
438  * (-1) for a general error
439  * (-2) if the input cloud is too large for the file format
440  * 0 on success
441  */
442  int
443  writeBinaryCompressed (std::ostream &os, const pcl::PCLPointCloud2 &cloud,
444  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
445  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity ());
446 
447  /** \brief Save point cloud data to a PCD file containing n-D points
448  * \param[in] file_name the output file name
449  * \param[in] cloud the point cloud data message
450  * \param[in] origin the sensor acquisition origin
451  * \param[in] orientation the sensor acquisition orientation
452  * \param[in] binary set to true if the file is to be written in a binary
453  * PCD format, false (default) for ASCII
454  *
455  * Caution: PointCloud structures containing an RGB field have
456  * traditionally used packed float values to store RGB data. Storing a
457  * float as ASCII can introduce variations to the smallest bits, and
458  * thus significantly alter the data. This is a known issue, and the fix
459  * involves switching RGB data to be stored as a packed integer in
460  * future versions of PCL.
461  *
462  * As an intermediary solution, precision 8 is used, which guarantees lossless storage for RGB.
463  */
464  inline int
465  write (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
466  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
467  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
468  const bool binary = false) override
469  {
470  if (binary)
471  return (writeBinary (file_name, cloud, origin, orientation));
472  return (writeASCII (file_name, cloud, origin, orientation, 8));
473  }
474 
475  /** \brief Save point cloud data to a PCD file containing n-D points
476  * \param[in] file_name the output file name
477  * \param[in] cloud the point cloud data message (boost shared pointer)
478  * \param[in] binary set to true if the file is to be written in a binary PCD format,
479  * false (default) for ASCII
480  * \param[in] origin the sensor acquisition origin
481  * \param[in] orientation the sensor acquisition orientation
482  *
483  * Caution: PointCloud structures containing an RGB field have
484  * traditionally used packed float values to store RGB data. Storing a
485  * float as ASCII can introduce variations to the smallest bits, and
486  * thus significantly alter the data. This is a known issue, and the fix
487  * involves switching RGB data to be stored as a packed integer in
488  * future versions of PCL.
489  */
490  inline int
491  write (const std::string &file_name, const pcl::PCLPointCloud2::ConstPtr &cloud,
492  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
493  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
494  const bool binary = false)
495  {
496  return (write (file_name, *cloud, origin, orientation, binary));
497  }
498 
499  /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
500  * \param[in] file_name the output file name
501  * \param[in] cloud the point cloud data message
502  */
503  template <typename PointT> int
504  writeBinary (const std::string &file_name,
505  const pcl::PointCloud<PointT> &cloud);
506 
507  /** \brief Save point cloud data to a binary comprssed PCD file
508  * \param[in] file_name the output file name
509  * \param[in] cloud the point cloud data message
510  * \return
511  * (-1) for a general error
512  * (-2) if the input cloud is too large for the file format
513  * 0 on success
514  */
515  template <typename PointT> int
516  writeBinaryCompressed (const std::string &file_name,
517  const pcl::PointCloud<PointT> &cloud);
518 
519  /** \brief Save point cloud data to a PCD file containing n-D points, in BINARY format
520  * \param[in] file_name the output file name
521  * \param[in] cloud the point cloud data message
522  * \param[in] indices the set of point indices that we want written to disk
523  */
524  template <typename PointT> int
525  writeBinary (const std::string &file_name,
526  const pcl::PointCloud<PointT> &cloud,
527  const pcl::Indices &indices);
528 
529  /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
530  * \param[in] file_name the output file name
531  * \param[in] cloud the point cloud data message
532  * \param[in] precision the specified output numeric stream precision (default: 8)
533  */
534  template <typename PointT> int
535  writeASCII (const std::string &file_name,
536  const pcl::PointCloud<PointT> &cloud,
537  const int precision = 8);
538 
539  /** \brief Save point cloud data to a PCD file containing n-D points, in ASCII format
540  * \param[in] file_name the output file name
541  * \param[in] cloud the point cloud data message
542  * \param[in] indices the set of point indices that we want written to disk
543  * \param[in] precision the specified output numeric stream precision (default: 8)
544  */
545  template <typename PointT> int
546  writeASCII (const std::string &file_name,
547  const pcl::PointCloud<PointT> &cloud,
548  const pcl::Indices &indices,
549  const int precision = 8);
550 
551  /** \brief Save point cloud data to a PCD file containing n-D points
552  * \param[in] file_name the output file name
553  * \param[in] cloud the pcl::PointCloud data
554  * \param[in] binary set to true if the file is to be written in a binary
555  * PCD format, false (default) for ASCII
556  *
557  * Caution: PointCloud structures containing an RGB field have
558  * traditionally used packed float values to store RGB data. Storing a
559  * float as ASCII can introduce variations to the smallest bits, and
560  * thus significantly alter the data. This is a known issue, and the fix
561  * involves switching RGB data to be stored as a packed integer in
562  * future versions of PCL.
563  */
564  template<typename PointT> inline int
565  write (const std::string &file_name,
566  const pcl::PointCloud<PointT> &cloud,
567  const bool binary = false)
568  {
569  if (binary)
570  return (writeBinary<PointT> (file_name, cloud));
571  return (writeASCII<PointT> (file_name, cloud));
572  }
573 
574  /** \brief Save point cloud data to a PCD file containing n-D points
575  * \param[in] file_name the output file name
576  * \param[in] cloud the pcl::PointCloud data
577  * \param[in] indices the set of point indices that we want written to disk
578  * \param[in] binary set to true if the file is to be written in a binary
579  * PCD format, false (default) for ASCII
580  *
581  * Caution: PointCloud structures containing an RGB field have
582  * traditionally used packed float values to store RGB data. Storing a
583  * float as ASCII can introduce variations to the smallest bits, and
584  * thus significantly alter the data. This is a known issue, and the fix
585  * involves switching RGB data to be stored as a packed integer in
586  * future versions of PCL.
587  */
588  template<typename PointT> inline int
589  write (const std::string &file_name,
590  const pcl::PointCloud<PointT> &cloud,
591  const pcl::Indices &indices,
592  bool binary = false)
593  {
594  if (binary)
595  return (writeBinary<PointT> (file_name, cloud, indices));
596  return (writeASCII<PointT> (file_name, cloud, indices));
597  }
598 
599  protected:
600  /** \brief Set permissions for file locking (Boost 1.49+).
601  * \param[in] file_name the file name to set permission for file locking
602  * \param[in,out] lock the file lock
603  */
604  void
605  setLockingPermissions (const std::string &file_name,
606  boost::interprocess::file_lock &lock);
607 
608  /** \brief Reset permissions for file locking (Boost 1.49+).
609  * \param[in] file_name the file name to reset permission for file locking
610  * \param[in,out] lock the file lock
611  */
612  void
613  resetLockingPermissions (const std::string &file_name,
614  boost::interprocess::file_lock &lock);
615 
616  private:
617  /** \brief Set to true if msync() should be called before munmap(). Prevents data loss on NFS systems. */
618  bool map_synchronization_{false};
619  };
620 
621  namespace io
622  {
623  /** \brief Load a PCD v.6 file into a templated PointCloud type.
624  *
625  * Any PCD files > v.6 will generate a warning as a
626  * pcl/PCLPointCloud2 message cannot hold the sensor origin.
627  *
628  * \param[in] file_name the name of the file to load
629  * \param[out] cloud the resultant templated point cloud
630  * \ingroup io
631  */
632  inline int
633  loadPCDFile (const std::string &file_name, pcl::PCLPointCloud2 &cloud)
634  {
635  pcl::PCDReader p;
636  return (p.read (file_name, cloud));
637  }
638 
639  /** \brief Load any PCD file into a templated PointCloud type.
640  * \param[in] file_name the name of the file to load
641  * \param[out] cloud the resultant templated point cloud
642  * \param[out] origin the sensor acquisition origin (only for > PCD_V7 - null if not present)
643  * \param[out] orientation the sensor acquisition orientation (only for >
644  * PCD_V7 - identity if not present)
645  * \ingroup io
646  */
647  inline int
648  loadPCDFile (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
649  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation)
650  {
651  pcl::PCDReader p;
652  int pcd_version;
653  return (p.read (file_name, cloud, origin, orientation, pcd_version));
654  }
655 
656  /** \brief Load any PCD file into a templated PointCloud type
657  * \param[in] file_name the name of the file to load
658  * \param[out] cloud the resultant templated point cloud
659  * \ingroup io
660  */
661  template<typename PointT> inline int
662  loadPCDFile (const std::string &file_name, pcl::PointCloud<PointT> &cloud)
663  {
664  pcl::PCDReader p;
665  return (p.read (file_name, cloud));
666  }
667 
668  /** \brief Save point cloud data to a PCD file containing n-D points
669  * \param[in] file_name the output file name
670  * \param[in] cloud the point cloud data message
671  * \param[in] origin the sensor acquisition origin
672  * \param[in] orientation the sensor acquisition orientation
673  * \param[in] binary_mode true for binary mode, false (default) for ASCII
674  *
675  * Caution: PointCloud structures containing an RGB field have
676  * traditionally used packed float values to store RGB data. Storing a
677  * float as ASCII can introduce variations to the smallest bits, and
678  * thus significantly alter the data. This is a known issue, and the fix
679  * involves switching RGB data to be stored as a packed integer in
680  * future versions of PCL.
681  * \ingroup io
682  */
683  inline int
684  savePCDFile (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
685  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
686  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
687  const bool binary_mode = false)
688  {
689  PCDWriter w;
690  return (w.write (file_name, cloud, origin, orientation, binary_mode));
691  }
692 
693  /** \brief Templated version for saving point cloud data to a PCD file
694  * containing a specific given cloud format
695  * \param[in] file_name the output file name
696  * \param[in] cloud the point cloud data message
697  * \param[in] binary_mode true for binary mode, false (default) for ASCII
698  *
699  * Caution: PointCloud structures containing an RGB field have
700  * traditionally used packed float values to store RGB data. Storing a
701  * float as ASCII can introduce variations to the smallest bits, and
702  * thus significantly alter the data. This is a known issue, and the fix
703  * involves switching RGB data to be stored as a packed integer in
704  * future versions of PCL.
705  * \ingroup io
706  */
707  template<typename PointT> inline int
708  savePCDFile (const std::string &file_name, const pcl::PointCloud<PointT> &cloud, bool binary_mode = false)
709  {
710  PCDWriter w;
711  return (w.write<PointT> (file_name, cloud, binary_mode));
712  }
713 
714  /**
715  * \brief Templated version for saving point cloud data to a PCD file
716  * containing a specific given cloud format.
717  *
718  * This version is to retain backwards compatibility.
719  * \param[in] file_name the output file name
720  * \param[in] cloud the point cloud data message
721  *
722  * Caution: PointCloud structures containing an RGB field have
723  * traditionally used packed float values to store RGB data. Storing a
724  * float as ASCII can introduce variations to the smallest bits, and
725  * thus significantly alter the data. This is a known issue, and the fix
726  * involves switching RGB data to be stored as a packed integer in
727  * future versions of PCL.
728  * \ingroup io
729  */
730  template<typename PointT> inline int
731  savePCDFileASCII (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
732  {
733  PCDWriter w;
734  return (w.write<PointT> (file_name, cloud, false));
735  }
736 
737  /**
738  * \brief Templated version for saving point cloud data to a PCD file
739  * containing a specific given cloud format. The resulting file will be an uncompressed binary.
740  *
741  * This version is to retain backwards compatibility.
742  * \param[in] file_name the output file name
743  * \param[in] cloud the point cloud data message
744  * \ingroup io
745  */
746  template<typename PointT> inline int
747  savePCDFileBinary (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
748  {
749  PCDWriter w;
750  return (w.write<PointT> (file_name, cloud, true));
751  }
752 
753  /**
754  * \brief Templated version for saving point cloud data to a PCD file
755  * containing a specific given cloud format
756  *
757  * \param[in] file_name the output file name
758  * \param[in] cloud the point cloud data message
759  * \param[in] indices the set of indices to save
760  * \param[in] binary_mode true for binary mode, false (default) for ASCII
761  *
762  * Caution: PointCloud structures containing an RGB field have
763  * traditionally used packed float values to store RGB data. Storing a
764  * float as ASCII can introduce variations to the smallest bits, and
765  * thus significantly alter the data. This is a known issue, and the fix
766  * involves switching RGB data to be stored as a packed integer in
767  * future versions of PCL.
768  * \ingroup io
769  */
770  template<typename PointT> int
771  savePCDFile (const std::string &file_name,
772  const pcl::PointCloud<PointT> &cloud,
773  const pcl::Indices &indices,
774  const bool binary_mode = false)
775  {
776  // Save the data
777  PCDWriter w;
778  return (w.write<PointT> (file_name, cloud, indices, binary_mode));
779  }
780 
781 
782  /**
783  * \brief Templated version for saving point cloud data to a PCD file
784  * containing a specific given cloud format. This method will write a compressed binary file.
785  *
786  * This version is to retain backwards compatibility.
787  * \param[in] file_name the output file name
788  * \param[in] cloud the point cloud data message
789  * \ingroup io
790  */
791  template<typename PointT> inline int
792  savePCDFileBinaryCompressed (const std::string &file_name, const pcl::PointCloud<PointT> &cloud)
793  {
794  PCDWriter w;
795  return (w.writeBinaryCompressed<PointT> (file_name, cloud));
796  }
797 
798  }
799 }
800 
801 #include <pcl/io/impl/pcd_io.hpp>
Point Cloud Data (FILE) file format reader interface.
Definition: file_io.h:57
Point Cloud Data (FILE) file format writer.
Definition: file_io.h:163
Point Cloud Data (PCD) file format reader.
Definition: pcd_io.h:55
int readHeader(const std::string &file_name, pcl::PCLPointCloud2 &cloud, Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version, int &data_type, unsigned int &data_idx, const int offset=0) override
Read a point cloud data header from a PCD file.
int readHeader(std::istream &binary_istream, pcl::PCLPointCloud2 &cloud, Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version, int &data_type, unsigned int &data_idx)
Read a point cloud data header from a PCD-formatted, binary istream.
PCDReader()=default
Empty constructor.
~PCDReader() override=default
Empty destructor.
int read(const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset=0)
Read a point cloud data from a PCD (PCD_V6) and store it into a pcl/PCLPointCloud2.
int read(const std::string &file_name, pcl::PointCloud< PointT > &cloud, const int offset=0)
Read a point cloud data from any PCD file, and convert it to the given template format.
Definition: pcd_io.h:277
int read(const std::string &file_name, pcl::PCLPointCloud2 &cloud, Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &pcd_version, const int offset=0) override
Read a point cloud data from a PCD file and store it into a pcl/PCLPointCloud2.
int readBodyASCII(std::istream &stream, pcl::PCLPointCloud2 &cloud, int pcd_version)
Read the point cloud data (body) from a PCD stream.
int readBodyBinary(const unsigned char *data, pcl::PCLPointCloud2 &cloud, int pcd_version, bool compressed, unsigned int data_idx)
Read the point cloud data (body) from a block of memory.
int readHeader(const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset=0)
Read a point cloud data header from a PCD file.
Point Cloud Data (PCD) file format writer.
Definition: pcd_io.h:299
std::string generateHeaderASCII(const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin, const Eigen::Quaternionf &orientation)
Generate the header of a PCD file format.
void resetLockingPermissions(const std::string &file_name, boost::interprocess::file_lock &lock)
Reset permissions for file locking (Boost 1.49+).
void setLockingPermissions(const std::string &file_name, boost::interprocess::file_lock &lock)
Set permissions for file locking (Boost 1.49+).
PCDWriter()=default
~PCDWriter() override=default
int write(const std::string &file_name, const pcl::PointCloud< PointT > &cloud, const bool binary=false)
Save point cloud data to a PCD file containing n-D points.
Definition: pcd_io.h:565
int writeBinary(std::ostream &os, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity())
Save point cloud data to a std::ostream containing n-D points, in BINARY format.
int writeBinaryCompressed(std::ostream &os, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity())
Save point cloud data to a std::ostream containing n-D points, in BINARY_COMPRESSED format.
std::string generateHeaderBinary(const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin, const Eigen::Quaternionf &orientation)
Generate the header of a PCD file format.
int write(const std::string &file_name, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity(), const bool binary=false) override
Save point cloud data to a PCD file containing n-D points.
Definition: pcd_io.h:465
std::string generateHeaderBinaryCompressed(const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin, const Eigen::Quaternionf &orientation)
Generate the header of a BINARY_COMPRESSED PCD file format.
int writeBinary(const std::string &file_name, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity())
Save point cloud data to a PCD file containing n-D points, in BINARY format.
int write(const std::string &file_name, const pcl::PCLPointCloud2::ConstPtr &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity(), const bool binary=false)
Save point cloud data to a PCD file containing n-D points.
Definition: pcd_io.h:491
void setMapSynchronization(bool sync)
Set whether mmap() synchornization via msync() is desired before munmap() calls.
Definition: pcd_io.h:313
int generateHeaderBinaryCompressed(std::ostream &os, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin, const Eigen::Quaternionf &orientation)
Generate the header of a BINARY_COMPRESSED PCD file format.
int write(const std::string &file_name, const pcl::PointCloud< PointT > &cloud, const pcl::Indices &indices, bool binary=false)
Save point cloud data to a PCD file containing n-D points.
Definition: pcd_io.h:589
int writeASCII(const std::string &file_name, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity(), const int precision=8)
Save point cloud data to a PCD file containing n-D points, in ASCII format.
int writeBinaryCompressed(const std::string &file_name, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity())
Save point cloud data to a PCD file containing n-D points, in BINARY_COMPRESSED format.
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
Eigen::Quaternionf sensor_orientation_
Sensor acquisition pose (rotation).
Definition: point_cloud.h:408
Eigen::Vector4f sensor_origin_
Sensor acquisition pose (origin/translation).
Definition: point_cloud.h:406
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: memory.h:63
int savePCDFileASCII(const std::string &file_name, const pcl::PointCloud< PointT > &cloud)
Templated version for saving point cloud data to a PCD file containing a specific given cloud format.
Definition: pcd_io.h:731
int savePCDFile(const std::string &file_name, const pcl::PCLPointCloud2 &cloud, const Eigen::Vector4f &origin=Eigen::Vector4f::Zero(), const Eigen::Quaternionf &orientation=Eigen::Quaternionf::Identity(), const bool binary_mode=false)
Save point cloud data to a PCD file containing n-D points.
Definition: pcd_io.h:684
int savePCDFileBinary(const std::string &file_name, const pcl::PointCloud< PointT > &cloud)
Templated version for saving point cloud data to a PCD file containing a specific given cloud format.
Definition: pcd_io.h:747
int loadPCDFile(const std::string &file_name, pcl::PCLPointCloud2 &cloud)
Load a PCD v.6 file into a templated PointCloud type.
Definition: pcd_io.h:633
int savePCDFileBinaryCompressed(const std::string &file_name, const pcl::PointCloud< PointT > &cloud)
Templated version for saving point cloud data to a PCD file containing a specific given cloud format.
Definition: pcd_io.h:792
Defines functions, macros and traits for allocating and using memory.
void read(std::istream &stream, Type &value)
Function for reading data from a stream.
Definition: region_xy.h:46
void fromPCLPointCloud2(const pcl::PCLPointCloud2 &msg, pcl::PointCloud< PointT > &cloud, const MsgFieldMap &field_map, const std::uint8_t *msg_data)
Convert a PCLPointCloud2 binary data blob into a pcl::PointCloud<T> object using a field_map.
Definition: conversions.h:229
IndicesAllocator<> Indices
Type used for indices in PCL.
Definition: types.h:133
void write(std::ostream &stream, Type value)
Function for writing data to a stream.
Definition: region_xy.h:63
Defines all the PCL and non-PCL macros used.
#define PCL_EXPORTS
Definition: pcl_macros.h:323
shared_ptr< const ::pcl::PCLPointCloud2 > ConstPtr
A point structure representing Euclidean xyz coordinates, and the RGB color.