SignDoc SDK (C++)  5.0.0
SignDocImage Class Reference

A bitmap image. More...

#include <SignDocSDK-cpp.h>

Public Member Functions

 SignDocImage ()
 Constructor. More...
 
 SignDocImage (const SignDocImage &aSource)
 Copy constructor. More...
 
 ~SignDocImage ()
 Destructor. More...
 
SignDocImageoperator= (const SignDocImage &aSource)
 Assignment operator. More...
 
void swap (SignDocImage &aOther)
 Efficiently swap this object with another one. More...
 
void clear ()
 Remove the image from this object. More...
 
ReturnCode setEmpty (int aWidth, int aHeight, int aBitsPerPixel, int aColor)
 Replace this image with an empty one of the specified size. More...
 
ReturnCode loadFromMemory (const unsigned char *aPtr, size_t aSize, int aIndex)
 Load an image from a blob. More...
 
ReturnCode loadFromFile (Encoding aEncoding, const std::string &aPath, int aIndex)
 Load an image from a file. More...
 
ReturnCode loadFromFile (const wchar_t *aPath, int aIndex)
 Load an image from a file. More...
 
ReturnCode getNumberOfPagesFromMemory (const unsigned char *aPtr, size_t aSize, int &aOutput) const
 Get the number of subimages (pages) in a blob. More...
 
ReturnCode getNumberOfPagesFromFile (Encoding aEncoding, const std::string &aPath, int &aOutput) const
 Get the number of subimages (pages) in a file. More...
 
ReturnCode getNumberOfPagesFromFile (const wchar_t *aPath, int &aOutput) const
 Get the number of subimages (pages) in a file. More...
 
int getBitsPerPixel () const
 Get the number of bits per pixel. More...
 
int getNumberOfComponents () const
 Get the number of components. More...
 
int getBitsPerComponent () const
 Get the number of bits per component. More...
 
int getWidth () const
 Get the width of the image. More...
 
int getHeight () const
 Get the height of the image. More...
 
int getResolutionX () const
 Get the horizontal resolution of the image. More...
 
int getResolutionY () const
 Get the vertical resolution of the image. More...
 
ReturnCode setResolution (int aResolutionX, int aResolutionY)
 Set the resolution of the image. More...
 
ReturnCode resizeToResolution (int aResolutionX, int aResolutionY, const std::string &aFilter)
 Resize the image. More...
 
ReturnCode crop (int aX, int aY, int aWidth, int aHeight)
 Crop the image. More...
 
ReturnCode convertToBiLevel (const SignDocImageParameters *aImageParameters)
 Convert the image to bi-level black and white. More...
 
ReturnCode convertToGrayscale ()
 Convert the image to 8-bit grayscale. More...
 
ReturnCode convertToTrueColor ()
 Convert the image to 24-bit RGB (8 bits per color channel). More...
 
ReturnCode invert (bool aAuto)
 Invert the image. More...
 
ReturnCode rotate (int aAngle, int aBackgroundColor)
 Rotate the image. More...
 
ReturnCode mirrorX ()
 Mirror along the vertical axis (flip horizontally). More...
 
ReturnCode mirrorY ()
 Mirror along the horizontal axis (flip vertically). More...
 
ReturnCode getPixelValue (int aX, int aY, int &aValue) const
 Get the value of a pixel. More...
 
ReturnCode setPixelValue (int aX, int aY, int aValue)
 Set the value of a pixel. More...
 
ReturnCode getPixelRGB (int aX, int aY, int &aColor) const
 Get the RGB color of a pixel. More...
 
ReturnCode setPixelRGB (int aX, int aY, int aColor)
 Set the RGB color of a pixel. More...
 
ReturnCode drawLine (int aX1, int aY1, int aX2, int aY2, double aStrokeWidth, int aColor)
 Draw a line. More...
 
ReturnCode drawRect (int aX1, int aY1, int aX2, int aY2, double aRadiusX, double aRadiusY, double aStrokeWidth, int aColor, bool aFill)
 Draw a rectangle (with both lines parallel to the axes). More...
 
ReturnCode drawRect (const SignDocImageRect &aRect, double aRadiusX, double aRadiusY, double aStrokeWidth, int aColor, bool aFill)
 Draw a rectangle (with both lines parallel to the axes). More...
 
ReturnCode getPalette (std::vector< int > &aOutput) const
 Get the palette. More...
 
ReturnCode setPaletteAt (int aIndex, int aColor)
 Set a palette entry. More...
 
ReturnCode getHistogram (std::vector< int > &aOutput) const
 Compute a histogram. More...
 
