Detailed Description

A class for storing images as grayscale or RGB bitmaps.

File I/O is supported as:

Binary dump using the CSerializable interface(<< and >> operators), just as most objects in the MRPT library. This format is not compatible with any standarized image format.
Saving/loading from files of different formats (bmp,jpg,png,...) using the methods CImage::loadFromFile and CImage::saveToFile. Available formats are all those supported by OpenCV
Importing from an XPM array (.xpm file format) using CImage::loadFromXPM
Importing TGA images. See CImage::loadTGA()

How to create color/grayscale images:

CImage img1(width, height, CH_GRAY ); // Grayscale image (8U1C)

CImage img2(width, height, CH_RGB ); // RGB image (8U3C)

Additional notes:

The OpenCV "IplImage" format is used internally for compatibility with all OpenCV functions. Use CImage::getAs<IplImage>() to retrieve the internal structure. Example:
CImage img;
...
// Call to OpenCV function expecting an "IplImage *" or a "void* arr":
cv::Mat cvImg = cv::cvarrToMat( img.getAs<IplImage>() );
cvFunction( img.getAs<IplImage>(), ... );
Only the unsigned 8-bit storage format for pixels (on each channel) is supported.
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.
To move images from one object to the another, use CImage::copyFastFrom rather than the copy operator =.
If you are interested in a smart pointer to an image, use:
CImagePtr myImgPtr = CImagePtr( new CImage(...) );
To set a CImage from an OpenCV "IPLImage*", use the methods:

Some functions are implemented in MRPT with highly optimized SSE2/SSE3 routines, in suitable platforms and compilers. To see the list of optimizations refer to this page. If optimized versions are not available in some platform it falls back to default OpenCV methods.

For many computer vision functions that use CImage as its image data type, see mrpt::vision.

Note: This class acts as a wrapper class to a small subset of OpenCV functions. IplImage is the internal storage structure.

See also: mrpt::vision, mrpt::vision::CFeatureExtractor, mrpt::vision::CImagePyramid, CSerializable, CCanvas

Definition at line 101 of file CImage.h.

#include <mrpt/utils/CImage.h>

Inheritance diagram for mrpt::utils::CImage:

Public Types
enum	TPenStyle { psSolid = 0, psDash, psDot, psDashDot, psDashDotDot }
	Definition of pen styles. More...

Public Member Functions
void *	operator new (size_t size)

void *	operator new[] (size_t size)

void	operator delete (void *ptr) throw ()

void	operator delete[] (void *ptr) throw ()

void	operator delete (void memory, void ptr) throw ()

void *	operator new (size_t size, const std::nothrow_t &) throw ()

void	operator delete (void *ptr, const std::nothrow_t &) throw ()

virtual mxArray *	writeToMatlab () const
	Introduces a pure virtual method responsible for writing to a `mxArray` Matlab object, typically a MATLAB `struct` whose contents are documented in each derived class. More...

mrpt::utils::CObjectPtr	duplicateGetSmartPtr () const
	Returns a copy of the object, indepently of its class, as a smart pointer (the newly created object will exist as long as any copy of this smart pointer). More...

CObject *	clone () const
	Cloning interface for smart pointers. More...

void	rectangle (int x0, int y0, int x1, int y1, const mrpt::utils::TColor color, unsigned int width=1)
	Draws a rectangle (an empty rectangle, without filling) More...

void	triangle (int x0, int y0, int size, const mrpt::utils::TColor color, bool inferior=true, unsigned int width=1)
	Draws a triangle. More...

virtual void	filledRectangle (int x0, int y0, int x1, int y1, const mrpt::utils::TColor color)
	Draws a filled rectangle. More...

virtual void	textOut (int x0, int y0, const std::string &str, const mrpt::utils::TColor color)
	Renders 2D text using bitmap fonts. More...

virtual void	selectTextFont (const std::string &fontName)
	Select the current font used when drawing text. More...

virtual void	drawImage (int x, int y, const utils::CImage &img)
	Draws an image as a bitmap at a given position. More...

virtual void	drawImage (int x, int y, const utils::CImage &img, float rotation, float scale)
	Draws an image as a bitmap at a given position, with some custom scale and rotation changes. More...

void	cross (int x0, int y0, const mrpt::utils::TColor color, char type, unsigned int size=5, unsigned int width=1)
	Draw a cross. More...

template<class MATRIX2X2 >
void	ellipseGaussian (const MATRIX2X2 *cov2D, const double mean_x, const double mean_y, double confIntervalStds=2, const mrpt::utils::TColor &color=mrpt::utils::TColor(255, 255, 255), unsigned int width=1, int nEllipsePoints=20)
	Draws an ellipse representing a given confidence interval of a 2D Gaussian distribution. More...

template<class FEATURELIST >
void	drawFeaturesSimple (const FEATURELIST &list, const TColor &color=TColor::red, const int cross_size=5)
	Draws a set of marks onto the image, given a generic container of entities having just "x" and "y" fields. More...

template<class FEATURELIST >
void	drawFeatures (const FEATURELIST &list, const TColor &color=TColor::red, const bool showIDs=false, const bool showResponse=false)
	Draws a set of marks (or scaled circles for features with scale) onto the image, given a generic container of features. More...

Constructors & destructor
	CImage ()
	Default constructor: initialize an 1x1 RGB image. More...

	CImage (unsigned int width, unsigned int height, TImageChannels nChannels=CH_RGB, bool originTopLeft=true)
	Constructor for a given image size and type. More...

	CImage (const CImage &o)
	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). More...

	CImage (TConstructorFlags_CImage)
	Fast constructor that leaves the image uninitialized (the internal IplImage pointer set to NULL). More...

	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 it already was in grayscale, or otherwise creating a new grayscale image and converting the original image into it. More...

	CImage (void *iplImage)
	Constructor from an IPLImage*, making a copy of the image. More...

template<typename Derived >
	CImage (const Eigen::MatrixBase< Derived > &m, bool matrix_is_normalized)
	Explicit constructor from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false) More...

virtual	~CImage ()
	Destructor: More...

Manipulate the image contents or size, various computer-vision methods (image filters, undistortion, etc.)
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, for that, see scaleImage). More...

void	scaleImage (unsigned int width, unsigned int height, TInterpolationMethod interp=IMG_INTERP_CUBIC)
	Scales this image to a new size, interpolating as needed. More...

void	scaleImage (CImage &out_img, unsigned int width, unsigned int height, TInterpolationMethod interp=IMG_INTERP_CUBIC) const
	Scales this image to a new size, interpolating as needed, saving the new image in a different output object. More...

void	rotateImage (double angle_radians, unsigned int center_x, unsigned int center_y, double scale=1.0)
	Rotates the image by the given angle around the given center point, with an optional scale factor. More...

void	setPixel (int x, int y, size_t color) MRPT_OVERRIDE
	Changes the value of the pixel (x,y). More...

void	setOriginTopLeft (bool val)
	Changes the property of the image stating if the top-left corner (vs. More...

void	line (int x0, int y0, int x1, int y1, const mrpt::utils::TColor color, unsigned int width=1, TPenStyle penStyle=psSolid) MRPT_OVERRIDE
	Draws a line. More...

void	drawCircle (int x, int y, int radius, const mrpt::utils::TColor &color=mrpt::utils::TColor(255, 255, 255), unsigned int width=1) MRPT_OVERRIDE
	Draws a circle of a given radius. More...

void	equalizeHistInPlace ()
	Equalize the image histogram, replacing the original image. More...

void	equalizeHist (CImage &outImg) const
	Equalize the image histogram, saving the new image in the given output object. More...

CImage	scaleHalf () const
	Returns a new image scaled down to half its original size. More...

void	scaleHalf (CImage &out_image) const

CImage	scaleHalfSmooth () const
	Returns a new image scaled down to half its original size (averaging between every two rows) More...

void	scaleHalfSmooth (CImage &out_image) const

CImage	scaleDouble () const
	Returns a new image scaled up to double its original size. More...

void	scaleDouble (CImage &out_image) const

void	update_patch (const CImage &patch, const unsigned int col, const unsigned int row)
	Update a part of this image with the "patch" given as argument. More...

void	extract_patch (CImage &patch, const unsigned int col=0, const unsigned int row=0, const unsigned int width=1, const unsigned int height=1) const
	Extract a patch from this image, saveing it into "patch" (its previous contents will be overwritten). More...

float	correlate (const CImage &img2int, int width_init=0, int height_init=0) const
	Computes the correlation coefficient (returned as val), between two images This function use grayscale images only img1, img2 must be same size (by AJOGD @ DEC-2006) More...

void	cross_correlation (const CImage &patch_img, size_t &u_max, size_t &v_max, double &max_val, int u_search_ini=-1, int v_search_ini=-1, int u_search_size=-1, int v_search_size=-1, CImage *out_corr_image=NULL) const
	Computes the correlation between this image and another one, encapsulating the openCV function cvMatchTemplate. More...

void	cross_correlation_FFT (const CImage &in_img, math::CMatrixFloat &out_corr, int u_search_ini=-1, int v_search_ini=-1, int u_search_size=-1, int v_search_size=-1, float biasThisImg=0, float biasInImg=0) const
	Computes the correlation matrix between this image and another one. More...

void	normalize ()
	Optimize the brightness range of an image without using histogram Only for one channel images. More...

void	flipVertical (bool also_swapRB=false)
	Flips the image vertically. More...

void	flipHorizontal ()
	Flips the image horizontally. More...

void	swapRB ()
	Swaps red and blue channels. More...

void	rectifyImage (CImage &out_img, const mrpt::utils::TCamera &cameraParams) const
	Rectify (un-distort) the image according to some camera parameters, and returns an output un-distorted image. More...

void	rectifyImageInPlace (const mrpt::utils::TCamera &cameraParams)
	Rectify (un-distort) the image according to a certain camera matrix and vector of distortion coefficients, replacing "this" with the rectified image. More...

void	rectifyImageInPlace (void mapX, void mapY)
	Rectify an image (undistorts and rectification) from a stereo pair according to a pair of precomputed rectification maps. More...

void	filterMedian (CImage &out_img, int W=3) const
	Filter the image with a Median filter with a window size WxW, returning the filtered image in out_img. More...

void	filterMedianInPlace (int W=3)
	Filter the image with a Median filter with a window size WxH, replacing "this" image by the filtered one. More...

void	filterGaussianInPlace (int W=3, int H=3)
	Filter the image with a Gaussian filter with a window size WxH, returning the filtered image in out_img. More...

void	filterGaussian (CImage &out_img, int W=3, int H=3) const
	Filter the image with a Gaussian filter with a window size WxH, replacing "this" image by the filtered one. More...

bool	drawChessboardCorners (std::vector< TPixelCoordf > &cornerCoords, unsigned int check_size_x, unsigned int check_size_y, unsigned int lines_width=1, unsigned int circles_radius=4)
	Draw onto this image the detected corners of a chessboard. More...

void	joinImagesHorz (const CImage &im1, const CImage &im2)
	Joins two images side-by-side horizontally. More...

float	KLT_response (const unsigned int x, const unsigned int y, const unsigned int half_window_size) const
	Compute the KLT response at a given pixel (x,y) - Only for grayscale images (for efficiency it avoids converting to grayscale internally). More...

Copy, move & swap operations
CImage &	operator= (const CImage &o)
	Copy operator (if the image is externally stored, the writen image will be such as well). More...

void	copyFromForceLoad (const CImage &o)
	Copies from another image, and, if that one is externally stored, the image file will be actually loaded into memory in "this" object. More...

void	copyFastFrom (CImage &o)
	Moves an image from another object, erasing the origin image in the process (this is much faster than copying) More...

void	swap (CImage &o)
	Very efficient swap of two images (just swap the internal pointers) More...

Access to image contents (IplImage structure and raw pixels).
template<typename T >
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's headers. More...

template<typename T >
T *	getAs ()
	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. More...

unsigned char *	get_unsafe (unsigned int col, unsigned int row, unsigned int channel=0) const
	Access to pixels without checking boundaries - Use normally the () operator better, which checks the coordinates. More...

float	getAsFloat (unsigned int col, unsigned int row, unsigned int channel) const
	Returns the contents of a given pixel at the desired channel, in float format: [0,255]->[0,1] The coordinate origin is pixel(0,0)=top-left corner of the image. More...

float	getAsFloat (unsigned int col, unsigned int row) const
	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] The coordinate origin is pixel(0,0)=top-left corner of the image. More...

