Main MRPT website > C++ reference for MRPT 1.5.7
CImage.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 #ifndef CImage_H
10 #define CImage_H
11 
12 #include <mrpt/utils/utils_defs.h>
14 #include <mrpt/math/eigen_frwds.h>
15 #include <mrpt/utils/CCanvas.h>
16 #include <mrpt/utils/TCamera.h>
17 #include <mrpt/utils/exceptions.h>
18 
19 // Add for declaration of mexplus::from template specialization
21 
22 namespace mrpt
23 {
24  namespace utils
25  {
26  /** Interpolation methods for images.
27  * Used for OpenCV related operations with images, but also with MRPT native classes.
28  * \sa mrpt::utils::CMappedImage, CImage::scaleImage
29  * \ingroup mrpt_base_grp
30  */
32  {
37  };
38 
39  /** For use in mrpt::utils::CImage */
40  typedef int TImageChannels;
41  #define CH_GRAY 1
42  #define CH_RGB 3
43 
44  /** For usage in one of the CImage constructors */
46  {
49  };
50 
51  // This must be added to any CSerializable derived class:
53 
54  /** A class for storing images as grayscale or RGB bitmaps.
55  * File I/O is supported as:
56  * - Binary dump using the CSerializable interface(<< and >> operators), just as most objects
57  * in the MRPT library. This format is not compatible with any standarized image format.
58  * - Saving/loading from files of different formats (bmp,jpg,png,...) using the methods CImage::loadFromFile and CImage::saveToFile.
59  * Available formats are all those supported by OpenCV
60  * - Importing from an XPM array (.xpm file format) using CImage::loadFromXPM
61  * - Importing TGA images. See CImage::loadTGA()
62  *
63  * How to create color/grayscale images:
64  * \code
65  * CImage img1(width, height, CH_GRAY ); // Grayscale image (8U1C)
66  * CImage img2(width, height, CH_RGB ); // RGB image (8U3C)
67  * \endcode
68  *
69  * Additional notes:
70  * - The OpenCV "IplImage" format is used internally for compatibility with all OpenCV functions. Use CImage::getAs<IplImage>() to retrieve the internal structure. Example:
71  * \code
72  * CImage img;
73  * ...
74  * // Call to OpenCV function expecting an "IplImage *" or a "void* arr":
75  * cv::Mat cvImg = cv::cvarrToMat( img.getAs<IplImage>() );
76  * cvFunction( img.getAs<IplImage>(), ... );
77  * \endcode
78  * - Only the unsigned 8-bit storage format for pixels (on each channel) is supported.
79  * - An external storage mode can be enabled by calling CImage::setExternalStorage, useful for storing large collections of image objects in memory while loading the image data itself only for the relevant images at any time.
80  * - To move images from one object to the another, use CImage::copyFastFrom rather than the copy operator =.
81  * - If you are interested in a smart pointer to an image, use:
82  * \code
83  * CImagePtr myImgPtr = CImagePtr( new CImage(...) );
84  * \endcode
85  * - To set a CImage from an OpenCV "IPLImage*", use the methods:
86  * - CImage::loadFromIplImage
87  * - CImage::setFromIplImage
88  * - CImage::CImage(void *IPL)
89  *
90  * Some functions are implemented in MRPT with highly optimized SSE2/SSE3 routines, in suitable platforms and compilers. To
91  * see the list of optimizations refer to \ref sse_optimizations "this page". If optimized versions are not available in some
92  * platform it falls back to default OpenCV methods.
93  *
94  * For many computer vision functions that use CImage as its image data type, see mrpt::vision.
95  *
96  * \note This class acts as a wrapper class to a small subset of OpenCV functions. IplImage is the internal storage structure.
97  *
98  * \sa mrpt::vision, mrpt::vision::CFeatureExtractor, mrpt::vision::CImagePyramid, CSerializable, CCanvas
99  * \ingroup mrpt_base_grp
100  */
101  class BASE_IMPEXP CImage : public mrpt::utils::CSerializable, public CCanvas
102  {
104 
105  // This must be added for declaration of MEX-related functions
107 
108 
109 
110  public:
111 
112  // ================================================================
113  /** @name Constructors & destructor
114  @{ */
115 
116  /** Default constructor: initialize an 1x1 RGB image. */
117  CImage();
118 
119  /** Constructor for a given image size and type.
120  * Examples:
121  * \code
122  * CImage img1(width, height, CH_GRAY ); // Grayscale image (8U1C)
123  * CImage img2(width, height, CH_RGB ); // RGB image (8U3C)
124  * \endcode
125  */
126  CImage( unsigned int width,
127  unsigned int height,
128  TImageChannels nChannels = CH_RGB,
129  bool originTopLeft = true
130  );
131 
132  /** Copy constructor, makes a full copy of the original image contents (unless it was externally stored, in that case, this new image will just point to the same image file). */
133  CImage( const CImage &o );
134 
135  /** Fast constructor that leaves the image uninitialized (the internal IplImage pointer set to NULL).
136  * Use only when you know the image will be soon be assigned another image.
137  * Example of usage:
138  * \code
139  * CImage myImg(UNINITIALIZED_IMAGE);
140  * \endcode
141  */
142  inline CImage(TConstructorFlags_CImage ) : img(NULL),m_imgIsReadOnly(false), m_imgIsExternalStorage(false)
143  { }
144 
145  /** Fast constructor of a grayscale version of another image, making a <b>reference</b> to the original image if it already was in grayscale, or otherwise creating a new grayscale image and converting the original image into it.
146  * It's <b>very important to keep in mind</b> that the original image can't be destroyed before the new object being created with this constructor.
147  * Example of usage:
148  * \code
149  * void my_func(const CImage &in_img) {
150  * const CImage gray_img(in_img, FAST_REF_OR_CONVERT_TO_GRAY);
151  * // We can now operate on "gray_img" being sure it's in grayscale.
152  * }
153  * \endcode
154  */
155  inline CImage(const CImage& other_img, TConstructorFlags_CImage constructor_flag) : img(NULL),m_imgIsReadOnly(false), m_imgIsExternalStorage(false)
156  {
157  MRPT_UNUSED_PARAM(constructor_flag);
158  if( other_img.isColor() ) other_img.grayscale(*this);
159  else this->setFromImageReadOnly(other_img);
160  }
161 
162  /** Constructor from an IPLImage*, making a copy of the image.
163  * \sa loadFromIplImage, setFromIplImage
164  */
165  CImage( void *iplImage );
166 
167  /** Explicit constructor from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false)
168  * \sa setFromMatrix
169  */
170  template <typename Derived>
171  explicit inline CImage(const Eigen::MatrixBase<Derived> &m, bool matrix_is_normalized) : img(NULL),m_imgIsReadOnly(false), m_imgIsExternalStorage(false)
172  {
173  this->setFromMatrix(m,matrix_is_normalized);
174  }
175 
176 
177  /** Destructor: */
178  virtual ~CImage( );
179 
180  /** @} */
181  // ================================================================
182 
183  /** @name Serialization format global flags
184  @{ */
185 
186  /** By default, when storing images through the CSerializable interface, grayscale images will be ZIP compressed if they are larger than 16Kb: this flag can be turn on to disable ZIP compression and gain speed versus occupied space.
187  * (Default = false) */
189 
190  /** By default, when storing images through the CSerializable interface, RGB images are JPEG-compressed to save space. If for some reason you prefer storing RAW image data, disable this feature by setting this flag to true.
191  * (Default = false) */
193 
194  /** Unless DISABLE_JPEG_COMPRESSION=true, this sets the JPEG quality (range 1-100) of serialized RGB images.
195  * (Default = 95) */
197 
198  /** @} */
199 
200  // ================================================================
201  /** @name Manipulate the image contents or size, various computer-vision methods (image filters, undistortion, etc.)
202  @{ */
203 
204  /** Changes the size of the image, erasing previous contents (does NOT scale its current content, for that, see scaleImage).
205  * - nChannels: Can be 3 for RGB images or 1 for grayscale images.
206  * - originTopLeft: Is true if the top-left corner is (0,0). In other case, the reference is the bottom-left corner.
207  * \sa scaleImage
208  */
209  inline void resize(
210  unsigned int width,
211  unsigned int height,
212  TImageChannels nChannels,
213  bool originTopLeft )
214  {
215  changeSize(width,height,nChannels,originTopLeft);
216  }
217 
218  /** Scales this image to a new size, interpolating as needed.
219  * \sa resize, rotateImage
220  */
221  void scaleImage( unsigned int width, unsigned int height, TInterpolationMethod interp = IMG_INTERP_CUBIC );
222 
223  /** Scales this image to a new size, interpolating as needed, saving the new image in a different output object.
224  * \sa resize, rotateImage
225  */
226  void scaleImage( CImage &out_img, unsigned int width, unsigned int height, TInterpolationMethod interp = IMG_INTERP_CUBIC ) const;
227 
228  /** Rotates the image by the given angle around the given center point, with an optional scale factor.
229  * \sa resize, scaleImage
230  */
231  void rotateImage( double angle_radians, unsigned int center_x, unsigned int center_y, double scale = 1.0 );
232 
233  /** Changes the value of the pixel (x,y).
234  * Pixel coordinates starts at the left-top corner of the image, and start in (0,0).
235  * The meaning of the parameter "color" depends on the implementation: it will usually
236  * be a 24bit RGB value (0x00RRGGBB), but it can also be just a 8bit gray level.
237  * This method must support (x,y) values OUT of the actual image size without neither
238  * raising exceptions, nor leading to memory access errors.
239  */
240  void setPixel(int x, int y, size_t color) MRPT_OVERRIDE;
241 
242  /** Changes the property of the image stating if the top-left corner (vs. bottom-left) is the coordinate reference */
243  void setOriginTopLeft(bool val);
244 
245  /** Draws a line.
246  * \param x0 The starting point x coordinate
247  * \param y0 The starting point y coordinate
248  * \param x1 The end point x coordinate
249  * \param y1 The end point y coordinate
250  * \param color The color of the line
251  * \param width The desired width of the line (this is IGNORED in this virtual class)
252  * This method may be redefined in some classes implementing this interface in a more appropiate manner.
253  */
254  void line(
255  int x0, int y0,
256  int x1, int y1,
258  unsigned int width = 1,
259  TPenStyle penStyle = psSolid) MRPT_OVERRIDE;
260 
261  /** Draws a circle of a given radius.
262  * \param x The center - x coordinate in pixels.
263  * \param y The center - y coordinate in pixels.
264  * \param radius The radius - in pixels.
265  * \param color The color of the circle.
266  * \param width The desired width of the line
267  */
268  void drawCircle(
269  int x,
270  int y,
271  int radius,
272  const mrpt::utils::TColor &color = mrpt::utils::TColor(255,255,255),
273  unsigned int width = 1) MRPT_OVERRIDE;
274 
275  void equalizeHistInPlace(); //!< Equalize the image histogram, replacing the original image. \note RGB images are first converted to HSV color space, then equalized for brightness (V)
276  void equalizeHist( CImage &outImg ) const; //!< Equalize the image histogram, saving the new image in the given output object. \note RGB images are first converted to HSV color space, then equalized for brightness (V)
277 
278  /** Returns a new image scaled down to half its original size.
279  * \exception std::exception On odd size
280  * \sa scaleDouble, scaleImage, scaleHalfSmooth
281  */
282  CImage scaleHalf()const
283  {
285  this->scaleHalf(ret);
286  return ret;
287  }
288 
289  //! \overload
290  void scaleHalf(CImage &out_image) const;
291 
292 
293  /** Returns a new image scaled down to half its original size (averaging between every two rows)
294  * \exception std::exception On odd size
295  * \sa scaleDouble, scaleImage, scaleHalf
296  */
298  {
300  this->scaleHalfSmooth(ret);
301  return ret;
302  }
303 
304  //! \overload
305  void scaleHalfSmooth(CImage &out_image) const;
306 
307 
308  /** Returns a new image scaled up to double its original size.
309  * \exception std::exception On odd size
310  * \sa scaleHalf, scaleImage
311  */
313  {
315  this->scaleDouble(ret);
316  return ret;
317  }
318 
319  //! \overload
320  void scaleDouble(CImage &out_image) const;
321 
322 
323  /** Update a part of this image with the "patch" given as argument.
324  * The "patch" will be "pasted" at the (col,row) coordinates of this image.
325  * \exception std::exception if patch pasted on the pixel (_row, _column) jut out
326  * of the image.
327  * \sa extract_patch
328  */
329  void update_patch(const CImage &patch,
330  const unsigned int col,
331  const unsigned int row);
332 
333  /** Extract a patch from this image, saveing it into "patch" (its previous contents will be overwritten).
334  * The patch to extract starts at (col,row) and has the given dimensions.
335  * \sa update_patch
336  */
337  void extract_patch(
338  CImage &patch,
339  const unsigned int col=0,
340  const unsigned int row=0,
341  const unsigned int width=1,
342  const unsigned int height=1 ) const;
343 
344  /** Computes the correlation coefficient (returned as val), between two images
345  * This function use grayscale images only
346  * img1, img2 must be same size
347  * (by AJOGD @ DEC-2006)
348  */
349  float correlate( const CImage &img2int, int width_init=0, int height_init=0 )const;
350 
351  /** Computes the correlation between this image and another one, encapsulating the openCV function cvMatchTemplate
352  *
353  * \param patch_img The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
354  * \param u_search_ini The "x" coordinate of the search window.
355  * \param v_search_ini The "y" coordinate of the search window.
356  * \param u_search_size The width of the search window.
357  * \param v_search_size The height of the search window.
358  * \param u_max The u coordinate where find the maximun cross correlation value.
359  * \param v_max The v coordinate where find the maximun cross correlation value
360  * \param max_val The maximun value of cross correlation which we can find
361  * \param out_corr_image If a !=NULL pointer is provided, it will be saved here the correlation image. The size of the output image is (this_width-patch_width+1, this_height-patch_height+1 )
362  * Note: By default, the search area is the whole (this) image.
363  * (by AJOGD @ MAR-2007)
364  */
365  void cross_correlation(
366  const CImage &patch_img,
367  size_t &u_max,
368  size_t &v_max,
369  double &max_val,
370  int u_search_ini=-1,
371  int v_search_ini=-1,
372  int u_search_size=-1,
373  int v_search_size=-1,
374  CImage *out_corr_image = NULL
375  )const;
376 
377  /** Computes the correlation matrix between this image and another one.
378  * This implementation uses the 2D FFT for achieving reduced computation time.
379  * \param in_img The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
380  * \param u_search_ini The "x" coordinate of the search window.
381  * \param v_search_ini The "y" coordinate of the search window.
382  * \param u_search_size The width of the search window.
383  * \param v_search_size The height of the search window.
384  * \param out_corr The output for the correlation matrix, which will be "u_search_size" x "v_search_size"
385  * \param biasThisImg This optional parameter is a fixed "bias" value to be substracted to the pixels of "this" image before performing correlation.
386  * \param biasInImg This optional parameter is a fixed "bias" value to be substracted to the pixels of "in_img" image before performing correlation.
387  * Note: By default, the search area is the whole (this) image.
388  * (by JLBC @ JAN-2006)
389  * \sa cross_correlation
390  */
392  const CImage &in_img,
393  math::CMatrixFloat &out_corr,
394  int u_search_ini=-1,
395  int v_search_ini=-1,
396  int u_search_size=-1,
397  int v_search_size=-1,
398  float biasThisImg = 0,
399  float biasInImg = 0
400  ) const;
401 
402 
403  /** Optimize the brightness range of an image without using histogram
404  * Only for one channel images.
405  * \sa equalizeHist
406  */
407  void normalize();
408 
409  void flipVertical(bool also_swapRB = false); //!< Flips the image vertically. \sa swapRB(), flipHorizontal()
410  void flipHorizontal(); //!< Flips the image horizontally \sa swapRB(), flipVertical()
411 
412  void swapRB(); //!< Swaps red and blue channels.
413 
414  /** Rectify (un-distort) the image according to some camera parameters, and returns an output un-distorted image.
415  * \param out_img The output rectified image
416  * \param cameraParams The input camera params (containing the intrinsic and distortion parameters of the camera)
417  * \sa mrpt::vision::CUndistortMap
418  */
419  void rectifyImage( CImage &out_img, const mrpt::utils::TCamera &cameraParams) const;
420 
421  /** Rectify (un-distort) the image according to a certain camera matrix and vector of distortion coefficients, replacing "this" with the rectified image
422  * \param cameraParams The input camera params (containing the intrinsic and distortion parameters of the camera)
423  * \sa mrpt::vision::CUndistortMap
424  */
425  void rectifyImageInPlace(const mrpt::utils::TCamera &cameraParams );
426 
427  /** Rectify an image (undistorts and rectification) from a stereo pair according to a pair of precomputed rectification maps
428  * \param mapX, mapY [IN] The pre-computed maps of the rectification (should be computed beforehand)
429  * \sa mrpt::vision::CStereoRectifyMap, mrpt::vision::computeStereoRectificationMaps
430  */
431  void rectifyImageInPlace( void *mapX, void *mapY );
432 
433  /** Filter the image with a Median filter with a window size WxW, returning the filtered image in out_img */
434  void filterMedian( CImage &out_img, int W=3 ) const;
435 
436  /** Filter the image with a Median filter with a window size WxH, replacing "this" image by the filtered one. */
437  void filterMedianInPlace( int W=3 );
438 
439  /** Filter the image with a Gaussian filter with a window size WxH, returning the filtered image in out_img */
440  void filterGaussianInPlace( int W = 3, int H = 3 );
441 
442  /** Filter the image with a Gaussian filter with a window size WxH, replacing "this" image by the filtered one. */
443  void filterGaussian( CImage &out_img, int W = 3, int H = 3) const;
444 
445  /** Draw onto this image the detected corners of a chessboard. The length of cornerCoords must be the product of the two check_sizes.
446  *
447  * \param cornerCoords [IN] The pixel coordinates of all the corners.
448  * \param check_size_x [IN] The number of squares, in the X direction
449  * \param check_size_y [IN] The number of squares, in the Y direction
450  *
451  * \return false if the length of cornerCoords is inconsistent (nothing is drawn then).
452  *
453  * \sa mrpt::vision::findChessboardCorners
454  */
455  bool drawChessboardCorners(
456  std::vector<TPixelCoordf> &cornerCoords,
457  unsigned int check_size_x,
458  unsigned int check_size_y,
459  unsigned int lines_width = 1,
460  unsigned int circles_radius = 4
461  );
462 
463  /** Joins two images side-by-side horizontally. Both images must have the same number of rows and be of the same type (i.e. depth and color mode)
464  *
465  * \param im1 [IN] The first image.
466  * \param im2 [IN] The other image.
467  */
468  void joinImagesHorz(
469  const CImage &im1,
470  const CImage &im2 );
471 
472  /** Compute the KLT response at a given pixel (x,y) - Only for grayscale images (for efficiency it avoids converting to grayscale internally).
473  * See KLT_response_optimized for more details on the internal optimizations of this method, but this graph shows a general view:
474  * <img src="KLT_response_performance_SSE2.png" >
475  */
476  float KLT_response(
477  const unsigned int x,
478  const unsigned int y,
479  const unsigned int half_window_size ) const;
480 
481  /** @} */
482  // ================================================================
483 
484 
485 
486  // ================================================================
487  /** @name Copy, move & swap operations
488  @{ */
489 
490  /** Copy operator (if the image is externally stored, the writen image will be such as well).
491  * \sa copyFastFrom
492  */
493  CImage& operator = (const CImage& o);
494 
495  /** Copies from another image, and, if that one is externally stored, the image file will be actually loaded into memory in "this" object.
496  * \sa operator =
497  * \exception CExceptionExternalImageNotFound If the external image couldn't be loaded.
498  */
499  void copyFromForceLoad(const CImage &o);
500 
501  /** Moves an image from another object, erasing the origin image in the process (this is much faster than copying)
502  * \sa operator =
503  */
504  void copyFastFrom( CImage &o );
505 
506  void swap(CImage &o); //!< Very efficient swap of two images (just swap the internal pointers)
507 
508  /** @} */
509  // ================================================================
510 
511 
512  // ================================================================
513  /** @name Access to image contents (IplImage structure and raw pixels).
514  @{ */
515 
516  /** Returns a pointer to a const T* containing the image - the idea is to call like "img.getAs<IplImage>()" so we can avoid here including OpenCV's headers. */
517  template <typename T> inline const T* getAs() const {
518  makeSureImageIsLoaded();
519  return static_cast<const T*>(img);
520  }
521  /** Returns a pointer to a T* containing the image - the idea is to call like "img.getAs<IplImage>()" so we can avoid here including OpenCV's headers. */
522  template <typename T> inline T* getAs(){
523  makeSureImageIsLoaded();
524  return static_cast<T*>(img);
525  }
526 
527  /** Access to pixels without checking boundaries - Use normally the () operator better, which checks the coordinates.
528  \sa CImage::operator()
529  */
530  unsigned char* get_unsafe(
531  unsigned int col,
532  unsigned int row,
533  unsigned int channel=0) const;
534 
535  /** Returns the contents of a given pixel at the desired channel, in float format: [0,255]->[0,1]
536  * The coordinate origin is pixel(0,0)=top-left corner of the image.
537  * \exception std::exception On pixel coordinates out of bounds
538  * \sa operator()
539  */
540  float getAsFloat(unsigned int col, unsigned int row, unsigned int channel) const;
541 
542  /** Returns the contents of a given pixel (for gray-scale images, in color images the gray scale equivalent is computed for the pixel), in float format: [0,255]->[0,1]
543  * The coordinate origin is pixel(0,0)=top-left corner of the image.
544  * \exception std::exception On pixel coordinates out of bounds
545  * \sa operator()
546  */
547  float getAsFloat(unsigned int col, unsigned int row) const;
548 
549  /** Returns a pointer to a given pixel information.
550  * The coordinate origin is pixel(0,0)=top-left corner of the image.
551  * \exception std::exception On pixel coordinates out of bounds
552  */
553  unsigned char* operator()(unsigned int col, unsigned int row, unsigned int channel = 0) const;
554 
555  /** @} */
556  // ================================================================
557 
558 
559 
560  // ================================================================
561  /** @name Query image properties
562  @{ */
563 
564  size_t getWidth() const MRPT_OVERRIDE; //!< Returns the width of the image in pixels \sa getSize
565  size_t getHeight() const MRPT_OVERRIDE; //!< Returns the height of the image in pixels \sa getSize
566 
567  void getSize(TImageSize &s) const; //!< Return the size of the image \sa getWidth, getHeight
568  /** Return the size of the image \sa getWidth, getHeight */
569  inline TImageSize getSize() const {
570  TImageSize ret;
571  getSize(ret);
572  return ret;
573  }
574 
575  /** Returns the row stride of the image: this is the number of *bytes* between two consecutive rows. You can access the pointer to the first row with get_unsafe(0,0)
576  * \sa getSize, get_unsafe */
577  size_t getRowStride() const;
578 
579  /** Return the maximum pixel value of the image, as a float value in the range [0,1]
580  * \sa getAsFloat */
581  float getMaxAsFloat() const;
582 
583  /** Returns true if the image is RGB, false if it is grayscale */
584  bool isColor() const;
585 
586  /** Returns true if the coordinates origin is top-left, or false if it is bottom-left */
587  bool isOriginTopLeft() const;
588 
589  /** Returns a string of the form "BGR","RGB" or "GRAY" indicating the channels ordering. \sa setChannelsOrder, swapRB */
590  const char * getChannelsOrder()const;
591 
592  /** Marks the channel ordering in a color image as "RGB" (this doesn't actually modify the image data, just the format description) \sa getChannelsOrder, swapRB */
593  void setChannelsOrder_RGB();
594  /** Marks the channel ordering in a color image as "BGR" (this doesn't actually modify the image data, just the format description) \sa getChannelsOrder, swapRB */
595  void setChannelsOrder_BGR();
596 
597  /** Returns the number of channels, typically 1 (GRAY) or 3 (RGB)
598  * \sa isColor
599  */
600  TImageChannels getChannelCount() const;
601 
602  /** Returns the image as a matrix with pixel grayscale values in the range [0,1]. Matrix indexes in this order: M(row,column)
603  * \param doResize If set to true (default), the output matrix will be always the size of the image at output. If set to false, the matrix will be enlarged to the size of the image, but it will not be cropped if it has room enough (useful for FFT2D,...)
604  * \param x_min The starting "x" coordinate to extract (default=0=the first column)
605  * \param y_min The starting "y" coordinate to extract (default=0=the first row)
606  * \param x_max The final "x" coordinate (inclusive) to extract (default=-1=the last column)
607  * \param y_max The final "y" coordinate (inclusive) to extract (default=-1=the last row)
608  * \sa setFromMatrix
609  */
610  void getAsMatrix(
611  mrpt::math::CMatrixFloat &outMatrix,
612  bool doResize = true,
613  int x_min = 0,
614  int y_min = 0,
615  int x_max = -1,
616  int y_max = -1
617  ) const;
618 
619  /** Returns the image as RGB matrices with pixel values in the range [0,1]. Matrix indexes in this order: M(row,column)
620  * \param doResize If set to true (default), the output matrix will be always the size of the image at output. If set to false, the matrix will be enlarged to the size of the image, but it will not be cropped if it has room enough (useful for FFT2D,...)
621  * \param x_min The starting "x" coordinate to extract (default=0=the first column)
622  * \param y_min The starting "y" coordinate to extract (default=0=the first row)
623  * \param x_max The final "x" coordinate (inclusive) to extract (default=-1=the last column)
624  * \param y_max The final "y" coordinate (inclusive) to extract (default=-1=the last row)
625  * \sa setFromRGBMatrices
626  */
627  void getAsRGBMatrices(
628  mrpt::math::CMatrixFloat &outMatrixR,
629  mrpt::math::CMatrixFloat &outMatrixG,
630  mrpt::math::CMatrixFloat &outMatrixB,
631  bool doResize = true,
632  int x_min = 0,
633  int y_min = 0,
634  int x_max = -1,
635  int y_max = -1
636  ) const;
637 
638  /** Returns the image as a matrix, where the image is "tiled" (repeated) the required number of times to fill the entire size of the matrix on input.
639  */
640  void getAsMatrixTiled( math::CMatrix &outMatrix ) const;
641 
642  /** @} */
643  // ================================================================
644 
645 
646  // ================================================================
647  /** @name External storage-mode methods
648  @{ */
649 
650  /** By using this method the image is marked as referenced to an external file, which will be loaded only under demand.
651  * A CImage with external storage does not consume memory until some method trying to access the image is invoked (e.g. getWidth(), isColor(),...)
652  * At any moment, the image can be unloaded from memory again by invoking unload.
653  * An image becomes of type "external storage" only through calling setExternalStorage. This property remains after serializing the object.
654  * File names can be absolute, or relative to the CImage::IMAGES_PATH_BASE directory. Filenames staring with "X:\" or "/" are considered absolute paths.
655  * By calling this method the current contents of the image are NOT saved to that file, because this method can be also called
656  * to let the object know where to load the image in case its contents are required. Thus, for saving images in this format (not when loading)
657  * the proper order of commands should be:
658  * \code
659  * img.saveToFile( fileName );
660  * img.setExternalStorage( fileName );
661  * \endcode
662  *
663  * \note Modifications to the memory copy of the image are not automatically saved to disk.
664  * \sa unload, isExternallyStored
665  */
666  void setExternalStorage( const std::string &fileName ) MRPT_NO_THROWS;
667 
668  static std::string IMAGES_PATH_BASE; //!< By default, "." \sa setExternalStorage
669 
670  /** See setExternalStorage(). */
671  bool isExternallyStored() const MRPT_NO_THROWS { return m_imgIsExternalStorage; }
672 
673  inline std::string getExternalStorageFile() const MRPT_NO_THROWS //!< Only if isExternallyStored() returns true. \sa getExternalStorageFileAbsolutePath
674  {
675  return m_externalFile;
676  }
677 
678  /** Only if isExternallyStored() returns true. \sa getExternalStorageFile */
679  void getExternalStorageFileAbsolutePath(std::string &out_path) const;
680 
681  /** Only if isExternallyStored() returns true. \sa getExternalStorageFile */
683  std::string tmp;
684  getExternalStorageFileAbsolutePath(tmp);
685  return tmp;
686  }
687 
688  /** For external storage image objects only, this method makes sure the image is loaded in memory. Note that usually images are loaded on-the-fly on first access and there's no need to call this.
689  * \unload
690  */
691  inline void forceLoad() const { makeSureImageIsLoaded(); }
692 
693  /** For external storage image objects only, this method unloads the image from memory (or does nothing if already unloaded).
694  * It does not need to be called explicitly, unless the user wants to save memory for images that will not be used often.
695  * If called for an image without the flag "external storage", it is simply ignored.
696  * \sa setExternalStorage, forceLoad
697  */
698  void unload() const MRPT_NO_THROWS;
699 
700  /** @} */
701  // ================================================================
702 
703 
704  // ================================================================
705  /** @name Set, load & save methods
706  @{ */
707 
708  /** Reads the image from raw pixels buffer in memory.
709  */
710  void loadFromMemoryBuffer( unsigned int width, unsigned int height, bool color, unsigned char *rawpixels, bool swapRedBlue = false );
711 
712  /** Reads a color image from three raw pixels buffers in memory.
713  * bytesPerRow is the number of bytes per row per channel, i.e. the row increment.
714  */
715  void loadFromMemoryBuffer( unsigned int width, unsigned int height, unsigned int bytesPerRow, unsigned char *red, unsigned char *green, unsigned char *blue );
716 
717  /** Reads the image from a OpenCV IplImage object (making a COPY).
718  */
719  void loadFromIplImage( void* iplImage );
720 
721  /** Reads the image from a OpenCV IplImage object (WITHOUT making a copy).
722  * This object will own the memory of the passed object and free the IplImage upon destruction,
723  * so the caller CAN'T free the original object.
724  * This method provides a fast method to grab images from a camera without making a copy of every frame.
725  */
726  void setFromIplImage( void* iplImage );
727 
728  /** Reads the image from a OpenCV IplImage object (WITHOUT making a copy) and from now on the image cannot be modified, just read.
729  * When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor.
730  * This method provides a fast method to grab images from a camera without making a copy of every frame.
731  * \sa setFromImageReadOnly
732  */
733  void setFromIplImageReadOnly( void* iplImage );
734 
735  /** Sets the internal IplImage pointer to that of another given image, WITHOUT making a copy, and from now on the image cannot be modified in this object (it will be neither freed, so the memory responsibility will still be of the original image object).
736  * When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor.
737  * \sa setFromIplImageReadOnly
738  */
739  inline void setFromImageReadOnly( const CImage &other_img ) { setFromIplImageReadOnly(const_cast<void*>(other_img.getAs<void>()) ); }
740 
741  /** Set the image from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false)
742  * Matrix indexes are assumed to be in this order: M(row,column)
743  * \sa getAsMatrix
744  */
745  template <typename Derived>
746  void setFromMatrix(const Eigen::MatrixBase<Derived> &m, bool matrix_is_normalized=true)
747  {
748  MRPT_START
749  const unsigned int lx = m.cols();
750  const unsigned int ly = m.rows();
751  this->changeSize(lx,ly,1,true);
752  if (matrix_is_normalized) { // Matrix: [0,1]
753  for (unsigned int y=0;y<ly;y++) {
754  unsigned char *pixels = this->get_unsafe(0,y,0);
755  for (unsigned int x=0;x<lx;x++)
756  (*pixels++) = static_cast<unsigned char>( m.get_unsafe(y,x) * 255 );
757  }
758  }
759  else { // Matrix: [0,255]
760  for (unsigned int y=0;y<ly;y++) {
761  unsigned char *pixels = this->get_unsafe(0,y,0);
762  for (unsigned int x=0;x<lx;x++)
763  (*pixels++) = static_cast<unsigned char>( m.get_unsafe(y,x) );
764  }
765  }
766  MRPT_END
767  }
768 
769  /** Set the image from RGB matrices, given the pixels in the range [0,1] (normalized=true) or [0,255] (normalized=false)
770  * Matrix indexes are assumed to be in this order: M(row,column)
771  * \sa getAsRGBMatrices
772  */
773  template <typename Derived>
774  void setFromRGBMatrices(const Eigen::MatrixBase<Derived> &m_r, const Eigen::MatrixBase<Derived> &m_g, const Eigen::MatrixBase<Derived> &m_b, bool matrix_is_normalized=true)
775  {
776  MRPT_START
777  makeSureImageIsLoaded(); // For delayed loaded images stored externally
778  ASSERT_(img);
779  ASSERT_((m_r.size() == m_g.size())&&(m_r.size() == m_b.size()));
780  const unsigned int lx = m_r.cols();
781  const unsigned int ly = m_r.rows();
782  this->changeSize(lx,ly,3,true);
783  this->setChannelsOrder_RGB();
784 
785  if (matrix_is_normalized) { // Matrix: [0,1]
786  for (unsigned int y=0;y<ly;y++) {
787  unsigned char *pixels = this->get_unsafe(0,y,0);
788  for (unsigned int x=0;x<lx;x++)
789  {
790  (*pixels++) = static_cast<unsigned char>( m_r.get_unsafe(y,x) * 255 );
791  (*pixels++) = static_cast<unsigned char>( m_g.get_unsafe(y,x) * 255 );
792  (*pixels++) = static_cast<unsigned char>( m_b.get_unsafe(y,x) * 255 );
793  }
794  }
795  }
796  else { // Matrix: [0,255]
797  for (unsigned int y=0;y<ly;y++) {
798  unsigned char *pixels = this->get_unsafe(0,y,0);
799  for (unsigned int x=0;x<lx;x++)
800  {
801  (*pixels++) = static_cast<unsigned char>( m_r.get_unsafe(y,x) );
802  (*pixels++) = static_cast<unsigned char>( m_g.get_unsafe(y,x) );
803  (*pixels++) = static_cast<unsigned char>( m_b.get_unsafe(y,x) );
804  }
805  }
806  }
807  MRPT_END
808  }
809 
810  /** Reads the image from a binary stream containing a binary jpeg file.
811  * \exception std::exception On pixel coordinates out of bounds
812  */
813  void loadFromStreamAsJPEG( CStream &in );
814 
815  /** Load image from a file, whose format is determined from the extension (internally uses OpenCV).
816  * \param fileName The file to read from.
817  * \param isColor Specifies colorness of the loaded image:
818  * - if >0, the loaded image is forced to be color 3-channel image;
819  * - if 0, the loaded image is forced to be grayscale;
820  * - if <0, the loaded image will be loaded as is (with number of channels depends on the file).
821  * The supported formats are:
822  *
823  * - Windows bitmaps - BMP, DIB;
824  * - JPEG files - JPEG, JPG, JPE;
825  * - Portable Network Graphics - PNG;
826  * - Portable image format - PBM, PGM, PPM;
827  * - Sun rasters - SR, RAS;
828  * - TIFF files - TIFF, TIF.
829  *
830  * \return False on any error
831  * \sa saveToFile, setExternalStorage,loadFromXPM, loadTGA
832  */
833  bool loadFromFile( const std::string& fileName, int isColor = -1 );
834 
835  /** Loads a TGA true-color RGBA image as two CImage objects, one for the RGB channels plus a separate gray-level image with A channel.
836  * \return true on success
837  */
838  static bool loadTGA(const std::string& fileName, mrpt::utils::CImage &out_RGB, mrpt::utils::CImage &out_alpha);
839 
840  /** Loads the image from an XPM array, as #include'd from a ".xpm" file.
841  * \param[in] swap_rb Swaps red/blue channels from loaded image. *Seems* to be always needed, so it's enabled by default.
842  * \sa loadFromFile
843  * \return false on any error */
844  bool loadFromXPM( const char** xpm_array, bool swap_rb = true );
845 
846  /** Save the image to a file, whose format is determined from the extension (internally uses OpenCV).
847  * \param fileName The file to write to.
848  *
849  * The supported formats are:
850  *
851  * - Windows bitmaps - BMP, DIB;
852  * - JPEG files - JPEG, JPG, JPE;
853  * - Portable Network Graphics - PNG;
854  * - Portable image format - PBM, PGM, PPM;
855  * - Sun rasters - SR, RAS;
856  * - TIFF files - TIFF, TIF.
857  *
858  * \param jpeg_quality Only for JPEG files, the quality of the compression in the range [0-100]. Larger is better quality but slower.
859  * \note jpeg_quality is only effective if MRPT is compiled against OpenCV 1.1.0 or newer.
860  * \return False on any error
861  * \sa loadFromFile
862  */
863  bool saveToFile( const std::string& fileName, int jpeg_quality = 95 ) const;
864 
865  /** Save image to binary stream as a JPEG (.jpg) compressed format.
866  * \exception std::exception On number of rows or cols equal to zero or other errors.
867  * \sa saveToJPEG
868  */
869  void saveToStreamAsJPEG(mrpt::utils::CStream &out, const int jpeg_quality = 95 ) const;
870 
871  /** @} */
872  // ================================================================
873 
874 
875  // ================================================================
876  /** @name Color/Grayscale conversion
877  @{ */
878 
879  /** Returns a grayscale version of the image, or itself if it is already a grayscale image.
880  */
881  CImage grayscale() const;
882 
883  /** Returns a grayscale version of the image, or itself if it is already a grayscale image.
884  * \sa colorImage
885  */
886  void grayscale( CImage &ret ) const;
887 
888  /** Returns a RGB version of the grayscale image, or itself if it is already a RGB image.
889  * \sa grayscale
890  */
891  void colorImage( CImage &ret ) const;
892 
893  /** Replaces this grayscale image with a RGB version of it.
894  * \sa grayscaleInPlace
895  */
896  void colorImageInPlace();
897 
898 
899  /** Replaces the image with a grayscale version of it.
900  * \sa colorImageInPlace
901  */
902  void grayscaleInPlace();
903 
904  /** @} */
905  // ================================================================
906 
907 
908  protected:
909  /** @name Data members
910  @{ */
911 
912  void *img; //!< The internal IplImage pointer to the actual image content.
913 
914  /** Set to true only when using setFromIplImageReadOnly.
915  * \sa setFromIplImageReadOnly */
917  /** Set to true only when using setExternalStorage.
918  * \sa setExternalStorage
919  */
921  mutable std::string m_externalFile; //!< The file name of a external storage image.
922 
923  /** @} */
924 
925  /** Resize the buffers in "img" to accomodate a new image size and/or format.
926  */
927  void changeSize(
928  unsigned int width,
929  unsigned int height,
930  TImageChannels nChannels,
931  bool originTopLeft );
932 
933  /** Release the internal IPL image, if not NULL or read-only. */
934  void releaseIpl(bool thisIsExternalImgUnload = false) MRPT_NO_THROWS;
935 
936  /** Checks if the image is of type "external storage", and if so and not loaded yet, load it.
937  * \exception mrpt::utils::CExceptionExternalImageNotFound */
938  void makeSureImageIsLoaded() const;
939 
940  }; // End of class
942 
943  } // end of namespace utils
944 
945 } // end of namespace mrpt
946 
947 #endif
TConstructorFlags_CImage
For usage in one of the CImage constructors.
Definition: CImage.h:45
CImage(const Eigen::MatrixBase< Derived > &m, bool matrix_is_normalized)
Explicit constructor from a matrix, interpreted as grayscale intensity values, in the range [0...
Definition: CImage.h:171
static bool DISABLE_JPEG_COMPRESSION
By default, when storing images through the CSerializable interface, RGB images are JPEG-compressed t...
Definition: CImage.h:192
static int SERIALIZATION_JPEG_QUALITY
Unless DISABLE_JPEG_COMPRESSION=true, this sets the JPEG quality (range 1-100) of serialized RGB imag...
Definition: CImage.h:196
std::string m_externalFile
The file name of a external storage image.
Definition: CImage.h:921
unsigned char red[10]
Definition: PbMapMaker.cpp:976
CImage scaleDouble() const
Returns a new image scaled up to double its original size.
Definition: CImage.h:312
The virtual base class which provides a unified interface for all persistent objects in MRPT...
Definition: CSerializable.h:39
bool m_imgIsReadOnly
Set to true only when using setFromIplImageReadOnly.
Definition: CImage.h:916
#define MRPT_OVERRIDE
C++11 "override" for virtuals:
A class for storing images as grayscale or RGB bitmaps.
Definition: CImage.h:101
GLenum GLenum GLenum GLenum GLenum scale
Definition: glext.h:5717
#define DECLARE_MEXPLUS_FROM(complete_type)
This must be inserted if a custom conversion method for MEX API is implemented in the class...
void resize(unsigned int width, unsigned int height, TImageChannels nChannels, bool originTopLeft)
Changes the size of the image, erasing previous contents (does NOT scale its current content...
Definition: CImage.h:209
CImage(TConstructorFlags_CImage)
Fast constructor that leaves the image uninitialized (the internal IplImage pointer set to NULL)...
Definition: CImage.h:142
A pair (x,y) of pixel coordinates (integer resolution).
Definition: TPixelCoord.h:37
std::string getExternalStorageFile() const MRPT_NO_THROWS
< Only if isExternallyStored() returns true.
Definition: CImage.h:673
#define MRPT_NO_THROWS
C++11 noexcept: Used after member declarations.
EIGEN_STRONG_INLINE Scalar get_unsafe(const size_t row, const size_t col) const
Read-only access to one element (Use with caution, bounds are not checked!)
Definition: eigen_plugins.h:82
GLdouble s
Definition: glext.h:3602
int TImageChannels
For use in mrpt::utils::CImage.
Definition: CImage.h:40
CImage(const CImage &other_img, TConstructorFlags_CImage constructor_flag)
Fast constructor of a grayscale version of another image, making a reference to the original image if...
Definition: CImage.h:155
static std::string IMAGES_PATH_BASE
By default, ".".
Definition: CImage.h:668
GLenum GLsizei width
Definition: glext.h:3513
const T * getAs() const
Returns a pointer to a const T* containing the image - the idea is to call like "img.getAs<IplImage>()" so we can avoid here including OpenCV&#39;s headers.
Definition: CImage.h:517
GLuint color
Definition: glext.h:7093
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:38
#define MRPT_END
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
#define DECLARE_MEX_CONVERSION
This must be inserted if a custom conversion method for MEX API is implemented in the class...
GLint GLvoid * img
Definition: glext.h:3645
#define CH_RGB
Definition: CImage.h:42
void BASE_IMPEXP cross_correlation_FFT(const CMatrixFloat &A, const CMatrixFloat &B, CMatrixFloat &out_corr)
Correlation of two matrixes using 2D FFT.
Definition: math.cpp:1991
CImage grayscale() const
Returns a grayscale version of the image, or itself if it is already a grayscale image.
Definition: CImage.cpp:992
A RGB color - 8bit.
Definition: TColor.h:26
int val
Definition: mrpt_jpeglib.h:953
void forceLoad() const
For external storage image objects only, this method makes sure the image is loaded in memory...
Definition: CImage.h:691
#define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name)
This declaration must be inserted in all CSerializable classes definition, before the class declarati...
bool isExternallyStored() const MRPT_NO_THROWS
See setExternalStorage().
Definition: CImage.h:671
void setFromRGBMatrices(const Eigen::MatrixBase< Derived > &m_r, const Eigen::MatrixBase< Derived > &m_g, const Eigen::MatrixBase< Derived > &m_b, bool matrix_is_normalized=true)
Set the image from RGB matrices, given the pixels in the range [0,1] (normalized=true) or [0...
Definition: CImage.h:774
GLsizei const GLchar ** string
Definition: glext.h:3919
GLint GLint GLsizei GLsizei GLsizei GLint GLenum GLenum const GLvoid * pixels
Definition: glext.h:3545
void setFromMatrix(const Eigen::MatrixBase< Derived > &m, bool matrix_is_normalized=true)
Set the image from a matrix, interpreted as grayscale intensity values, in the range [0...
Definition: CImage.h:746
TInterpolationMethod
Interpolation methods for images.
Definition: CImage.h:31
#define MRPT_START
void normalize(Scalar valMin, Scalar valMax)
Scales all elements such as the minimum & maximum values are shifted to the given values...
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
#define DEFINE_SERIALIZABLE(class_name)
This declaration must be inserted in all CSerializable classes definition, within the class declarati...
CImage scaleHalfSmooth() const
Returns a new image scaled down to half its original size (averaging between every two rows) ...
Definition: CImage.h:297
GLclampf green
Definition: glext.h:3510
#define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE(class_name, base_name)
GLenum GLenum GLvoid * row
Definition: glext.h:3533
GLuint in
Definition: glext.h:6301
#define ASSERT_(f)
This virtual class defines the interface of any object accepting drawing primitives on it...
Definition: CCanvas.h:40
GLenum GLint GLint y
Definition: glext.h:3516
static bool DISABLE_ZIP_COMPRESSION
By default, when storing images through the CSerializable interface, grayscale images will be ZIP com...
Definition: CImage.h:188
bool m_imgIsExternalStorage
Set to true only when using setExternalStorage.
Definition: CImage.h:920
T * getAs()
Returns a pointer to a T* containing the image - the idea is to call like "img.getAs<IplImage>()" so ...
Definition: CImage.h:522
bool isColor() const
Returns true if the image is RGB, false if it is grayscale.
Definition: CImage.cpp:898
GLuint interp
Definition: glext.h:6197
GLclampf GLclampf blue
Definition: glext.h:3510
GLenum GLint x
Definition: glext.h:3516
This class is a "CSerializable" wrapper for "CMatrixFloat".
Definition: CMatrix.h:30
double getHeight(const TPolygon3D &p, const TPoint3D &c)
GLenum GLsizei GLsizei height
Definition: glext.h:3523
void * img
The internal IplImage pointer to the actual image content.
Definition: CImage.h:912
Structure to hold the parameters of a pinhole camera model.
Definition: TCamera.h:31
std::string getExternalStorageFileAbsolutePath() const
Only if isExternallyStored() returns true.
Definition: CImage.h:682



Page generated by Doxygen 1.8.14 for MRPT 1.5.7 Git: 5902e14cc Wed Apr 24 15:04:01 2019 +0200 at lun oct 28 01:39:17 CET 2019