ReturnCode getComplexity (const SignDocImageParameters *aImageParameters, int &aOutput) const
 Compute the complexity of a signature image. More...
 
ReturnCode clean (const SignDocImageParameters *aImageParameters, const SignDocCleanParameters &aCleanParameters)
 Clean a signature image according to the provided parameters. More...
 
ReturnCode cleanSignature (const SignDocImageParameters *aImageParameters, SignDocImageRect *aRect)
 Clean a signature image. More...
 
ReturnCode cleanLines (const SignDocImageParameters *aImageParameters)
 Clean lines. More...
 
ReturnCode cleanDate (const SignDocImageParameters *aImageParameters, SignDocImageRect *aRect)
 Remove handwritten text from the signature image. More...
 
ReturnCode cleanFrames (const SignDocImageParameters *aImageParameters, double aTrust)
 Clean frames. More...
 
ReturnCode removeMargins (const SignDocImageParameters *aImageParameters, SignDocImageRect *aRect)
 Remove white margins. More...
 
ReturnCode getFrames (const SignDocImageParameters *aImageParameters, std::vector< SignDocWeightedFrame > &aOutput) const
 Get the frames of the image. More...
 
ReturnCode getSplitPositions (const SignDocImageParameters *aImageParameters, std::vector< int > &aOutput) const
 Get the vertical split positions of the image. More...
 
ReturnCode matchImage (const SignDocImage &aOther, const SignDocMatchParameters *aMatchParameters, std::unique_ptr< SignDocMatchResult > &aOutput) const
 Match against a signature image. More...
 
ReturnCode matchSignature (const SignDocSignatureData &aOther, const SignDocMatchParameters *aMatchParameters, const SignDocImageParameters *aImageParameters, std::unique_ptr< SignDocMatchResult > &aOutput) const
 Match against a signature. More...
 
ReturnCode matchReference (const SignDocSignatureData &aOther, const SignDocMatchParameters *aMatchParameters, const SignDocImageParameters *aImageParameters, std::unique_ptr< SignDocMatchResult > &aOutput) const
 Match against a reference. More...
 
ReturnCode saveToMemory (std::vector< unsigned char > &aOutput, const SignDocImageParameters &aParameters) const
 Save this image as a blob. More...
 
ReturnCode saveToMemory2 (std::vector< unsigned char > &aOutput, const std::string &aFormat) const
 Save this image as a blob. More...
 
ReturnCode saveToFile (Encoding aEncoding, const std::string &aPath, const SignDocImageParameters &aParameters) const
 Save this image to a file. More...
 
ReturnCode saveToFile (const wchar_t *aPath, const SignDocImageParameters &aParameters) const
 Save this image to a file. More...
 
ReturnCode saveToFile2 (Encoding aEncoding, const std::string &aPath, const std::string &aFormat) const
 Save this image to a file. More...
 
ReturnCode saveToFile2 (const wchar_t *aPath, const std::string &aFormat) const
 Save this image to a file. More...
 
const char * getErrorMessage (Encoding aEncoding) const
 Get an error message for the last function call. More...
 
const wchar_t * getErrorMessageW () const
 Get an error message for the last function call. More...
 
 SignDocImage (SIGNDOC_Image *aP)
 Internal function. More...
 
SIGNDOC_Image * getImpl ()
 Internal function. More...
 
const SIGNDOC_Image * getImpl () const
 Internal function. More...
 
void setImpl (SIGNDOC_Image *aP)
 Internal function. More...
 

Detailed Description

A bitmap image.

This class supports images with 1 bit per pixel (bi-level, with RGB palette), 8 bits per pixel (indexed, with RGB palette), and 24 bits per pixel (RGB, 256 levels per color channel). RGB colors are specified as integers of the form 0x00rrggbb (rr is the red component, gg is the green component, bb is the blue component). All three components have values 0 (off) through 255 (on): 0x000000 is black, 0xffffff is white.

Some functions assume (for computing the intensity) that the color profile is sRGB.

Images that have transparent pixels are not supported.

The origin of the coordinate system is in the upper left corner, see Coordinate Systems.

See also
SignDocColor::getRGB()

Constructor & Destructor Documentation

SignDocImage ( )
inline

Constructor.

This object won't contain an image, getWidth() and getHeight() will return 0.

See also
setEmpty(), setResolution()
SignDocImage ( const SignDocImage aSource)
inline

Copy constructor.

Parameters
[in]aSourceThe object to be copied.
~SignDocImage ( )
inline

Destructor.

SignDocImage ( SIGNDOC_Image *  aP)
inline

Internal function.

Member Function Documentation

