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


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013