A bitmap image. More...

#include <SignDocSDK-c.h>

Public Member Functions
struct SIGNDOC_Image *	SIGNDOC_Image_new (struct SIGNDOC_Exception **aEx)
	SIGNDOC_Image constructor. More...

void	SIGNDOC_Image_delete (struct SIGNDOC_Image *aObj)
	SIGNDOC_Image destructor. More...

struct SIGNDOC_Image *	SIGNDOC_Image_clone (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aSource)
	Clone a SIGNDOC_Image object. More...

void	SIGNDOC_Image_assign (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_Image *aSource)
	SIGNDOC_Image assignment operator. More...

void	SIGNDOC_Image_clear (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj)
	Remove the image from a SIGNDOC_Image object. More...

int	SIGNDOC_Image_setEmpty (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aWidth, int aHeight, int aBitsPerPixel, int aColor)
	Replace an image with an empty one of the specified size. More...

int	SIGNDOC_Image_loadFromMemory (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const unsigned char *aPtr, size_t aSize, int aIndex)
	Load an image from a blob. More...

int	SIGNDOC_Image_loadFromFile (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aEncoding, const char *aPath, int aIndex)
	Load an image from a file. More...

int	SIGNDOC_Image_loadFromFileW (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const wchar_t *aPath, int aIndex)
	Load an image from a file. More...

int	SIGNDOC_Image_getNumberOfPagesFromMemory (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const unsigned char aPtr, size_t aSize, int aOutput)
	Get the number of subimages (pages) in a blob. More...

int	SIGNDOC_Image_getNumberOfPagesFromFile (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aEncoding, const char aPath, int aOutput)
	Get the number of subimages (pages) in a file. More...

int	SIGNDOC_Image_getNumberOfPagesFromFileW (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const wchar_t aPath, int aOutput)
	Get the number of subimages (pages) in a file. More...