ReturnCode clean ( const SignDocImageParameters aImageParameters,
const SignDocCleanParameters aCleanParameters 
)
inline

Clean a signature image according to the provided parameters.

This function performs multiple clean operations with a single call.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then mask the original image with the cleaned bi-level image, making all parts white that are not considered part of the signature.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[in]aCleanParametersActions and parameters.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
cleanDate(), cleanFrames(), cleanLines(), cleanSignature(), convertToBiLevel(), convertToGrayscale(), convertToTrueColor(), crop(), invert(), mirrorX(), mirrorY(), rotate()
ReturnCode cleanDate ( const SignDocImageParameters aImageParameters,
SignDocImageRect aRect 
)
inline

Remove handwritten text from the signature image.

Handwritten text (such as a date) will be removed from the signature image. Dirt, lines, and machine-printed text must be removed before calling this function.

After cleaning, the image will be cropped to the signature region.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then crop the original image to the cleaned bi-level image.

If the height or width would become zero, the image will be replaced by a single white pixel (if the image uses a palette, the brightest color in the palette will be used).

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aRectThe object pointed to by this argument will be set to a rectangle bounding the signature region within the original image. Can be nullptr.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean(), cleanFrames(), cleanLines(), cleanSignature()
ReturnCode cleanFrames ( const SignDocImageParameters aImageParameters,
double  aTrust 
)
inline

Clean frames.

This function removes all frames that have a weight smaller than aTrust.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then mask the original image with the cleaned bi-level image, making all parts white that are not considered part of the signature.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[in]aTrustMinimum frame weight (0.0 through 1.0). 0.0 removes dirt, 1.0 removes all frames.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean(), cleanDate(), cleanLines(), cleanSignature(), getFrames()
ReturnCode cleanLines ( const SignDocImageParameters aImageParameters)
inline

Clean lines.

Horizontal and vertical lines will be removed.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then mask the original image with the cleaned bi-level image, making all parts white that are not considered part of the signature.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean(), cleanDate(), cleanFrames(), cleanSignature()
ReturnCode cleanSignature ( const SignDocImageParameters aImageParameters,
SignDocImageRect aRect 
)
inline

Clean a signature image.

This function cleans horizontal Lines, printed text, and dirt not being part of a signature.

After cleaning, the image will be cropped to the signature region.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then crop the original image to the cleaned bi-level image.

If the height or width would become zero, the image will be replaced by a single white pixel (if the image uses a palette, the brightest color in the palette will be used).

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aRectThe object pointed to by this argument will be set to a rectangle bounding the signature region within the original image. Can be nullptr.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean(), cleanDate(), cleanFrames(), cleanLines()
void clear ( )
inline

Remove the image from this object.

See also
setEmpty()
ReturnCode convertToBiLevel ( const SignDocImageParameters aImageParameters)
inline

Convert the image to bi-level black and white.

This function uses thresholding.

Unlike SignWare's SPImageBinarize(), this function never inverts the image.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
convertToGrayscale(), convertToTrueColor()
ReturnCode convertToGrayscale ( )
inline

Convert the image to 8-bit grayscale.

Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
convertToBiLevel(), convertToTrueColor()
ReturnCode convertToTrueColor ( )
inline

Convert the image to 24-bit RGB (8 bits per color channel).

Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
convertToBiLevel(), convertToGrayscale()
ReturnCode crop ( int  aX,
int  aY,
int  aWidth,
int  aHeight 
)
inline

Crop the image.

The the rectangle to be preserved must lie completely within the current image.

Parameters
[in]aXThe X coordinate of the upper left corner of the rectangle that will be preserved.
[in]aYThe Y coordinate of the upper left corner of the rectangle that will be preserved.
[in]aWidthThe width of the rectangle that will be preserved. Must be positive.
[in]aHeightThe height of the rectangle that will be preserved. Must be positive.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
getWidth(), getHeight(), getResolutionX(), getResolutionY(), removeMargins(), resizeToResolution(), rotate()
ReturnCode drawLine ( int  aX1,
int  aY1,
int  aX2,
int  aY2,
double  aStrokeWidth,
int  aColor 
)
inline

Draw a line.

Parameters
[in]aX1X coordinate of the first endpoint of the line.
[in]aY1Y coordinate of the first endpoint of the line.
[in]aX2X coordinate of the second endpoint of the line.
[in]aY2Y coordinate of the second endpoint of the line.
[in]aStrokeWidthStroke width in pixels (need not be an integer, 0 for minimum width).
[in]aColorThe RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
drawRect(), setPixelRGB()
ReturnCode drawRect ( int  aX1,
int  aY1,
int  aX2,
int  aY2,
double  aRadiusX,
double  aRadiusY,
double  aStrokeWidth,
int  aColor,
bool  aFill 
)
inline

