Point Cloud Library (PCL)  1.9.1-dev
file_io.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Copyright (c) 2009, Willow Garage, Inc.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * * Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * * Redistributions in binary form must reproduce the above
14  * copyright notice, this list of conditions and the following
15  * disclaimer in the documentation and/or other materials provided
16  * with the distribution.
17  * * Neither the name of the copyright holder(s) nor the names of its
18  * contributors may be used to endorse or promote products derived
19  * from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  * $Id: file_io.h 827 2011-05-04 02:00:04Z nizar $
35  *
36  */
37 
38 #pragma once
39 
40 #include <pcl/pcl_macros.h>
41 #include <pcl/common/io.h>
42 #include <pcl/io/boost.h>
43 #include <cmath>
44 #include <sstream>
45 #include <pcl/PolygonMesh.h>
46 #include <pcl/TextureMesh.h>
47 
48 namespace pcl
49 {
50  /** \brief Point Cloud Data (FILE) file format reader interface.
51  * Any (FILE) format file reader should implement its virtual methods.
52  * \author Nizar Sallem
53  * \ingroup io
54  */
55  class PCL_EXPORTS FileReader
56  {
57  public:
58  /** \brief empty constructor */
60  /** \brief empty destructor */
61  virtual ~FileReader() {}
62  /** \brief Read a point cloud data header from a FILE file.
63  *
64  * Load only the meta information (number of points, their types, etc),
65  * and not the points themselves, from a given FILE file. Useful for fast
66  * evaluation of the underlying data structure.
67  *
68  * Returns:
69  * * < 0 (-1) on error
70  * * > 0 on success
71  * \param[in] file_name the name of the file to load
72  * \param[out] cloud the resultant point cloud dataset (only the header will be filled)
73  * \param[out] origin the sensor acquisition origin (only for > FILE_V7 - null if not present)
74  * \param[out] orientation the sensor acquisition orientation (only for > FILE_V7 - identity if not present)
75  * \param[out] file_version the FILE version of the file (either FILE_V6 or FILE_V7)
76  * \param[out] data_type the type of data (binary data=1, ascii=0, etc)
77  * \param[out] data_idx the offset of cloud data within the file
78  * \param[in] offset the offset in the file where to expect the true header to begin.
79  * One usage example for setting the offset parameter is for reading
80  * data from a TAR "archive containing multiple files: TAR files always
81  * add a 512 byte header in front of the actual file, so set the offset
82  * to the next byte after the header (e.g., 513).
83  */
84  virtual int
85  readHeader (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
86  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation,
87  int &file_version, int &data_type, unsigned int &data_idx, const int offset = 0) = 0;
88 
89  /** \brief Read a point cloud data from a FILE file and store it into a pcl/PCLPointCloud2.
90  * \param[in] file_name the name of the file containing the actual PointCloud data
91  * \param[out] cloud the resultant PointCloud message read from disk
92  * \param[out] origin the sensor acquisition origin (only for > FILE_V7 - null if not present)
93  * \param[out] orientation the sensor acquisition orientation (only for > FILE_V7 - identity if not present)
94  * \param[out] file_version the FILE version of the file (either FILE_V6 or FILE_V7)
95  * \param[in] offset the offset in the file where to expect the true header to begin.
96  * One usage example for setting the offset parameter is for reading
97  * data from a TAR "archive containing multiple files: TAR files always
98  * add a 512 byte header in front of the actual file, so set the offset
99  * to the next byte after the header (e.g., 513).
100  */
101  virtual int
102  read (const std::string &file_name, pcl::PCLPointCloud2 &cloud,
103  Eigen::Vector4f &origin, Eigen::Quaternionf &orientation, int &file_version,
104  const int offset = 0) = 0;
105 
106  /** \brief Read a point cloud data from a FILE file (FILE_V6 only!) and store it into a pcl/PCLPointCloud2.
107  *
108  * \note This function is provided for backwards compatibility only and
109  * it can only read FILE_V6 files correctly, as pcl::PCLPointCloud2
110  * does not contain a sensor origin/orientation. Reading any file
111  * > FILE_V6 will generate a warning.
112  *
113  * \param[in] file_name the name of the file containing the actual PointCloud data
114  * \param[out] cloud the resultant PointCloud message read from disk
115  *
116  * \param[in] offset the offset in the file where to expect the true header to begin.
117  * One usage example for setting the offset parameter is for reading
118  * data from a TAR "archive containing multiple files: TAR files always
119  * add a 512 byte header in front of the actual file, so set the offset
120  * to the next byte after the header (e.g., 513).
121  */
122  int
123  read (const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset = 0)
124  {
125  Eigen::Vector4f origin;
126  Eigen::Quaternionf orientation;
127  int file_version;
128  return (read (file_name, cloud, origin, orientation, file_version, offset));
129  }
130 
131  /** \brief Read a point cloud data from any FILE file, and convert it to the given template format.
132  * \param[in] file_name the name of the file containing the actual PointCloud data
133  * \param[out] cloud the resultant PointCloud message read from disk
134  * \param[in] offset the offset in the file where to expect the true header to begin.
135  * One usage example for setting the offset parameter is for reading
136  * data from a TAR "archive containing multiple files: TAR files always
137  * add a 512 byte header in front of the actual file, so set the offset
138  * to the next byte after the header (e.g., 513).
139  */
140  template<typename PointT> inline int
141  read (const std::string &file_name, pcl::PointCloud<PointT> &cloud, const int offset =0)
142  {
143  pcl::PCLPointCloud2 blob;
144  int file_version;
145  int res = read (file_name, blob, cloud.sensor_origin_, cloud.sensor_orientation_,
146  file_version, offset);
147 
148  // Exit in case of error
149  if (res < 0)
150  return res;
151  pcl::fromPCLPointCloud2 (blob, cloud);
152  return (0);
153  }
154  };
155 
156  /** \brief Point Cloud Data (FILE) file format writer.
157  * Any (FILE) format file reader should implement its virtual methods
158  * \author Nizar Sallem
159  * \ingroup io
160  */
161  class PCL_EXPORTS FileWriter
162  {
163  public:
164  /** \brief Empty constructor */
166 
167  /** \brief Empty destructor */
168  virtual ~FileWriter () {}
169 
170  /** \brief Save point cloud data to a FILE file containing n-D points
171  * \param[in] file_name the output file name
172  * \param[in] cloud the point cloud data message
173  * \param[in] origin the sensor acquisition origin
174  * \param[in] orientation the sensor acquisition orientation
175  * \param[in] binary set to true if the file is to be written in a binary
176  * FILE format, false (default) for ASCII
177  */
178  virtual int
179  write (const std::string &file_name, const pcl::PCLPointCloud2 &cloud,
180  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
181  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
182  const bool binary = false) = 0;
183 
184  /** \brief Save point cloud data to a FILE file containing n-D points
185  * \param[in] file_name the output file name
186  * \param[in] cloud the point cloud data message (boost shared pointer)
187  * \param[in] binary set to true if the file is to be written in a binary
188  * FILE format, false (default) for ASCII
189  * \param[in] origin the sensor acquisition origin
190  * \param[in] orientation the sensor acquisition orientation
191  */
192  inline int
193  write (const std::string &file_name, const pcl::PCLPointCloud2::ConstPtr &cloud,
194  const Eigen::Vector4f &origin = Eigen::Vector4f::Zero (),
195  const Eigen::Quaternionf &orientation = Eigen::Quaternionf::Identity (),
196  const bool binary = false)
197  {
198  return (write (file_name, *cloud, origin, orientation, binary));
199  }
200 
201  /** \brief Save point cloud data to a FILE file containing n-D points
202  * \param[in] file_name the output file name
203  * \param[in] cloud the pcl::PointCloud data
204  * \param[in] binary set to true if the file is to be written in a binary
205  * FILE format, false (default) for ASCII
206  */
207  template<typename PointT> inline int
208  write (const std::string &file_name,
209  const pcl::PointCloud<PointT> &cloud,
210  const bool binary = false)
211  {
212  Eigen::Vector4f origin = cloud.sensor_origin_;
213  Eigen::Quaternionf orientation = cloud.sensor_orientation_;
214 
215  pcl::PCLPointCloud2 blob;
216  pcl::toPCLPointCloud2 (cloud, blob);
217 
218  // Save the data
219  return (write (file_name, blob, origin, orientation, binary));
220  }
221  };
222 
223  /** \brief inserts a value of type Type (uchar, char, uint, int, float, double, ...) into a stringstream.
224  *
225  * If the value is NaN, it inserts "nan".
226  *
227  * \param[in] cloud the cloud to copy from
228  * \param[in] point_index the index of the point
229  * \param[in] point_size the size of the point in the cloud
230  * \param[in] field_idx the index of the dimension/field
231  * \param[in] fields_count the current fields count
232  * \param[out] stream the ostringstream to copy into
233  */
234  template <typename Type> inline
235  std::enable_if_t<std::is_floating_point<Type>::value>
237  const unsigned int point_index,
238  const int point_size,
239  const unsigned int field_idx,
240  const unsigned int fields_count,
241  std::ostream &stream)
242  {
243  Type value;
244  memcpy (&value, &cloud.data[point_index * point_size + cloud.fields[field_idx].offset + fields_count * sizeof (Type)], sizeof (Type));
245  if (std::isnan (value))
246  stream << "nan";
247  else
248  stream << value;
249  }
250 
251  template <typename Type> inline
252  std::enable_if_t<std::is_integral<Type>::value>
254  const unsigned int point_index,
255  const int point_size,
256  const unsigned int field_idx,
257  const unsigned int fields_count,
258  std::ostream &stream)
259  {
260  Type value;
261  memcpy (&value, &cloud.data[point_index * point_size + cloud.fields[field_idx].offset + fields_count * sizeof (Type)], sizeof (Type));
262  stream << value;
263  }
264 
265  template <> inline void
267  const unsigned int point_index,
268  const int point_size,
269  const unsigned int field_idx,
270  const unsigned int fields_count,
271  std::ostream &stream)
272  {
273  int8_t value;
274  memcpy (&value, &cloud.data[point_index * point_size + cloud.fields[field_idx].offset + fields_count * sizeof (int8_t)], sizeof (int8_t));
275  //Cast to int to prevent value is handled as char
276  stream << boost::numeric_cast<int>(value);
277  }
278 
279  template <> inline void
281  const unsigned int point_index,
282  const int point_size,
283  const unsigned int field_idx,
284  const unsigned int fields_count,
285  std::ostream &stream)
286  {
287  uint8_t value;
288  memcpy (&value, &cloud.data[point_index * point_size + cloud.fields[field_idx].offset + fields_count * sizeof (uint8_t)], sizeof (uint8_t));
289  //Cast to unsigned int to prevent value is handled as char
290  stream << boost::numeric_cast<unsigned int>(value);
291  }
292 
293  /** \brief Check whether a given value of type Type (uchar, char, uint, int, float, double, ...) is finite or not
294  *
295  * \param[in] cloud the cloud that contains the data
296  * \param[in] point_index the index of the point
297  * \param[in] point_size the size of the point in the cloud
298  * \param[in] field_idx the index of the dimension/field
299  * \param[in] fields_count the current fields count
300  *
301  * \return true if the value is finite, false otherwise
302  */
303  template <typename Type> inline
304  std::enable_if_t<std::is_floating_point<Type>::value, bool>
306  const unsigned int point_index,
307  const int point_size,
308  const unsigned int field_idx,
309  const unsigned int fields_count)
310  {
311  Type value;
312  memcpy (&value, &cloud.data[point_index * point_size + cloud.fields[field_idx].offset + fields_count * sizeof (Type)], sizeof (Type));
313  return std::isfinite (value);
314  }
315 
316  template <typename Type> inline
317  std::enable_if_t<std::is_integral<Type>::value, bool>
318  isValueFinite (const pcl::PCLPointCloud2& /* cloud */,
319  const unsigned int /* point_index */,
320  const int /* point_size */,
321  const unsigned int /* field_idx */,
322  const unsigned int /* fields_count */)
323  {
324  return true;
325  }
326 
327  /** \brief Copy one single value of type T (uchar, char, uint, int, float, double, ...) from a string
328  *
329  * Uses aoti/atof to do the conversion.
330  * Checks if the st is "nan" and converts it accordingly.
331  *
332  * \param[in] st the string containing the value to convert and copy
333  * \param[out] cloud the cloud to copy it to
334  * \param[in] point_index the index of the point
335  * \param[in] field_idx the index of the dimension/field
336  * \param[in] fields_count the current fields count
337  */
338  template <typename Type> inline void
339  copyStringValue (const std::string &st, pcl::PCLPointCloud2 &cloud,
340  unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
341  {
342  Type value;
343  if (boost::iequals(st, "nan"))
344  {
345  value = std::numeric_limits<Type>::quiet_NaN ();
346  cloud.is_dense = false;
347  }
348  else
349  {
350  std::istringstream is (st);
351  is.imbue (std::locale::classic ());
352  if (!(is >> value))
353  value = static_cast<Type> (atof (st.c_str ()));
354  }
355 
356  memcpy (&cloud.data[point_index * cloud.point_step +
357  cloud.fields[field_idx].offset +
358  fields_count * sizeof (Type)], reinterpret_cast<char*> (&value), sizeof (Type));
359  }
360 
361  template <> inline void
362  copyStringValue<int8_t> (const std::string &st, pcl::PCLPointCloud2 &cloud,
363  unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
364  {
365  int8_t value;
366  if (boost::iequals(st, "nan"))
367  {
368  value = static_cast<int8_t> (std::numeric_limits<int>::quiet_NaN ());
369  cloud.is_dense = false;
370  }
371  else
372  {
373  int val;
374  std::istringstream is (st);
375  is.imbue (std::locale::classic ());
376  //is >> val; -- unfortunately this fails on older GCC versions and CLANG on MacOS
377  if (!(is >> val))
378  val = static_cast<int> (atof (st.c_str ()));
379  value = static_cast<int8_t> (val);
380  }
381 
382  memcpy (&cloud.data[point_index * cloud.point_step +
383  cloud.fields[field_idx].offset +
384  fields_count * sizeof (int8_t)], reinterpret_cast<char*> (&value), sizeof (int8_t));
385  }
386 
387  template <> inline void
388  copyStringValue<uint8_t> (const std::string &st, pcl::PCLPointCloud2 &cloud,
389  unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
390  {
391  uint8_t value;
392  if (boost::iequals(st, "nan"))
393  {
394  value = static_cast<uint8_t> (std::numeric_limits<int>::quiet_NaN ());
395  cloud.is_dense = false;
396  }
397  else
398  {
399  int val;
400  std::istringstream is (st);
401  is.imbue (std::locale::classic ());
402  //is >> val; -- unfortunately this fails on older GCC versions and CLANG on MacOS
403  if (!(is >> val))
404  val = static_cast<int> (atof (st.c_str ()));
405  value = static_cast<uint8_t> (val);
406  }
407 
408  memcpy (&cloud.data[point_index * cloud.point_step +
409  cloud.fields[field_idx].offset +
410  fields_count * sizeof (uint8_t)], reinterpret_cast<char*> (&value), sizeof (uint8_t));
411  }
412 
413 }
void fromPCLPointCloud2(const pcl::PCLPointCloud2 &msg, pcl::PointCloud< PointT > &cloud, const MsgFieldMap &field_map)
Convert a PCLPointCloud2 binary data blob into a pcl::PointCloud<T> object using a field_map...
Definition: conversions.h:168
void copyStringValue< uint8_t >(const std::string &st, pcl::PCLPointCloud2 &cloud, unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
Definition: file_io.h:388
void copyStringValue< int8_t >(const std::string &st, pcl::PCLPointCloud2 &cloud, unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
Definition: file_io.h:362
pcl::uint32_t point_step
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:44
FileWriter()
Empty constructor.
Definition: file_io.h:165
pcl::uint8_t is_dense
void read(std::istream &stream, Type &value)
Function for reading data from a stream.
Definition: region_xy.h:46
Point Cloud Data (FILE) file format writer.
Definition: file_io.h:161
virtual ~FileReader()
empty destructor
Definition: file_io.h:61
Eigen::Vector4f sensor_origin_
Sensor acquisition pose (origin/translation).
Definition: point_cloud.h:420
int read(const std::string &file_name, pcl::PointCloud< PointT > &cloud, const int offset=0)
Read a point cloud data from any FILE file, and convert it to the given template format.
Definition: file_io.h:141
int write(const std::string &file_name, const pcl::PointCloud< PointT > &cloud, const bool binary=false)
Save point cloud data to a FILE file containing n-D points.
Definition: file_io.h:208
void copyValueString< int8_t >(const pcl::PCLPointCloud2 &cloud, const unsigned int point_index, const int point_size, const unsigned int field_idx, const unsigned int fields_count, std::ostream &stream)
Definition: file_io.h:266
Point Cloud Data (FILE) file format reader interface.
Definition: file_io.h:55
Eigen::Quaternionf sensor_orientation_
Sensor acquisition pose (rotation).
Definition: point_cloud.h:422
std::enable_if_t< std::is_floating_point< Type >::value > copyValueString(const pcl::PCLPointCloud2 &cloud, const unsigned int point_index, const int point_size, const unsigned int field_idx, const unsigned int fields_count, std::ostream &stream)
inserts a value of type Type (uchar, char, uint, int, float, double, ...) into a stringstream.
Definition: file_io.h:236
boost::shared_ptr< ::pcl::PCLPointCloud2 const > ConstPtr
PointCloud represents the base class in PCL for storing collections of 3D points. ...
std::vector< ::pcl::PCLPointField > fields
virtual ~FileWriter()
Empty destructor.
Definition: file_io.h:168
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 FILE file containing n-D points.
Definition: file_io.h:193
void toPCLPointCloud2(const pcl::PointCloud< PointT > &cloud, pcl::PCLPointCloud2 &msg)
Convert a pcl::PointCloud<T> object to a PCLPointCloud2 binary data blob.
Definition: conversions.h:241
void write(std::ostream &stream, Type value)
Function for writing data to a stream.
Definition: region_xy.h:63
std::enable_if_t< std::is_floating_point< Type >::value, bool > isValueFinite(const pcl::PCLPointCloud2 &cloud, const unsigned int point_index, const int point_size, const unsigned int field_idx, const unsigned int fields_count)
Check whether a given value of type Type (uchar, char, uint, int, float, double, ...) is finite or not.
Definition: file_io.h:305
FileReader()
empty constructor
Definition: file_io.h:59
int read(const std::string &file_name, pcl::PCLPointCloud2 &cloud, const int offset=0)
Read a point cloud data from a FILE file (FILE_V6 only!) and store it into a pcl/PCLPointCloud2.
Definition: file_io.h:123
void copyStringValue(const std::string &st, pcl::PCLPointCloud2 &cloud, unsigned int point_index, unsigned int field_idx, unsigned int fields_count)
Copy one single value of type T (uchar, char, uint, int, float, double, ...) from a string...
Definition: file_io.h:339
std::vector< pcl::uint8_t > data
void copyValueString< uint8_t >(const pcl::PCLPointCloud2 &cloud, const unsigned int point_index, const int point_size, const unsigned int field_idx, const unsigned int fields_count, std::ostream &stream)
Definition: file_io.h:280