int	SIGNDOC_Image_getBitsPerPixel (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the number of bits per pixel. More...

int	SIGNDOC_Image_getNumberOfComponents (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the number of components. More...

int	SIGNDOC_Image_getBitsPerComponent (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the number of bits per component. More...

int	SIGNDOC_Image_getWidth (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the width of the image. More...

int	SIGNDOC_Image_getHeight (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the height of the image. More...

int	SIGNDOC_Image_getResolutionX (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the horizontal resolution of the image. More...

int	SIGNDOC_Image_getResolutionY (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get the vertical resolution of the image. More...

int	SIGNDOC_Image_setResolution (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aResolutionX, int aResolutionY)
	Set the resolution of the image. More...

int	SIGNDOC_Image_resizeToResolution (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aResolutionX, int aResolutionY, const char *aFilter)
	Resize the image. More...

int	SIGNDOC_Image_crop (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aX, int aY, int aWidth, int aHeight)
	Crop the image. More...

int	SIGNDOC_Image_convertToBiLevel (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters *aImageParameters)
	Convert the image to bi-level black and white. More...

int	SIGNDOC_Image_convertToGrayscale (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj)
	Convert the image to 8-bit grayscale. More...

int	SIGNDOC_Image_convertToTrueColor (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj)
	Convert the image to 24-bit RGB (8 bits per color channel). More...

int	SIGNDOC_Image_invert (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, SIGNDOC_Boolean aAuto)
	Invert the image. More...

int	SIGNDOC_Image_rotate (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aAngle, int aBackgroundColor)
	Rotate the image. More...

int	SIGNDOC_Image_mirrorX (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj)
	Mirror along the vertical axis (flip horizontally). More...

int	SIGNDOC_Image_mirrorY (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj)
	Mirror along the horizontal axis (flip vertically). More...

int	SIGNDOC_Image_getPixelValue (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aX, int aY, int *aValue)
	Get the value of a pixel. More...

int	SIGNDOC_Image_setPixelValue (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aX, int aY, int aValue)
	Set the value a pixel. More...

int	SIGNDOC_Image_getPixelRGB (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aX, int aY, int *aColor)
	Get the RGB color of a pixel. More...

int	SIGNDOC_Image_setPixelRGB (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aX, int aY, int aColor)
	Set the RGB color of a pixel. More...

int	SIGNDOC_Image_drawLine (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aX1, int aY1, int aX2, int aY2, double aStrokeWidth, int aColor)
	Draw a line. More...

int	SIGNDOC_Image_drawRect (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aX1, int aY1, int aX2, int aY2, double aRadiusX, double aRadiusY, double aStrokeWidth, int aColor, SIGNDOC_Boolean aFill)
	Draw a rectangle (with both lines parallel to the axes). More...

int	SIGNDOC_Image_drawRect2 (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageRect *aRect, double aRadiusX, double aRadiusY, double aStrokeWidth, int aColor, SIGNDOC_Boolean aFill)
	Draw a rectangle (with both lines parallel to the axes). More...

int	SIGNDOC_Image_getPalette (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, struct SIGNDOC_IntArray *aOutput)
	Get the palette. More...

int	SIGNDOC_Image_setPaletteAt (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, int aIndex, int aColor)
	Set a palette entry. More...

int	SIGNDOC_Image_getHistogram (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, struct SIGNDOC_IntArray *aOutput)
	Compute a histogram. More...

int	SIGNDOC_Image_getComplexity (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, int aOutput)
	Compute the complexity of a signature image. More...

int	SIGNDOC_Image_clean (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, const struct SIGNDOC_CleanParameters aCleanParameters)
	Clean a signature image according to the provided parameters. More...

int	SIGNDOC_Image_cleanSignature (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_ImageRect aRect)
	Clean a signature image. More...

int	SIGNDOC_Image_cleanLines (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters *aImageParameters)
	Clean lines. More...

int	SIGNDOC_Image_cleanDate (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_ImageRect aRect)
	Remove handwritten text from the signature image. More...

int	SIGNDOC_Image_cleanFrames (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters *aImageParameters, double aTrust)
	Clean frames. More...

int	SIGNDOC_Image_removeMargins (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_ImageRect aRect)
	Remove white margins. More...

int	SIGNDOC_Image_getFrames (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_WeightedFrameArray aOutput)
	Get the frames of the image. More...

int	SIGNDOC_Image_getSplitPositions (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_IntArray aOutput)
	Get the vertical split positions of the image. More...

int	SIGNDOC_Image_matchImage (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_Image aOther, const struct SIGNDOC_MatchParameters aMatchParameters, struct SIGNDOC_MatchResult **aOutput)
	Match against a signature image. More...

int	SIGNDOC_Image_matchSignature (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_SignatureData aOther, const struct SIGNDOC_MatchParameters aMatchParameters, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_MatchResult *aOutput)
	Match against a signature. More...

int	SIGNDOC_Image_matchReference (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const struct SIGNDOC_SignatureData aOther, const struct SIGNDOC_MatchParameters aMatchParameters, const struct SIGNDOC_ImageParameters aImageParameters, struct SIGNDOC_MatchResult *aOutput)
	Match against a reference. More...

int	SIGNDOC_Image_saveToMemory (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, struct SIGNDOC_ByteArray aOutput, const struct SIGNDOC_ImageParameters aParameters)
	Save an image to a blob. More...

int	SIGNDOC_Image_saveToMemory2 (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, struct SIGNDOC_ByteArray aOutput, const char aFormat)
	Save an image to a blob. More...

int	SIGNDOC_Image_saveToFile (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aEncoding, const char aPath, const struct SIGNDOC_ImageParameters aParameters)
	Save an image to a file. More...

int	SIGNDOC_Image_saveToFileW (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const wchar_t aPath, const struct SIGNDOC_ImageParameters aParameters)
	Save an image to a file. More...

int	SIGNDOC_Image_saveToFile2 (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aEncoding, const char aPath, const char aFormat)
	Save an image to a file. More...

int	SIGNDOC_Image_saveToFile2W (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, const wchar_t aPath, const char aFormat)
	Save an image to a file. More...

const char *	SIGNDOC_Image_getErrorMessage (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj, int aEncoding)
	Get an error message for the last function call. More...

const wchar_t *	SIGNDOC_Image_getErrorMessageW (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Image aObj)
	Get an error message for the last function call. 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: SIGNDOC_Color_getRGB()

Member Function Documentation

void SIGNDOC_Image_assign	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_Image *	aSource
	)

SIGNDOC_Image assignment operator.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aSource	The source object.

int SIGNDOC_Image_clean	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		const struct SIGNDOC_CleanParameters *	aCleanParameters
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[in]	aCleanParameters	Actions and parameters, must not be NULL.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_cleanDate(), SIGNDOC_Image_cleanFrames(), SIGNDOC_Image_cleanLines(), SIGNDOC_Image_cleanSignature()

int SIGNDOC_Image_cleanDate	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_ImageRect *	aRect
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[out]	aRect	The object pointed to by this argument will be set to a rectangle bounding the signature region within the original image. Can be NULL.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_cleanFrames(), SIGNDOC_Image_cleanLines(), SIGNDOC_Image_cleanSignature()

int SIGNDOC_Image_cleanFrames	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		double	aTrust
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[in]	aTrust	Minimum frame weight (0.0 through 1.0). 0.0 removes dirt, 1.0 removes all frames.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_cleanDate(), SIGNDOC_Image_cleanLines(), SIGNDOC_Image_cleanSignature(), SIGNDOC_Image_getFrames()

int SIGNDOC_Image_cleanLines	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_cleanDate(), SIGNDOC_Image_cleanFrames(), SIGNDOC_Image_cleanSignature()

int SIGNDOC_Image_cleanSignature	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_ImageRect *	aRect
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[out]	aRect	The object pointed to by this argument will be set to a rectangle bounding the signature region within the original image. Can be NULL.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_cleanDate(), SIGNDOC_Image_cleanFrames(), SIGNDOC_Image_cleanLines()

void SIGNDOC_Image_clear	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj
	)

Remove the image from a SIGNDOC_Image object.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

See also: SIGNDOC_Image_setEmpty()

struct SIGNDOC_Image * SIGNDOC_Image_clone	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aSource
	)

Clone a SIGNDOC_Image object.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aSource	The object to be copied.

Returns: A pointer to the new SIGNDOC_Image object.

See also: SIGNDOC_Image_delete()

int SIGNDOC_Image_convertToBiLevel	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters
	)

Convert the image to bi-level black and white.

This function uses thresholding.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_converToGrayscale(), SIGNDOC_Image_convertToTrueColor()

int SIGNDOC_Image_convertToGrayscale	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj
	)

Convert the image to 8-bit grayscale.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_convertToBiLevel(), SIGNDOC_Image_convertToTrueColor()

int SIGNDOC_Image_convertToTrueColor	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj
	)

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_convertToBiLevel(), SIGNDOC_Image_convertToGrayscale()

int SIGNDOC_Image_crop	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aX,
		int	aY,
		int	aWidth,
		int	aHeight
	)