Draw a rectangle (with both lines parallel to the axes).

If aRadiusX and aRadiusY are positive, a quarter ellipse will be drawn in each corner. If aRadiusX or aRadiusY is zero, a normal rectangle will be drawn.

Parameters
[in]aX1X coordinate of the first corner of the rectangle.
[in]aY1Y coordinate of the first corner of the rectangle.
[in]aX2X coordinate of the opposite corner of the rectangle.
[in]aY2Y coordinate of the opposite corner of the rectangle.
[in]aRadiusXHorizontal radius of quarter ellipse.
[in]aRadiusYVertical radius of quarter ellipse.
[in]aStrokeWidthStroke width in pixels (need not be an integer, 0 for minimum width).
[in]aColorThe RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.
[in]aFilltrue to fill interior of rectangle, false to stroke border. For filling you might want do use 0 for aStrokeWidth as the stroked rectangle will be filled, that is, the outer dimensions of the rectangle don't depend on aFill.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
drawLine(), setPixelRGB()
ReturnCode drawRect ( const SignDocImageRect aRect,
double  aRadiusX,
double  aRadiusY,
double  aStrokeWidth,
int  aColor,
bool  aFill 
)
inline

Draw a rectangle (with both lines parallel to the axes).

If aRadiusX and aRadiusY are positive, a quarter ellipse will be drawn in each corner. If aRadiusX or aRadiusY is zero, a normal rectangle will be drawn.

Parameters
[in]aRectThe rectangle (does not need to be normalized).
[in]aRadiusXHorizontal radius of quarter ellipse.
[in]aRadiusYVertical radius of quarter ellipse.
[in]aStrokeWidthStroke width in pixels (need not be an integer, 0 for minimum width).
[in]aColorThe RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.
[in]aFilltrue to fill interior of rectangle, false to stroke border. For filling you might want do use 0 for aStrokeWidth as the stroked rectangle will be filled, that is, the outer dimensions of the rectangle don't depend on aFill.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
drawLine(), setPixelRGB()
int getBitsPerComponent ( ) const
inline

Get the number of bits per component.

Returns
The number of bits per component: 0 (no image), 1 (bi-level), or 8.
See also
getBitsPerPixel(), getNumberOfComponents()
int getBitsPerPixel ( ) const
inline

Get the number of bits per pixel.

This function returns the product of the return values of getNumberOfComponents() and getBitsPerComponent().

Returns
The number of bits per pixel: 0 (no image), 1 (bi-level), 8 (indexed), or 24 (RGB).
See also
getBitsPerComponent(), getHeight(), getNumberOfComponents(), getWidth()
ReturnCode getComplexity ( const SignDocImageParameters aImageParameters,
int &  aOutput 
) const
inline

Compute the complexity of a signature image.

The computed complexity is valid only if this object contains a clean signature image.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aOutputThe complexity of the signature in the range 0 (simplest) through 100 (most complex) will be stored here.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean()
const char * getErrorMessage ( Encoding  aEncoding) const
inline

Get an error message for the last function call.

Parameters
[in]aEncodingThe encoding to be used for the error message.
Returns
A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until this object is destroyed or a member function of this object is called.
See also
getErrorMessageW()
const wchar_t * getErrorMessageW ( ) const
inline

Get an error message for the last function call.

Returns
A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until this object is destroyed or a member function of this object is called.
See also
getErrorMessage()
ReturnCode getFrames ( const SignDocImageParameters aImageParameters,
std::vector< SignDocWeightedFrame > &  aOutput 
) const
inline

Get the frames of the image.

This function computes the frames and their weights. Frame weights are floating-point numbers in the range 0.0 through 1.0: 0.0 identifies dirt, 1.0 identifies frames that are part of a signature.

If the image is not a bi-level image, this function will create a temporary bi-level image.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aOutputThe frames will be stored here.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
cleanFrames(), getSplitPositions()
int getHeight ( ) const
inline

Get the height of the image.

Returns
The height of the image (in pixels), 0 if there is no image.
See also
getBitsPerPixel(), getWidth(), resizeToResolution()
ReturnCode getHistogram ( std::vector< int > &  aOutput) const
inline

Compute a histogram.

This function computes an array of integers the same size as the palette returned by getPalette(). Element i tells how many pixels use palette entry i.

Parameters
[out]aOutputThe histogram will be stored here. The vector will be empty if the image does not use a palette.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
getBitsPerPixel(), getPalette()
SIGNDOC_Image* getImpl ( )
inline

Internal function.

