Class CImage

Defined in File CImage.h

Nested Relationships

Nested Types

Struct CImage::Impl

Inheritance Relationships

Base Types

public mrpt::serialization::CSerializable
public mrpt::img::CCanvas (Class CCanvas)

Class Documentation

class CImage : public mrpt::serialization::CSerializable, public mrpt::img::CCanvas 

A class for storing images as grayscale, RGB, or RGBA bitmaps.

Supported I/O are:

Saving/loading from files of different formats (JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC) using the methods CImage::loadFromFile() and CImage::saveToFile(). This uses the stb library.
Importing from an XPM array (.xpm file format) using CImage::loadFromXPM()
Binary dump using the CSerializable interface (<< and >> operators), just as most objects in MRPT. This format is not compatible with any standardized image format but it is fast.

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:

Since MRPT 3.0.0, the internal format for images is a raw memory buffer managed by the STB library. Previous versions used OpenCV’s cv::Mat, but this was removed to reduce dependencies.
By default, all images use unsigned 8-bit storage format for pixels (on each channel), but 16-bit depth is also supported via PixelDepth::D16U.
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. See CImage::forceLoad() and CImage::unload().

Operator = and copy ctor make shallow copies. For deep copies, see CImage::makeDeepCopy() or CImage(const CImage&, copy_type_t), e.g:

CImage a(20, 10, CH_GRAY);
// Shallow copy ctor:
CImage b(a, mrpt::img::SHALLOW_COPY);
CImage c(a, mrpt::img::DEEP_COPY);

If you are interested in a smart pointer to an image, use:

CImage::Ptr myImg = CImage::Create(); // optional ctor arguments
// or:
CImage::Ptr myImg = std::make_shared<CImage>(...);

See also

mrpt::vision, mrpt::serialization::CSerializable, mrpt::img::CCanvas

Data members

std::shared_ptr<Impl> m_state

Constructors & destructor

CImage(): Default constructor: initialize to empty image. It’s an error trying to access the image in such a state (except reading the image width/height, which are both zero). Either call resize(), assign from another image, load from disk, deserialize from an archive, etc. to properly initialize the image.

CImage(int32_t width, int32_t height, TImageChannels nChannels = CH_RGB)

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)

inline CImage(const CImage &other_img, [[maybe_unused]] ctor_CImage_ref_or_gray _)

Fast constructor of a grayscale version of another image, making a shallow copy from the original image if it already was grayscale, or otherwise creating a new grayscale image and converting the original image into it. 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.
}

CImage(const CImage &img, copy_type_t copy_type): Constructor from another CImage, making or not a deep copy of the data.

Manipulate the image contents or size, various computer-vision methods

void clear(): Resets the image to the state after a default ctor. Accessing the image after will throw an exception, unless it is formerly initialized somehow: loading an image from disk, calling resize(), etc.

void resize(int32_t width, int32_t height, TImageChannels nChannels, PixelDepth depth = PixelDepth::D8U)

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

See also

scaleImage

PixelDepth getPixelDepth() const