Crop the image.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX	The X coordinate of the upper left corner of the rectangle that will be preserved.
[in]	aY	The Y coordinate of the upper left corner of the rectangle that will be preserved.
[in]	aWidth	The width of the rectangle that will be preserved. Must be positive.
[in]	aHeight	The height of the rectangle that will be preserved. Must be positive.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_getWidth(), SIGNDOC_Image_getHeight(), SIGNDOC_Image_getResolutionX(), SIGNDOC_Image_getResolutionY(), SIGNDOC_Image_removeMargins(), SIGNDOC_Image_resizeToResolution(), SIGNDOC_Image_rotate()

void SIGNDOC_Image_delete ( struct SIGNDOC_Image * aObj )

SIGNDOC_Image destructor.

Parameters

[in] aObj A pointer to the SIGNDOC_Image object.

See also: SIGNDOC_Image_new()

int SIGNDOC_Image_drawLine	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aX1,
		int	aY1,
		int	aX2,
		int	aY2,
		double	aStrokeWidth,
		int	aColor
	)

Draw a line.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX1	X coordinate of the first endpoint of the line.
[in]	aY1	Y coordinate of the first endpoint of the line.
[in]	aX2	X coordinate of the second endpoint of the line.
[in]	aY2	Y coordinate of the second endpoint of the line.
[in]	aStrokeWidth	Stroke width in pixels (need not be an integer, 0 for minimum width).
[in]	aColor	The RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_drawRect(), SIGNDOC_Image_setPixelRGB()