const SIGNDOC_Image* getImpl ( ) const
inline

Internal function.

int getNumberOfComponents ( ) const
inline

Get the number of components.

Returns
The number of components: 0 (no image), 1 (indexed), or 3 (RGB).
See also
getBitsPerComponent(), getBitsPerPixel()
ReturnCode getNumberOfPagesFromFile ( Encoding  aEncoding,
const std::string &  aPath,
int &  aOutput 
) const
inline

Get the number of subimages (pages) in a file.

This function opens the file, gets the number of subimages from the file, and closes the file.

This SignDocImage object is used only for storing any error message.

Parameters
[in]aEncodingThe encoding of aPath.
[in]aPathThe pathname of the file to be read.
[out]aOutputThe number of subimages (pages) will be stored here.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromMemory(), loadFromFile()
ReturnCode getNumberOfPagesFromFile ( const wchar_t *  aPath,
int &  aOutput 
) const
inline

Get the number of subimages (pages) in a file.

This function opens the file, gets the number of subimages from the file, and closes the file.

This SignDocImage object is used only for storing any error message.

Parameters
[in]aPathThe pathname of the file to be read.
[out]aOutputThe number of subimages (pages) will be stored here.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromMemory(), loadFromFile()
ReturnCode getNumberOfPagesFromMemory ( const unsigned char *  aPtr,
size_t  aSize,
int &  aOutput 
) const
inline

Get the number of subimages (pages) in a blob.

This SignDocImage object is used only for storing any error message.

Parameters
[in]aPtrA pointer to the first octet of a blob containing an image in BMP (Windows bitmap), TIFF, PNG, or GIF format.
[in]aSizeSize in octets of the blob pointed to by aPtr.
[out]aOutputThe number of subimages (pages) will be stored here.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromFile(), loadFromMemory()
ReturnCode getPalette ( std::vector< int > &  aOutput) const
inline

Get the palette.

This function gets the palette of the image as an array of integers representing RGB colors (0x00rrggbb). The array will contain 2 elements if getBitsPerPixel() returns 1, 256 elements if getBitsPerPixel() returns 8, or 0 elements otherwise (the image does not use a palette).

Parameters
[out]aOutputThe palette will be stored here.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
getBitsPerPixel(), getHistogram()
ReturnCode getPixelRGB ( int  aX,
int  aY,
int &  aColor 
) const
inline

Get the RGB color of a pixel.

Parameters
[in]aXX coordinate.
[in]aYY coordinate.
[out]aColorThe RGB color (0x00rrggbb) of the pixel will be stored here.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
getPixelValue(), setPixelRGB()
ReturnCode getPixelValue ( int  aX,
int  aY,
int &  aValue 
) const
inline

Get the value of a pixel.

Parameters
[in]aXX coordinate.
[in]aYY coordinate.
[out]aValueThe value of the pixel will be stored here. If getBitsPerPixel() returns 1 or 8, this is the index into the palette, if getBitsPerPixel() returns 24, this is the RGB color (0x00rrggbb).
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
getHistogram(), getPixelRGB(), setPixelValue()
int getResolutionX ( ) const
inline

Get the horizontal resolution of the image.

Returns
The horizontal resolution of the image in DPI, 0 if there is no image.
See also
getResolutionY(), setResolution()
int getResolutionY ( ) const
inline

Get the vertical resolution of the image.

Returns
The vertical resolution of the image in DPI, 0 if there is no image.
See also
getResolutionX(), setResolution()
ReturnCode getSplitPositions ( const SignDocImageParameters aImageParameters,
std::vector< int > &  aOutput 
) const
inline

Get the vertical split positions of the image.

If the image is not a bi-level image, this function will create a temporary bi-level image.

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aOutputThe X coordinates of the split positions will be stored here, ordered by importance, most important first.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
getFrames()
int getWidth ( ) const
inline

Get the width of the image.

Returns
The width of the image (in pixels), 0 if there is no image.
See also
getBitsPerPixel(), getHeight(), resizeToResolution()
ReturnCode invert ( bool  aAuto)
inline

Invert the image.

It is unspecified whether inverting is done by modifying the palette or by modifying the pixels.

Parameters
[in]aAutofalse to invert the image unconditionally, true to invert the image only if more than half the pixels have brightness (0 through 255) less than 128.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if there is no image.
ReturnCode loadFromFile ( Encoding  aEncoding,
const std::string &  aPath,
int  aIndex 
)
inline

Load an image from a file.

This function opens the file, loads the image from the file, and closes the file.