void scaleImage(CImage &out_img, int32_t width, int32_t 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, or operating in-place if out_img==this.

See also

resize, rotateImage

void rotateImage(CImage &out_img, double ang, const TPixelCoord &center, double scale = 1.0) const

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

See also

resize, scaleImage

Note

This method is marked as TODO - not yet implemented with STB.

virtual void setPixel(const TPixelCoord &pt, const mrpt::img::TColor &color) override

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. If writing into an grayscale image, only the BLUE channel (least significant byte) will be used from the incoming RGBA color.

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

See also

at, ptr

void setPixelGray(const TPixelCoord &pt, const uint8_t &grayLevel)

virtual void drawImage(const TPixelCoord &pt, const mrpt::img::CImage &img) override

Draws an image as a bitmap at a given position.

Parameters:

pt – The top-left corner 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 appropriate manner.

virtual void filledRectangle(const TPixelCoord &pt0, const TPixelCoord &pt1, mrpt::img::TColor color) override

Draws a filled rectangle.

See also

rectangle

Parameters:

pt0 – The top-left point
pt1 – The right-bottom point
color – The color of the rectangle fill This method may be redefined in some classes implementing this interface in a more appropriate manner.

inline CImage scaleHalf(TInterpolationMethod interp) const

Returns a new image scaled down to half its original size

See also

scaleDouble, scaleImage

Throws:: std::exception – On odd size

bool scaleHalf(CImage &out_image, TInterpolationMethod interp) const

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

Returns:: true if an optimized SSE2/SSE3 version could be used.

inline CImage scaleDouble(TInterpolationMethod interp) const

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

See also

scaleHalf, scaleImage

Throws:: std::exception – On odd size

void scaleDouble(CImage &out_image, TInterpolationMethod interp) const: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void extract_patch(CImage &patch, const TPixelCoord &top_left_corner, const TImageSize &patch_size) const: Extract a patch from this image, saving it into “patch” (its previous contents will be overwritten). The patch to extract starts at (col,row) and has the given dimensions.

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

Note

Marked as TODO - not yet implemented with STB.

void flipVertical()

Flips the image vertically.

See also

swapRB(), flipHorizontal()

void flipHorizontal()

Flips the image horizontally

See also

swapRB(), flipVertical()

void swapRB(): Swaps red and blue channels.

void undistort(CImage &out_img, const mrpt::img::TCamera &cameraParams) const: Undistort the image according to some camera parameters.

Note

Marked as TODO - not yet implemented with STB.

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

Note

Marked as TODO - not yet implemented with STB.

void filterGaussian(CImage &out_img, int W = 3, int H = 3, double sigma = 1.0) const: Filter the image with a Gaussian filter with a window size WxH.

Note

Marked as TODO - not yet implemented with STB.

bool drawChessboardCorners(const 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.

Note

Marked as TODO - not yet implemented with STB.

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

float KLT_response(const TPixelCoord &pt, int32_t half_window_size) const: Compute the KLT response at a given pixel (x,y) - Only for grayscale images.

Copy, move & swap operations

inline CImage makeShallowCopy() const: Returns a shallow copy of the original image

inline CImage makeDeepCopy() const

Returns a deep copy of this image. If the image is externally-stored, there is no difference with a shallow copy.

See also

makeShallowCopy()

void copyFromForceLoad(const CImage &o)

Copies from another image (shallow copy), and, if it is externally stored, the image file will be actually loaded into memory in “this” object.

See also

operator =

Throws:: CExceptionExternalImageNotFound – If the external image couldn’t be loaded.

void swap(CImage &o) noexcept: Efficiently swap of two images

Access to image contents

template<typename T> inline const T &at(int32_t col, int32_t row, int8_t channel = 0) const

Access to pixels without checking boundaries, and doing a reinterpret_cast<> of the data as the given type.

See also

The CImage::operator() which does check for coordinate limits.

template<typename T> inline T &at(int32_t col, int32_t row, int8_t channel = 0)

template<typename T> inline const T *ptr(int32_t col, int32_t row, int8_t channel = 0) const

Returns a pointer to a given pixel, without checking for boundaries.

See also

The CImage::operator() which does check for coordinate limits.

template<typename T> inline T *ptr(int32_t col, int32_t row, int8_t channel = 0)

template<typename T> inline const T *ptrLine(int32_t row) const

Returns a pointer to the first pixel of the given line.

See also

ptr, at

template<typename T> inline T *ptrLine(int32_t row)

float getAsFloat(const TPixelCoord &pt, int8_t 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.

Throws:: std::exception – On pixel coordinates out of bounds

float getAsFloat(const TPixelCoord &pt) 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.

Throws:: std::exception – On pixel coordinates out of bounds

Query image properties

virtual int32_t getWidth() const override

Returns the width of the image in pixels

See also

getSize

virtual int32_t getHeight() const override

Returns the height of the image in pixels

See also

getSize

TImageSize getSize() const

Return the size of the image

See also

getWidth, getHeight

size_t 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 ptrLine(0)

See also

getSize, as, ptr, ptrLine

std::string getChannelsOrder() const: As of mrpt 3.0.0, this returns either “GRAY”, “RGB”, or “RGBA”.

TImageChannels channels() const: Returns 1 (grayscale), 3 (RGB) or 4 (RGBA)

bool isColor() const: Returns true if the image is RGB or RGBA, false if it is grayscale

bool isEmpty() const: Returns true if the object is in the state after default constructor. Returns false for delay-loaded images, disregarding whether the image is actually on disk or memory.

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, bool normalize_01 = true) const

Returns the image as a matrix with pixel grayscale values in the range [0,1]. Matrix indexes in this order: M(row,column)

See also

setFromMatrix

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.
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)
normalize_01 – Normalize the image values such that they fall in the range [0,1] (default: true). If set to false, the matrix will hold numbers in the range [0,255].

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

std::tuple<mrpt::math::CMatrixFloat, mrpt::math::CMatrixFloat, mrpt::math::CMatrixFloat> getAsRGBMatricesFloat(int x_min = 0, int y_min = 0, int x_max = -1, int y_max = -1) const

Returns three image as [R,G,B] matrices with pixel values in the range [0,1]. Matrix indexes in this order: M(row,column)

See also

setFromRGBMatrices

Parameters:

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)

std::tuple<mrpt::math::CMatrix_u8, mrpt::math::CMatrix_u8, mrpt::math::CMatrix_u8> getAsRGBMatricesBytes(int x_min = 0, int y_min = 0, int x_max = -1, int y_max = -1) const

External storage-mode methods

void setExternalStorage(const std::string &fileName) noexcept

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::getImagesPathBase() 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 );

See also

unload, isExternallyStored

Note

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

inline bool isExternallyStored() const noexcept: See setExternalStorage().

inline std::string getExternalStorageFile() const noexcept

Only if isExternallyStored() returns true.

See also

getExternalStorageFileAbsolutePath

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

Only if isExternallyStored() returns true.

See also

getExternalStorageFile

