Main MRPT website > C++ reference for MRPT 1.3.2
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-2015, 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);
241 
242  /** Changes the property of the image stating if the top-left corner (vs. bottom-left) is the coordinate reference.
243  */
244  void setOriginTopLeft(bool val);
245 
246  /** Draws a line.
247  * \param x0 The starting point x coordinate
248  * \param y0 The starting point y coordinate
249  * \param x1 The end point x coordinate
250  * \param y1 The end point y coordinate
251  * \param color The color of the line
252  * \param width The desired width of the line (this is IGNORED in this virtual class)
253  * This method may be redefined in some classes implementing this interface in a more appropiate manner.
254  */
255  virtual void line(
256  int x0,
257  int y0,
258  int x1,
259  int y1,
260  const mrpt::utils::TColor color,
261  unsigned int width = 1,
262  TPenStyle penStyle = psSolid);
263 
264  /** Draws a circle of a given radius.
265  * \param x The center - x coordinate in pixels.
266  * \param y The center - y coordinate in pixels.
267  * \param radius The radius - in pixels.
268  * \param color The color of the circle.
269  * \param width The desired width of the line
270  */
271  void drawCircle(
272  int x,
273  int y,
274  int radius,
275  const mrpt::utils::TColor &color = mrpt::utils::TColor(255,255,255),
276  unsigned int width = 1);
277 
278  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)
279  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)
280 
281  /** Returns a new image scaled down to half its original size.
282  * \exception std::exception On odd size
283  * \sa scaleDouble, scaleImage, scaleHalfSmooth
284  */
286  {
288  this->scaleHalf(ret);
289  return ret;
290  }
291 
292  //! \overload
293  void scaleHalf(CImage &out_image) const;
294 
295 
296  /** Returns a new image scaled down to half its original size (averaging between every two rows)
297  * \exception std::exception On odd size
298  * \sa scaleDouble, scaleImage, scaleHalf
299  */
301  {
303  this->scaleHalfSmooth(ret);
304  return ret;
305  }
306 
307  //! \overload
308  void scaleHalfSmooth(CImage &out_image) const;
309 
310 
311  /** Returns a new image scaled up to double its original size.
312  * \exception std::exception On odd size
313  * \sa scaleHalf, scaleImage
314  */
316  {
318  this->scaleDouble(ret);
319  return ret;
320  }
321 
322  //! \overload
323  void scaleDouble(CImage &out_image) const;
324 
325 
326  /** Update a part of this image with the "patch" given as argument.
327  * The "patch" will be "pasted" at the (col,row) coordinates of this image.
328  * \exception std::exception if patch pasted on the pixel (_row, _column) jut out
329  * of the image.
330  * \sa extract_patch
331  */
332  void update_patch(const CImage &patch,
333  const unsigned int col,
334  const unsigned int row);
335 
336  /** Extract a patch from this image, saveing it into "patch" (its previous contents will be overwritten).
337  * The patch to extract starts at (col,row) and has the given dimensions.
338  * \sa update_patch
339  */
340  void extract_patch(
341  CImage &patch,
342  const unsigned int col=0,
343  const unsigned int row=0,
344  const unsigned int width=1,
345  const unsigned int height=1 ) const;
346 
347  /** Computes the correlation coefficient (returned as val), between two images
348  * This function use grayscale images only
349  * img1, img2 must be same size
350  * (by AJOGD @ DEC-2006)
351  */
352  float correlate( const CImage &img2int, int width_init=0, int height_init=0 )const;
353 
354  /** Computes the correlation between this image and another one, encapsulating the openCV function cvMatchTemplate
355  *
356  * \param patch_img The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
357  * \param u_search_ini The "x" coordinate of the search window.
358  * \param v_search_ini The "y" coordinate of the search window.
359  * \param u_search_size The width of the search window.
360  * \param v_search_size The height of the search window.
361  * \param u_max The u coordinate where find the maximun cross correlation value.
362  * \param v_max The v coordinate where find the maximun cross correlation value
363  * \param max_val The maximun value of cross correlation which we can find
364  * \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 )
365  * Note: By default, the search area is the whole (this) image.
366  * (by AJOGD @ MAR-2007)
367  */
368  void cross_correlation(
369  const CImage &patch_img,
370  size_t &u_max,
371  size_t &v_max,
372  double &max_val,
373  int u_search_ini=-1,
374  int v_search_ini=-1,
375  int u_search_size=-1,
376  int v_search_size=-1,
377  CImage *out_corr_image = NULL
378  )const;
379 
380  /** Computes the correlation matrix between this image and another one.
381  * This implementation uses the 2D FFT for achieving reduced computation time.
382  * \param in_img The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
383  * \param u_search_ini The "x" coordinate of the search window.
384  * \param v_search_ini The "y" coordinate of the search window.
385  * \param u_search_size The width of the search window.
386  * \param v_search_size The height of the search window.
387  * \param out_corr The output for the correlation matrix, which will be "u_search_size" x "v_search_size"
388  * \param biasThisImg This optional parameter is a fixed "bias" value to be substracted to the pixels of "this" image before performing correlation.
389  * \param biasInImg This optional parameter is a fixed "bias" value to be substracted to the pixels of "in_img" image before performing correlation.
390  * Note: By default, the search area is the whole (this) image.
391  * (by JLBC @ JAN-2006)
392  * \sa cross_correlation
393  */
395  const CImage &in_img,
396  math::CMatrixFloat &out_corr,
397  int u_search_ini=-1,
398  int v_search_ini=-1,
399  int u_search_size=-1,
400  int v_search_size=-1,
401  float biasThisImg = 0,
402  float biasInImg = 0
403  ) const;
404 
405 
406  /** Optimize the brightness range of an image without using histogram
407  * Only for one channel images.
408  * \sa equalizeHist
409  */
410  void normalize();
411 
412  /** Flips vertically the image.
413  * \sa swapRB
414  */
415  void flipVertical(bool also_swapRB = false);
416 
417  /** Swaps red and blue channels.
418  * \sa flipVertical
419  */
420  void swapRB();
421 
422  /** Rectify (un-distort) the image according to some camera parameters, and returns an output un-distorted image.
423  * \param out_img The output rectified image
424  * \param cameraParams The input camera params (containing the intrinsic and distortion parameters of the camera)
425  * \sa mrpt::vision::CUndistortMap
426  */
427  void rectifyImage( CImage &out_img, const mrpt::utils::TCamera &cameraParams) const;
428 
429  /** Rectify (un-distort) the image according to a certain camera matrix and vector of distortion coefficients, replacing "this" with the rectified image
430  * \param cameraParams The input camera params (containing the intrinsic and distortion parameters of the camera)
431  * \sa mrpt::vision::CUndistortMap
432  */
433  void rectifyImageInPlace(const mrpt::utils::TCamera &cameraParams );
434 
435  /** Rectify an image (undistorts and rectification) from a stereo pair according to a pair of precomputed rectification maps
436  * \param mapX, mapY [IN] The pre-computed maps of the rectification (should be computed beforehand)
437  * \sa mrpt::vision::CStereoRectifyMap, mrpt::vision::computeStereoRectificationMaps
438  */
439  void rectifyImageInPlace( void *mapX, void *mapY );
440 
441  /** Filter the image with a Median filter with a window size WxW, returning the filtered image in out_img */
442  void filterMedian( CImage &out_img, int W=3 ) const;
443 
444  /** Filter the image with a Median filter with a window size WxH, replacing "this" image by the filtered one. */
445  void filterMedianInPlace( int W=3 );
446 
447  /** Filter the image with a Gaussian filter with a window size WxH, returning the filtered image in out_img */
448  void filterGaussianInPlace( int W = 3, int H = 3 );
449 
450  /** Filter the image with a Gaussian filter with a window size WxH, replacing "this" image by the filtered one. */
451  void filterGaussian( CImage &out_img, int W = 3, int H = 3) const;
452 
453  /** Draw onto this image the detected corners of a chessboard. The length of cornerCoords must be the product of the two check_sizes.
454  *
455  * \param cornerCoords [IN] The pixel coordinates of all the corners.
456  * \param check_size_x [IN] The number of squares, in the X direction
457  * \param check_size_y [IN] The number of squares, in the Y direction
458  *
459  * \return false if the length of cornerCoords is inconsistent (nothing is drawn then).
460  *
461  * \sa mrpt::vision::findChessboardCorners
462  */
463  bool drawChessboardCorners(
464  std::vector<TPixelCoordf> &cornerCoords,
465  unsigned int check_size_x,
466  unsigned int check_size_y,
467  unsigned int lines_width = 1,
468  unsigned int circles_radius = 4
469  );
470 
471  /** 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)
472  *
473  * \param im1 [IN] The first image.
474  * \param im2 [IN] The other image.
475  */
476  void joinImagesHorz(
477  const CImage &im1,
478  const CImage &im2 );
479 
480  /** Compute the KLT response at a given pixel (x,y) - Only for grayscale images (for efficiency it avoids converting to grayscale internally).
481  * See KLT_response_optimized for more details on the internal optimizations of this method, but this graph shows a general view:
482  * <img src="KLT_response_performance_SSE2.png" >
483  */
484  float KLT_response(
485  const unsigned int x,
486  const unsigned int y,
487  const unsigned int half_window_size ) const;
488 
489  /** @} */
490  // ================================================================
491 
492 
493 
494  // ================================================================
495  /** @name Copy, move & swap operations
496  @{ */
497 
498  /** Copy operator (if the image is externally stored, the writen image will be such as well).
499  * \sa copyFastFrom
500  */
501  CImage& operator = (const CImage& o);
502 
503  /** Copies from another image, and, if that one is externally stored, the image file will be actually loaded into memory in "this" object.
504  * \sa operator =
505  * \exception CExceptionExternalImageNotFound If the external image couldn't be loaded.
506  */
507  void copyFromForceLoad(const CImage &o);
508 
509  /** Moves an image from another object, erasing the origin image in the process (this is much faster than copying)
510  * \sa operator =
511  */
512  void copyFastFrom( CImage &o );
513 
514  void swap(CImage &o); //!< Very efficient swap of two images (just swap the internal pointers)
515 
516  /** @} */
517  // ================================================================
518 
519 
520  // ================================================================
521  /** @name Access to image contents (IplImage structure and raw pixels).
522  @{ */
523 
524  /** 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. */
525  template <typename T> inline const T* getAs() const {
526  makeSureImageIsLoaded();
527  return static_cast<const T*>(img);
528  }
529  /** 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. */
530  template <typename T> inline T* getAs(){
531  makeSureImageIsLoaded();
532  return static_cast<T*>(img);
533  }
534 
535  /** Access to pixels without checking boundaries - Use normally the () operator better, which checks the coordinates.
536  \sa CImage::operator()
537  */
538  unsigned char* get_unsafe(
539  unsigned int col,
540  unsigned int row,
541  unsigned int channel=0) const;
542 
543  /** Returns the contents of a given pixel at the desired channel, in float format: [0,255]->[0,1]
544  * The coordinate origin is pixel(0,0)=top-left corner of the image.
545  * \exception std::exception On pixel coordinates out of bounds
546  * \sa operator()
547  */
548  float getAsFloat(unsigned int col, unsigned int row, unsigned int channel) const;
549 
550  /** 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]
551  * The coordinate origin is pixel(0,0)=top-left corner of the image.
552  * \exception std::exception On pixel coordinates out of bounds
553  * \sa operator()
554  */
555  float getAsFloat(unsigned int col, unsigned int row) const;
556 
557  /** Returns a pointer to a given pixel information.
558  * The coordinate origin is pixel(0,0)=top-left corner of the image.
559  * \exception std::exception On pixel coordinates out of bounds
560  */
561  unsigned char* operator()(unsigned int col, unsigned int row, unsigned int channel = 0) const;
562 
563  /** @} */
564  // ================================================================
565 
566 
567 
568  // ================================================================
569  /** @name Query image properties
570  @{ */
571 
572  /** Returns the width of the image in pixels
573  * \sa getSize
574  */
575  size_t getWidth() const;
576 
577  /** Returns the height of the image in pixels
578  * \sa getSize
579  */
580  size_t getHeight() const;
581 
582  /** Return the size of the image
583  * \sa getWidth, getHeight
584  */
585  void getSize(TImageSize &s) const;
586 
587  /** Return the size of the image
588  * \sa getWidth, getHeight
589  */
590  inline TImageSize getSize() const {
591  TImageSize ret;
592  getSize(ret);
593  return ret;
594  }
595 
596  /** 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)
597  * \sa getSize, get_unsafe
598  */
599  size_t getRowStride() const;
600 
601  /** Return the maximum pixel value of the image, as a float value in the range [0,1]
602  * \sa getAsFloat
603  */
604  float getMaxAsFloat() const;
605 
606  /** Returns true if the image is RGB, false if it is grayscale */
607  bool isColor() const;
608 
609  /** Returns true if the coordinates origin is top-left, or false if it is bottom-left */
610  bool isOriginTopLeft() const;
611 
612  /** Returns a string of the form "BGR","RGB" or "GRAY" indicating the channels ordering. \sa setChannelsOrder, swapRB */
613  const char * getChannelsOrder()const;
614 
615  /** 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 */
616  void setChannelsOrder_RGB();
617  /** 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 */
618  void setChannelsOrder_BGR();
619 
620  /** Returns the number of channels, typically 1 (GRAY) or 3 (RGB)
621  * \sa isColor
622  */
623  TImageChannels getChannelCount() const;
624 
625  /** Returns the image as a matrix with pixel grayscale values in the range [0,1]. Matrix indexes in this order: M(row,column)
626  * \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,...)
627  * \param x_min The starting "x" coordinate to extract (default=0=the first column)
628  * \param y_min The starting "y" coordinate to extract (default=0=the first row)
629  * \param x_max The final "x" coordinate (inclusive) to extract (default=-1=the last column)
630  * \param y_max The final "y" coordinate (inclusive) to extract (default=-1=the last row)
631  * \sa setFromMatrix
632  */
633  void getAsMatrix(
634  mrpt::math::CMatrixFloat &outMatrix,
635  bool doResize = true,
636  int x_min = 0,
637  int y_min = 0,
638  int x_max = -1,
639  int y_max = -1
640  ) const;
641 
642  /** Returns the image as RGB matrices with pixel values in the range [0,1]. Matrix indexes in this order: M(row,column)
643  * \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,...)
644  * \param x_min The starting "x" coordinate to extract (default=0=the first column)
645  * \param y_min The starting "y" coordinate to extract (default=0=the first row)
646  * \param x_max The final "x" coordinate (inclusive) to extract (default=-1=the last column)
647  * \param y_max The final "y" coordinate (inclusive) to extract (default=-1=the last row)
648  * \sa setFromRGBMatrices
649  */
650  void getAsRGBMatrices(
651  mrpt::math::CMatrixFloat &outMatrixR,
652  mrpt::math::CMatrixFloat &outMatrixG,
653  mrpt::math::CMatrixFloat &outMatrixB,
654  bool doResize = true,
655  int x_min = 0,
656  int y_min = 0,
657  int x_max = -1,
658  int y_max = -1
659  ) const;
660 
661  /** 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.
662  */
663  void getAsMatrixTiled( math::CMatrix &outMatrix ) const;
664 
665  /** @} */
666  // ================================================================
667 
668 
669  // ================================================================
670  /** @name External storage-mode methods
671  @{ */
672 
673  /** By using this method the image is marked as referenced to an external file, which will be loaded only under demand.
674  * A CImage with external storage does not consume memory until some method trying to access the image is invoked (e.g. getWidth(), isColor(),...)
675  * At any moment, the image can be unloaded from memory again by invoking unload.
676  * An image becomes of type "external storage" only through calling setExternalStorage. This property remains after serializing the object.
677  * File names can be absolute, or relative to the CImage::IMAGES_PATH_BASE directory. Filenames staring with "X:\" or "/" are considered absolute paths.
678  * By calling this method the current contents of the image are NOT saved to that file, because this method can be also called
679  * 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)
680  * the proper order of commands should be:
681  * \code
682  * img.saveToFile( fileName );
683  * img.setExternalStorage( fileName );
684  * \endcode
685  *
686  * \note Modifications to the memory copy of the image are not automatically saved to disk.
687  * \sa unload, isExternallyStored
688  */
689  void setExternalStorage( const std::string &fileName ) MRPT_NO_THROWS;
690 
691  static std::string IMAGES_PATH_BASE; //!< By default, "." \sa setExternalStorage
692 
693  /** See setExternalStorage(). */
694  bool isExternallyStored() const MRPT_NO_THROWS { return m_imgIsExternalStorage; }
695 
696  inline std::string getExternalStorageFile() const MRPT_NO_THROWS //!< Only if isExternallyStored() returns true. \sa getExternalStorageFileAbsolutePath
697  {
698  return m_externalFile;
699  }
700 
701  /** Only if isExternallyStored() returns true. \sa getExternalStorageFile */
702  void getExternalStorageFileAbsolutePath(std::string &out_path) const;
703 
704  /** Only if isExternallyStored() returns true. \sa getExternalStorageFile */
705  inline std::string getExternalStorageFileAbsolutePath() const {
706  std::string tmp;
707  getExternalStorageFileAbsolutePath(tmp);
708  return tmp;
709  }
710 
711  /** 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.
712  * \unload
713  */
714  inline void forceLoad() const { makeSureImageIsLoaded(); }
715 
716  /** For external storage image objects only, this method unloads the image from memory (or does nothing if already unloaded).
717  * It does not need to be called explicitly, unless the user wants to save memory for images that will not be used often.
718  * If called for an image without the flag "external storage", it is simply ignored.
719  * \sa setExternalStorage, forceLoad
720  */
721  void unload() const MRPT_NO_THROWS;
722 
723  /** @} */
724  // ================================================================
725 
726 
727  // ================================================================
728  /** @name Set, load & save methods
729  @{ */
730 
731  /** Reads the image from raw pixels buffer in memory.
732  */
733  void loadFromMemoryBuffer( unsigned int width, unsigned int height, bool color, unsigned char *rawpixels, bool swapRedBlue = false );
734 
735  /** Reads a color image from three raw pixels buffers in memory.
736  * bytesPerRow is the number of bytes per row per channel, i.e. the row increment.
737  */
738  void loadFromMemoryBuffer( unsigned int width, unsigned int height, unsigned int bytesPerRow, unsigned char *red, unsigned char *green, unsigned char *blue );
739 
740  /** Reads the image from a OpenCV IplImage object (making a COPY).
741  */
742  void loadFromIplImage( void* iplImage );
743 
744  /** Reads the image from a OpenCV IplImage object (WITHOUT making a copy).
745  * This object will own the memory of the passed object and free the IplImage upon destruction,
746  * so the caller CAN'T free the original object.
747  * This method provides a fast method to grab images from a camera without making a copy of every frame.
748  */
749  void setFromIplImage( void* iplImage );
750 
751  /** Reads the image from a OpenCV IplImage object (WITHOUT making a copy) and from now on the image cannot be modified, just read.
752  * When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor.
753  * This method provides a fast method to grab images from a camera without making a copy of every frame.
754  * \sa setFromImageReadOnly
755  */
756  void setFromIplImageReadOnly( void* iplImage );
757 
758  /** 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).
759  * When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor.
760  * \sa setFromIplImageReadOnly
761  */
762  inline void setFromImageReadOnly( const CImage &other_img ) { setFromIplImageReadOnly(const_cast<void*>(other_img.getAs<void>()) ); }
763 
764  /** Set the image from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false)
765  * Matrix indexes are assumed to be in this order: M(row,column)
766  * \sa getAsMatrix
767  */
768  template <typename Derived>
769  void setFromMatrix(const Eigen::MatrixBase<Derived> &m, bool matrix_is_normalized=true)
770  {
771  MRPT_START
772  const unsigned int lx = m.cols();
773  const unsigned int ly = m.rows();
774  this->changeSize(lx,ly,1,true);
775  if (matrix_is_normalized) { // Matrix: [0,1]
776  for (unsigned int y=0;y<ly;y++) {
777  unsigned char *pixels = this->get_unsafe(0,y,0);
778  for (unsigned int x=0;x<lx;x++)
779  (*pixels++) = static_cast<unsigned char>( m.get_unsafe(y,x) * 255 );
780  }
781  }
782  else { // Matrix: [0,255]
783  for (unsigned int y=0;y<ly;y++) {
784  unsigned char *pixels = this->get_unsafe(0,y,0);
785  for (unsigned int x=0;x<lx;x++)
786  (*pixels++) = static_cast<unsigned char>( m.get_unsafe(y,x) );
787  }
788  }
789  MRPT_END
790  }
791 
792  /** Set the image from RGB matrices, given the pixels in the range [0,1] (normalized=true) or [0,255] (normalized=false)
793  * Matrix indexes are assumed to be in this order: M(row,column)
794  * \sa getAsRGBMatrices
795  */
796  template <typename Derived>
797  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)
798  {
799  MRPT_START
800  makeSureImageIsLoaded(); // For delayed loaded images stored externally
801  ASSERT_(img);
802  ASSERT_((m_r.size() == m_g.size())&&(m_r.size() == m_b.size()));
803  const unsigned int lx = m_r.cols();
804  const unsigned int ly = m_r.rows();
805  this->changeSize(lx,ly,3,true);
806  this->setChannelsOrder_RGB();
807 
808  if (matrix_is_normalized) { // Matrix: [0,1]
809  for (unsigned int y=0;y<ly;y++) {
810  unsigned char *pixels = this->get_unsafe(0,y,0);
811  for (unsigned int x=0;x<lx;x++)
812  {
813  (*pixels++) = static_cast<unsigned char>( m_r.get_unsafe(y,x) * 255 );
814  (*pixels++) = static_cast<unsigned char>( m_g.get_unsafe(y,x) * 255 );
815  (*pixels++) = static_cast<unsigned char>( m_b.get_unsafe(y,x) * 255 );
816  }
817  }
818  }
819  else { // Matrix: [0,255]
820  for (unsigned int y=0;y<ly;y++) {
821  unsigned char *pixels = this->get_unsafe(0,y,0);
822  for (unsigned int x=0;x<lx;x++)
823  {
824  (*pixels++) = static_cast<unsigned char>( m_r.get_unsafe(y,x) );
825  (*pixels++) = static_cast<unsigned char>( m_g.get_unsafe(y,x) );
826  (*pixels++) = static_cast<unsigned char>( m_b.get_unsafe(y,x) );
827  }
828  }
829  }
830  MRPT_END
831  }
832 
833  /** Reads the image from a binary stream containing a binary jpeg file.
834  * \exception std::exception On pixel coordinates out of bounds
835  */
836  void loadFromStreamAsJPEG( CStream &in );
837 
838  /** Load image from a file, whose format is determined from the extension (internally uses OpenCV).
839  * \param fileName The file to read from.
840  * \param isColor Specifies colorness of the loaded image:
841  * - if >0, the loaded image is forced to be color 3-channel image;
842  * - if 0, the loaded image is forced to be grayscale;
843  * - if <0, the loaded image will be loaded as is (with number of channels depends on the file).
844  * The supported formats are:
845  *
846  * - Windows bitmaps - BMP, DIB;
847  * - JPEG files - JPEG, JPG, JPE;
848  * - Portable Network Graphics - PNG;
849  * - Portable image format - PBM, PGM, PPM;
850  * - Sun rasters - SR, RAS;
851  * - TIFF files - TIFF, TIF.
852  *
853  * \return False on any error
854  * \sa saveToFile, setExternalStorage,loadFromXPM, loadTGA
855  */
856  bool loadFromFile( const std::string& fileName, int isColor = -1 );
857 
858  /** 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.
859  * \return true on success
860  */
861  static bool loadTGA(const std::string& fileName, mrpt::utils::CImage &out_RGB, mrpt::utils::CImage &out_alpha);
862 
863  /** Loads the image from an XPM array, as #include'd from a ".xpm" file.
864  * \param[in] swap_rb Swaps red/blue channels from loaded image. *Seems* to be always needed, so it's enabled by default.
865  * \sa loadFromFile
866  * \return false on any error */
867  bool loadFromXPM( const char** xpm_array, bool swap_rb = true );
868 
869  /** Save the image to a file, whose format is determined from the extension (internally uses OpenCV).
870  * \param fileName The file to write to.
871  *
872  * The supported formats are:
873  *
874  * - Windows bitmaps - BMP, DIB;
875  * - JPEG files - JPEG, JPG, JPE;
876  * - Portable Network Graphics - PNG;
877  * - Portable image format - PBM, PGM, PPM;
878  * - Sun rasters - SR, RAS;
879  * - TIFF files - TIFF, TIF.
880  *
881  * \param jpeg_quality Only for JPEG files, the quality of the compression in the range [0-100]. Larger is better quality but slower.
882  * \note jpeg_quality is only effective if MRPT is compiled against OpenCV 1.1.0 or newer.
883  * \return False on any error
884  * \sa loadFromFile
885  */
886  bool saveToFile( const std::string& fileName, int jpeg_quality = 95 ) const;
887 
888  /** Save image to binary stream as a JPEG (.jpg) compressed format.
889  * \exception std::exception On number of rows or cols equal to zero or other errors.
890  * \sa saveToJPEG
891  */
892  void saveToStreamAsJPEG(mrpt::utils::CStream &out, const int jpeg_quality = 95 ) const;
893 
894  /** @} */
895  // ================================================================
896 
897 
898  // ================================================================
899  /** @name Color/Grayscale conversion
900  @{ */
901 
902  /** Returns a grayscale version of the image, or itself if it is already a grayscale image.
903  */
904  CImage grayscale() const;
905 
906  /** Returns a grayscale version of the image, or itself if it is already a grayscale image.
907  * \sa colorImage
908  */
909  void grayscale( CImage &ret ) const;
910 
911  /** Returns a RGB version of the grayscale image, or itself if it is already a RGB image.
912  * \sa grayscale
913  */
914  void colorImage( CImage &ret ) const;
915 
916  /** Replaces this grayscale image with a RGB version of it.
917  * \sa grayscaleInPlace
918  */
919  void colorImageInPlace();
920 
921 
922  /** Replaces the image with a grayscale version of it.
923  * \sa colorImageInPlace
924  */
925  void grayscaleInPlace();
926 
927  /** @} */
928  // ================================================================
929 
930 
931  protected:
932  /** @name Data members
933  @{ */
934 
935  void *img; //!< The internal IplImage pointer to the actual image content.
936 
937  /** Set to true only when using setFromIplImageReadOnly.
938  * \sa setFromIplImageReadOnly */
940  /** Set to true only when using setExternalStorage.
941  * \sa setExternalStorage
942  */
944  mutable std::string m_externalFile; //!< The file name of a external storage image.
945 
946  /** @} */
947 
948  /** Resize the buffers in "img" to accomodate a new image size and/or format.
949  */
950  void changeSize(
951  unsigned int width,
952  unsigned int height,
953  TImageChannels nChannels,
954  bool originTopLeft );
955 
956  /** Release the internal IPL image, if not NULL or read-only. */
957  void releaseIpl(bool thisIsExternalImgUnload = false) MRPT_NO_THROWS;
958 
959  /** Checks if the image is of type "external storage", and if so and not loaded yet, load it. */
960  void makeSureImageIsLoaded() const throw (std::exception,utils::CExceptionExternalImageNotFound );
961 
962  }; // End of class
963  DEFINE_SERIALIZABLE_POST_CUSTOM_BASE( CImage, mrpt::utils::CSerializable )
964 
965  } // end of namespace utils
966 
967 } // end of namespace mrpt
968 
969 #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
CImage scaleHalf() const
Returns a new image scaled down to half its original size.
Definition: CImage.h:285
std::string m_externalFile
The file name of a external storage image.
Definition: CImage.h:944
CImage scaleHalfSmooth() const
Returns a new image scaled down to half its original size (averaging between every two rows) On odd s...
Definition: CImage.h:300
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:939
A class for storing images as grayscale or RGB bitmaps.
Definition: CImage.h:101
#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
A pair (x,y) of pixel coordinates (integer resolution).
Definition: TPixelCoord.h:37
static std::string IMAGES_PATH_BASE
By default, ".".
Definition: CImage.h:691
std::string getExternalStorageFile() const MRPT_NO_THROWS
< Only if isExternallyStored() returns true.
Definition: CImage.h:696
#define MRPT_NO_THROWS
Used after member declarations.
STL namespace.
TImageSize getSize() const
Return the size of the image.
Definition: CImage.h:590
int TImageChannels
For use in mrpt::utils::CImage.
Definition: CImage.h:40
static bool DISABLE_JPEG_COMPRESSION
By default, when storing images through the CSerializable interface, RGB images are JPEG-compressed t...
Definition: CImage.h:192
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
bool isColor() const
Returns true if the image is RGB, false if it is grayscale.
CImage grayscale() const
Returns a grayscale version of the image, or itself if it is already a grayscale image.
void forceLoad() const
For external storage image objects only, this method makes sure the image is loaded in memory...
Definition: CImage.h:714
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...
#define CH_RGB
Definition: CImage.h:42
A RGB color - 8bit.
Definition: TColor.h:25
#define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name)
This declaration must be inserted in all CSerializable classes definition, before the class declarati...
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
bool isExternallyStored() const MRPT_NO_THROWS
See setExternalStorage().
Definition: CImage.h:694
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:797
std::string getExternalStorageFileAbsolutePath() const
Only if isExternallyStored() returns true.
Definition: CImage.h:705
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:769
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...
void setFromImageReadOnly(const CImage &other_img)
Sets the internal IplImage pointer to that of another given image, WITHOUT making a copy...
Definition: CImage.h:762
CImage scaleDouble() const
Returns a new image scaled up to double its original size.
Definition: CImage.h:315
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:525
#define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE(class_name, base_name)
#define ASSERT_(f)
This virtual class defines the interface of any object accepting drawing primitives on it...
Definition: CCanvas.h:40
bool m_imgIsExternalStorage
Set to true only when using setExternalStorage.
Definition: CImage.h:943
T * getAs()
Returns a pointer to a T* containing the image - the idea is to call like "img.getAs<IplImage>()" so ...
Definition: CImage.h:530
This class is a "CSerializable" wrapper for "CMatrixFloat".
Definition: CMatrix.h:30
TPenStyle
Definition of pen styles.
Definition: CCanvas.h:53
Used in mrpt::utils::CImage.
Definition: exceptions.h:31
void * img
The internal IplImage pointer to the actual image content.
Definition: CImage.h:935
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
Structure to hold the parameters of a pinhole camera model.
Definition: TCamera.h:31
void BASE_IMPEXP cross_correlation_FFT(const CMatrixFloat &A, const CMatrixFloat &B, CMatrixFloat &out_corr)
Correlation of two matrixes using 2D FFT.
static bool DISABLE_ZIP_COMPRESSION
By default, when storing images through the CSerializable interface, grayscale images will be ZIP com...
Definition: CImage.h:188



Page generated by Doxygen 1.8.11 for MRPT 1.3.2 SVN: at Wed May 25 02:34:21 UTC 2016