Parameters
[in]aEncodingThe encoding of aPath.
[in]aPathThe pathname of the file to be read.
[in]aIndex0-based page number for selecting a subimage (page) of the source image.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromFile(), loadFromMemory(), saveToFile()
ReturnCode loadFromFile ( const wchar_t *  aPath,
int  aIndex 
)
inline

Load an image from a file.

This function opens the file, loads the image from the file, and closes the file.

Parameters
[in]aPathThe pathname of the file to be read.
[in]aIndex0-based page number for selecting a subimage (page) of the source image.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromFile(), loadFromMemory(), saveToFile()
ReturnCode loadFromMemory ( const unsigned char *  aPtr,
size_t  aSize,
int  aIndex 
)
inline

Load an image from a blob.

Parameters
[in]aPtrA pointer to the first octet of a blob containing an image in BMP (Windows bitmap), TIFF, PNG, or GIF format.
[in]aSizeSize in octets of the blob pointed to by aPtr.
[in]aIndex0-based page number for selecting a subimage (page) of the source image.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument or the blob is invalid.
See also
getNumberOfPagesFromMemory(), loadFromFile(), saveToMemory(), saveToMemory2()
ReturnCode matchImage ( const SignDocImage aOther,
const SignDocMatchParameters aMatchParameters,
std::unique_ptr< SignDocMatchResult > &  aOutput 
) const
inline

Match against a signature image.

The license must allow comparing signatures.

Note
Only the static matching engine can be used.
Parameters
[in]aOtherThe signature image to match against.
[in]aMatchParametersParameters controlling how signature are matched. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aOutputA pointer to a new SignDocMatchResult object or nullptr will be stored here. The caller is responsible for destroying that object.
Returns
ReturnCode::rc_ok iff successful.
See also
clean(), matchSignature()
ReturnCode matchReference ( const SignDocSignatureData aOther,
const SignDocMatchParameters aMatchParameters,
const SignDocImageParameters aImageParameters,
std::unique_ptr< SignDocMatchResult > &  aOutput 
) const
inline

Match against a reference.

This function fails if aOther does not have type SignDocSignatureData::t_reference.

The license must allow comparing signatures.

Note
Only the static matching engine can be used.
Parameters
[in]aOtherThe reference to match against.
[in]aMatchParametersParameters controlling how signature are matched. If this argument is nullptr, all parameters will be set to their respective default value.
[in]aImageParametersParameters controlling how signature are rendered as images for static matching. If this argument is nullptr, all parameters will be set to their respective default value. String parameter "Format" will be ignored.
[out]aOutputA pointer to a new SignDocMatchResult object or nullptr will be stored here. The caller is responsible for destroying that object.
Returns
ReturnCode::rc_ok iff successful.
See also
clean(), matchSignature(), SignDocSignatureData::matchReference()
ReturnCode matchSignature ( const SignDocSignatureData aOther,
const SignDocMatchParameters aMatchParameters,
const SignDocImageParameters aImageParameters,
std::unique_ptr< SignDocMatchResult > &  aOutput 
) const
inline

Match against a signature.

If aOther has type SignDocSignatureData::t_reference, SignDocSignatureData::selectSignature() must be called once for aOther before calling this function.

This function fails if aOther has type SignDocSignatureData::t_empty.

The license must allow comparing signatures.

Note
Only the static matching engine can be used.
Parameters
[in]aOtherThe signature or reference to match against.
[in]aMatchParametersParameters controlling how signature are matched. If this argument is nullptr, all parameters will be set to their respective default value.
[in]aImageParametersParameters controlling how signature are rendered as images for static matching. If this argument is nullptr, all parameters will be set to their respective default value. String parameter "Format" will be ignored.
[out]aOutputA pointer to a new SignDocMatchResult object or nullptr will be stored here. The caller is responsible for destroying that object.
Returns
ReturnCode::rc_ok iff successful.
See also
clean(), matchImage(), matchReference(), SignDocSignatureData::matchSignature()
ReturnCode mirrorX ( )
inline

Mirror along the vertical axis (flip horizontally).

Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if there is no image.
See also
mirrorY(), rotate()
ReturnCode mirrorY ( )
inline

Mirror along the horizontal axis (flip vertically).

Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if there is no image.
See also
mirrorX(), rotate()
SignDocImage & operator= ( const SignDocImage aSource)
inline

Assignment operator.

Parameters
[in]aSourceThe source object.
Returns
This object.
ReturnCode removeMargins ( const SignDocImageParameters aImageParameters,
SignDocImageRect aRect 
)
inline

Remove white margins.

This function removes white margins ignoring single black pixels.

If the image is not a bi-level image, this function will create a bi-level image, clean the bi-level image, and then crop the original image to the cleaned bi-level image.