int SIGNDOC_Image_drawRect	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aX1,
		int	aY1,
		int	aX2,
		int	aY2,
		double	aRadiusX,
		double	aRadiusY,
		double	aStrokeWidth,
		int	aColor,
		SIGNDOC_Boolean	aFill
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX1	X coordinate of the first corner of the rectangle.
[in]	aY1	Y coordinate of the first corner of the rectangle.
[in]	aX2	X coordinate of the opposite corner of the rectangle.
[in]	aY2	Y coordinate of the opposite corner of the rectangle.
[in]	aRadiusX	Horizontal radius of quarter ellipse.
[in]	aRadiusY	Vertical radius of quarter ellipse.
[in]	aStrokeWidth	Stroke width in pixels (need not be an integer, 0 for minimum width).
[in]	aColor	The RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.
[in]	aFill	SIGNDOC_TRUE to fill interior of rectangle, SIGNDOC_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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_drawLine(), SIGNDOC_Image_drawRect2(), SIGNDOC_Image_setPixelRGB()

int SIGNDOC_Image_drawRect2	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageRect *	aRect,
		double	aRadiusX,
		double	aRadiusY,
		double	aStrokeWidth,
		int	aColor,
		SIGNDOC_Boolean	aFill
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aRect	The rectangle (does not need to be normalized).
[in]	aRadiusX	Horizontal radius of quarter ellipse.
[in]	aRadiusY	Vertical radius of quarter ellipse.
[in]	aStrokeWidth	Stroke width in pixels (need not be an integer, 0 for minimum width).
[in]	aColor	The RGB color (0x00rrggbb). This function fails if the color does not exist in the palette of an indexed image.
[in]	aFill	SIGNDOC_TRUE to fill interior of rectangle, SIGNDOC_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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_drawLine(), SIGNDOC_Image_drawRect(), SIGNDOC_Image_setPixelRGB()

int SIGNDOC_Image_getBitsPerComponent	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the number of bits per component.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The number of bits per component: 0 (no image), 1 (bi-level), or 8.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getNumberOfComponents()

int SIGNDOC_Image_getBitsPerPixel	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the number of bits per pixel.

This function returns the product of the return values of SIGNDOC_Image_getNumberOfComponents() and SIGNDOC_Image_getBitsPerComponent().

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The number of bits per pixel: 0 (no image), 1 (bi-level), 8 (indexed), or 24 (RGB).

See also: SIGNDOC_Image_getBitsPerComponent(), SIGNDOC_Image_getHeight(), SIGNDOC_Image_getNumberOfComponents(), SIGNDOC_Image_getWidth()

int SIGNDOC_Image_getComplexity	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		int *	aOutput
	)

Compute the complexity of a signature image.

The computed complexity is valid only if aObj 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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[out]	aOutput	The complexity of the signature in the range 0 (simplest) through 100 (most complex) will be stored in the object pointed to by this argument.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean()

const char * SIGNDOC_Image_getErrorMessage	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aEncoding
	)

Get an error message for the last function call.

Note: Do not call SIGNDOC_free() on the return value.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aEncoding	The encoding to be used for the error message (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).

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 aObj is destroyed or a member function of aObj is called.

See also: SIGNDOC_Image_getErrorMessageW()

const wchar_t * SIGNDOC_Image_getErrorMessageW	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get an error message for the last function call.

Note: Do not call SIGNDOC_free() on the return value.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

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 aObj is destroyed or a member function of aObj is called.

See also: SIGNDOC_Image_getErrorMessage()

int SIGNDOC_Image_getFrames	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_WeightedFrameArray *	aOutput
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[in,out]	aOutput	The frames will be stored here.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_cleanFrames(), SIGNDOC_Image_getSplitPositions()

int SIGNDOC_Image_getHeight	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the height of the image.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The height of the image (in pixels) or 0 if there is no image.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getWidth(), SIGNDOC_Image_resizeToResolution()

int SIGNDOC_Image_getHistogram	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		struct SIGNDOC_IntArray *	aOutput
	)

Compute a histogram.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in,out]	aOutput	The histogram will be stored in the object pointed to be this argument. The array will be empty if the image does not use a palette.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getPalette()

int SIGNDOC_Image_getNumberOfComponents	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the number of components.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The number of components: 0 (no image), 1 (indexed), or 3 (RGB).

See also: SIGNDOC_Image_getBitsPerComponent(), SIGNDOC_Image_getBitsPerPixel()

int SIGNDOC_Image_getNumberOfPagesFromFile	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aEncoding,
		const char *	aPath,
		int *	aOutput
	)

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.