unsigned char *	operator() (unsigned int col, unsigned int row, unsigned int channel=0) const
	Returns a pointer to a given pixel information. More...

Query image properties
size_t	getWidth () const MRPT_OVERRIDE
	Returns the width of the image in pixels. More...

size_t	getHeight () const MRPT_OVERRIDE
	Returns the height of the image in pixels. More...

void	getSize (TImageSize &s) const
	Return the size of the image. More...

TImageSize	getSize () const
	Return the size of the image. More...

size_t	getRowStride () const
	Returns the row stride of the image: this is the number of bytes between two consecutive rows. More...

float	getMaxAsFloat () const
	Return the maximum pixel value of the image, as a float value in the range [0,1]. More...

bool	isColor () const
	Returns true if the image is RGB, false if it is grayscale. More...

bool	isOriginTopLeft () const
	Returns true if the coordinates origin is top-left, or false if it is bottom-left. More...

const char *	getChannelsOrder () const
	Returns a string of the form "BGR","RGB" or "GRAY" indicating the channels ordering. More...

void	setChannelsOrder_RGB ()
	Marks the channel ordering in a color image as "RGB" (this doesn't actually modify the image data, just the format description) More...

void	setChannelsOrder_BGR ()
	Marks the channel ordering in a color image as "BGR" (this doesn't actually modify the image data, just the format description) More...

TImageChannels	getChannelCount () const
	Returns the number of channels, typically 1 (GRAY) or 3 (RGB) More...

void	getAsMatrix (mrpt::math::CMatrixFloat &outMatrix, bool doResize=true, int x_min=0, int y_min=0, int x_max=-1, int y_max=-1) const
	Returns the image as a matrix with pixel grayscale values in the range [0,1]. More...

void	getAsRGBMatrices (mrpt::math::CMatrixFloat &outMatrixR, mrpt::math::CMatrixFloat &outMatrixG, mrpt::math::CMatrixFloat &outMatrixB, bool doResize=true, int x_min=0, int y_min=0, int x_max=-1, int y_max=-1) const
	Returns the image as RGB matrices with pixel values in the range [0,1]. More...

void	getAsMatrixTiled (math::CMatrix &outMatrix) const
	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. More...

Color/Grayscale conversion
CImage	grayscale () const
	Returns a grayscale version of the image, or itself if it is already a grayscale image. More...

void	grayscale (CImage &ret) const
	Returns a grayscale version of the image, or itself if it is already a grayscale image. More...

void	colorImage (CImage &ret) const
	Returns a RGB version of the grayscale image, or itself if it is already a RGB image. More...

void	colorImageInPlace ()
	Replaces this grayscale image with a RGB version of it. More...

void	grayscaleInPlace ()
	Replaces the image with a grayscale version of it. More...

Static Public Member Functions
static void *	operator new (size_t size, void *ptr)

Static Public Attributes
static const mrpt::utils::TRuntimeClassId	classCObject

Serialization format global flags
static bool	DISABLE_ZIP_COMPRESSION = false
	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. More...

static bool	DISABLE_JPEG_COMPRESSION = false
	By default, when storing images through the CSerializable interface, RGB images are JPEG-compressed to save space. More...

static int	SERIALIZATION_JPEG_QUALITY = 95
	Unless DISABLE_JPEG_COMPRESSION=true, this sets the JPEG quality (range 1-100) of serialized RGB images. More...

RTTI stuff
static const mrpt::utils::TRuntimeClassId	classCSerializable

Protected Member Functions
void	changeSize (unsigned int width, unsigned int height, TImageChannels nChannels, bool originTopLeft)
	Resize the buffers in "img" to accomodate a new image size and/or format. More...

void	releaseIpl (bool thisIsExternalImgUnload=false) MRPT_NO_THROWS
	Release the internal IPL image, if not NULL or read-only. More...

void	makeSureImageIsLoaded () const
	Checks if the image is of type "external storage", and if so and not loaded yet, load it. More...

CSerializable virtual methods
void	writeToStream (mrpt::utils::CStream &out, int *getVersion) const
	Introduces a pure virtual method responsible for writing to a CStream. More...

void	readFromStream (mrpt::utils::CStream &in, int version)
	Introduces a pure virtual method responsible for loading from a CStream This can not be used directly be users, instead use "stream >> object;" for reading it from a stream or "stream >> object_ptr;" if the class is unknown apriori. More...

Protected Attributes
std::string	m_selectedFont
	The selected font name. More...

const uint32_t *	m_selectedFontBitmaps
	Direct access to character bitmaps. More...

Data members
void *	img
	The internal IplImage pointer to the actual image content. More...

bool	m_imgIsReadOnly
	Set to true only when using setFromIplImageReadOnly. More...

bool	m_imgIsExternalStorage
	Set to true only when using setExternalStorage. More...

std::string	m_externalFile
	The file name of a external storage image. More...

RTTI stuff
typedef CImagePtr	Ptr

typedef CImagePtr	ConstPtr

static mrpt::utils::CLASSINIT	_init_CImage

static mrpt::utils::TRuntimeClassId	classCImage

static const mrpt::utils::TRuntimeClassId *	classinfo

static const mrpt::utils::TRuntimeClassId *	_GetBaseClass ()

virtual const mrpt::utils::TRuntimeClassId *	GetRuntimeClass () const
	Returns information about the class of an object in runtime. More...

virtual mrpt::utils::CObject *	duplicate () const
	Returns a copy of the object, indepently of its class. More...

static mrpt::utils::CObject *	CreateObject ()

static CImagePtr	Create ()

External storage-mode methods
static std::string	IMAGES_PATH_BASE
	By default, ".". More...

void	setExternalStorage (const std::string &fileName) MRPT_NO_THROWS
	By using this method the image is marked as referenced to an external file, which will be loaded only under demand. More...

bool	isExternallyStored () const MRPT_NO_THROWS
	See setExternalStorage(). More...

std::string	getExternalStorageFile () const MRPT_NO_THROWS
	< Only if isExternallyStored() returns true. More...

void	getExternalStorageFileAbsolutePath (std::string &out_path) const
	Only if isExternallyStored() returns true. More...

std::string	getExternalStorageFileAbsolutePath () const
	Only if isExternallyStored() returns true. More...

void	forceLoad () const
	For external storage image objects only, this method makes sure the image is loaded in memory. More...

void	unload () const MRPT_NO_THROWS
	For external storage image objects only, this method unloads the image from memory (or does nothing if already unloaded). More...

Set, load & save methods
void	loadFromMemoryBuffer (unsigned int width, unsigned int height, bool color, unsigned char *rawpixels, bool swapRedBlue=false)
	Reads the image from raw pixels buffer in memory. More...

void	loadFromMemoryBuffer (unsigned int width, unsigned int height, unsigned int bytesPerRow, unsigned char red, unsigned char green, unsigned char *blue)
	Reads a color image from three raw pixels buffers in memory. More...

void	loadFromIplImage (void *iplImage)
	Reads the image from a OpenCV IplImage object (making a COPY). More...

void	setFromIplImage (void *iplImage)
	Reads the image from a OpenCV IplImage object (WITHOUT making a copy). More...

void	setFromIplImageReadOnly (void *iplImage)
	Reads the image from a OpenCV IplImage object (WITHOUT making a copy) and from now on the image cannot be modified, just read. More...

void	setFromImageReadOnly (const CImage &other_img)
	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). More...

template<typename Derived >
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,1] (normalized=true) or [0,255] (normalized=false) Matrix indexes are assumed to be in this order: M(row,column) More...

template<typename Derived >
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,255] (normalized=false) Matrix indexes are assumed to be in this order: M(row,column) More...

void	loadFromStreamAsJPEG (CStream &in)
	Reads the image from a binary stream containing a binary jpeg file. More...

bool	loadFromFile (const std::string &fileName, int isColor=-1)
	Load image from a file, whose format is determined from the extension (internally uses OpenCV). More...

bool	loadFromXPM (const char **xpm_array, bool swap_rb=true)
	Loads the image from an XPM array, as #include'd from a ".xpm" file. More...

bool	saveToFile (const std::string &fileName, int jpeg_quality=95) const
	Save the image to a file, whose format is determined from the extension (internally uses OpenCV). More...

void	saveToStreamAsJPEG (mrpt::utils::CStream &out, const int jpeg_quality=95) const
	Save image to binary stream as a JPEG (.jpg) compressed format. More...

static bool	loadTGA (const std::string &fileName, mrpt::utils::CImage &out_RGB, mrpt::utils::CImage &out_alpha)
	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. More...

Member Typedef Documentation

◆ ConstPtr

typedef CImagePtr mrpt::utils::CImage::ConstPtr

Definition at line 103 of file CImage.h.

◆ Ptr

typedef CImagePtr mrpt::utils::CImage::Ptr

A typedef for the associated smart pointer

Definition at line 103 of file CImage.h.

Member Enumeration Documentation

◆ TPenStyle

enum mrpt::utils::CCanvas::TPenStyle

inherited

Definition of pen styles.

Enumerator
psSolid
psDash
psDot
psDashDot
psDashDotDot

Definition at line 53 of file CCanvas.h.

Constructor & Destructor Documentation

◆ CImage() [1/7]

CImage::CImage ( )

Default constructor: initialize an 1x1 RGB image.

Definition at line 81 of file CImage.cpp.

References CH_RGB, changeSize(), MRPT_END, and MRPT_START.

◆ CImage() [2/7]

CImage::CImage	(	unsigned int	width,
		unsigned int	height,
		TImageChannels	nChannels = `CH_RGB`,
		bool	originTopLeft = `true`
	)

Constructor for a given image size and type.

Examples:

CImage img1(width, height, CH_GRAY ); // Grayscale image (8U1C)

CImage img2(width, height, CH_RGB ); // RGB image (8U3C)

Definition at line 66 of file CImage.cpp.

References changeSize(), MRPT_END, and MRPT_START.

◆ CImage() [3/7]

CImage::CImage ( const CImage & o )

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).

Definition at line 96 of file CImage.cpp.

References MRPT_END, and MRPT_START.

◆ CImage() [4/7]

mrpt::utils::CImage::CImage ( TConstructorFlags_CImage )

inline

Fast constructor that leaves the image uninitialized (the internal IplImage pointer set to NULL).

Use only when you know the image will be soon be assigned another image. Example of usage:

CImage myImg(UNINITIALIZED_IMAGE);

Definition at line 142 of file CImage.h.

◆ CImage() [5/7]

mrpt::utils::CImage::CImage	(	const CImage &	other_img,
		TConstructorFlags_CImage	constructor_flag
	)

inline

Fast constructor of a grayscale version of another image, making a reference to the original image if it already was in grayscale, or otherwise creating a new grayscale image and converting the original image into it.