If the height or width would become zero, the image will be replaced by a single white pixel (if the image uses a palette, the brightest color in the palette will be used).

The width of the image must not exceed 1280 pixels, the height of the image must not exceed 960 pixels.

See Cleaning signature images for information about cleaning.

Parameters
[in]aImageParametersParameters controlling how images are converted to bi-level black and white. If this argument is nullptr, all parameters will be set to their respective default value.
[out]aRectThe object pointed to by this argument will be set to the rectangle occupied by the new image within the original image. Can be nullptr.
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument or ReturnCode::rc_unexpected_error on error.
See also
clean(), cleanSignature(), crop()
ReturnCode resizeToResolution ( int  aResolutionX,
int  aResolutionY,
const std::string &  aFilter 
)
inline

Resize the image.

This function may change the pixel format.

Parameters
[in]aResolutionXThe new horizontal resolution of the image in DPI. Must be positive.
[in]aResolutionYThe new vertical resolution of the image in DPI. Must be positive.
[in]aFilterThe resampling filter, an empty string for the default filter. The following filters are available (case-sensitive):
  • "box": box scaling (fastest)
  • "bilinear": bilinear filter
  • "b-spline": B-Spline filter
  • "bicubic": Bicubic filter (default)
  • "catmull-rom": Catmull-Rom filter
  • "lanczos": Lanczos filter
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
crop(), getWidth(), getHeight(), getResolutionX(), getResolutionY(), rotate(), setResolution()
ReturnCode rotate ( int  aAngle,
int  aBackgroundColor 
)
inline

Rotate the image.

If the image has 1 bit per pixel, aAngle must be an integer multiple of 90.

The resolution of the image is adjusted only if aAngle is an even integer multiple of 90.

This function fails exception if aAngle is not an integer multiple of 90, the image uses a palette, and aBackgroundColor is not a color in the palette.

Parameters
[in]aAngleRotation angle (degrees), positive for counter-clockwise, negative for clockwise.
[in]aBackgroundColorThe RGB color (0x00rrggbb) to be used for filling pixels that are not mapped from the source image. This value is used only if aAngle is not an integer multiple of 90.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
crop(), mirrorX(), mirrorY(), resizeToResolution()
ReturnCode saveToFile ( Encoding  aEncoding,
const std::string &  aPath,
const SignDocImageParameters aParameters 
) const
inline

Save this image to a file.

The following parameters of aParameters are used:

  • BitsPerComponent (integer)
  • BlackIsZero (boolean)
  • BottomUp (boolean)
  • Components (integer)
  • Compression (string)
  • Format (string)
  • OverrideResolution (integer)
  • Padding (integer)
  • PixelFormat (string)
  • WhiteIsZero (boolean)
Parameters
[in]aEncodingThe encoding of aPath.
[in]aPathThe pathname of the file to be created or overwritten.
[in]aParametersParameters controlling the format of the blob.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromFile(), saveToFile2(), saveToMemory()
ReturnCode saveToFile ( const wchar_t *  aPath,
const SignDocImageParameters aParameters 
) const
inline

Save this image to a file.

The following parameters of aParameters are used:

  • BitsPerComponent (integer)
  • BlackIsZero (boolean)
  • BottomUp (boolean)
  • Components (integer)
  • Compression (string)
  • Format (string)
  • OverrideResolution (integer)
  • Padding (integer)
  • PixelFormat (string)
  • WhiteIsZero (boolean)
Parameters
[in]aPathThe pathname of the file to be created or overwritten.
[in]aParametersParameters controlling the format of the blob.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromFile(), saveToFile2(), saveToMemory()
ReturnCode saveToFile2 ( Encoding  aEncoding,
const std::string &  aPath,
const std::string &  aFormat 
) const
inline

Save this image to a file.

This is a simplified version of saveToFile().

Parameters
[in]aEncodingThe encoding of aPath and aFormat.
[in]aPathThe pathname of the file to be created or overwritten.
[in]aFormatThe format to be used for the image file:
  • "auto": derive the format from the suffix of aPath
  • "bmp": Windows bitmap
  • "gif": GIF
  • "png": PNG
  • "tiff": TIFF; CCITT Group 4 compression is used for images with 1 bit per pixel, LZW compression is used otherwise.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromFile(), saveToFile(), saveToMemory2()
ReturnCode saveToFile2 ( const wchar_t *  aPath,
const std::string &  aFormat 
) const
inline

Save this image to a file.

This is a simplified version of saveToFile().