aObj is used only for storing any error message.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aEncoding	The encoding of the string pointed to by aPath (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aPath	The pathname of the file to be read.
[out]	aOutput	The number of subimages (pages) will be stored in the object pointed to by this argument.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_getNumberOfPagesFromFileW(), SIGNDOC_Image_getNumberOfPagesFromMemory(), SIGNDOC_Image_loadFromFile()

int SIGNDOC_Image_getNumberOfPagesFromFileW	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const wchar_t *	aPath,
		int *	aOutput
	)

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.

aObj is used only for storing any error message.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPath	The pathname of the file to be read.
[out]	aOutput	The number of subimages (pages) will be stored in the object pointed to by this argument.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_getNumberOfPagesFromFile(), SIGNDOC_Image_getNumberOfPagesFromMemory(), SIGNDOC_Image_loadFromFileW()

int SIGNDOC_Image_getNumberOfPagesFromMemory	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const unsigned char *	aPtr,
		size_t	aSize,
		int *	aOutput
	)

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

aObj is used only for storing any error message.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPtr	A pointer to the first octet of a blob containing an image in BMP (Windows bitmap), TIFF, PNG, or GIF format.
[in]	aSize	Size in octets of the blob pointed to by aPtr.
[out]	aOutput	The number of subimages (pages) will be stored in the object pointed to by this argument.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_loadFromMemory()

int SIGNDOC_Image_getPalette	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		struct SIGNDOC_IntArray *	aOutput
	)

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 SIGNDOC_Image_getBitsPerPixel() returns 1, 256 elements if SIGNDOC_Image_getBitsPerPixel() returns 8, or 0 elements otherwise (the image does not use a palette).

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in,out]	aOutput	The palette will be stored here.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getHistogram()

int SIGNDOC_Image_getPixelRGB	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aX,
		int	aY,
		int *	aColor
	)

Get the RGB color of a pixel.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[out]	aColor	The RGB color (0x00rrggbb) of the pixel will be stored into the object pointed to by this argument.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_getPalette(), SIGNDOC_Image_getPixelValue(), SIGNDOC_Image_setPixelRGB()

int SIGNDOC_Image_getPixelValue	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aX,
		int	aY,
		int *	aValue
	)

Get the value of a pixel.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[out]	aValue	The value of the pixel will be stored into the object pointed to by this argument. If SIGNDOC_Image_getBitsPerPixel() returns 1 or 8, this is the index into the palette, if SIGNDOC_Image_getBitsPerPixel() returns 24, this is the RGB color (0x00rrggbb).

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_getHistogram(), SIGNDOC_Image_getPalette(), SIGNDOC_Image_getPixelRGB(), SIGNDOC_Image_setPixelValue()

int SIGNDOC_Image_getResolutionX	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the horizontal resolution of the image.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The horizontal resolution of the image in DPI, 0 if there is no image.

See also: SIGNDOC_Image_getResolutionY(), SIGNDOC_Image_setResolution()

int SIGNDOC_Image_getResolutionY	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the vertical resolution of the image.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The vertical resolution of the image in DPI, 0 if there is no image.

See also: SIGNDOC_Image_getResolutionX(), SIGNDOC_Image_setResolution()

int SIGNDOC_Image_getSplitPositions	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_IntArray *	aOutput
	)

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[in,out]	aOutput	The X coordinates of the split positions will be stored here, ordered by importance, most important first.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_getFrames()

int SIGNDOC_Image_getWidth	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj
	)

Get the width of the image.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_SignatureData object.

Returns: The width of the image (in pixels) or 0 if there is no image.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getHeight(), SIGNDOC_Image_resizeToResolution()

int SIGNDOC_Image_invert	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		SIGNDOC_Boolean	aAuto
	)

Invert the image.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aAuto	SIGNDOC_FALSE to invert the image unconditionally, SIGNDOC_TRUE to invert the image only if more than half the pixels have brightness (0 through 255) less than 128.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if there is no image.

int SIGNDOC_Image_loadFromFile	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aEncoding,
		const char *	aPath,
		int	aIndex
	)

Load an image from a file.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aEncoding	The encoding of the string pointed to by aPath (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aPath	The pathname of the file to be read.
[in]	aIndex	0-based page number for selecting a subimage (page) of the source image.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_getNumberOfPagesFromFile(), SIGNDOC_Image_loadFromFileW(), SIGNDOC_Image_loadFromMemory(), SIGNDOC_Image_saveToFile(), SIGNDOC_Image_saveToFile2()

int SIGNDOC_Image_loadFromFileW	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const wchar_t *	aPath,
		int	aIndex
	)

Load an image from a file.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPath	The pathname of the file to be read.
[in]	aIndex	0-based page number for selecting a subimage (page) of the source image.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_getNumberOfPagesFromFileW(), SIGNDOC_Image_loadFromFile(), SIGNDOC_Image_loadFromMemory(), SIGNDOC_Image_saveToFileW(), SIGNDOC_Image_saveToFile2W()

int SIGNDOC_Image_loadFromMemory	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const unsigned char *	aPtr,
		size_t	aSize,
		int	aIndex
	)

Load an image from a blob.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPtr	A pointer to the first octet of a blob containing an image in BMP (Windows bitmap), TIFF, PNG, or GIF format.
[in]	aSize	Size in octets of the blob pointed to by aPtr.
[in]	aIndex	0-based page number for selecting a subimage (page) of the source image.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if the blob is invalid.

See also: SIGNDOC_Image_getNumberOfPagesFromMemory(), SIGNDOC_Image_loadFromFile(), SIGNDOC_Image_saveToMemory(), SIGNDOC_Image_saveToMemory2()

int SIGNDOC_Image_matchImage	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_Image *	aOther,
		const struct SIGNDOC_MatchParameters *	aMatchParameters,
		struct SIGNDOC_MatchResult **	aOutput
	)

Match against a signature image.

The license must allow comparing signatures.

Note: Only the static matching engine can be used.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aOther	The signature image to match against.
[in]	aMatchParameters	Parameters controlling how signature are matched. If this argument is NULL, all parameters will be set to their respective default value.
[out]	aOutput	A pointer to a new SIGNDOC_MatchResult object or NULL will be stored here. The caller is responsible for destroying that object.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_matchSignature()

int SIGNDOC_Image_matchReference	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_SignatureData *	aOther,
		const struct SIGNDOC_MatchParameters *	aMatchParameters,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_MatchResult **	aOutput
	)

Match against a reference.

This function fails if aOther does not have type SIGNDOC_SIGNATUREDATA_TYPE_REFERENCE.

The license must allow comparing signatures.

Note: Only the static matching engine can be used.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aOther	The reference to match against.
[in]	aMatchParameters	Parameters controlling how signature are matched. If this argument is NULL, all parameters will be set to their respective default value.
[in]	aImageParameters	Parameters controlling how signature are rendered as images for static matching. If this argument is NULL, all parameters will be set to their respective default value. String parameter "Format" will be ignored.
[out]	aOutput	A pointer to a new SIGNDOC_MatchResult object or NULL will be stored here. The caller is responsible for destroying that object.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_matchSignature(), SIGNDOC_SignatureData_matchReference()

int SIGNDOC_Image_matchSignature	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_SignatureData *	aOther,
		const struct SIGNDOC_MatchParameters *	aMatchParameters,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_MatchResult **	aOutput
	)

Match against a signature.

If aOther has type SIGNDOC_SIGNATUREDATA_TYPE_REFERENCE, SIGNDOC_SignatureData_selectSignature() must be called once for aOther before this function.

This function fails if aOther has type SIGNDOC_SIGNATUREDATA_TYPE_EMPTY.

The license must allow comparing signatures.

Note: Only the static matching engine can be used.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aOther	The signature or reference to match against.
[in]	aMatchParameters	Parameters controlling how signature are matched. If this argument is NULL, all parameters will be set to their respective default value.
[in]	aImageParameters	Parameters controlling how signature are rendered as images for static matching. If this argument is NULL, all parameters will be set to their respective default value. String parameter "Format" will be ignored.
[out]	aOutput	A pointer to a new SIGNDOC_MatchResult object or NULL will be stored here. The caller is responsible for destroying that object.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_matchImage(), SIGNDOC_Image_matchReference(), SIGNDOC_SignatureData_matchSignature()

int SIGNDOC_Image_mirrorX	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj
	)

Mirror along the vertical axis (flip horizontally).

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if there is no image.

See also: SIGNDOC_Image_mirrorY(), SIGNDOC_Image_rotate()

int SIGNDOC_Image_mirrorY	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj
	)

Mirror along the horizontal axis (flip vertically).

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if there is no image.

See also: SIGNDOC_Image_mirrorX(), SIGNDOC_Image_rotate()

struct SIGNDOC_Image * SIGNDOC_Image_new ( struct SIGNDOC_Exception ** aEx )

SIGNDOC_Image constructor.

The new object won't contain an image, SIGNDOC_Image_getWidth() and SIGNDOC_Image_getHeight() will return 0.

Parameters

[out] aEx Any exception will be returned in the object pointed to by this parameter.

Returns: A pointer to the new SIGNDOC_Image object.

See also: SIGNDOC_Image_delete(), SIGNDOC_Image_setEmpty(), SIGNDOC_Image_setResolution()

int SIGNDOC_Image_removeMargins	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		const struct SIGNDOC_ImageParameters *	aImageParameters,
		struct SIGNDOC_ImageRect *	aRect
	)

Remove white margins.

This function removes white margins ignoring single black pixels.

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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aImageParameters	Parameters controlling how images are converted to bi-level black and white. If this argument is NULL, all parameters will be set to their respective default value.
[out]	aRect	The object pointed to by this argument will be set to the rectangle occupied by the new image within the original image. Can be NULL.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT or SIGNDOC_RETURNCODE_UNEXPECTED_ERROR on error.

See also: SIGNDOC_Image_clean(), SIGNDOC_Image_cleanSignature(), SIGNDOC_Image_crop()

int SIGNDOC_Image_resizeToResolution	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aResolutionX,
		int	aResolutionY,
		const char *	aFilter
	)

Resize the image.

This function may change the pixel format.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aResolutionX	The new horizontal resolution of the image in DPI. Must be positive.
[in]	aResolutionY	The new vertical resolution of the image in DPI. Must be positive.
[in]	aFilter	The 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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_crop(), SIGNDOC_Image_getResolutionX(), SIGNDOC_Image_getResolutionY(), SIGNDOC_Image_getWidth(), SIGNDOC_Image_getHeight(), SIGNDOC_Image_getResolutionX(), SIGNDOC_Image_getResolutionY(), SIGNDOC_Image_rotate(), SIGNDOC_Image_setResolution()

int SIGNDOC_Image_rotate	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aAngle,
		int	aBackgroundColor
	)

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 throws an 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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aAngle	Rotation angle (degrees), positive for counter-clockwise, negative for clockwise.
[in]	aBackgroundColor	The 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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_crop(), SIGNDOC_Image_getPalette(), SIGNDOC_Image_mirrorX(), SIGNDOC_Image_mirrorY(), SIGNDOC_Image_resizeToResolution()

int SIGNDOC_Image_saveToFile	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aEncoding,
		const char *	aPath,
		const struct SIGNDOC_ImageParameters *	aParameters
	)

Save an 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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aEncoding	The encoding of the string pointed to by aPath (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aPath	The pathname of the file to be created or overwritten.
[in]	aParameters	Parameters controlling how the format of the blob.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromFile(), SIGNDOC_Image_saveToFile2(), SIGNDOC_Image_saveToFileW(), SIGNDOC_Image_saveToMemory()

int SIGNDOC_Image_saveToFile2	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		int	aEncoding,
		const char *	aPath,
		const char *	aFormat
	)

Save an image to a file.

This is a simplified version of SIGNDOC_Image_saveToFile().

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aEncoding	The encoding of the strings pointed to by aPath and aFormat (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aPath	The pathname of the file to be created or overwritten.
[in]	aFormat	The format to be used for the image blob: "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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromFile(), SIGNDOC_Image_saveToFile(), SIGNDOC_Image_saveToFile2W(), SIGNDOC_Image_saveToMemory2()

int SIGNDOC_Image_saveToFile2W	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const wchar_t *	aPath,
		const char *	aFormat
	)

Save an image to a file.

This is a simplified version of SIGNDOC_Image_saveToFileW().

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPath	The pathname of the file to be created or overwritten.
[in]	aFormat	The format to be used for the image blob: "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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromFileW(), SIGNDOC_Image_saveToFile2(), SIGNDOC_Image_saveToFileW(), SIGNDOC_Image_saveToMemory2()

int SIGNDOC_Image_saveToFileW	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		const wchar_t *	aPath,
		const struct SIGNDOC_ImageParameters *	aParameters
	)

Save an 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

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aPath	The pathname of the file to be created or overwritten.
[in]	aParameters	Parameters controlling how the format of the blob.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromFileW(), SIGNDOC_Image_saveToFile(), SIGNDOC_Image_saveToFile2W(), SIGNDOC_Image_saveToMemory()

int SIGNDOC_Image_saveToMemory	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		struct SIGNDOC_ByteArray *	aOutput,
		const struct SIGNDOC_ImageParameters *	aParameters
	)

Save an image to 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]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in,out]	aOutput	The blob will be stored here.
[in]	aParameters	Parameters controlling how the format of the blob.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromMemory(), SIGNDOC_Image_saveToFile(), SIGNDOC_Image_saveToMemory2()

int SIGNDOC_Image_saveToMemory2	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Image *	aObj,
		struct SIGNDOC_ByteArray *	aOutput,
		const char *	aFormat
	)

Save an image to a blob.

This is a simplified version of SIGNDOC_Image_saveToMemory().

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in,out]	aOutput	The blob will be stored here.
[in]	aFormat	The 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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if the parameters in aParameters are invalid or if aObj does not contain an image.

See also: SIGNDOC_Image_loadFromMemory(), SIGNDOC_Image_saveToFile2(), SIGNDOC_Image_saveToMemory()

int SIGNDOC_Image_setEmpty	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aWidth,
		int	aHeight,
		int	aBitsPerPixel,
		int	aColor
	)

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

The resolution will be set to 72 dots per inch.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aWidth	The width of the image (in pixels). Must be positive.
[in]	aHeight	The height of the image (in pixels). Must be positive.
[in]	aBitsPerPixel	Number of bits per pixel: 1 (bi-level black and white), 8 (grayscale), or 24 (RGB).
[in]	aColor	All 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).

See also: SIGNDOC_Image_setEmpty(), SIGNDOC_Image_setPaletteAt(), SIGNDOC_Image_setResolution()

int SIGNDOC_Image_setPaletteAt	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aIndex,
		int	aColor
	)

Set a palette entry.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aIndex	The 0-based index of the palette entry (0 through 1 if SIGNDOC_Image_getBitsPerPixel() returns 1, 0 through 255 if SIGNDOC_Image_getBitsPerPixel() returns 8).
[in]	aColor	The new color for the palette entry (0x00rrggbb).

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT on error.

See also: SIGNDOC_Image_getBitsPerPixel(), SIGNDOC_Image_getPalette()

int SIGNDOC_Image_setPixelRGB	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aX,
		int	aY,
		int	aColor
	)

Set the RGB color of a pixel.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[in]	aColor	The new RGB color (0x00rrggbb) of the pixel. This function fails if the color does not exist in the palette of an indexed image.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_drawLine(), SIGNDOC_Image_drawRect(), SIGNDOC_Image_getPalette(), SIGNDOC_Image_getPixelRGB(), SIGNDOC_Image_setPixelValue()

int SIGNDOC_Image_setPixelValue	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aX,
		int	aY,
		int	aValue
	)

Set the value a pixel.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[in]	aValue	The new value of the pixel. If SIGNDOC_Image_getBitsPerPixel() returns 1 or 8, this is the index into the palette, if SIGNDOC_Image_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: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_getPalette(), SIGNDOC_Image_getPixelRGB(), SIGNDOC_Image_setPixelValue()

int SIGNDOC_Image_setResolution	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Image *	aObj,
		int	aResolutionX,
		int	aResolutionY
	)

Set the resolution of the image.

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

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Image object.
[in]	aResolutionX	The new horizontal resolution of the image in DPI. Must be positive.
[in]	aResolutionY	The new vertical resolution of the image in DPI. Must be positive.

Returns: SIGNDOC_RETURNCODE_OK if successful, SIGNDOC_RETURNCODE_INVALID_ARGUMENT if an argument is invalid or if there is no image.

See also: SIGNDOC_Image_getResolutionX(), SIGNDOC_Image_getResolutionY(), SIGNDOC_Image_resizeToResolution()

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

SignDocSDK-c.h

Public Member Functions

Detailed Description

Member Function Documentation