It's very important to keep in mind that the original image can't be destroyed before the new object being created with this constructor. Example of usage:

void my_func(const CImage &in_img) {
   const CImage gray_img(in_img, FAST_REF_OR_CONVERT_TO_GRAY);
   // We can now operate on "gray_img" being sure it's in grayscale.
}

Definition at line 155 of file CImage.h.

References grayscale(), isColor(), and MRPT_UNUSED_PARAM.

◆ CImage() [6/7]

CImage::CImage ( void * iplImage )

Constructor from an IPLImage*, making a copy of the image.

See also: loadFromIplImage, setFromIplImage

Definition at line 201 of file CImage.cpp.

References changeSize(), MRPT_END, and MRPT_START.

◆ CImage() [7/7]

template<typename Derived >

mrpt::utils::CImage::CImage	(	const Eigen::MatrixBase< Derived > &	m,
		bool	matrix_is_normalized
	)

inlineexplicit

Explicit constructor from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false)

See also: setFromMatrix

Definition at line 171 of file CImage.h.

◆ ~CImage()

CImage::~CImage ( )

virtual

Destructor:

Definition at line 220 of file CImage.cpp.

References releaseIpl().

Member Function Documentation

◆ _GetBaseClass()

static const mrpt::utils::TRuntimeClassId* mrpt::utils::CImage::_GetBaseClass ( )

staticprotected

◆ changeSize()

void CImage::changeSize	(	unsigned int	width,
		unsigned int	height,
		TImageChannels	nChannels,
		bool	originTopLeft
	)

protected

Resize the buffers in "img" to accomodate a new image size and/or format.

Definition at line 228 of file CImage.cpp.

References mrpt::utils::CTimeLogger::enter(), mrpt::mrpt::format(), img, mrpt::utils::CTimeLogger::leave(), makeSureImageIsLoaded(), MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by CImage(), equalizeHist(), loadFromMemoryBuffer(), loadFromStreamAsJPEG(), and readFromStream().

◆ clone()

CObject* mrpt::utils::CObject::clone ( ) const

inlineinherited

Cloning interface for smart pointers.

Definition at line 143 of file CObject.h.

◆ colorImage()

void CImage::colorImage ( CImage & ret ) const

Returns a RGB version of the grayscale image, or itself if it is already a RGB image.

Replaces this grayscale image with a RGB version of it.

See also: grayscale; grayscaleInPlace

Definition at line 2392 of file CImage.cpp.

References isColor(), and setFromIplImage().

Referenced by mrpt::vision::checkerBoardCameraCalibration(), mrpt::vision::checkerBoardStereoCalibration(), and find_chessboard_corners_multiple().

◆ colorImageInPlace()

void CImage::colorImageInPlace ( )

Replaces this grayscale image with a RGB version of it.

See also: grayscaleInPlace

Definition at line 2415 of file CImage.cpp.

References isColor(), and releaseIpl().

◆ copyFastFrom()

void CImage::copyFastFrom ( CImage & o )

Moves an image from another object, erasing the origin image in the process (this is much faster than copying)

See also: operator =

Definition at line 167 of file CImage.cpp.

References img, m_externalFile, m_imgIsExternalStorage, m_imgIsReadOnly, MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by mrpt::opengl::CTexturedObject::assignImage_fast(), and mrpt::opengl::COpenGLViewport::internal_setImageView_fast().

◆ copyFromForceLoad()

void CImage::copyFromForceLoad ( const CImage & o )

Copies from another image, and, if that one is externally stored, the image file will be actually loaded into memory in "this" object.

See also: operator =

Exceptions

CExceptionExternalImageNotFound If the external image couldn't be loaded.

Definition at line 150 of file CImage.cpp.

References getExternalStorageFileAbsolutePath(), isExternallyStored(), loadFromFile(), and THROW_TYPED_EXCEPTION_FMT.

◆ correlate()

float CImage::correlate	(	const CImage &	img2int,
		int	width_init = `0`,
		int	height_init = `0`
	)		const

Computes the correlation coefficient (returned as val), between two images This function use grayscale images only img1, img2 must be same size (by AJOGD @ DEC-2006)

Definition at line 1403 of file CImage.cpp.

References getHeight(), getWidth(), makeSureImageIsLoaded(), and THROW_EXCEPTION.

◆ Create()

static CImagePtr mrpt::utils::CImage::Create ( )

static

Referenced by mrpt::opengl::COpenGLViewport::internal_setImageView_fast().

◆ CreateObject()

static mrpt::utils::CObject* mrpt::utils::CImage::CreateObject ( )

static

◆ cross()

void CCanvas::cross	(	int	x0,
		int	y0,
		const mrpt::utils::TColor	color,
		char	type,
		unsigned int	size = `5`,
		unsigned int	width = `1`
	)

inherited

Draw a cross.

Parameters

x0	The point x coordinate
y0	The point y coordinate
color	The color of the cross
size	The size of the cross
type	The cross type. It could be: 'x', '+' or ':'(like '+' but clear at the center dot)
width	The desired width of the cross (this is IGNORED yet)

Definition at line 329 of file CCanvas.cpp.

References mrpt::utils::CCanvas::line(), and THROW_EXCEPTION.

Referenced by find_chessboard_corners_multiple(), and mrpt::gui::CDisplayWindow::plot().

◆ cross_correlation()

void CImage::cross_correlation	(	const CImage &	patch_img,
		size_t &	u_max,
		size_t &	v_max,
		double &	max_val,
		int	u_search_ini = `-1`,
		int	v_search_ini = `-1`,
		int	u_search_size = `-1`,
		int	v_search_size = `-1`,
		CImage *	out_corr_image = `NULL`
	)		const

Computes the correlation between this image and another one, encapsulating the openCV function cvMatchTemplate.

Parameters

patch_img	The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
u_search_ini	The "x" coordinate of the search window.
v_search_ini	The "y" coordinate of the search window.
u_search_size	The width of the search window.
v_search_size	The height of the search window.
u_max	The u coordinate where find the maximun cross correlation value.
v_max	The v coordinate where find the maximun cross correlation value
max_val	The maximun value of cross correlation which we can find
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 ) Note: By default, the search area is the whole (this) image. (by AJOGD @ MAR-2007)

Definition at line 1451 of file CImage.cpp.

References ASSERT_, getAs(), isColor(), makeSureImageIsLoaded(), mrpt::system::os::memcpy(), MRPT_END, MRPT_START, mrpt::utils::round(), setFromIplImage(), and THROW_EXCEPTION.

Referenced by mrpt::vision::CFeature::patchCorrelationTo().

◆ cross_correlation_FFT()

void CImage::cross_correlation_FFT	(	const CImage &	in_img,
		math::CMatrixFloat &	out_corr,
		int	u_search_ini = `-1`,
		int	v_search_ini = `-1`,
		int	u_search_size = `-1`,
		int	v_search_size = `-1`,
		float	biasThisImg = `0`,
		float	biasInImg = `0`
	)		const

Computes the correlation matrix between this image and another one.

This implementation uses the 2D FFT for achieving reduced computation time.

Parameters

in_img	The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
u_search_ini	The "x" coordinate of the search window.
v_search_ini	The "y" coordinate of the search window.
u_search_size	The width of the search window.
v_search_size	The height of the search window.
out_corr	The output for the correlation matrix, which will be "u_search_size" x "v_search_size"
biasThisImg	This optional parameter is a fixed "bias" value to be substracted to the pixels of "this" image before performing correlation.
biasInImg	This optional parameter is a fixed "bias" value to be substracted to the pixels of "in_img" image before performing correlation. Note: By default, the search area is the whole (this) image. (by JLBC @ JAN-2006)

See also: cross_correlation

Definition at line 1736 of file CImage.cpp.

References ASSERT_, mrpt::math::dft2_complex(), getAsMatrix(), getHeight(), getWidth(), mrpt::math::idft2_complex(), makeSureImageIsLoaded(), MRPT_END, MRPT_START, mrpt::math::round2up(), and mrpt::math::square().

Referenced by mrpt::slam::CGridMapAligner::AlignPDF_correlation().

◆ drawChessboardCorners()

bool CImage::drawChessboardCorners	(	std::vector< TPixelCoordf > &	cornerCoords,
		unsigned int	check_size_x,
		unsigned int	check_size_y,
		unsigned int	lines_width = `1`,
		unsigned int	r = `4`
	)

Draw onto this image the detected corners of a chessboard.

The length of cornerCoords must be the product of the two check_sizes.

Parameters

cornerCoords	[IN] The pixel coordinates of all the corners.
check_size_x	[IN] The number of squares, in the X direction
check_size_y	[IN] The number of squares, in the Y direction

Returns: false if the length of cornerCoords is inconsistent (nothing is drawn then).

See also: mrpt::vision::findChessboardCorners

The length of cornerCoords must be the product of the two check_sizes.

Parameters

cornerCoords	[IN] The pixel coordinates of all the corners.
check_size_x	[IN] The number of squares, in the X direction
check_size_y	[IN] The number of squares, in the Y direction

Returns: false if the length of cornerCoords is inconsistent (nothing is drawn then).

Definition at line 2325 of file CImage.cpp.

References mrpt::utils::TColor::blue, mrpt::mrpt::format(), mrpt::utils::CCanvas::selectTextFont(), and mrpt::utils::CCanvas::textOut().

Referenced by mrpt::vision::checkerBoardStereoCalibration().

◆ drawCircle()

void CImage::drawCircle	(	int	x,
		int	y,
		int	radius,
		const mrpt::utils::TColor &	color = `mrpt::utils::TColor(255,255,255)`,
		unsigned int	width = `1`
	)

virtual

Draws a circle of a given radius.

Parameters

x	The center - x coordinate in pixels.
y	The center - y coordinate in pixels.
radius	The radius - in pixels.
color	The color of the circle.
width	The desired width of the line

Reimplemented from mrpt::utils::CCanvas.

Definition at line 1323 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

Referenced by mrpt::vision::CFeatureExtraction::internal_computeSpinImageDescriptors().

◆ drawFeatures()

template<class FEATURELIST >

void mrpt::utils::CCanvas::drawFeatures	(	const FEATURELIST &	list,
		const TColor &	color = `TColor::red`,
		const bool	showIDs = `false`,
		const bool	showResponse = `false`
	)

inlineinherited

Draws a set of marks (or scaled circles for features with scale) onto the image, given a generic container of features.

The class of FEATURELIST can be:

See also: drawFeaturesSimple

Definition at line 322 of file CCanvas.h.

References cross(), mrpt::format(), mrpt::utils::TColor::red, and mrpt::utils::round().

◆ drawFeaturesSimple()

template<class FEATURELIST >

void mrpt::utils::CCanvas::drawFeaturesSimple	(	const FEATURELIST &	list,
		const TColor &	color = `TColor::red`,
		const int	cross_size = `5`
	)

inlineinherited

Draws a set of marks onto the image, given a generic container of entities having just "x" and "y" fields.

The class of FEATURELIST can be, for example, std::vector<mrpt::math::TPoint2D>, std::vector<TPixelCoordsf> or mrpt::vision::CFeatureList

See also: drawFeatures

Definition at line 304 of file CCanvas.h.

References cross(), and mrpt::utils::round().

◆ drawImage() [1/2]

void CCanvas::drawImage	(	int	x,
		int	y,
		const utils::CImage &	img
	)

virtualinherited

Draws an image as a bitmap at a given position.

Parameters

x0	The top-left corner x coordinates on this canvas where the image is to be drawn
y0	The top-left corner y coordinates on this canvas where the image is to be drawn
img	The image to be drawn in this canvas This method may be redefined in some classes implementing this interface in a more appropiate manner.

Reimplemented in mrpt::utils::CEnhancedMetaFile.

Definition at line 271 of file CCanvas.cpp.

References MRPT_END, MRPT_START, and mrpt::utils::CCanvas::setPixel().

Referenced by mrpt::slam::CGridMapAligner::AlignPDF_robustMatch(), mrpt::slam::CMetricMapBuilderRBPF::drawCurrentEstimationToImage(), and mrpt::utils::CEnhancedMetaFile::drawImage().

◆ drawImage() [2/2]

void CCanvas::drawImage	(	int	x,
		int	y,
		const utils::CImage &	img,
		float	rotation,
		float	scale
	)

virtualinherited

Draws an image as a bitmap at a given position, with some custom scale and rotation changes.

Parameters

x0	The top-left corner x coordinates on this canvas where the image is to be drawn
y0	The top-left corner y coordinates on this canvas where the image is to be drawn
rotation	The rotation in radians, positive values being anti-clockwise direction, 0 is the normal position.
scale	The scale factor, e.g. 2 means twice the original size.
img	The image to be drawn in this canvas This method may be redefined in some classes implementing this interface in a more appropiate manner.

Reimplemented in mrpt::utils::CEnhancedMetaFile.

Definition at line 307 of file CCanvas.cpp.

References MRPT_END, MRPT_START, MRPT_UNUSED_PARAM, and THROW_EXCEPTION.

◆ duplicate()

virtual mrpt::utils::CObject* mrpt::utils::CImage::duplicate ( ) const

virtual

Returns a copy of the object, indepently of its class.

Implements mrpt::utils::CObject.

◆ duplicateGetSmartPtr()

mrpt::utils::CObjectPtr mrpt::utils::CObject::duplicateGetSmartPtr ( ) const

inlineinherited

Returns a copy of the object, indepently of its class, as a smart pointer (the newly created object will exist as long as any copy of this smart pointer).

Definition at line 140 of file CObject.h.

Referenced by mrpt::obs::CRawlog::addActions(), mrpt::slam::CIncrementalMapPartitioner::addMapFrame(), and mrpt::obs::CRawlog::addObservations().

◆ ellipseGaussian()

template<class MATRIX2X2 >

void mrpt::utils::CCanvas::ellipseGaussian	(	const MATRIX2X2 *	cov2D,
		const double	mean_x,
		const double	mean_y,
		double	confIntervalStds = `2`,
		const mrpt::utils::TColor &	color = `mrpt::utils::TColor(255,255,255)`,
		unsigned int	width = `1`,
		int	nEllipsePoints = `20`
	)

inlineinherited

Draws an ellipse representing a given confidence interval of a 2D Gaussian distribution.

Parameters

mean_x	The x coordinate of the center point of the ellipse.
mean_y	The y coordinate of the center point of the ellipse.
cov2D	A 2x2 covariance matrix.
confIntervalStds	How many "sigmas" for the confidence level (i.e. 2->95%, 3=99.97%,...)
color	The color of the ellipse
width	The desired width of the line (this is IGNORED in this virtual class)
nEllipsePoints	The number of points to generate to approximate the ellipse shape.

Exceptions

std::exception On an invalid matrix.

Definition at line 255 of file CCanvas.h.

References M_2PI, MRPT_END_WITH_CLEAN_UP, MRPT_START, and mrpt::utils::round().

◆ equalizeHist()

void CImage::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)

Definition at line 2474 of file CImage.cpp.

References ASSERT_, changeSize(), getAs(), and isOriginTopLeft().

◆ equalizeHistInPlace()

void CImage::equalizeHistInPlace ( )

Equalize the image histogram, replacing the original image.

Note: RGB images are first converted to HSV color space, then equalized for brightness (V)

Definition at line 2514 of file CImage.cpp.

References ASSERT_, and releaseIpl().

Referenced by mrpt::hwdrivers::CSwissRanger3DCamera::getNextObservation().

◆ extract_patch()

void CImage::extract_patch	(	CImage &	patch,
		const unsigned int	col = `0`,
		const unsigned int	row = `0`,
		const unsigned int	width = `1`,
		const unsigned int	height = `1`
	)		const

Extract a patch from this image, saveing it into "patch" (its previous contents will be overwritten).

The patch to extract starts at (col,row) and has the given dimensions.

See also: update_patch

Definition at line 1368 of file CImage.cpp.

References ASSERT_, mrpt::format(), img, makeSureImageIsLoaded(), mrpt::system::os::memcpy(), resize(), and THROW_EXCEPTION.

Referenced by mrpt::vision::computeHistogramOfOrientations(), mrpt::vision::computeMoreDescriptors(), mrpt::vision::computeMultiOrientations(), mrpt::vision::computeMultiResolutionDescriptors(), mrpt::vision::CFeatureExtraction::extractFeaturesFAST(), mrpt::vision::CFeatureExtraction::extractFeaturesFASTER_N(), mrpt::vision::CFeatureExtraction::extractFeaturesKLT(), mrpt::vision::CFeatureExtraction::extractFeaturesORB(), mrpt::vision::CFeatureExtraction::extractFeaturesSIFT(), mrpt::vision::CFeatureExtraction::extractFeaturesSURF(), mrpt::obs::CObservation3DRangeScan::getZoneAsObs(), and mrpt::vision::openCV_cross_correlation().

◆ filledRectangle()

void CCanvas::filledRectangle	(	int	x0,
		int	y0,
		int	x1,
		int	y1,
		const mrpt::utils::TColor	color
	)

virtualinherited

Draws a filled rectangle.

Parameters

x0	The top-left x coordinate
y0	The top-left y coordinate
x1	The right-bottom x coordinate
y1	The right-bottom y coordinate
color	The color of the rectangle fill This method may be redefined in some classes implementing this interface in a more appropiate manner.

See also: rectangle

Definition at line 229 of file CCanvas.cpp.

References mrpt::utils::CCanvas::getHeight(), mrpt::utils::CCanvas::getWidth(), min, and mrpt::utils::CCanvas::setPixel().

Referenced by mrpt::slam::CGridMapAligner::AlignPDF_robustMatch(), and mrpt::gui::CDisplayWindow::plot().

◆ filterGaussian()

void CImage::filterGaussian	(	CImage &	out_img,
		int	W = `3`,
		int	H = `3`
	)		const

Filter the image with a Gaussian filter with a window size WxH, replacing "this" image by the filtered one.

Definition at line 2173 of file CImage.cpp.

References ASSERT_, loadFromIplImage(), and makeSureImageIsLoaded().

◆ filterGaussianInPlace()

void CImage::filterGaussianInPlace	(	int	W = `3`,
		int	H = `3`
	)

Filter the image with a Gaussian filter with a window size WxH, returning the filtered image in out_img.

Definition at line 2199 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and releaseIpl().

◆ filterMedian()

void CImage::filterMedian	(	CImage &	out_img,
		int	W = `3`
	)		const

Filter the image with a Median filter with a window size WxW, returning the filtered image in out_img.

Definition at line 2123 of file CImage.cpp.

References ASSERT_, loadFromIplImage(), and makeSureImageIsLoaded().

◆ filterMedianInPlace()

void CImage::filterMedianInPlace ( int W = 3 )

Filter the image with a Median filter with a window size WxH, replacing "this" image by the filtered one.

Definition at line 2149 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and releaseIpl().

◆ flipHorizontal()

void CImage::flipHorizontal ( )

Flips the image horizontally.

See also: swapRB(), flipVertical()

Definition at line 1995 of file CImage.cpp.

◆ flipVertical()

void CImage::flipVertical ( bool also_swapRB = false )

Flips the image vertically.

See also: swapRB(), flipHorizontal()

Definition at line 1985 of file CImage.cpp.

◆ forceLoad()

void mrpt::utils::CImage::forceLoad ( ) const

inline

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.

Definition at line 691 of file CImage.h.

◆ get_unsafe()

unsigned char * CImage::get_unsafe	(	unsigned int	col,
		unsigned int	row,
		unsigned int	channel = `0`
	)		const

Access to pixels without checking boundaries - Use normally the () operator better, which checks the coordinates.

See also: CImage::operator()

Definition at line 491 of file CImage.cpp.

References makeSureImageIsLoaded().

Referenced by getAsMatrix(), getAsRGBMatrices(), mrpt::hwdrivers::CSwissRanger3DCamera::getNextObservation(), mrpt::vision::CFeatureExtraction::internal_computeSpinImageDescriptors(), mrpt::maps::detail::pointmap_traits< CColouredPointsMap >::internal_loadFromRangeScan3D_prepareOneRange(), mrpt::opengl::CTexturedObject::loadTextureInOpenGL(), and mrpt::obs::detail::project3DPointsFromDepthImageInto().

◆ getAs() [1/2]

template<typename T >

const T* mrpt::utils::CImage::getAs ( ) const

inline

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.

Definition at line 517 of file CImage.h.

◆ getAs() [2/2]

template<typename T >

T* mrpt::utils::CImage::getAs ( )

inline

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.

Definition at line 522 of file CImage.h.

◆ getAsFloat() [1/2]

float CImage::getAsFloat	(	unsigned int	col,
		unsigned int	row,
		unsigned int	channel
	)		const

Returns the contents of a given pixel at the desired channel, in float format: [0,255]->[0,1] The coordinate origin is pixel(0,0)=top-left corner of the image.

Exceptions

std::exception On pixel coordinates out of bounds

See also: operator()

Definition at line 942 of file CImage.cpp.

References makeSureImageIsLoaded().

Referenced by mrpt::vision::computeHistogramOfOrientations(), getMaxAsFloat(), and mrpt::maps::COccupancyGridMap2D::loadFromBitmap().

◆ getAsFloat() [2/2]

float CImage::getAsFloat	(	unsigned int	col,
		unsigned int	row
	)		const

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] The coordinate origin is pixel(0,0)=top-left corner of the image.

Exceptions

std::exception On pixel coordinates out of bounds

See also: operator()

Definition at line 955 of file CImage.cpp.

References isColor().

◆ getAsMatrix()

void CImage::getAsMatrix	(	mrpt::math::CMatrixFloat &	outMatrix,
		bool	doResize = `true`,
		int	x_min = `0`,
		int	y_min = `0`,
		int	x_max = `-1`,
		int	y_max = `-1`
	)		const

Returns the image as a matrix with pixel grayscale values in the range [0,1].

Matrix indexes in this order: M(row,column)

Parameters

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,...)
x_min	The starting "x" coordinate to extract (default=0=the first column)
y_min	The starting "y" coordinate to extract (default=0=the first row)
x_max	The final "x" coordinate (inclusive) to extract (default=-1=the last column)
y_max	The final "y" coordinate (inclusive) to extract (default=-1=the last row)

See also: setFromMatrix

Definition at line 1601 of file CImage.cpp.

References ASSERT_, get_unsafe(), isColor(), makeSureImageIsLoaded(), MRPT_END, and MRPT_START.

Referenced by cross_correlation_FFT().

◆ getAsMatrixTiled()

void CImage::getAsMatrixTiled ( math::CMatrix & outMatrix ) const

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.

Definition at line 1840 of file CImage.cpp.

References ASSERT_, isColor(), makeSureImageIsLoaded(), MRPT_END, and MRPT_START.

◆ getAsRGBMatrices()

void CImage::getAsRGBMatrices	(	mrpt::math::CMatrixFloat &	outMatrixR,
		mrpt::math::CMatrixFloat &	outMatrixG,
		mrpt::math::CMatrixFloat &	outMatrixB,
		bool	doResize = `true`,
		int	x_min = `0`,
		int	y_min = `0`,
		int	x_max = `-1`,
		int	y_max = `-1`
	)		const

Returns the image as RGB matrices with pixel values in the range [0,1].

Matrix indexes in this order: M(row,column)

Parameters

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,...)
x_min	The starting "x" coordinate to extract (default=0=the first column)
y_min	The starting "y" coordinate to extract (default=0=the first row)
x_max	The final "x" coordinate (inclusive) to extract (default=-1=the last column)
y_max	The final "y" coordinate (inclusive) to extract (default=-1=the last row)

See also: setFromRGBMatrices

Definition at line 1662 of file CImage.cpp.

References ASSERT_, get_unsafe(), isColor(), makeSureImageIsLoaded(), MRPT_END, and MRPT_START.

◆ getChannelCount()

TImageChannels CImage::getChannelCount ( ) const

Returns the number of channels, typically 1 (GRAY) or 3 (RGB)

See also: isColor

Definition at line 912 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

Referenced by mrpt::vision::CFeatureExtraction::internal_computeLogPolarImageDescriptors(), and mrpt::vision::CFeatureExtraction::internal_computePolarImageDescriptors().

◆ getChannelsOrder()

const char * CImage::getChannelsOrder ( ) const

Returns a string of the form "BGR","RGB" or "GRAY" indicating the channels ordering.

See also: setChannelsOrder, swapRB

Definition at line 1180 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and THROW_EXCEPTION.

Referenced by mrpt::maps::CColouredPointsMap::colourFromObservation(), mrpt::obs::CObservationStereoImages::getDescriptionAsText(), and mrpt::opengl::CTexturedObject::loadTextureInOpenGL().

◆ getExternalStorageFile()

std::string mrpt::utils::CImage::getExternalStorageFile ( ) const

inline

< Only if isExternallyStored() returns true.

See also: getExternalStorageFileAbsolutePath

Definition at line 673 of file CImage.h.

Referenced by mrpt::obs::CObservationStereoImages::getDescriptionAsText(), and mrpt::obs::CObservation3DRangeScan::getDescriptionAsText().

◆ getExternalStorageFileAbsolutePath() [1/2]

void CImage::getExternalStorageFileAbsolutePath ( std::string & out_path ) const

Only if isExternallyStored() returns true.

See also: getExternalStorageFile

Definition at line 1962 of file CImage.cpp.

References ASSERT_, IMAGES_PATH_BASE, and m_externalFile.

Referenced by copyFromForceLoad().

◆ getExternalStorageFileAbsolutePath() [2/2]

std::string mrpt::utils::CImage::getExternalStorageFileAbsolutePath ( ) const

inline

Only if isExternallyStored() returns true.

See also: getExternalStorageFile

Definition at line 682 of file CImage.h.

Referenced by makeSureImageIsLoaded().

◆ getHeight()

size_t CImage::getHeight ( ) const

virtual

Returns the height of the image in pixels.

See also: getSize

Implements mrpt::utils::CCanvas.

Definition at line 884 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

◆ getMaxAsFloat()

float CImage::getMaxAsFloat ( ) const

Return the maximum pixel value of the image, as a float value in the range [0,1].

See also: getAsFloat

Definition at line 976 of file CImage.cpp.

References getAsFloat(), getHeight(), and getWidth().

◆ getRowStride()

size_t CImage::getRowStride ( ) const

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)

See also: getSize, get_unsafe

Definition at line 869 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

Referenced by mrpt::opengl::CTexturedObject::loadTextureInOpenGL().

◆ GetRuntimeClass()

virtual const mrpt::utils::TRuntimeClassId* mrpt::utils::CImage::GetRuntimeClass ( ) const

virtual

Returns information about the class of an object in runtime.

Reimplemented from mrpt::utils::CSerializable.

◆ getSize() [1/2]

void CImage::getSize ( TImageSize & s ) const

Return the size of the image.

See also: getWidth, getHeight

Definition at line 842 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

Referenced by mrpt::vision::checkerBoardStereoCalibration().

◆ getSize() [2/2]

TImageSize mrpt::utils::CImage::getSize ( ) const

inline

Return the size of the image.

See also: getWidth, getHeight

Definition at line 569 of file CImage.h.

Referenced by scaleDouble().

◆ getWidth()

size_t CImage::getWidth ( ) const

virtual

Returns the width of the image in pixels.

See also: getSize

Implements mrpt::utils::CCanvas.

Definition at line 855 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

◆ grayscale() [1/2]

CImage CImage::grayscale ( ) const

Returns a grayscale version of the image, or itself if it is already a grayscale image.

Definition at line 992 of file CImage.cpp.

Referenced by CImage(), and mrpt::vision::openCV_cross_correlation().

◆ grayscale() [2/2]

void CImage::grayscale ( CImage & ret ) const

Returns a grayscale version of the image, or itself if it is already a grayscale image.

See also: colorImage

Definition at line 1028 of file CImage.cpp.

References ASSERT_, ipl_to_grayscale(), makeSureImageIsLoaded(), and setFromIplImage().

◆ grayscaleInPlace()

void CImage::grayscaleInPlace ( )

Replaces the image with a grayscale version of it.

See also: colorImageInPlace

Definition at line 1052 of file CImage.cpp.

References ASSERT_, ipl_to_grayscale(), makeSureImageIsLoaded(), and setFromIplImage().

◆ isColor()

bool CImage::isColor ( ) const

Returns true if the image is RGB, false if it is grayscale.

Definition at line 898 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

Referenced by CImage(), colorImage(), colorImageInPlace(), mrpt::maps::CColouredPointsMap::colourFromObservation(), cross_correlation(), getAsFloat(), getAsMatrix(), getAsMatrixTiled(), getAsRGBMatrices(), mrpt::vision::CFeatureExtraction::internal_computeSpinImageDescriptors(), mrpt::maps::detail::pointmap_traits< CColouredPointsMap >::internal_loadFromRangeScan3D_init(), loadFromFile(), loadFromStreamAsJPEG(), mrpt::opengl::CTexturedObject::loadTextureInOpenGL(), mrpt::vision::openCV_cross_correlation(), mrpt::obs::detail::project3DPointsFromDepthImageInto(), mrpt::vision::CStereoRectifyMap::rectify(), and writeToStream().

◆ isExternallyStored()

bool mrpt::utils::CImage::isExternallyStored ( ) const

inline

See setExternalStorage().

Definition at line 671 of file CImage.h.

Referenced by mrpt::vision::checkerBoardCameraCalibration(), mrpt::vision::checkerBoardStereoCalibration(), copyFromForceLoad(), mrpt::obs::CObservationStereoImages::getDescriptionAsText(), and mrpt::obs::CObservation3DRangeScan::getDescriptionAsText().

◆ isOriginTopLeft()

bool CImage::isOriginTopLeft ( ) const

Returns true if the coordinates origin is top-left, or false if it is bottom-left.

Definition at line 927 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and THROW_EXCEPTION.

Referenced by equalizeHist(), mrpt::obs::CObservationStereoImages::getDescriptionAsText(), mrpt::vision::CStereoRectifyMap::rectify(), and mrpt::utils::CCanvas::textOut().

◆ joinImagesHorz()

void CImage::joinImagesHorz	(	const CImage &	im1,
		const CImage &	im2
	)

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)

Parameters

im1	[IN] The first image.
im2	[IN] The other image.

Definition at line 2437 of file CImage.cpp.

References ASSERT_, getAs(), getHeight(), and setFromIplImageReadOnly().

Referenced by mrpt::gui::CDisplayWindow::showImagesAndMatchedPoints().

◆ KLT_response()

float CImage::KLT_response	(	const unsigned int	x,
		const unsigned int	y,
		const unsigned int	half_window_size
	)		const

Compute the KLT response at a given pixel (x,y) - Only for grayscale images (for efficiency it avoids converting to grayscale internally).

See KLT_response_optimized for more details on the internal optimizations of this method, but this graph shows a general view:

Definition at line 2590 of file CImage.cpp.

References ASSERT_, and ASSERTMSG_.

Referenced by mrpt::vision::CFeatureExtraction::extractFeaturesFAST(), mrpt::vision::CGenericFeatureTracker::internal_trackFeatures(), and mrpt::vision::detail::trackFeatures_checkResponses_impl_simple().

◆ line()

void CImage::line	(	int	x0,
		int	y0,
		int	x1,
		int	y1,
		const mrpt::utils::TColor	color,
		unsigned int	width = `1`,
		TPenStyle	penStyle = `psSolid`
	)

virtual

Draws a line.

Parameters

x0	The starting point x coordinate
y0	The starting point y coordinate
x1	The end point x coordinate
y1	The end point y coordinate
color	The color of the line
width	The desired width of the line (this is IGNORED in this virtual class) This method may be redefined in some classes implementing this interface in a more appropiate manner.

Reimplemented from mrpt::utils::CCanvas.

Definition at line 1301 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and MRPT_UNUSED_PARAM.

Referenced by mrpt::gui::CDisplayWindow::plot(), and mrpt::gui::CDisplayWindow::showTiledImageAndPoints().

◆ loadFromFile()

bool CImage::loadFromFile	(	const std::string &	fileName,
		int	isColor = `-1`
	)

Load image from a file, whose format is determined from the extension (internally uses OpenCV).

Parameters

fileName	The file to read from.
isColor	Specifies colorness of the loaded image: if >0, the loaded image is forced to be color 3-channel image; if 0, the loaded image is forced to be grayscale; if <0, the loaded image will be loaded as is (with number of channels depends on the file). The supported formats are:

Windows bitmaps - BMP, DIB;
JPEG files - JPEG, JPG, JPE;
Portable Network Graphics - PNG;
Portable image format - PBM, PGM, PPM;
Sun rasters - SR, RAS;
TIFF files - TIFF, TIF.

Returns: False on any error

See also: saveToFile, setExternalStorage,loadFromXPM, loadTGA

Definition at line 277 of file CImage.cpp.

References isColor(), MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by mrpt::vision::checkerBoardCameraCalibration(), copyFromForceLoad(), and makeSureImageIsLoaded().

◆ loadFromIplImage()

void CImage::loadFromIplImage ( void * iplImage )

Reads the image from a OpenCV IplImage object (making a COPY).

Definition at line 324 of file CImage.cpp.

References ASSERT_, MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by filterGaussian(), filterMedian(), and rectifyImage().

◆ loadFromMemoryBuffer() [1/2]

void CImage::loadFromMemoryBuffer	(	unsigned int	width,
		unsigned int	height,
		bool	color,
		unsigned char *	rawpixels,
		bool	swapRedBlue = `false`
	)

Reads the image from raw pixels buffer in memory.

Definition at line 387 of file CImage.cpp.

References img, m_imgIsExternalStorage, m_imgIsReadOnly, mrpt::system::os::memcpy(), MRPT_END, MRPT_START, resize(), and THROW_EXCEPTION.

Referenced by mrpt::hwdrivers::CImageGrabber_dc1394::getObservation(), mrpt::hwdrivers::CImageGrabber_FlyCapture2::getObservation(), mrpt::hwdrivers::CDUO3DCamera::getObservations(), loadFromXPM(), mrpt::hwdrivers::CFFMPEG_InputStream::retrieveFrame(), and mrpt::gui::wxImage2MRPTImage().

◆ loadFromMemoryBuffer() [2/2]

void CImage::loadFromMemoryBuffer	(	unsigned int	width,
		unsigned int	height,
		unsigned int	bytesPerRow,
		unsigned char *	red,
		unsigned char *	green,
		unsigned char *	blue
	)

Reads a color image from three raw pixels buffers in memory.

bytesPerRow is the number of bytes per row per channel, i.e. the row increment.