Parameters
[in]aPathThe pathname of the file to be created or overwritten.
[in]aFormatThe format to be used for the image file:
  • "auto": derive the format from the suffix of aPath
  • "bmp": Windows bitmap
  • "gif": GIF
  • "png": PNG
  • "tiff": TIFF; CCITT Group 4 compression is used for images with 1 bit per pixel, LZW compression is used otherwise.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromFile(), saveToFile(), saveToMemory2()
ReturnCode saveToMemory ( std::vector< unsigned char > &  aOutput,
const SignDocImageParameters aParameters 
) const
inline

Save this image as a blob.

The following parameters of aParameters are used:

  • BitsPerComponent (integer)
  • BlackIsZero (boolean)
  • BottomUp (boolean)
  • Components (integer)
  • Compression (string)
  • Format (string)
  • OverrideResolution (integer)
  • Padding (integer)
  • PixelFormat (string)
  • WhiteIsZero (boolean)
Parameters
[out]aOutputThe blob will be stored here.
[in]aParametersParameters controlling the format of the blob.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromMemory(), saveToFile(), saveToMemory2()
ReturnCode saveToMemory2 ( std::vector< unsigned char > &  aOutput,
const std::string &  aFormat 
) const
inline

Save this image as a blob.

This is a simplified version of saveToMemory().

Parameters
[out]aOutputThe blob will be stored here.
[in]aFormatThe format to be used for the image blob:
  • "bmp": Windows bitmap
  • "gif": GIF
  • "png": PNG
  • "tiff": TIFF; CCITT Group 4 compression is used for images with 1 bit per pixel, LZW compression is used otherwise.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if the parameters in aParameters are invalid or if there is no image.
See also
loadFromMemory(), saveToFile2(), saveToMemory()
ReturnCode setEmpty ( int  aWidth,
int  aHeight,
int  aBitsPerPixel,
int  aColor 
)
inline

Replace this image with an empty one of the specified size.

The resolution will be set to 72 dots per inch.

Parameters
[in]aWidthThe width of the image (in pixels). Must be positive.
[in]aHeightThe height of the image (in pixels). Must be positive.
[in]aBitsPerPixelNumber of bits per pixel: 1 (bi-level black and white), 8 (grayscale), or 24 (RGB).
[in]aColorAll pixels will be set to this color. If aBitsPerPixel is 24, this is an RGB color (0x00rrggbb), otherwise this is an index into the palette (0 is black).
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid.
See also
clear(), setPaletteAt(), setResolution()
void setImpl ( SIGNDOC_Image *  aP)
inline

Internal function.

ReturnCode setPaletteAt ( int  aIndex,
int  aColor 
)
inline

Set a palette entry.

Parameters
[in]aIndexThe 0-based index of the palette entry (0 through 1 if getBitsPerPixel() returns 1, 0 through 255 if getBitsPerPixel() returns 8).
[in]aColorThe new color for the palette entry (0x00rrggbb).
Returns
ReturnCode::rc_ok iff successful, ReturnCode::rc_invalid_argument on error.
See also
getBitsPerPixel(), getPalette()
ReturnCode setPixelRGB ( int  aX,
int  aY,
int  aColor 
)
inline

Set the RGB color of a pixel.

Parameters
[in]aXX coordinate.
[in]aYY coordinate.
[in]aColorThe new RGB color (0x00rrggbb) of the pixel. This function fails if the color does not exist in the palette of an indexed image.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
drawLine(), drawRect(), getPixelRGB(), setPixelValue()
ReturnCode setPixelValue ( int  aX,
int  aY,
int  aValue 
)
inline

Set the value of a pixel.

Parameters
[in]aXX coordinate.
[in]aYY coordinate.
[in]aValueThe new value of the pixel. If getBitsPerPixel() returns 1 or 8, this is the index into the palette, if getBitsPerPixel() returns 24, this is the RGB color (0x00rrggbb). For bi-level images, any value greater than 1 has the same effect as 1.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
getPixelValue()
ReturnCode setResolution ( int  aResolutionX,
int  aResolutionY 
)
inline

Set the resolution of the image.

This function does not modify the pixels of the image. Use resizeToResolution() to change the size of the image.

Parameters
[in]aResolutionXThe new horizontal resolution of the image in DPI. Must be positive.
[in]aResolutionYThe new vertical resolution of the image in DPI. Must be positive.
Returns
ReturnCode::rc_ok if successful, ReturnCode::rc_invalid_argument if an argument is invalid or if there is no image.
See also
getResolutionX(), getResolutionY(), resizeToResolution()
void swap ( SignDocImage aOther)
inline

Efficiently swap this object with another one.

Parameters
[in]aOtherThe other object.

The documentation for this class was generated from the following file: