CImage library

ConcatenateImage

Combines two image files into a single image file

Note: This function only works on image files and not on the internal image. The source files must not be of the same type (for example, one may be a TIF type and the second can be a JPG type).

The function works in the following sequence:

Imports SourceImage0 to an ImageObject0
Rotates ImageObject0 by Angle0
Imports SourceImage1 to an ImageObject1
Rotates ImageObject1 by Angle1
Combines Image0 and Image1 one on top of each other (if CombType is equal to IMAGE_COMB_VERTICAL) or one to the left of the other (if CombType is equal to IMAGE_COMB_ HORIZONTAL
Saves the resulting image to an external file or to the clipboard.

Syntax

ConcatenateImage(SourceImage0 As String, Angle0 As Long, SourceImage1 As String, Angle1 As Long, CombType As Long, DestType As Long, DestImage As String) As Long

Parameters

Parameter	Description
[in] SourceImage0	Full path name of the first image
[in] Angle0	The angle to rotate SourceImage0 before the combination
[in] SourceImage1	Full path name of the second image
[in] Angle1	The angle to rotate SourceImage1 before the combination
[in] CombType	Location of the images in the result image file:
[in]DestType	Destination of the rotated image:
[in]DestImage	Full path name of the destination file; ignored if DestType is set to SAVE_TO_CLIPBOARD

Return Values

Value	Description
IMG_ERR_SUCCESS	Function succeeded
LICENSE_INVALID	License invalid; library not initialized with proper license
IMG_ERR_BAD_ANGLE_0	Bad rotation parameter for SourceImage0
IMG_ERR_BAD_ANGLE_1	Bad rotation parameter for SourceImage1
IMG_ERR_FILE_OPEN_FIRST	Can’t open SourceImage0 file
IMG_ERR_FILE_OPEN_SECOND	Can’t open SourceImage1 file
IMG_ERR_BAD_DESTINATION	Bad destination parameter (not file or clipboard)
IMG_ERR_FILE_OPEN	Can’t open input file; SourceImage string is not empty but points to missing or invalid source image file
INVALID_INTERNAL_IMAGE	No document scanned (internal image in the memory); SourceImage string empty
IMG_ERR_FILE_SAVE_TO_CLIPBOARD	Can’t save image to the clipboard
IMG_ERR_FILE_SAVE_TO_FILE	Can’t save destination file; invalid destination file or disk save error

ConvertImage

This function is a shorter version of the RotateImage**()** function. It takes an input file (if SourceImage is not empty) or uses the internal image as a source (if SourceImage is empty) and saves it to a file. Using different file extensions for the source and the destination converts the image type to the desired type.

Image type conversion must be done carefully because some color schemes are not supported in all file types.

The following table shows the available destination types and the color schemes they are capable of storing:

Destination image extension	Destination image type
Destination image extension	True color (24-bit)	256 colors (8-bit)	Grayscale (8-bit)	Black & White (1-bit)
BMP	√	√	√	√
TIF	√		√	√
JPG	√		√
PCX	√	√	√
TGA	√	√	√
PNG	√	√	√
PSD	√

Note: This table is applicable to all functions in this library.

Syntax

 ConvertImage(SourceImage As String, DestImage As String) As Long

Parameters

Parameter	Description
[in] SourceImage	Full path name of the original image file. If this string is empty, the rotation is performed on the internal image.
[in] DestImage	Full path name of the destination file

Return Values

Value	Description
IMG_ERR_SUCCESS	Function succeeded
LICENSE_INVALID	Library not initialized with proper license
IMG_ERR_BAD_DESTINATION	Bad destination parameter (not file or clipboard)
IMG_ERR_FILE_OPEN	Can’t open input file; SourceImage string is not empty but points to missing or invalid source image file
INVALID_INTERNAL_IMAGE	No document scanned (internal image in the memory); SourceImage string empty
IMG_ERR_FILE_SAVE_TO_FILE	Can’t save destination file; invalid destination file or disk save error

GetImageBufferData

Gets a copy of the internal image buffer. If successful, the function formats the image using the image format specified by the sFileType parameter and copies it to the pBuf. The application can dump content of pBuf to the hard drive as a binary file while assigning it a proper file extension, creating a standard image file.

Syntax

GetImageBufferData(sFileType As String, sBuffer As String) As Long

Parameters

Parameter	Description
[in] sFileType	Sets the buffer image format. May be one of the following strings (case insensitive): BMP \| PNG \| JPG \| PCX \| PSD \| TIF \| TGA
[in] sBuffer	A string buffer that contains the image content upon successful return

Return Values

Value	Description
BAD_IMAGE_DUMP	Function failed
INVALID_INTERNAL_IMAGE	Can’t process image; internal image buffer is empty or invalid
IMG_ERR_SUCCESS	Function processed successfully

GetImageBufferDataDirect

Gets a copy of the internal image buffer. If successful, the function will format the image using the image format specified by the sFileType parameter. The application can dump the content of the return buffer data to the hard drive as a binary file while assigning it a proper file extension, creating a standard image file.

Syntax

GetImageBufferDataDirect(sFileType As String) As String

Parameters

Parameter	Description
sFileType	Sets the buffer image format. May be one of the following strings (case insensitive): BMP \| PNG \| JPG \| PCX \| PSD \| TIF \| TGA

Return Values

Returns a string buffer that contains the image content

GetImageBufferDataBack

Gets a copy of the internal image buffer. If successful, the function will format the image using the image format specified by the sFileType parameter and copies it to the pBuf. The application can dump content of pBuf to the hard drive as a binary file while assigning it a proper file extension, creating a standard image file.

Syntax

GetImageBufferDataBack(sFileType As String, sBuffer As String) As Long

Parameters

Parameter	Description
pBuf	A string buffer that contains the back image content upon successful return
sFileType	Sets the buffer image format. May be one of the following strings (case insensitive): BMP \| PNG \| JPG \| PCX \| PSD \| TIF \| TGA

Return Values

Value	Description
BAD_IMAGE_DUMP	Failed to dump the Back image buffer; internal error
INVALID_INTERNAL_IMAGE	Can’t process back image; internal image buffer is empty or invalid
IMG_ERR_SUCCESS	Function processed successfully

GetImageBufferDataBackDirect

Gets a copy of the internal image buffer. If successful, the function will format the image using the image format specified by the sFileType parameter and copies it to the pBuf. The application can dump content of pBuf to the hard drive as a binary file while assigning it a proper file extension, creating a standard image file.

Syntax

GetImageBufferDataBack(sFileType As String) As String

Parameters

Parameter	Description
sFileType	Sets the buffer image format. May be one of the following strings (case insensitive): BMP \| PNG \| JPG \| PCX \| PSD \| TIF \| TGA

Return Values

Returns a string buffer that contains the back image content

GetImageDimensions

Finds the image dimension in pixels

Syntax

GetImageDimensions(fileName As String, Width As Long, Height As Long) As Long

Parameters

Parameter	Description
fileName	Image file name (or empty string if referring to the internal image)
Width	Returns the width of the image (in pixels)
Height	Returns the height of the image (in pixels)

Return Values

Value	Description
IMG_ERR_FILE_OPEN	Failed to open input file
INVALID_INTERNAL_IMAGE	Can’t process image; internal image buffer is empty or invalid
IMG_ERR_SUCCESS	Function processed successfully

GetImageProperties

Finds the image color scheme and resolution. The color scheme may be set to one of the following:

Color scheme	Image description
IMAGE_COLOR_TRUE	A TRUE COLOR image (24-bit)
IMAGE_COLOR_256	Contains 256 colors
IMAGE_GRAY_256	Contains 256 gray colors
IMAGE_BW	Contains black and white only

Syntax

GetImageProperties(fileName As String, Color As Long,
dpi As Long) As Long

Parameters

Parameter	Description
[in] fileName	Image file name (or empty string if referring to the internal image)
[out] Color	Returns the image color scheme
[out] dpi	Returns the image resolution in dots per inch (dpi)

Return Values

Value	Description
IMG_ERR_FILE_OPEN	Failed to open input file
INVALID_INTERNAL_IMAGE	Can’t process image; internal image buffer is empty or invalid
IMG_ERR_SUCCESS	Function processed successfully

ImageColor

Returns the ImageColor value in Long format (read-only)

Syntax

ImageColor As Long

Parameters

None

Return Values

Returns the ImageColor value

ImageDPI

Returns the ImageDPI value in Long format (read-only)

Syntax

ImageDPI As Long

Parameters

None

Return Values

Returns the ImageDPI value

ImageHeight

Returns the ImageHeight value in string format (read-only)

Syntax

ImageHeight As String

Parameters

None

Return Values

Returns the ImageHeight value

ImageWidth

Returns the ImageWidth value in string format (read-only)

Syntax

ImageWidth As String

Parameters

None

Return Values

Returns the ImageWidth value

ImgDespeckle

Cleans random pixels from black and white images. Such noise may be shown when converting images with gradient color transition from color to black and white color. The higher the value set in maxBlobArea, the more details in the image will be considered.

Syntax

ImgDespeckle(ImgFile As String, maxBlobArea As Long) As Long

Parameters

Parameter	Description
sImageFileType	Source image file name or an empty string if referring to the internal image
maxBlobArea	Maximum area size (in square pixels) of random pixels that will be considered as noise and will be removed from the image (DEFAULT is 30)

Return Values

Value	Description
IMG_ERR_FILE_OPEN	Failed to open input file specified by sImageFile
INVALID_INTERNAL_IMAGE	Can’t process image; internal image buffer is empty or invalid
IMG_ERR_SUCCESS	Function processed successfully

InitLibrary

Initializes the CImage library

Note: This function must be called before calling any other function in the library.

Syntax

InitLibrary(license As String) As Long

Parameters

Parameter	Description
[in] license	Null-terminated string that contains the license key value

Return Values

Value	Description
LICENSE_VALID	Library initialized successfully and is ready to use
LICENSE_INVALID	Library failed to initialize because the license is invalid; all scanner operations disabled
LICENSE_EXPIRED	Library failed to initialize because the license has expired; all scanner operations disabled
LICENSE_DOES_NOT_MATCH_LIBRARY	License invalid for this library; all library functions disabled

JpgQuality

Returns the JpgQuality value in Integer format (read-only)

Syntax

JpgQuality As Integer

Parameters

None

Return Values

Returns the JpgQuality value

ReformatImage

Modifies the image color scheme and resolution and saves it to a file in any one of seven formats. The manipulated image may be loaded from an external file (if SourceImage string holds a string value equal to the source image file name) or performed on the internal image buffer (if SourceImage string is empty). When using a file as the image source, it is important to use the proper file extension to indicate the image format. Proper extension types are: BMP, JPG, TIFF, PCX, PNG, TGA, and PSD. If an image has an unrecognizable extension due to an error (for example, TIF instead of TIFF), the function refers to the file as BITMAP.

Image reformatting can be done either on the image color scheme, on the image dpi, or both. Notice that changing the image format may lose the image color information (for example, when converting from 24-bit true color to 256 grayscale). Modifying an image format from 256 grayscale to 24-bit true color will obviously not add color to the image but it will save the image with the proper RGB format (no color map) instead of using the 256 grayscale palette.

After the image is reformatted, it can be exported to an external image file. The destination file name may be one of the seven file formats indicated above. If the destination file name has an unrecognizable extension, the function exports to the file in a BITMAP format (the default format). If no destination image file name is provided (empty string), then the image is not saved.

Note: The 256-color scheme is not supported for JPG and TIFF files.

Syntax

ReformatImage(SourceImage As String, toColor As Integer, toDpi As Integer, DestImage As String)

Parameters

Parameter	Description
[in] SourceImage	Full path name of the original image file. If this string is empty, the rotation is performed on the internal image
[in] toColor	One of the following values:
[in] toDpi	Sets the new image DPI (a value of 0 indicates no DPI modification)
[in] DestImage	Full path name of the destination file (If an empty string, no save performed)

Return Values

Value	Description
IMG_ERR_BAD_COLOR	Bad toColor parameter value
IMG_ERR_BAD_DPI	Bad toDpi parameter value
IMG_ERR_FILE_OPEN	Can’t open input file. Returned if SourceImage string is not empty but points to a missing or invalid source image file
INVALID_INTERNAL_IMAGE	Returned if SourceImage string is empty but no document was scanned (no internal image in memory)
IMG_ERR_FILE_SAVE_TO_FILE	Can’t save destination file due to an invalid destination file or disk save error
IMG_ERR_SUCCESS	Function processed successfully

RotateImage

Rotates an image by 0, 90, 180, or 270 degrees and saves it to a file in one of 7 formats. The manipulated image may be loaded from an external file (if SourceImage string holds a string value equal to the source image file name) or performed on the internal image buffer (if SourceImage string is empty). When using a file as the image source, it is important to use the proper file extension to indicate the image format. Proper extension types are: BMP, JPG, TIFF, PCX, PNG, TGA, and PSD. If an image has an unrecognizable extension due to an error (for example, TIF instead of TIFF), the function refers to the file as BITMAP.

After the image is rotated, it can be exported to either the clipboard or to an external image file. The destination file name may be one of the seven file formats indicated above. If an image has an unrecognizable extension due to an error (for example, TIF instead of TIFF), the function exports the file in a BITMAP format. The destination file name may be the same as the source file name. In such a case, the new file, resulting with a rotated image, will overwrite the original file. If no destination image file name is provided (empty string), then the image is not saved.

Note: Do not be misled by the name of this function.

The RotateImage function’s flexibility actually allows you to do the following implicitly:

Function call	Description
RotateImage (“xxx.bmp”, ANGLE_0, SAVE_TO_FILE, “xxx.jpg”)	Converts an image file from one type to another
RotateImage (“xxx.bmp”, ANGLE_0, SAVE_TO_CLIPBOARD, “”)	Copies an image file to the clipboard
RotateImage (“”, ANGLE_0, SAVE_TO_FILE, “”)	Rotates the internal image
RotateImage (“”, ANGLE_0, SAVE_TO_FILE, “xxx.bmp”)	Saves the internal image to a file

Syntax

RotateImage(SourceImage As String, Angle As Long, DestType As Long, DestImage As String)

Parameters

Parameter	Description
[in] SourceImage	Full path name of the original image file. If this string is empty, the rotation is performed on the internal image.
[in] Angle	Angle to rotate original image:
[in] DestType	Destination of the rotated image:
[in] DestImage	Full path and name of the destination file. This parameter is ignored if the parameter DestType is set to SAVE_TO_CLIPBOARD. If this value is an empty string, no save is performed.

Return Values

Value	Description
IMG_ERR_SUCCESS	Function succeeded
LICENSE_INVALID	License invalid; library not initialized with proper license
IMG_ERR_BAD_ANGLE_0	Bad rotation parameter
IMG_ERR_BAD_DESTINATION	Bad destination parameter (not file or clipboard)
IMG_ERR_FILE_OPEN	Can’t open input file; SourceImage string is not empty but points to missing or invalid source image file
INVALID_INTERNAL_IMAGE	No document scanned (internal image in the memory); SourceImage string empty
IMG_ERR_FILE_SAVE_ TO_CLIPBOARD	Can’t save image to the clipboard due to error
IMG_ERR_FILE_SAVE_TO_FILE	Can’t save destination file; invalid destination file or disk save error

textStampOnImg

Stamps text on the horizontal center of the image and the vertical location specified. The vertical alignment of the text is set by the vertLocation parameter as follows:

IMAGE_TOP	Prints the text on the upper portion of the image
IMAGE_MIDDLE	Prints the text on the middle portion of the image
IMAGE_BOTTOM	Prints the text on the bottom portion of the image

Syntax

textStampOnImg(srcFile As String, text As String, textHeight As Long, vertLocation As Long, textColor As Long, dstFile As String) As Long

Parameters

Parameter	Description
[in] srcFile	Full path name of the original image file. If this string is empty, the rotation is performed on the internal image.
[in] text	Text to print on the image
[in] textHeight	Height of the text, in pixels
[in] vertLocation	Location of the text in the image (top, middle, bottom).
[in] textColor
[in] dstFile

Return Values

Value	Description
IMG_ERR_SUCCESS	Function succeeded
INVALID_INTERNAL_IMAGE	Can’t process image; internal image buffer is empty or invalid
IMG_ERR_BAD_PARAM	Bad vertical location parameter
IMG_ERR_FILE_OPEN	Can’t open input file

textStampOnImgEx

Stamps text on an image in the location specified by horizontalPos and verticalPos

Syntax

TextStampOnImgEx(sourceFile As String, Text As String, color As Long, opacity As Long, verticalPos As Long, horizontalPos As Long, fontName As String, fontSize As Long, bold As Long, bUnderline As Long)

Parameters

Parameter	Description
image	Source image file name (or empty string if referring to the internal image)
txt	Text to print on the image
color	Color of the text (RGB)
Opacity	Opacity value of the text color
vertPos	Location of the text in the image
horizontalPos	Location of the text in the image
fontName	Name of the font
fontSize	Size of the font
bold	Indicates whether to use boldface
bUnderline	Indicates whether to use underline

Return Values

None

Version

Returns the Version value in string format (read-only)

Syntax

Version As String

Parameters

None

Return Values

Returns the Version value