Definition at line 1195 of file CImage.cpp.

References changeSize(), img, MRPT_END, MRPT_START, and red.

◆ loadFromStreamAsJPEG()

void CImage::loadFromStreamAsJPEG ( CStream & in )

Reads the image from a binary stream containing a binary jpeg file.

Exceptions

std::exception On pixel coordinates out of bounds

Definition at line 482 of file CImage_JPEG_streams.cpp.

References changeSize(), img, isColor(), jpeg_create_decompress, jpeg_destroy_decompress(), jpeg_finish_decompress(), jpeg_read_header(), jpeg_read_scanlines(), jpeg_start_decompress(), jpeg_std_error(), jpeg_stdio_src(), JPOOL_IMAGE, mrpt::system::os::memcpy(), MRPT_END, MRPT_START, jpeg_decompress_struct::out_color_components, jpeg_decompress_struct::output_components, jpeg_decompress_struct::output_height, jpeg_decompress_struct::output_width, and TRUE.

Referenced by mrpt::hwdrivers::CRovio::captureImageAsync(), and readFromStream().

◆ loadFromXPM()

bool CImage::loadFromXPM	(	const char **	xpm_array,
		bool	swap_rb = `true`
	)

Loads the image from an XPM array, as #include'd from a ".xpm" file.

Parameters

[in] swap_rb Swaps red/blue channels from loaded image. Seems to be always needed, so it's enabled by default.

See also: loadFromFile

Returns: false on any error

See also: loadFromFile

Returns: false on any error

Definition at line 2701 of file CImage.cpp.

References loadFromMemoryBuffer(), and MRPT_UNUSED_PARAM.

◆ loadTGA()

bool CImage::loadTGA	(	const std::string &	fileName,
		mrpt::utils::CImage &	out_RGB,
		mrpt::utils::CImage &	out_alpha
	)

static

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.

Returns: true on success

Definition at line 2727 of file CImage.cpp.

References CH_GRAY, CH_RGB, img, and resize().

◆ makeSureImageIsLoaded()

void CImage::makeSureImageIsLoaded ( ) const

protected

Checks if the image is of type "external storage", and if so and not loaded yet, load it.

Exceptions

mrpt::utils::CExceptionExternalImageNotFound

Definition at line 1935 of file CImage.cpp.

References getExternalStorageFileAbsolutePath(), loadFromFile(), m_externalFile, m_imgIsExternalStorage, THROW_EXCEPTION, and THROW_TYPED_EXCEPTION_FMT.

Referenced by changeSize(), correlate(), cross_correlation(), cross_correlation_FFT(), drawCircle(), extract_patch(), filterGaussian(), filterGaussianInPlace(), filterMedian(), filterMedianInPlace(), get_unsafe(), getAsFloat(), getAsMatrix(), getAsMatrixTiled(), getAsRGBMatrices(), getChannelCount(), getChannelsOrder(), getHeight(), getRowStride(), getSize(), getWidth(), grayscale(), grayscaleInPlace(), isColor(), isOriginTopLeft(), line(), normalize(), operator()(), rectifyImage(), rectifyImageInPlace(), rotateImage(), saveToFile(), saveToStreamAsJPEG(), scaleHalf(), scaleHalfSmooth(), scaleImage(), setChannelsOrder_BGR(), setChannelsOrder_RGB(), setOriginTopLeft(), setPixel(), and swapRB().

◆ normalize()

void CImage::normalize ( )

Optimize the brightness range of an image without using histogram Only for one channel images.

See also: equalizeHist

Definition at line 1560 of file CImage.cpp.

References ASSERT_, ASSERTMSG_, makeSureImageIsLoaded(), and val.

◆ operator delete() [1/3]

void mrpt::utils::CImage::operator delete	(	void *	ptr	)
throw	(
	)

inline

Definition at line 103 of file CImage.h.

◆ operator delete() [2/3]

void mrpt::utils::CImage::operator delete	(	void *	ptr,
		const std::nothrow_t &
	)
throw	(
	)

inline

Definition at line 103 of file CImage.h.

◆ operator delete() [3/3]

void mrpt::utils::CImage::operator delete	(	void *	memory,
		void *	ptr
	)
throw	(
	)

inline

Definition at line 103 of file CImage.h.

◆ operator delete[]()

void mrpt::utils::CImage::operator delete[]	(	void *	ptr	)
throw	(
	)

inline

Definition at line 103 of file CImage.h.

◆ operator new() [1/3]

static void* mrpt::utils::CImage::operator new	(	size_t	size,
		void *	ptr
	)

inlinestatic

Definition at line 103 of file CImage.h.

◆ operator new() [2/3]

void* mrpt::utils::CImage::operator new ( size_t size )

inline

Definition at line 103 of file CImage.h.

◆ operator new() [3/3]

void* mrpt::utils::CImage::operator new	(	size_t	size,
		const std::nothrow_t &
	)
throw	(
	)

inline

Definition at line 103 of file CImage.h.

◆ operator new[]()

void* mrpt::utils::CImage::operator new[] ( size_t size )

inline

Definition at line 103 of file CImage.h.

◆ operator()()

unsigned char * CImage::operator()	(	unsigned int	col,
		unsigned int	row,
		unsigned int	channel = `0`
	)		const

Returns a pointer to a given pixel information.

The coordinate origin is pixel(0,0)=top-left corner of the image.

Exceptions

std::exception On pixel coordinates out of bounds

Definition at line 451 of file CImage.cpp.

References ASSERT_, mrpt::format(), makeSureImageIsLoaded(), MRPT_END, MRPT_START, and THROW_EXCEPTION.

◆ operator=()

CImage & CImage::operator= ( const CImage & o )

Copy operator (if the image is externally stored, the writen image will be such as well).

See also: copyFastFrom

Definition at line 109 of file CImage.cpp.

References ASSERTMSG_, img, m_externalFile, m_imgIsExternalStorage, m_imgIsReadOnly, MRPT_END, MRPT_START, and releaseIpl().

◆ readFromStream()

void CImage::readFromStream	(	mrpt::utils::CStream &	in,
		int	version
	)

protectedvirtual

Introduces a pure virtual method responsible for loading from a CStream This can not be used directly be users, instead use "stream >> object;" for reading it from a stream or "stream >> object_ptr;" if the class is unknown apriori.

Parameters

in	The input binary stream where the object data must read from.
version	The version of the object stored in the stream: use this version number in your code to know how to read the incoming data.

Exceptions

std::exception On any error, see CStream::ReadBuffer

See also: CStream

Implements mrpt::utils::CSerializable.

Definition at line 633 of file CImage.cpp.

References ASSERT_, mrpt::utils::CMemoryStream::changeSize(), changeSize(), mrpt::compress::zip::decompress(), mrpt::utils::CMemoryStream::getRawBufferData(), img, loadFromStreamAsJPEG(), m_externalFile, m_imgIsExternalStorage, MRPT_THROW_UNKNOWN_SERIALIZATION_VERSION, releaseIpl(), mrpt::utils::CMemoryStream::Seek(), THROW_EXCEPTION, and version.

◆ rectangle()

void CCanvas::rectangle	(	int	x0,
		int	y0,
		int	x1,
		int	y1,
		const mrpt::utils::TColor	color,
		unsigned int	width = `1`
	)

inherited

Draws a rectangle (an empty rectangle, without filling)

Parameters

x0	The top-left x coordinate
y0	The top-left y coordinate
x1	The right-bottom x coordinate
y1	The right-bottom y coordinate
color	The color of the line
width	The desired width of the line.

See also: filledRectangle

Definition at line 176 of file CCanvas.cpp.

References mrpt::utils::CCanvas::line().

Referenced by mrpt::vision::addFeaturesToImage().

◆ rectifyImage()

void CImage::rectifyImage	(	CImage &	out_img,
		const mrpt::utils::TCamera &	cameraParams
	)		const

Rectify (un-distort) the image according to some camera parameters, and returns an output un-distorted image.

Parameters

out_img	The output rectified image
cameraParams	The input camera params (containing the intrinsic and distortion parameters of the camera)

See also: mrpt::vision::CUndistortMap

Definition at line 2084 of file CImage.cpp.

References ASSERT_, mrpt::utils::TCamera::dist, mrpt::utils::TCamera::intrinsicParams, loadFromIplImage(), and makeSureImageIsLoaded().

Referenced by mrpt::vision::checkerBoardCameraCalibration().

◆ rectifyImageInPlace() [1/2]

void CImage::rectifyImageInPlace ( const mrpt::utils::TCamera & cameraParams )

Rectify (un-distort) the image according to a certain camera matrix and vector of distortion coefficients, replacing "this" with the rectified image.

Parameters

cameraParams The input camera params (containing the intrinsic and distortion parameters of the camera)

See also: mrpt::vision::CUndistortMap

Definition at line 2050 of file CImage.cpp.

References ASSERT_, mrpt::utils::TCamera::dist, mrpt::utils::TCamera::intrinsicParams, makeSureImageIsLoaded(), and releaseIpl().

Referenced by mrpt::hwdrivers::CRovio::captureImageAsync().

◆ rectifyImageInPlace() [2/2]

void CImage::rectifyImageInPlace	(	void *	mapX,
		void *	mapY
	)

Rectify an image (undistorts and rectification) from a stereo pair according to a pair of precomputed rectification maps.

Parameters

mapX,mapY [IN] The pre-computed maps of the rectification (should be computed beforehand)

See also: mrpt::vision::CStereoRectifyMap, mrpt::vision::computeStereoRectificationMaps

Definition at line 2019 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), releaseIpl(), and THROW_EXCEPTION.

◆ releaseIpl()

void CImage::releaseIpl ( bool thisIsExternalImgUnload = false )

protected

Release the internal IPL image, if not NULL or read-only.

Definition at line 1914 of file CImage.cpp.

Referenced by changeSize(), colorImageInPlace(), copyFastFrom(), equalizeHistInPlace(), filterGaussianInPlace(), filterMedianInPlace(), loadFromFile(), loadFromIplImage(), operator=(), readFromStream(), rectifyImageInPlace(), rotateImage(), scaleImage(), setFromIplImage(), setFromIplImageReadOnly(), unload(), and ~CImage().

◆ resize()

void mrpt::utils::CImage::resize	(	unsigned int	width,
		unsigned int	height,
		TImageChannels	nChannels,
		bool	originTopLeft
	)

inline

Changes the size of the image, erasing previous contents (does NOT scale its current content, for that, see scaleImage).

nChannels: Can be 3 for RGB images or 1 for grayscale images.
originTopLeft: Is true if the top-left corner is (0,0). In other case, the reference is the bottom-left corner.
See also
scaleImage

Definition at line 209 of file CImage.h.

Referenced by mrpt::slam::CMetricMapBuilderRBPF::drawCurrentEstimationToImage(), extract_patch(), mrpt::hwdrivers::CSwissRanger3DCamera::getNextObservation(), loadFromMemoryBuffer(), loadTGA(), mrpt::vision::normalizeImage(), mrpt::gui::CDisplayWindow::plot(), and mrpt::vision::CStereoRectifyMap::rectify().

◆ rotateImage()

void CImage::rotateImage	(	double	angle_radians,
		unsigned int	center_x,
		unsigned int	center_y,
		double	scale = `1.0`
	)

Rotates the image by the given angle around the given center point, with an optional scale factor.

See also: resize, scaleImage

Definition at line 2281 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and releaseIpl().

◆ saveToFile()

bool CImage::saveToFile	(	const std::string &	fileName,
		int	jpeg_quality = `95`
	)		const

Save the image to a file, whose format is determined from the extension (internally uses OpenCV).

