Detailed Description
The PImage class represents a 2D-image; several pixel format and number of channels are supported (BGR, grey-scale, ...).
Frequently Asked Questions:
- What is the maximum image size?
16384 x 16384 - How to get a PImage from file? Use PImage::Load()
- Which image format are supported when loading an image from a file?
JPG, PNG, TIF, BMP, WEBP, PBM, PGM, PPM, JPEG 2000 (JP2) - Are 2-colors (1 bit) TIF images supported: Yes, they will be loaded and converted to BGR8U (3 channels, 8-bits) format, but they remain 2-colors internally
- How to copy an image?
Use PImage::Clone() - How to avoid memory allocation and re-use the same image buffer?
See PImage::Allocate() which contains an example
#include <PImage.h>
Member Enumeration Documentation
◆ EAspectRatioMode
All the available aspect ratio mode for resize.
◆ EFileFormat
enum PImage::EFileFormat |
◆ EFont
enum PImage::EFont |
◆ EInterpolation
All the available interpolation mode for resize.
◆ EPixelFormat
enum PImage::EPixelFormat |
All the available pixel formats.
Constructor & Destructor Documentation
◆ PImage() [1/2]
|
explicit |
Constructs a 2D image of size width x height using the specified pixel format (RGB, 8-bits per channel, by default).
Can be used to store color, gray scale images, etc.
Image width and height must be in the range 0..16384 (MaxSize()). These parameters are automatically clamped if outside the valid range.
Default image type is BGR8U, a 3 channels color image. If pixelFormat is wrong, then pixelFormat is forced to Grey8U.
When the image is created, all pixels are set to 0 (the image is entirely cleared).
Use the following idiom to load an image from file:
- See also
- Allocate()
- Load()
◆ PImage() [2/2]
◆ ~PImage()
|
virtual |
Destroys this object.
Member Function Documentation
◆ Allocate()
void PImage::Allocate | ( | papillon::int32 | width, |
papillon::int32 | height, | ||
PImage::EPixelFormat | pixelFormat = PImage::E_BGR8U |
||
) |
Allocates memory to be able to store the specified image if needed.
Do nothing is this image already has the specified format.
Image width and height must be in the range 0..16384 (MaxSize()). These parameters are automatically clamped if outside the valid range.
Default image type is BGR8U, a 3 channel color image. If type is wrong, then type is automatically set to E_GREY8U.
Warning: image is not cleared, i.e. not filled with 0.
You can use this method to allocate buffer once and for all and re-use memory for several frames:
◆ Blur()
Blurs this image (gaussian blur) and put the result in the specified image.
Blur factor parameter must be >= 1.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Clear()
void PImage::Clear | ( | ) |
Fills this image with 0.
◆ Clone()
PImage PImage::Clone | ( | ) | const |
Returns a deep copy of this object.
◆ Convert()
PResult PImage::Convert | ( | PImage & | dest, |
PImage::EPixelFormat | destImageType | ||
) | const |
Converts an image from one color space to another.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Crop() [1/2]
PResult PImage::Crop | ( | papillon::int32 | x, |
papillon::int32 | y, | ||
papillon::int32 | width, | ||
papillon::int32 | height | ||
) |
Crops this image to the specified rectangle.
Returns PResult::C_OK if success, another result otherwise.
◆ Crop() [2/2]
PResult PImage::Crop | ( | const PRectanglei & | r | ) |
Crops this image to the specified rectangle.
Returns PResult::C_OK if success, another result otherwise.
◆ Display()
Displays this image into a window with the specified title (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.
Returns PResult::C_OK if success, another result otherwise.
◆ DisplayOff()
◆ DisplayScaled() [1/2]
PResult PImage::DisplayScaled | ( | const PString & | title, |
papillon::int32 | width, | ||
papillon::int32 | height, | ||
papillon::int32 | waitTimeMs = 0 |
||
) | const |
Displays this image into a window with the specified title and the specified size (a resize is performed if necessary) (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.
If width and height are <= 0, then resolution of the primary screen will be used.
Returns PResult::C_OK if success, another result otherwise.
◆ DisplayScaled() [2/2]
Displays this image into a window at the size of the screen (primary monitor) (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.
Returns PResult::C_OK if success, another result otherwise.
◆ DrawCircle() [1/2]
PResult PImage::DrawCircle | ( | const PPoint2Df & | p, |
papillon::int32 | radius, | ||
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified circle to this image.
◆ DrawCircle() [2/2]
PResult PImage::DrawCircle | ( | papillon::int32 | x, |
papillon::int32 | y, | ||
papillon::int32 | radius, | ||
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified circle to this image.
◆ DrawEllipse()
PResult PImage::DrawEllipse | ( | papillon::int32 | x, |
papillon::int32 | y, | ||
papillon::int32 | width, | ||
papillon::int32 | height, | ||
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified ellipse to this image.
◆ DrawLabel()
PResult PImage::DrawLabel | ( | const PString & | text, |
const PPoint2Di & | centre, | ||
const PColour3i & | labelColour = PColour3i::Black() , |
||
const PColour3i & | textColor = PColour3i::White() , |
||
PImage::EFont | font = PImage::E_FONT_HERSHEY_PLAIN , |
||
double | labelScale = 1.0 |
||
) |
Draws a label on an image.
WARNING: only 7-bit ASCII characters are accepted (limitation of the internal fonts used to draw characters); other characters will be displayed as '?'. Returns PResult::C_OK on success, another results otherwise.
- Parameters
-
text The text to write in the label. centre The centre point to place the label. If part of the label is outside the image, you will not see it. labelColour The colour of the label. textColor The colour of the text (make it in contrast to the label colour). font The font to use. labelScale The scale of the font. Note the label will automatically resize to fit the fontScale.
- Returns
- PResult PResult::C_OK on success, another results otherwise
◆ DrawLine()
PResult PImage::DrawLine | ( | papillon::int32 | x1, |
papillon::int32 | y1, | ||
papillon::int32 | x2, | ||
papillon::int32 | y2, | ||
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified line to this image.
◆ DrawPolygon() [1/2]
PResult PImage::DrawPolygon | ( | const PPolygoni & | p, |
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified polygon to this image.
◆ DrawPolygon() [2/2]
PResult PImage::DrawPolygon | ( | const PPolygonf & | p, |
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified polygon to this image.
◆ DrawRectangle() [1/2]
PResult PImage::DrawRectangle | ( | const PRectanglei & | r, |
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified rectangle to this image.
◆ DrawRectangle() [2/2]
PResult PImage::DrawRectangle | ( | const PRectanglef & | r, |
const PColour3i & | color, | ||
papillon::int32 | thickness = 1 |
||
) |
Draws the specified rectangle to this image.
◆ DrawString() [1/2]
PResult PImage::DrawString | ( | const PString & | text, |
const PPoint2Di & | origin, | ||
PImage::EFont | font, | ||
const PColour3i & | color, | ||
double | fontScale = 1.0 |
||
) |
Draws the specified string to this image.
WARNING: only 7-bit ASCII characters are accepted (limitation of the internal fonts used to draw characters); other characters will be displayed as '?'.
◆ DrawString() [2/2]
PResult PImage::DrawString | ( | const PString & | text, |
const PPoint2Di & | origin, | ||
const PString & | fontName, | ||
papillon::int32 | fontSize, | ||
const PColour3i & | fontColor | ||
) |
Draws the specified string to this image.
WARNING: only 7-bit ASCII characters are accepted (limitation of the internal fonts used to draw characters); other characters will be displayed as '?'.
◆ EqualizeHistogram()
Performs an histogram equalization of this image and put the result in the specified image.
Works only for grayscale images.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ ExtractSubImage() [1/2]
PResult PImage::ExtractSubImage | ( | PImage & | dest, |
papillon::int32 | x, | ||
papillon::int32 | y, | ||
papillon::int32 | width, | ||
papillon::int32 | height | ||
) | const |
Copies (deep copy) a region of this image to dest.
The sub-image is defined by the rectangle starting at pixel (x,y) and size width x height. The specified rectangle is cropped if outside the image.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ ExtractSubImage() [2/2]
PResult PImage::ExtractSubImage | ( | PImage & | dest, |
const PRectanglei & | r | ||
) | const |
Copies (deep copy) a region of this image to dest.
The sub-image is defined by the rectangle starting at pixel (x,y) and size width x height. The specified rectangle is cropped if outside the image.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Fill()
Fills this image with the specified RGB color.
The RGB color is first converted to the same color space as this image. Returns PResult::C_OK if success, another result otherwise.
◆ FillRectangle()
PResult PImage::FillRectangle | ( | const PRectanglei & | r, |
const PColour3i & | color | ||
) |
Fills the specified rectangle to this image.
◆ GetAspectRatio()
float PImage::GetAspectRatio | ( | ) | const |
Returns the aspect ratio of this image or NaN if both width and height are 0.
◆ GetAspectRatioToString()
|
static |
Returns a string describing the aspect ratio mode used for resizing.
◆ GetDataPtr()
papillon::uint8* PImage::GetDataPtr | ( | papillon::int32 | row = 0 | ) | const |
UNSAFE: Returns a pointer to the internal buffer of this image, starting at the specified row.
If row is invalid, then return a NULL pointer.
◆ GetEFileFormatFromString()
|
static |
Converts a string to EFileFormat if possible (e.g.
"JPG" or ".jpeg" gives PImage::E_JPG). Set fileFormat to E_UNKNOWN if any error occurs. Returns PResult::C_OK if success, another result otherwise.
◆ GetEFileFormatToString()
|
static |
Converts EFileFormat to string.
◆ GetFingerPrint()
PString PImage::GetFingerPrint | ( | ) | const |
Gets a unique fingerprint for that image.
This is actually based on the contents of the image data. This can be useful for caching results based on the contents of the image.
◆ GetHeight()
papillon::int32 PImage::GetHeight | ( | ) | const |
Returns the height of this image (number of rows), in pixels.
◆ GetNumberOfChannels()
papillon::int32 PImage::GetNumberOfChannels | ( | ) | const |
Returns the number of channels of this image (e.g.
3 for a RGB image or 1 for a grayscale image).
◆ GetPixel()
papillon::uint8* PImage::GetPixel | ( | papillon::int32 | x, |
papillon::int32 | y | ||
) | const |
UNSAFE: Returns a pointer toward the pixel of coordinates (x,y), or NULL if the coordinates are invalid.
◆ GetPixelFormat()
PImage::EPixelFormat PImage::GetPixelFormat | ( | ) | const |
Returns the type of pixels (e.g.
BGR8U, RGB8U, Grey8U, etc.).
◆ GetPixelFormatToString() [1/2]
PString PImage::GetPixelFormatToString | ( | ) | const |
Returns a string describing the type of pixels.
◆ GetPixelFormatToString() [2/2]
|
static |
Returns a string describing the specified type of image.
◆ GetRectangle()
PRectanglei PImage::GetRectangle | ( | ) | const |
Gets the image rectangle: (0, 0, width, height).
◆ GetSize()
PSizei PImage::GetSize | ( | ) | const |
Returns the size (width and height) of this image, in pixels.
◆ GetSizeInBytes()
papillon::int32 PImage::GetSizeInBytes | ( | ) | const |
Returns the number of bytes required to store this image (width x height x sizeof(pixel)).
◆ GetSizeOfPixelInBytes()
papillon::int32 PImage::GetSizeOfPixelInBytes | ( | ) | const |
Returns the number of bytes used to store 1 pixel.
◆ GetSizeOfRowInBytes()
papillon::int32 PImage::GetSizeOfRowInBytes | ( | ) | const |
Returns the number of bytes used to store a row of this image (also known as "step").
It could be different of width x sizeof(pixel) because of padding.
◆ GetWidth()
papillon::int32 PImage::GetWidth | ( | ) | const |
Returns the width of this image (number of columns), in pixels.
◆ InsertImageInPlace()
Inserts image into this image.
Returns PResult::C_OK if success, another result otherwise.
◆ IsEmpty()
bool PImage::IsEmpty | ( | ) | const |
Returns true if the image is empty (with or height is 0), false otherwise.
◆ IsGrayscale()
bool PImage::IsGrayscale | ( | ) | const |
Returns true if the image is grayscale (Grey8U), false otherwise.
◆ IsSame()
bool PImage::IsSame | ( | const PImage & | other | ) | const |
Returns true if this image and other have exactly the same type, same size and same pixels.
◆ Load() [1/2]
PResult PImage::Load | ( | const PByteArray & | inputBuffer, |
papillon::int32 | offset = 0 |
||
) |
Reads an image from a buffer in memory; the buffer is decoded to get the image.
The following formats are recognized: JPG, PNG, TIF, BMP, WEBP, PBM, PGM, PPM, JP2 (jpeg 2000)
The resulting image is a E_BGR8U colored image.
WARNING: the decoding starts at the internal buffer position. See PByteArray::SetPosition().
If any error occurs, the image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Load() [2/2]
Loads a BGR8U image from the specified file (format must be JPG, PNG, TIF, BMP, WEBP, PBM, PGM, PPM, JP2).
The resulting image is a E_BGR8U colored image.
The idiom to load an image from file is the following:
If any error occurs, the image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ LoadFromBase64()
Loads a BGR8U image from the specified string representing a base64 image in the format JPG, PNG, TIF, BMP, WEBP, JP2.
Returns PResult::C_OK if success, another result otherwise.
◆ MaxSize()
|
inlinestatic |
◆ MD5()
PString PImage::MD5 | ( | ) | const |
Returns the MD5 hash value of this image.
◆ operator=()
Performs a shared copy of other to this object.
- See also
- Clone()
◆ operator==()
bool PImage::operator== | ( | const PImage & | other | ) | const |
Returns true if this image and other have exactly the same type, same size and same pixels.
- See also
- IsSame()
◆ Resize() [1/6]
PResult PImage::Resize | ( | PImage & | dest, |
papillon::int32 | newWidth, | ||
papillon::int32 | newHeight, | ||
PImage::EAspectRatioMode | aspectRatioMode = PImage::E_IGNORE_ASPECT_RATIO , |
||
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) | const |
Resizes this image to the size newWidth x newHeight using the specified interpolation algorithm and put resulting image in specified destination.
By default, do not preserve aspect ratio (see EAspectRatioMode modes).
New image size must be in the range 0..16384 (MaxSize()). Dimensions are automatically clamped if outside the valid range.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Resize() [2/6]
PResult PImage::Resize | ( | papillon::int32 | newWidth, |
papillon::int32 | newHeight, | ||
PImage::EAspectRatioMode | aspectRatioMode = PImage::E_IGNORE_ASPECT_RATIO , |
||
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) |
Resizes this image to the size newWidth x newHeight using the specified interpolation algorithm.
By default, do not preserve aspect ratio (see EAspectRatioMode modes).
New image size must be in the range 0..16384 (MaxSize()).Dimensions are automatically clamped if outside the valid range.
Returns PResult::C_OK if success, another result otherwise.
◆ Resize() [3/6]
PResult PImage::Resize | ( | PImage & | dest, |
const PSizei & | newSize, | ||
PImage::EAspectRatioMode | aspectRatioMode = PImage::E_IGNORE_ASPECT_RATIO , |
||
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) | const |
Resizes this image to the new size using the specified interpolation algorithm and put resulting image in specified destination.
New image size must be in the range 0..16384 (MaxSize()). Dimensions are automatically clamped if outside the valid range.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Resize() [4/6]
PResult PImage::Resize | ( | const PSizei & | newSize, |
PImage::EAspectRatioMode | aspectRatioMode = PImage::E_IGNORE_ASPECT_RATIO , |
||
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) |
Resizes this image to the new size using the specified interpolation algorithm.
New image size must be in the range 0..16384 (MaxSize()). Dimensions are automatically clamped if outside the valid range.
Returns PResult::C_OK if success, another result otherwise.
◆ Resize() [5/6]
PResult PImage::Resize | ( | PImage & | dest, |
const float | scaleFactor, | ||
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) | const |
Resizes this image using the specified scale factor and interpolation algorithm and put resulting image in specified destination.
New image size must be in the range 0..16384 (MaxSize()). Dimensions are automatically clamped if outside the valid range.
Source and destination images can be the same.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ Resize() [6/6]
PResult PImage::Resize | ( | const float | scaleFactor, |
PImage::EInterpolation | interpolation = PImage::E_INTERPOLATION_LINEAR |
||
) |
Resizes this image using the specified scale factor and interpolation algorithm.
New image size must be in the range 0..16384 (MaxSize()). Dimensions are automatically clamped if outside the valid range.
Returns PResult::C_OK if success, another result otherwise.
◆ Rotate()
Rotates image by +/- 0, 90, 180, 270 or 360 degrees, clockwise.
If any error occurs (e.g. invalid angle), the dest image remains unchanged. Returns PResult::C_OK if success, another result otherwise.
◆ Save() [1/2]
PResult PImage::Save | ( | PByteArray & | outputBuffer, |
PImage::EFileFormat | format, | ||
papillon::int32 | quality = -1 |
||
) | const |
Encodes this image to the specified format (JPG, PNG, TIF, BMP, WEBP) into a memory buffer.
If file format is unknown, returns an error. The method compresses the image and stores it in the memory buffer. WARNING: the buffer is not cleared. Data of the image are appended.
In case of Grey8U image type, only PNG and TIFF are supported. If the image is 3-channel image, then only BGR8U and RGB8U are supported. If the image type is different, you must convert the image to a supported format before (see Convert()).
Quality (optional) can used to specify:
- JPG: image quality in 0..100; the higher is the better (95 by default)
- PNG: compression level in 0..9; higher value means smaller size but longer compression time (3 by default)
- WEBP: image quality in 0..100; the higher is the better
Returns PResult::C_OK if success, another result otherwise.
◆ Save() [2/2]
Saves this image to the specified file (format must be JPG, PNG, TIF or BMP).
The image format is chosen based on the filename extension.
In case of Grey8U image type, only PNG and TIFF are supported. If the image is 3-channel image, then only BGR8U and RGB8U are supported. If the image type is different, you must convert the image to a supported format before (see Convert()).
Quality (optional) can used to specify:
- JPG: image quality in 0..100; the higher is the better (95 by default)
- PNG: compression level in 0..9; higher value means smaller size but longer compression time (3 by default)
Returns PResult::C_OK if success, another result otherwise.
◆ ScaleSize()
PSizei PImage::ScaleSize | ( | float | scaleFactor | ) | const |
Returns the size (width and height) of this image scaled by the specified scaleFactor.
◆ Set()
PResult PImage::Set | ( | const void * | inputRawBuffer, |
papillon::int32 | width, | ||
papillon::int32 | height, | ||
PImage::EPixelFormat | pixelFormat | ||
) |
Sets this image from a raw buffer in memory.
Performs a deep copy of the pixel buffer. If any error occurs, the image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ SetDisplayPosition()
void PImage::SetDisplayPosition | ( | const PString & | title, |
int | x, | ||
int | y | ||
) | const |
Moves a display (window) to the specified position (x,y).
◆ SetFromCvMat()
PResult PImage::SetFromCvMat | ( | const void * | cvMat, |
EPixelFormat | pixelFormat, | ||
bool | clone = true |
||
) |
Sets this image from the specified OpenCV cv::Mat object.
See http://docs.opencv.org/modules/core/doc/basic_structures.html#mat to learn more.
- Parameters
-
cvMat pointer to cv::Mat object pixelFormat pixel format in cvMat clone whether to make copy of cv::Mat or share the buffer it will be forced if cvMat is not continuous
This function does not do any conversions therefore openCv type needs to match EPixelFormat Supported pixel types: CV_8UC3 - E_BGR8U, E_RGB8U, E_YCrCb8U or E_HSV8U CV_8UC4 - E_BGRA8U or E_RGBA8U CV_8UC1 - E_GREY8U
Returns PResult::C_OK if success, another result otherwise.
◆ SwapRGB()
Swaps red and blue channels in RGB or BGR image.
Source image format must be BGR8U, RGB8U, BGRA8U or RGBA8U.
Source and destination images can be the same.
Do not change the pixel format. A BRG8U image remains a BRGR8U image.
If any error occurs, the dest image is emptied. Returns PResult::C_OK if success, another result otherwise.
◆ ToJpegBase64()
PString PImage::ToJpegBase64 | ( | papillon::int32 | quality = -1 | ) | const |
Returns a base64 jpeg encoding of this image.
Jpg image quality must be in 0..100; the higher is the better (95 by default, if you do not specify this parameter).