Point Cloud Library (PCL)  1.7.0
lzf_image_io.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2012-, Open Perception, 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  */
37 
38 #ifndef PCL_LZF_IMAGE_IO_H_
39 #define PCL_LZF_IMAGE_IO_H_
40 
41 #include <pcl/pcl_macros.h>
42 #include <pcl/point_cloud.h>
43 #include <vector>
44 
45 namespace pcl
46 {
47  namespace io
48  {
49  /** \brief Basic camera parameters placeholder. */
51  {
52  /** fx */
54  /** fy */
56  /** cx */
58  /** cy */
60  };
61 
62  /** \brief PCL-LZF image format reader.
63  * The PCL-LZF image format is nothing else but a LZF-modified compression over
64  * an existing file type (e.g., PNG). However, in certain situations, like RGB data for
65  * example, an [RGBRGB...RGB] array will be first reordered into [RR...RGG...GBB...B]
66  * in order to ensure better compression.
67  *
68  * The current list of compressors/decompressors include:
69  * * LZF compressed 24-bit [RR...RGG...GBB...B] data
70  * * LZF compressed 8-bit Bayer data
71  * * LZF compressed 16-bit YUV422 data
72  * * LZF compressed 16-bit depth data
73  *
74  * Please note that files found using the above mentioned extensions will be treated
75  * as such. Inherit from this class and overwrite the I/O methods if you plan to change
76  * this behavior.
77  *
78  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
79  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
80  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
81  * provide the best score for the types of applications PCL is suited for.
82  *
83  * \author Radu B. Rusu
84  * \ingroup io
85  */
86  class PCL_EXPORTS LZFImageReader
87  {
88  public:
89  /** Empty constructor */
90  LZFImageReader ();
91  /** Empty destructor */
92  virtual ~LZFImageReader () {}
93 
94  /** \brief Read camera parameters from a given file and store them internally.
95  * \return true if operation successful, false otherwise
96  */
97  bool
98  readParameters (const std::string &filename);
99 
100  /** \brief Read the parameters from a struct instead
101  * \param[in] parameters Camera parameters to use */
102  inline void
103  setParameters (const CameraParameters &parameters)
104  {
105  parameters_ = parameters;
106  }
107 
108  /** \brief Get the camera parameters currently being used
109  * returns a CameraParameters struct */
110  inline CameraParameters
111  getParameters () const
112  {
113  return parameters_;
114  }
115 
116  /** \brief Get the image width as read from disk. */
117  inline uint32_t
118  getWidth () const
119  {
120  return (width_);
121  }
122 
123  /** \brief Get the image height as read from disk. */
124  inline uint32_t
125  getHeight () const
126  {
127  return (height_);
128  }
129 
130  /** \brief Get the type of the image read from disk. */
131  inline std::string
132  getImageType () const
133  {
134  return (image_type_identifier_);
135  }
136 
137  protected:
138  /** \brief Read camera parameters from a given stream and store them internally.
139  * \return true if operation successful, false otherwise
140  */
141  virtual bool
142  readParameters (std::istream&) { return (false); }
143 
144  /** \brief Load a compressed image array from disk
145  * \param[in] filename the file name to load the data from
146  * \param[out] data_size the size of the data
147  * \return an array filled with the data loaded from disk, NULL if error
148  */
149  bool
150  loadImageBlob (const std::string &filename,
151  std::vector<char> &data,
152  uint32_t &uncompressed_size);
153 
154  /** \brief Realtime LZF decompression.
155  * \param[in] input the array to decompress
156  * \param[out] output the decompressed array
157  * \return true if operation successful, false otherwise
158  */
159  bool
160  decompress (const std::vector<char> &input,
161  std::vector<char> &output);
162 
163  /** \brief The image width, as read from the file. */
164  uint32_t width_;
165 
166  /** \brief The image height, as read from the file. */
167  uint32_t height_;
168 
169  /** \brief The image type string, as read from the file. */
171 
172  /** \brief Internal set of camera parameters. */
174  };
175 
176  /** \brief PCL-LZF 16-bit depth image format reader.
177  *
178  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
179  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
180  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
181  * provide the best score for the types of applications PCL is suited for.
182  *
183  * \author Radu B. Rusu
184  * \ingroup io
185  */
186  class PCL_EXPORTS LZFDepth16ImageReader : public LZFImageReader
187  {
188  public:
190 
191  /** Empty constructor */
193  : LZFImageReader ()
194  , z_multiplication_factor_ (0.001) // Set default multiplication factor
195  {}
196 
197  /** Empty destructor */
199 
200  /** \brief Read the data stored in a PCLZF depth file and convert it to a pcl::PointCloud type.
201  * \param[in] filename the file name to read the data from
202  * \param[out] cloud the resultant output point cloud
203  */
204  template <typename PointT> bool
205  read (const std::string &filename, pcl::PointCloud<PointT> &cloud);
206 
207  /** \brief Read the data stored in a PCLZF depth file and convert it to a pcl::PointCloud type.
208  * \param[in] filename the file name to read the data from
209  * \param[in] num_threads The number of threads to use. 0 indicates OpenMP is free to choose.
210  * \param[out] cloud the resultant output point cloud
211  */
212  template <typename PointT> bool
213  readOMP (const std::string &filename, pcl::PointCloud<PointT> &cloud,
214  unsigned int num_threads=0);
215 
216  /** \brief Read camera parameters from a given stream and store them internally.
217  * The parameters will be read from the <depth> ... </depth> tag.
218  * \return true if operation successful, false otherwise
219  */
220  virtual bool
221  readParameters (std::istream& is);
222 
223  protected:
224  /** \brief Z-value depth multiplication factor
225  * (i.e., if raw data is in [mm] and we want [m], we need to multiply with 0.001)
226  */
228  };
229 
230  /** \brief PCL-LZF 24-bit RGB image format reader.
231  *
232  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
233  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
234  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
235  * provide the best score for the types of applications PCL is suited for.
236  *
237  * \author Radu B. Rusu
238  * \ingroup io
239  */
240  class PCL_EXPORTS LZFRGB24ImageReader : public LZFImageReader
241  {
242  public:
244 
245  /** Empty constructor */
247  /** Empty destructor */
248  virtual ~LZFRGB24ImageReader () {}
249 
250  /** \brief Read the data stored in a PCLZF RGB file and convert it to a pcl::PointCloud type.
251  * \param[in] filename the file name to read the data from
252  * \param[out] cloud the resultant output point cloud
253  */
254  template<typename PointT> bool
255  read (const std::string &filename, pcl::PointCloud<PointT> &cloud);
256 
257  /** \brief Read the data stored in a PCLZF RGB file and convert it to a pcl::PointCloud type.
258  * Note that, unless massively multithreaded, this will likely not result in a significant speedup and may even slow performance.
259  * \param[in] filename the file name to read the data from
260  * \param[in] num_threads The number of threads to use
261  * \param[out] cloud the resultant output point cloud
262  */
263  template <typename PointT> bool
264  readOMP (const std::string &filename, pcl::PointCloud<PointT> &cloud,
265  unsigned int num_threads=0);
266 
267  /** \brief Read camera parameters from a given stream and store them internally.
268  * The parameters will be read from the <rgb> ... </rgb> tag.
269  * \return true if operation successful, false otherwise
270  */
271  virtual bool
272  readParameters (std::istream& is);
273 
274  protected:
275  };
276 
277  /** \brief PCL-LZF 8-bit Bayer image format reader.
278  *
279  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
280  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
281  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
282  * provide the best score for the types of applications PCL is suited for.
283  *
284  * \author Radu B. Rusu
285  * \ingroup io
286  */
287  class PCL_EXPORTS LZFYUV422ImageReader : public LZFRGB24ImageReader
288  {
289  public:
291 
292  /** Empty constructor */
294  /** Empty destructor */
296 
297  /** \brief Read the data stored in a PCLZF YUV422 16bit file and convert it to a pcl::PointCloud type.
298  * \param[in] filename the file name to read the data from
299  * \param[out] cloud the resultant output point cloud
300  */
301  template<typename PointT> bool
302  read (const std::string &filename, pcl::PointCloud<PointT> &cloud);
303 
304  /** \brief Read the data stored in a PCLZF YUV422 file and convert it to a pcl::PointCloud type.
305  * Note that, unless massively multithreaded, this will likely not result in a significant speedup
306  * \param[in] filename the file name to read the data from
307  * \param[in] num_threads The number of threads to use
308  * \param[out] cloud the resultant output point cloud
309  */
310  template <typename PointT> bool
311  readOMP (const std::string &filename, pcl::PointCloud<PointT> &cloud,
312  unsigned int num_threads=0);
313  };
314 
315  /** \brief PCL-LZF 8-bit Bayer image format reader.
316  *
317  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
318  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
319  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
320  * provide the best score for the types of applications PCL is suited for.
321  *
322  * \author Radu B. Rusu
323  * \ingroup io
324  */
325  class PCL_EXPORTS LZFBayer8ImageReader : public LZFRGB24ImageReader
326  {
327  public:
329 
330  /** Empty constructor */
332  /** Empty destructor */
334 
335  /** \brief Read the data stored in a PCLZF Bayer 8bit file and convert it to a pcl::PointCloud type.
336  * \param[in] filename the file name to read the data from
337  * \param[out] cloud the resultant output point cloud
338  */
339  template<typename PointT> bool
340  read (const std::string &filename, pcl::PointCloud<PointT> &cloud);
341 
342  /** \brief Read the data stored in a PCLZF Bayer 8bit file and convert it to a pcl::PointCloud type.
343  * Note that, unless massively multithreaded, this will likely not result in a significant speedup and may even slow performance.
344  * \param[in] filename the file name to read the data from
345  * \param[in] num_threads The number of threads to use
346  * \param[out] cloud the resultant output point cloud
347  */
348  template <typename PointT> bool
349  readOMP (const std::string &filename, pcl::PointCloud<PointT> &cloud,
350  unsigned int num_threads=0);
351  };
352 
353  /** \brief PCL-LZF image format writer.
354  * The PCL-LZF image format is nothing else but a LZF-modified compression over
355  * an existing file type (e.g., PNG). However, in certain situations, like RGB data for
356  * example, an [RGBRGB...RGB] array will be first reordered into [RR...RGG...GBB...B]
357  * in order to ensure better compression.
358  *
359  * The current list of compressors/decompressors include:
360  * * LZF compressed 24-bit [RR...RGG...GBB...B] data
361  * * LZF compressed 8-bit Bayer data
362  * * LZF compressed 16-bit YUV422 data
363  * * LZF compressed 16-bit depth data
364  *
365  * Please note that files found using the above mentioned extensions will be treated
366  * as such. Inherit from this class and overwrite the I/O methods if you plan to change
367  * this behavior.
368  *
369  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
370  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
371  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
372  * provide the best score for the types of applications PCL is suited for.
373  *
374  * \author Radu B. Rusu
375  * \ingroup io
376  */
377  class PCL_EXPORTS LZFImageWriter
378  {
379  public:
380  /** Empty constructor */
382  /** Empty destructor */
383  virtual ~LZFImageWriter () {}
384 
385  /** \brief Save an image into PCL-LZF format. Virtual.
386  * \param[in] data the array holding the image
387  * \param[in] width the with of the data array
388  * \param[in] height the height of the data array
389  * \param[in] filename the file name to write
390  * \return true if operation successful, false otherwise
391  */
392  virtual bool
393  write (const char* data,
394  uint32_t width, uint32_t height,
395  const std::string &filename) = 0;
396 
397  /** \brief Write camera parameters to disk. Virtual.
398  * \param[in] parameters the camera parameters
399  * \param[in] filename the file name to write
400  * \return true if operation successful, false otherwise
401  */
402  virtual bool
403  writeParameters (const CameraParameters &parameters,
404  const std::string &filename) = 0;
405 
406  /** \brief Save an image and its camera parameters into PCL-LZF format.
407  * \param[in] data the array holding the image
408  * \param[in] width the with of the data array
409  * \param[in] height the height of the data array
410  * \param[in] parameters the camera parameters
411  * \param[in] filename_data the file name to write the data to
412  * \param[in] filename_xml the file name to write the parameters to
413  * \return true if operation successful, false otherwise
414  */
415  virtual bool
416  write (const char* data,
417  uint32_t width, uint32_t height,
418  const CameraParameters &parameters,
419  const std::string &filename_data,
420  const std::string &filename_xml)
421  {
422  bool res1 = write (data, width, height, filename_data);
423  bool res2 = writeParameters (parameters, filename_xml);
424  return (res1 && res2);
425  }
426 
427  /** \brief Write a single image/camera parameter to file, given an XML tag
428  * \param[in] parameter the value of the parameter to write
429  * \param[in] tag the value of the XML tag
430  * \param[in] filename the file name to write
431  * \return true if operation successful, false otherwise
432  * Example:
433  * \code
434  * pcl::io::LZFDepthImageWriter w;
435  * w.writeParameter (0.001, "depth.multiplication_factor", "parameters.xml");
436  * \endcode
437  */
438  bool
439  writeParameter (const double &parameter, const std::string &tag,
440  const std::string &filename);
441  protected:
442  /** \brief Save a compressed image array to disk
443  * \param[in] data the data to save
444  * \param[in] data_size the size of the data
445  * \param[in] filename the file name to write the data to
446  * \return true if operation successful, false otherwise
447  */
448  bool
449  saveImageBlob (const char* data, size_t data_size,
450  const std::string &filename);
451 
452  /** \brief Realtime LZF compression.
453  * \param[in] input the array to compress
454  * \param[in] input_size the size of the array to compress
455  * \param[in] width the with of the data array
456  * \param[in] height the height of the data array
457  * \param[in] image_type the type of the image to save. This should be an up to
458  * 16 characters string describing the data type. Examples are: "bayer8", "rgb24",
459  * "yuv422", "depth16".
460  * \param[out] output the compressed output array (must be pre-allocated!)
461  * \return the number of bytes in the output array
462  */
463  uint32_t
464  compress (const char* input, uint32_t input_size,
465  uint32_t width, uint32_t height,
466  const std::string &image_type,
467  char *output);
468  };
469 
470  /** \brief PCL-LZF 16-bit depth image format writer.
471  *
472  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
473  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
474  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
475  * provide the best score for the types of applications PCL is suited for.
476  *
477  * \author Radu B. Rusu
478  * \ingroup io
479  */
480  class PCL_EXPORTS LZFDepth16ImageWriter : public LZFImageWriter
481  {
482  public:
483  /** Empty constructor */
485  : LZFImageWriter ()
486  , z_multiplication_factor_ (0.001) // Set default multiplication factor
487  {}
488 
489  /** Empty destructor */
491 
492  /** \brief Save a 16-bit depth image into PCL-LZF format.
493  * \param[in] data the array holding the depth image
494  * \param[in] width the with of the data array
495  * \param[in] height the height of the data array
496  * \param[in] filename the file name to write (preferred extension: .pclzf)
497  * \return true if operation successful, false otherwise
498  */
499  virtual bool
500  write (const char* data,
501  uint32_t width, uint32_t height,
502  const std::string &filename);
503 
504  /** \brief Write camera parameters to disk.
505  * \param[in] parameters the camera parameters
506  * \param[in] filename the file name to write
507  * \return true if operation successful, false otherwise
508  * This overwrites the following parameters in the xml file, under the
509  * <depth> tag:
510  * <focal_length_x>...</focal_length_x>
511  * <focal_length_y>...</focal_length_y>
512  * <principal_point_x>...</principal_point_x>
513  * <principal_point_y>...</principal_point_y>
514  * <z_multiplication_factor>...</z_multiplication_factor>
515  */
516  virtual bool
517  writeParameters (const CameraParameters &parameters,
518  const std::string &filename);
519 
520  protected:
521  /** \brief Z-value depth multiplication factor
522  * (i.e., if raw data is in [mm] and we want [m], we need to multiply with 0.001)
523  */
525  };
526 
527  /** \brief PCL-LZF 24-bit RGB image format writer.
528  *
529  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
530  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
531  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
532  * provide the best score for the types of applications PCL is suited for.
533  *
534  * \author Radu B. Rusu
535  * \ingroup io
536  */
537  class PCL_EXPORTS LZFRGB24ImageWriter : public LZFImageWriter
538  {
539  public:
540  /** Empty constructor */
542  /** Empty destructor */
543  virtual ~LZFRGB24ImageWriter () {}
544 
545  /** \brief Save a 24-bit RGB image into PCL-LZF format.
546  * \param[in] data the array holding the RGB image (as [RGB..RGB] or [BGR..BGR])
547  * \param[in] width the with of the data array
548  * \param[in] height the height of the data array
549  * \param[in] filename the file name to write (preferred extension: .pclzf)
550  * \return true if operation successful, false otherwise
551  */
552  virtual bool
553  write (const char *data,
554  uint32_t width, uint32_t height,
555  const std::string &filename);
556 
557  /** \brief Write camera parameters to disk.
558  * \param[in] parameters the camera parameters
559  * \param[in] filename the file name to write
560  * \return true if operation successful, false otherwise
561  */
562  virtual bool
563  writeParameters (const CameraParameters &parameters,
564  const std::string &filename);
565 
566  protected:
567  };
568 
569  /** \brief PCL-LZF 16-bit YUV422 image format writer.
570  *
571  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
572  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
573  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
574  * provide the best score for the types of applications PCL is suited for.
575  *
576  * \author Radu B. Rusu
577  * \ingroup io
578  */
579  class PCL_EXPORTS LZFYUV422ImageWriter : public LZFRGB24ImageWriter
580  {
581  public:
582  /** Empty constructor */
584  /** Empty destructor */
585  virtual ~LZFYUV422ImageWriter () {}
586 
587  /** \brief Save a 16-bit YUV422 image into PCL-LZF format.
588  * \param[in] data the array holding the YUV422 image (as [YUYV...YUYV])
589  * \param[in] width the with of the data array
590  * \param[in] height the height of the data array
591  * \param[in] filename the file name to write (preferred extension: .pclzf)
592  * \return true if operation successful, false otherwise
593  */
594  virtual bool
595  write (const char *data,
596  uint32_t width, uint32_t height,
597  const std::string &filename);
598  };
599 
600  /** \brief PCL-LZF 8-bit Bayer image format writer.
601  *
602  * The main advantage of using the PCL-LZF image I/O routines is a very good file size
603  * versus I/O speed ratio. Tests performed using LZF, Snappy, ZIP, GZ2, BZIP2, as well
604  * as PNG, JPEG, and TIFF compression have shown that the internal PCL LZF methods
605  * provide the best score for the types of applications PCL is suited for.
606  *
607  * \author Radu B. Rusu
608  * \ingroup io
609  */
610  class PCL_EXPORTS LZFBayer8ImageWriter : public LZFRGB24ImageWriter
611  {
612  public:
613  /** Empty constructor */
615  /** Empty destructor */
616  virtual ~LZFBayer8ImageWriter () {}
617 
618  /** \brief Save a 8-bit Bayer image into PCL-LZF format.
619  * \param[in] data the array holding the 8-bit Bayer array
620  * \param[in] width the with of the data array
621  * \param[in] height the height of the data array
622  * \param[in] filename the file name to write (preferred extension: .pclzf)
623  * \return true if operation successful, false otherwise
624  */
625  virtual bool
626  write (const char *data,
627  uint32_t width, uint32_t height,
628  const std::string &filename);
629  };
630  }
631 }
632 
633 #include <pcl/io/impl/lzf_image_io.hpp>
634 
635 #endif //#ifndef PCL_LZF_IMAGE_IO_H_