Parameters

fileName The file to write to.

The supported formats are:

Windows bitmaps - BMP, DIB;
JPEG files - JPEG, JPG, JPE;
Portable Network Graphics - PNG;
Portable image format - PBM, PGM, PPM;
Sun rasters - SR, RAS;
TIFF files - TIFF, TIF.

Parameters

jpeg_quality Only for JPEG files, the quality of the compression in the range [0-100]. Larger is better quality but slower.

Note: jpeg_quality is only effective if MRPT is compiled against OpenCV 1.1.0 or newer.

Returns: False on any error

See also: loadFromFile

Definition at line 299 of file CImage.cpp.

References ASSERT_, img, makeSureImageIsLoaded(), MRPT_END, MRPT_START, and THROW_EXCEPTION.

Referenced by mrpt::slam::CGridMapAligner::AlignPDF_correlation(), mrpt::slam::CGridMapAligner::AlignPDF_robustMatch(), mrpt::vision::CFeatureExtraction::extractFeaturesSIFT(), mrpt::hmtslam::CHMTSLAM::generateLogFiles(), mrpt::hwdrivers::CSwissRanger3DCamera::getNextObservation(), mrpt::vision::CFeatureExtraction::internal_computeSiftDescriptors(), mrpt::vision::CFeatureExtraction::internal_computeSpinImageDescriptors(), mrpt::maps::CMultiMetricMapPDF::prediction_and_update_pfOptimalProposal(), and mrpt::maps::CRandomFieldGridMap2D::saveMetricMapRepresentationToFile().

◆ saveToStreamAsJPEG()

void CImage::saveToStreamAsJPEG	(	mrpt::utils::CStream &	out,
		const int	jpeg_quality = `95`
	)		const

Save image to binary stream as a JPEG (.jpg) compressed format.

Exceptions

std::exception On number of rows or cols equal to zero or other errors.

See also: saveToJPEG

Definition at line 368 of file CImage_JPEG_streams.cpp.

References ASSERT_, jpeg_compress_struct::image_height, jpeg_compress_struct::image_width, img, jpeg_compress_struct::in_color_space, jpeg_compress_struct::input_components, JCS_GRAYSCALE, JCS_RGB, jpeg_create_compress, jpeg_destroy_compress(), jpeg_finish_compress(), jpeg_set_defaults(), jpeg_set_quality(), jpeg_start_compress(), jpeg_std_error(), jpeg_stdio_dest(), jpeg_write_scanlines(), makeSureImageIsLoaded(), MRPT_END, MRPT_START, THROW_EXCEPTION, and TRUE.

Referenced by writeToStream().

◆ scaleDouble() [1/2]

CImage mrpt::utils::CImage::scaleDouble ( ) const

inline

Returns a new image scaled up to double its original size.

Exceptions

std::exception On odd size

See also: scaleHalf, scaleImage

Definition at line 312 of file CImage.h.

References mrpt::utils::UNINITIALIZED_IMAGE.

◆ scaleDouble() [2/2]

void CImage::scaleDouble ( CImage & out_image ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1170 of file CImage.cpp.

References getSize(), scaleImage(), mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

◆ scaleHalf() [1/2]

CImage mrpt::utils::CImage::scaleHalf ( ) const

inline

Returns a new image scaled down to half its original size.

Exceptions

std::exception On odd size

See also: scaleDouble, scaleImage, scaleHalfSmooth

Definition at line 282 of file CImage.h.

References mrpt::utils::UNINITIALIZED_IMAGE.

Referenced by mrpt::opengl::CTexturedObject::loadTextureInOpenGL().

◆ scaleHalf() [2/2]

void CImage::scaleHalf ( CImage & out_image ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1068 of file CImage.cpp.

References ASSERT_, image_SSE2_scale_half_1c8u(), image_SSSE3_scale_half_3c8u(), mrpt::utils::IMG_INTERP_NN, mrpt::system::is_aligned< 16 >(), makeSureImageIsLoaded(), mrpt::system::os::memcpy(), and setFromIplImage().

◆ scaleHalfSmooth() [1/2]

CImage mrpt::utils::CImage::scaleHalfSmooth ( ) const

inline

Returns a new image scaled down to half its original size (averaging between every two rows)

Exceptions

std::exception On odd size

See also: scaleDouble, scaleImage, scaleHalf

Definition at line 297 of file CImage.h.

References mrpt::utils::UNINITIALIZED_IMAGE.

◆ scaleHalfSmooth() [2/2]

void CImage::scaleHalfSmooth ( CImage & out_image ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1126 of file CImage.cpp.

References ASSERT_, image_SSE2_scale_half_smooth_1c8u(), mrpt::utils::IMG_INTERP_LINEAR, mrpt::system::is_aligned< 16 >(), makeSureImageIsLoaded(), mrpt::system::os::memcpy(), and setFromIplImage().

◆ scaleImage() [1/2]

void CImage::scaleImage	(	unsigned int	width,
		unsigned int	height,
		TInterpolationMethod	interp = `IMG_INTERP_CUBIC`
	)

Scales this image to a new size, interpolating as needed.

See also: resize, rotateImage

Definition at line 2224 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and releaseIpl().

Referenced by scaleDouble().

◆ scaleImage() [2/2]

void CImage::scaleImage	(	CImage &	out_img,
		unsigned int	width,
		unsigned int	height,
		TInterpolationMethod	interp = `IMG_INTERP_CUBIC`
	)		const

Scales this image to a new size, interpolating as needed, saving the new image in a different output object.

See also: resize, rotateImage

Definition at line 2251 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and setFromIplImage().

◆ selectTextFont()

void CCanvas::selectTextFont ( const std::string & fontName )

virtualinherited

Select the current font used when drawing text.

Parameters

fontName The name of the font

Valid font names:

5x7
6x13
6x13B
6x13O
9x15 (Default at start-up)
9x15B
10x20
18x18ja (Asian characters for UTF-8 strings - Only available if MRPT is built with MRPT_HAS_ASIAN_FONTS = true)

See also: textOut, The example in this page.

Definition at line 249 of file CCanvas.cpp.

References init_fonts_list(), list_registered_fonts, mrpt::utils::CCanvas::m_selectedFont, and mrpt::utils::CCanvas::m_selectedFontBitmaps.

Referenced by drawChessboardCorners(), and mrpt::utils::CCanvas::textOut().

◆ setChannelsOrder_BGR()

void CImage::setChannelsOrder_BGR ( )

Marks the channel ordering in a color image as "BGR" (this doesn't actually modify the image data, just the format description)

See also: getChannelsOrder, swapRB

Definition at line 2686 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), mrpt::system::os::strcpy(), and THROW_EXCEPTION.

◆ setChannelsOrder_RGB()

void CImage::setChannelsOrder_RGB ( )

Marks the channel ordering in a color image as "RGB" (this doesn't actually modify the image data, just the format description)

Marks the channel ordering in a color image (this doesn't actually modify the image data, just the format description)

See also: getChannelsOrder, swapRB

Definition at line 2675 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), mrpt::system::os::strcpy(), and THROW_EXCEPTION.

◆ setExternalStorage()

void CImage::setExternalStorage ( const std::string & fileName )

By using this method the image is marked as referenced to an external file, which will be loaded only under demand.

A CImage with external storage does not consume memory until some method trying to access the image is invoked (e.g. getWidth(), isColor(),...) At any moment, the image can be unloaded from memory again by invoking unload. An image becomes of type "external storage" only through calling setExternalStorage. This property remains after serializing the object. File names can be absolute, or relative to the CImage::IMAGES_PATH_BASE directory. Filenames staring with "X:\" or "/" are considered absolute paths. By calling this method the current contents of the image are NOT saved to that file, because this method can be also called 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) the proper order of commands should be:

img.saveToFile( fileName );

img.setExternalStorage( fileName );

Note: Modifications to the memory copy of the image are not automatically saved to disk.

See also: unload, isExternallyStored

Definition at line 1895 of file CImage.cpp.

Referenced by mrpt::hwdrivers::CSwissRanger3DCamera::getNextObservation().

◆ setFromImageReadOnly()

void mrpt::utils::CImage::setFromImageReadOnly ( const CImage & other_img )

inline

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).

When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor.

See also: setFromIplImageReadOnly

Definition at line 739 of file CImage.h.

Referenced by mrpt::detectors::CObjectDetection::detectObjects(), and mrpt::vision::openCV_cross_correlation().

◆ setFromIplImage()

void CImage::setFromIplImage ( void * iplImage )

Reads the image from a OpenCV IplImage object (WITHOUT making a copy).

This object will own the memory of the passed object and free the IplImage upon destruction, so the caller CAN'T free the original object. This method provides a fast method to grab images from a camera without making a copy of every frame.

Definition at line 365 of file CImage.cpp.

References m_imgIsExternalStorage, m_imgIsReadOnly, MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by colorImage(), cross_correlation(), mrpt::hwdrivers::CImageGrabber_FlyCapture2::getObservation(), grayscale(), grayscaleInPlace(), mrpt::vision::CStereoRectifyMap::rectify(), scaleHalf(), scaleHalfSmooth(), scaleImage(), and mrpt::vision::CUndistortMap::undistort().

◆ setFromIplImageReadOnly()

void CImage::setFromIplImageReadOnly ( void * iplImage )

Reads the image from a OpenCV IplImage object (WITHOUT making a copy) and from now on the image cannot be modified, just read.

When assigning an IPLImage to this object with this method, the IPLImage will NOT be released/freed at this object destructor. This method provides a fast method to grab images from a camera without making a copy of every frame.

See also: setFromImageReadOnly

Definition at line 343 of file CImage.cpp.

References ASSERT_, ASSERTMSG_, m_imgIsExternalStorage, m_imgIsReadOnly, MRPT_END, MRPT_START, releaseIpl(), and THROW_EXCEPTION.

Referenced by mrpt::hwdrivers::CImageGrabber_OpenCV::getObservation(), joinImagesHorz(), and mrpt::vision::openCV_cross_correlation().

◆ setFromMatrix()

template<typename Derived >

void mrpt::utils::CImage::setFromMatrix	(	const Eigen::MatrixBase< Derived > &	m,
		bool	matrix_is_normalized = `true`
	)

inline

Set the image from a matrix, interpreted as grayscale intensity values, in the range [0,1] (normalized=true) or [0,255] (normalized=false) Matrix indexes are assumed to be in this order: M(row,column)

See also: getAsMatrix

Definition at line 746 of file CImage.h.

References get_unsafe(), MRPT_END, and MRPT_START.

Referenced by mrpt::maps::CRandomFieldGridMap2D::getAsBitmapFile(), and mrpt::vision::normalizeImage().

◆ setFromRGBMatrices()

template<typename Derived >

void mrpt::utils::CImage::setFromRGBMatrices	(	const Eigen::MatrixBase< Derived > &	m_r,
		const Eigen::MatrixBase< Derived > &	m_g,
		const Eigen::MatrixBase< Derived > &	m_b,
		bool	matrix_is_normalized = `true`
	)

inline

Set the image from RGB matrices, given the pixels in the range [0,1] (normalized=true) or [0,255] (normalized=false) Matrix indexes are assumed to be in this order: M(row,column)

See also: getAsRGBMatrices

Definition at line 774 of file CImage.h.

References ASSERT_, get_unsafe(), MRPT_END, and MRPT_START.

◆ setOriginTopLeft()

void CImage::setOriginTopLeft ( bool val )

Changes the property of the image stating if the top-left corner (vs.

bottom-left) is the coordinate reference

Definition at line 1236 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), and val.

◆ setPixel()

void CImage::setPixel	(	int	x,
		int	y,
		size_t	color
	)

virtual

Changes the value of the pixel (x,y).

Pixel coordinates starts at the left-top corner of the image, and start in (0,0). The meaning of the parameter "color" depends on the implementation: it will usually be a 24bit RGB value (0x00RRGGBB), but it can also be just a 8bit gray level. This method must support (x,y) values OUT of the actual image size without neither raising exceptions, nor leading to memory access errors.

Implements mrpt::utils::CCanvas.

Definition at line 1248 of file CImage.cpp.

References ASSERT_, makeSureImageIsLoaded(), MRPT_END, MRPT_START, and THROW_EXCEPTION.

◆ swap()

void CImage::swap ( CImage & o )

Very efficient swap of two images (just swap the internal pointers)

Definition at line 135 of file CImage.cpp.

References img, m_externalFile, m_imgIsExternalStorage, and m_imgIsReadOnly.

Referenced by mrpt::vision::CFeatureExtraction::extractFeaturesSIFT(), mrpt::obs::CObservationStereoImages::swap(), and mrpt::obs::CObservation3DRangeScan::swap().

◆ swapRB()

void CImage::swapRB ( )

Swaps red and blue channels.

Definition at line 2006 of file CImage.cpp.

References ASSERT_, and makeSureImageIsLoaded().

◆ textOut()

void CCanvas::textOut	(	int	x0,
		int	y0,
		const std::string &	str,
		const mrpt::utils::TColor	color
	)

virtualinherited

Renders 2D text using bitmap fonts.

Parameters

x0	The x coordinates
y0	The y coordinates
str	The string to put. If using UNICODE characters, use UTF-8 encoding.
color	The text color

See also: selectTextFont

Reimplemented in mrpt::utils::CEnhancedMetaFile.

Definition at line 397 of file CCanvas.cpp.

References mrpt::system::decodeUTF8(), isOriginTopLeft(), mrpt::utils::CCanvas::m_selectedFontBitmaps, MRPT_END, MRPT_START, mrpt::utils::CCanvas::selectTextFont(), and mrpt::utils::CCanvas::setPixel().

Referenced by drawChessboardCorners(), and mrpt::gui::CDisplayWindow::plot().

◆ triangle()

void CCanvas::triangle	(	int	x0,
		int	y0,
		int	size,
		const mrpt::utils::TColor	color,
		bool	inferior = `true`,
		unsigned int	width = `1`
	)

inherited

Draws a triangle.

Parameters

x0	The triangle center x coordinate
y0	The triangle center y coordinate
size	The size of the triangle
color	The color of the line
inferior	The position of the triangle
width	The desired width of the line.

See also: triangle

Definition at line 200 of file CCanvas.cpp.

References mrpt::utils::CCanvas::line(), and mrpt::utils::round().

◆ unload()

void CImage::unload ( ) const

For external storage image objects only, this method unloads the image from memory (or does nothing if already unloaded).

It does not need to be called explicitly, unless the user wants to save memory for images that will not be used often. If called for an image without the flag "external storage", it is simply ignored.

See also: setExternalStorage, forceLoad

Definition at line 1905 of file CImage.cpp.

References m_imgIsExternalStorage, and releaseIpl().

Referenced by mrpt::obs::CObservation3DRangeScan::unload().

◆ update_patch()

void CImage::update_patch	(	const CImage &	patch,
		const unsigned int	col,
		const unsigned int	row
	)

Update a part of this image with the "patch" given as argument.

The "patch" will be "pasted" at the (col,row) coordinates of this image.

Exceptions

std::exception if patch pasted on the pixel (_row, _column) jut out of the image.

See also: extract_patch

Definition at line 1342 of file CImage.cpp.

References ASSERT_, getHeight(), getWidth(), img, mrpt::system::os::memcpy(), and THROW_EXCEPTION.

◆ writeToMatlab()

virtual mxArray* mrpt::utils::CSerializable::writeToMatlab ( ) const

inlinevirtualinherited

Introduces a pure virtual method responsible for writing to a mxArray Matlab object, typically a MATLAB struct whose contents are documented in each derived class.

Returns: A new mxArray (caller is responsible of memory freeing) or NULL is class does not support conversion to MATLAB.

Definition at line 79 of file CSerializable.h.

◆ writeToStream()

void CImage::writeToStream	(	mrpt::utils::CStream &	out,
		int *	getVersion
	)		const

protectedvirtual

Introduces a pure virtual method responsible for writing to a CStream.

This can not be used directly be users, instead use "stream << object;" for writing it to a stream.

Parameters

out	The output binary stream where object must be dumped.
getVersion	If NULL, the object must be dumped. If not, only the version of the object dump must be returned in this pointer. This enables the versioning of objects dumping and backward compatibility with previously stored data.

Exceptions

std::exception On any error, see CStream::WriteBuffer

See also: CStream

Implements mrpt::utils::CSerializable.

Definition at line 510 of file CImage.cpp.

References ASSERT_, mrpt::compress::zip::compress(), DISABLE_JPEG_COMPRESSION, DISABLE_ZIP_COMPRESSION, mrpt::utils::CMemoryStream::getRawBufferData(), mrpt::utils::CMemoryStream::getTotalBytesCount(), img, isColor(), m_externalFile, m_imgIsExternalStorage, saveToStreamAsJPEG(), SERIALIZATION_JPEG_QUALITY, version, and mrpt::utils::CStream::WriteBuffer().

Member Data Documentation

◆ _init_CImage

mrpt::utils::CLASSINIT mrpt::utils::CImage::_init_CImage

staticprotected

Definition at line 103 of file CImage.h.

◆ classCImage

mrpt::utils::TRuntimeClassId mrpt::utils::CImage::classCImage

static

Definition at line 103 of file CImage.h.

◆ classCObject

const mrpt::utils::TRuntimeClassId mrpt::utils::CObject::classCObject

staticinherited

Definition at line 128 of file CObject.h.

◆ classCSerializable

const mrpt::utils::TRuntimeClassId mrpt::utils::CSerializable::classCSerializable

staticinherited

Definition at line 42 of file CSerializable.h.

◆ classinfo

const mrpt::utils::TRuntimeClassId* mrpt::utils::CImage::classinfo

static

Definition at line 103 of file CImage.h.

◆ DISABLE_JPEG_COMPRESSION

bool CImage::DISABLE_JPEG_COMPRESSION = false

static

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. (Default = false)

Definition at line 192 of file CImage.h.

Referenced by writeToStream().

◆ DISABLE_ZIP_COMPRESSION

bool CImage::DISABLE_ZIP_COMPRESSION = false

static

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.

(Default = false)

Definition at line 188 of file CImage.h.

Referenced by writeToStream().

◆ IMAGES_PATH_BASE

std::string CImage::IMAGES_PATH_BASE

static

By default, ".".

See also: setExternalStorage

Definition at line 668 of file CImage.h.

Referenced by getExternalStorageFileAbsolutePath().

◆ img

void* mrpt::utils::CImage::img

protected

The internal IplImage pointer to the actual image content.

Definition at line 912 of file CImage.h.

Referenced by changeSize(), copyFastFrom(), extract_patch(), loadFromMemoryBuffer(), loadFromStreamAsJPEG(), loadTGA(), operator=(), readFromStream(), saveToFile(), saveToStreamAsJPEG(), swap(), update_patch(), and writeToStream().

◆ m_externalFile

std::string mrpt::utils::CImage::m_externalFile

mutableprotected

The file name of a external storage image.

Definition at line 921 of file CImage.h.

Referenced by copyFastFrom(), getExternalStorageFileAbsolutePath(), makeSureImageIsLoaded(), operator=(), readFromStream(), swap(), and writeToStream().

◆ m_imgIsExternalStorage

bool mrpt::utils::CImage::m_imgIsExternalStorage

mutableprotected

Set to true only when using setExternalStorage.

See also: setExternalStorage

Definition at line 920 of file CImage.h.

Referenced by copyFastFrom(), loadFromMemoryBuffer(), makeSureImageIsLoaded(), operator=(), readFromStream(), setFromIplImage(), setFromIplImageReadOnly(), swap(), unload(), and writeToStream().

◆ m_imgIsReadOnly

bool mrpt::utils::CImage::m_imgIsReadOnly

protected

Set to true only when using setFromIplImageReadOnly.

See also: setFromIplImageReadOnly

Definition at line 916 of file CImage.h.

Referenced by copyFastFrom(), loadFromMemoryBuffer(), operator=(), setFromIplImage(), setFromIplImageReadOnly(), and swap().

◆ m_selectedFont

std::string mrpt::utils::CCanvas::m_selectedFont

protectedinherited

The selected font name.

Definition at line 43 of file CCanvas.h.

Referenced by mrpt::utils::CCanvas::selectTextFont().

◆ m_selectedFontBitmaps

const uint32_t* mrpt::utils::CCanvas::m_selectedFontBitmaps

protectedinherited

Direct access to character bitmaps.

Definition at line 45 of file CCanvas.h.

Referenced by mrpt::utils::CCanvas::selectTextFont(), and mrpt::utils::CCanvas::textOut().

◆ SERIALIZATION_JPEG_QUALITY

int CImage::SERIALIZATION_JPEG_QUALITY = 95

static

Unless DISABLE_JPEG_COMPRESSION=true, this sets the JPEG quality (range 1-100) of serialized RGB images.

(Default = 95)

Definition at line 196 of file CImage.h.

Referenced by writeToStream().

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

RTTI stuff

External storage-mode methods

Set, load & save methods

Member Typedef Documentation

◆ ConstPtr

◆ Ptr

Member Enumeration Documentation

◆ TPenStyle

Constructor & Destructor Documentation

◆ CImage() [1/7]

◆ CImage() [2/7]

◆ CImage() [3/7]

◆ CImage() [4/7]

◆ CImage() [5/7]

◆ CImage() [6/7]

◆ CImage() [7/7]

◆ ~CImage()

Member Function Documentation

◆ _GetBaseClass()

◆ changeSize()

◆ clone()

◆ colorImage()

◆ colorImageInPlace()

◆ copyFastFrom()

◆ copyFromForceLoad()

◆ correlate()

◆ Create()

◆ CreateObject()

◆ cross()

◆ cross_correlation()

◆ cross_correlation_FFT()

◆ drawChessboardCorners()

◆ drawCircle()

◆ drawFeatures()

◆ drawFeaturesSimple()

◆ drawImage() [1/2]

◆ drawImage() [2/2]

◆ duplicate()

◆ duplicateGetSmartPtr()

◆ ellipseGaussian()

◆ equalizeHist()

◆ equalizeHistInPlace()

◆ extract_patch()

◆ filledRectangle()

◆ filterGaussian()

◆ filterGaussianInPlace()

◆ filterMedian()

◆ filterMedianInPlace()

◆ flipHorizontal()

◆ flipVertical()

◆ forceLoad()

◆ get_unsafe()

◆ getAs() [1/2]

◆ getAs() [2/2]

◆ getAsFloat() [1/2]

◆ getAsFloat() [2/2]

◆ getAsMatrix()

◆ getAsMatrixTiled()

◆ getAsRGBMatrices()

◆ getChannelCount()

◆ getChannelsOrder()

◆ getExternalStorageFile()

◆ getExternalStorageFileAbsolutePath() [1/2]

◆ getExternalStorageFileAbsolutePath() [2/2]

◆ getHeight()

◆ getMaxAsFloat()

◆ getRowStride()

◆ GetRuntimeClass()

◆ getSize() [1/2]

◆ getSize() [2/2]

◆ getWidth()

◆ grayscale() [1/2]

◆ grayscale() [2/2]