inline std::string getExternalStorageFileAbsolutePath() const

Only if isExternallyStored() returns true.

See also

getExternalStorageFile

inline void forceLoad() const

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.

See also

unload

void unload() const noexcept

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

void cross_correlation_FFT(const CImage &in_img, mrpt::math::CMatrixFloat &out_corr, std::optional<int32_t> u_search_ini = std::nullopt, std::optional<int32_t> v_search_ini = std::nullopt, std::optional<int32_t> u_search_size = std::nullopt, std::optional<int32_t> v_search_size = std::nullopt, std::optional<float> biasThisImg = std::nullopt, std::optional<float> biasInImg = std::nullopt) 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 subtracted to the pixels of “this” image before performing correlation.
biasInImg – This optional parameter is a fixed “bias” value to be subtracted 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)

static const std::string &getImagesPathBase()

By default, “.”

See also

setExternalStorage

Note

Since MRPT 2.3.3 this is a synonym with mrpt::io::getLazyLoadPathBase()

static void setImagesPathBase(const std::string &path): Note

Since MRPT 2.3.3 this is a synonym with mrpt::io::setLazyLoadPathBase()

Set, load & save methods

void loadFromMemoryBuffer(int32_t width, int32_t height, TImageChannels color_channels, uint8_t *rawpixels, bool swapRedBlue = false): Reads the image from raw pixels buffer in memory.

template<typename MAT> inline void setFromMatrix(const MAT &m, bool matrix_is_normalized = true, bool flip_vertically = false)

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

template<typename MAT> inline void setFromRGBMatrices(const MAT &r, const MAT &g, const MAT &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)

See also

getAsRGBMatrices

void loadFromStreamAsJPEG(mrpt::io::CStream &in)

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

Throws:: std::exception – On pixel coordinates out of bounds

bool loadFromFile(const std::string &fileName, TImageChannels loadChannels = CH_AS_IS)

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

MRPT also provides the special loader

loadFromXPM().

Parameters:: fileName – The file to read from.
Returns:: False on any error

bool loadFromXPM(const char *const *xpm_array, bool swap_rb = true)

Loads the image from an XPM array, as included from a “.xpm” file.

See also

loadFromFile

Parameters:: swap_rb – [in] Swaps red/blue channels from loaded image. Seems to be always needed, so it’s enabled by default.
Returns:: false on any error

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 the stb library).

The supported formats are:

*.png: Portable Network Graphics
*.bmp: Windows bitmaps
*.tga: TGA files
*.jpeg|*.jpg: JPEG files

See also

loadFromFile

Parameters:

fileName – The file to write to.
jpeg_quality – Only for JPEG files, the quality of the compression in the range [0-100]. Larger is better quality but slower.

Returns:

False on any error

void saveToStreamAsJPEG(mrpt::io::CStream &out, int jpeg_quality = 95) const

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

See also

saveToJPEG

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

static mrpt::img::CImage LoadFromFile(const std::string &fileName, TImageChannels loadChannels = CH_AS_IS)

Static method to construct an CImage object from a file. See CImage::loadFromFile() for meaning of parameters.

Note

New in MRPT 2.4.2

Throws:: std::exception – On load error.

Color/Grayscale conversion

CImage grayscale() const: Returns a grayscale version of the image, or a shallow copy of itself if it is already a grayscale image.

bool grayscale(CImage &ret) const

CImage colorImage() const

Returns a color (RGB) version of the grayscale image, or a shallow copy of itself if it is already a color image.

See also

grayscale

void colorImage(CImage &ret) const

Protected Functions

void makeSureImageIsLoaded(bool allowNonInitialized = false) const

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

Throws:: CExceptionExternalImageNotFound –

uint8_t *internal_get(int32_t col, int32_t row, int8_t channel = 0)

const uint8_t *internal_get(int32_t col, int32_t row, int8_t channel = 0) const

struct Impl

PIMPL actual struct holding the image data

Public Functions

Impl() = default

~Impl()

Impl(const Impl&) = delete

Impl &operator=(const Impl&) = delete

Impl(Impl&&) noexcept = default

Impl &operator=(Impl&&) noexcept = default

inline bool empty() const

void clear(): Clears the image data, external image data, etc. To clear just the image data, use clear_image_data()

void clear_image_data()

inline void deep_copy(const Impl &o)

inline std::size_t image_buffer_size_bytes() const: Returns the image buffer size according to width, height, channels, and pixel depth. This function just computes the size of the image buffer in bytes from the properties filled in in the structure.

inline std::size_t row_stride_in_bytes() const

inline std::size_t pixel_size_in_bytes() const

Public Members

int32_t width = 0

int32_t height = 0

TImageChannels channels = TImageChannels::CH_GRAY 

PixelDepth depth = PixelDepth::D8U 

uint8_t *image_data = nullptr: Pointer to the loaded image data.

mutable bool imgIsExternalStorage = {false}

Set to true only when using setExternalStorage.

See also

setExternalStorage

mutable std::string externalFile: The file name of a external storage image.