CImage library

The CImage library is a collection of graphic functions, capable of manipulating an image object. The image object may be loaded from an external file or the image object stored in the ScanLib library (which is the image of the last scanned document).

The library functions can perform the following:

Image rotation: Rotates an image by 90, 180 or 270 degrees
Resolution modification: Modifies the resolution to any value
Image color conversion: Converts the image to 24-bit (true color), 256 colors (gray or color) or black and white (1-bit)
Concatenate two image files to a single image: Attaches two images (horizontally or vertically) to form a single image file of both ID card sides

The image can be exported (saved) to an external image file in any one of seven popular image formats such as BMP, JPG, TIFF, PCX, PNG, TGA and PSD. Alternatively, the image object can be exported to the clipboard and from there, be imported to other applications.

InitLibrary

Use this function to initialize the CImage library. 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 license key value

Return Values

Value	Description
LICENSE_VALID	License valid; library ready for use
LICENSE_INVALID	License invalid; all scanner operations disabled
LICENSE_EXPIRED	License has expired. All scanner operations are disabled
LICENSE_DOES_NOT_MATCH_LIBRARY	License invalid for library; all library operations disabled

GetImageColor

Obtains the image color scheme

Syntax

 GetImageColor(FileName As Integer) As Long

Parameters

Parameter	Description
[in] FileName	Image file name or empty string if evaluating the internal image

Return Values

Value	Description
IMG_ERR_FILE_OPEN	Can’t open input image file
INVALID_INTERNAL_IMAGE	Invalid internal image; image can’t be scanned
IMAGE_BW	Image contains Black and White colors (1- bit image)
IMAGE_GRAY_256	Image contains 256 colors of gray (8-bit image)
IMAGE_COLOR_256	Image contains 256 colors (8-bit image)
IMAGE_COLOR_TRUE	Image contains 16 million colors (24-bit image)

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.

Do not be misled by the name of this function. This 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] 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.
[in] Angle	Angle to rotate original image:
[in] DestType	Destination of the rotated image:

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 (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

ConvertImage

This function is a shorter version of the function RotateImage. 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:

File extension	Destination image type
File 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 _
       )

Parameters

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

Return Values

Value	Description
IMG_ERR_SUCCESS	Function succeeded
LICENSE_INVALID	License invalid; Library not initialized with proper license
IMG_ERR_BAD_DESTINATION	Bad destination parameter (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

ReformatImage

Use this function to modify the image color scheme and resolution and save 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_DP	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

ConcatenateImage

Combines two image files into a single image file. The function follows this sequence:

Imports SourceImage0 to an image object 0.
Rotates image object0 by Angle0.
Imports SourceImage1 to an image object 1.
Rotates image object1 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.

Note: This function only works on image files and not on the internal image.

Syntax

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

Parameters

Parameter	Description
[in] SourceImage0	Full path name of the first image.
[in] Angle0	Angle to rotate the SourceImage0 before the combination.
[in] SourceImage1	Full path name of the second image.
[in] Angle1	Angle to rotate SourceImage0 before the combination.
[in] CombType	Location of the images in the result image file:
[in] DestType	Destination of rotated image:
[in] DestImage	Full path 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 Image 0
IMG_ERR_BAD_ANGLE_1	Bad rotation parameter for Image 1
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_COMB_TYPE	Bad CombType value
IMG_ERR_FILE_SAVE_TO_CLIPBOARD	Can’t save image to clipboard
IMG_ERR_FILE_SAVE_TO_FILE	Can’t save destination file (bad destination path or disk error)