IdData library

The IdData library is where most of the image processing and data extraction is being handled. The library fetches the internal image (the last scanned image), processes its graphic information and activates the OCR. The resultant text is kept in internal data structure ready to be retrieved by the application.

Note: The library processes only the last image that was recently scanned. The library does not support external image file processing.

AutoDetectState

Automatically detects the state type according to the image. If the function returns with no error values, then the return value is the state ID. This value can be assigned to the IdState input parameter in the ProcState function for data extraction.

Syntax

AutoDetectState(Reserved As String) As Long

Parameters

Parameter	Description
[in] Reserved	Reserved; null-terminated empty string

Return Values

Value	Description
LICENSE_INVALID	License invalid; all scanner operations disabled
LICENSE_EXPIRED	License expired; all scanner operations disabled
INVALID_INTERNAL_IMAGE	No internal image loaded; must scan an image first
ID_ERR_STATE_NOT_SUPPORTED	License image does not match any state template
ID_ERR_STATE_NOT_RECOGNIZED	License image does not match any state template

AutoDetectStateEx

Use this function to automatically align the internal image horizontally and then to detect the angle of rotation.

If the function returns with none of the above error values, then the return value is the state ID. This value can be assigned to the IdState input parameter in the ProcState function for data extraction. The function loads in the parameter an angle of one of the following values:

ANGLE_0	Image received in proper alignment
ANGLE_90	Image rotated once by 90 degrees (clockwise)
ANGLE_180	Image rotated twice by 90 degrees (clockwise)
ANGLE_270	Image rotated three times by 90 degrees (clockwise)

You can dump the rotated image from the internal buffer to a file using the RotateImage function.

Syntax

AutoDetectStateEx(Reserved As String, angle As Long) As Long

Parameters

Parameter	Description
[in] Reserved	Reserved; Null-terminated empty string
[out] Angle	Returns the number of clockwise 90 degree turns that the image was rotated to be aligned horizontally

Return Values

Value	Description
LICENSE_INVALID	License invalid; all scanner operations disabled
ID_ERR_USA_TEMPLATES_NOT_FOUND	Template database UsaIds.bin file for U.S. missing from the SDK files location
INVALID_INTERNAL_IMAGE	No internal image loaded; must scan an image first
ID_ERR_STATE_NOT_SUPPORTED	License image does not match any state template
ID_ERR_STATE_NOT_RECOGNIZED	License image does not match any state template

InitLibrary

Initialize the COcr 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 the license key value

Return Values

Value	Description
LICENSE_INVALID	License invalid; all scanner operations disabled
LICENSE_EXPIRED	License expired; all scanner operations disabled
LICENSE_DOES_NOT_MATCH_LIBRARY	License invalid for this library; all library operations disabled
GENERAL_ERR_PLUG_NOT_FOUND	Error returned if attached scanner is not one of these scanners: ScanShell® 600. ScanShell® 800. ScanShell® 1000
SLIB_LIBRARY_ALREADY_INITIALIZED	InitLibrary function call ignored; library already loaded

ProcState

Processes the internal image acquired in the previous scan. The function deskews (straightens) and cleans the image and then passes it to the OCR for analysis. The resultant textual data is kept in internal structure ready for retrieval by the RefreshData function. Processing the image does not modify the image content.

Successful image processing depends on the following:

The image must be scanned in 24-bit (true color) and 300 dpi.
The image must be aligned horizontally with a tolerance of no more than ±10 degrees.

Syntax

ProcState(Reserved As String, idState As Long) As Long

Parameters

Parameter	Description
[in] Reserved	Reserved; Null-terminated empty string
[in] idState	Constant numeric value of the processed state ID

Return Values

Value	Description
ID_TRUE	Function succeeded
LICENSE_INVALID	License invalid; library not initialized
SLIB_ERR_SCANNER_NOT_FOUND	Scanner not connected to PC; all scanner operations disabled. Check the scanner connection. Restart the function
SLIB_ERR_INVALID_SCANNER	Attached scanner invalid
ID_ERR_STATE_NOT_SUPORTED	Requested state ID not supported
INVALID_INTERNAL_IMAGE	No internal image loaded; must scan an image first

GetFaceImage

Extracts an image rectangle of a person’s face from the source ID image. The source image can be either:

Internal Image - The last scanned image (stored in the internal memory). Used only if SourceFileName string is empty.
External Image File - The full file name is given in SourceFileName parameter. If an external file is used as the source image, it must be a 24-bit image (true color) and have a resolution of 300 dpi. The source and file destination can be one of the following formats: BMP, TIFF, JPG, PCX, TGA, PNG, and PSD. To set the image format, use the proper file extension.

Syntax

 GetFaceImage(SourceFileName As String, DestFileName As String,
   stateId As Integer) As Long

Parameters

Parameter	Description
[in] SourceFileName	Null-terminated string that contains the full path of the scanned ID image. If empty, uses the internal image as the image source
[in] DestFileName	Null-terminated string that contains the full name of the destination image file (which contains the face image from the ID document)
[in] stateId	State index value as defined in idLibDef.bas file

Return Values

Value	Description
ID_TRUE	Function succeeded
LICENSE_INVALID	License invalid; library not initialized
ID_ERR_FILE_OPEN	Failed to load source image (if SourceFileName is not empty)
INVALID_INTERNAL_IMAGE	No internal image loaded; must scan an image first
ID_ERR_STATE_NOT_SUPORTED	Requested state ID not supported
ID_BAD_DESTINATION_FILE	Bad destination path (could not create the destination file)
ID_FALSE	Internal processing error
ID_ERR_FACE_IMAGE_ NOT_FOUND	Can’t detect face image in the driver’s license image
ID_ERR_CANNOT_DELETE_ DESTINATION_IMAGE	A file with the same name as the destination file already exists and can’t be overwritten
ID_ERR_CANNOT_COPY_ TO_DESTINATION	Destination file can’t be opened for write

GetFirstCountry

Gets the first country in the countries list. Combining this function with the function GetNextCountry lets you get the constant values of all supported countries. The countries’ constant values in the Region are not always consecutive and should be obtained using the GetNextCountry function.

Syntax

 GetFirstCountry( ) As Long

Return Values

Returns the constant value of the first country in the countries list.

GetFirstStateByCountry

Retrieves the first state constant in the country. The states constant values in the country are not always consecutive and should be obtained using the GetNextStateByCountry function.

Syntax

 GetFirstStateByCountry(country As Integer) As Long

Parameters

Parameter	Description
[in] country	Constant value of the country

Return Values

Value	Description
ID_ERR_NO_MATCH	Bad country constant; otherwise, the returns the constant value of the first state in the country

GetNextCountry

Gets the next country in the country list. To get the countries list, call GetFirstCountry once to obtain the first country and then continuously call GetNextCountry until ID_ERR_NO_NEXT_COUNTRY is returned.

Syntax

 GetNextCountry() As Long

Parameters

Parameter	Description
[in] country	Constant value of the country

Return Values

Value	Description
ID_ERR_COUNTRY_NOT_INIT	The GetFirstCntry function not previously called
ID_ERR_COUNTRY_NOT_INIT	Bad country constant; otherwise, returns the constant value of the first state in the country
ID_ERR_COUNTRY_NOT_INIT	Last country in the list

GetNextStateByCountry

Gets the next state in the list

Syntax

GetNextStateByCountry(country As Integer) As Long

Return Values

Value	Description
ID_ERR_ NO_MATCH	Bad country constant; otherwise, returns the constant value of the first state in the country
ID_ERR_COUNTRY_NOT_INIT	GetFirstCountry function not previously called
ID_ERR_NO_NEXT_STATE	Last state on the country state list

GetSignImage

Extracts the image rectangle of the person’s signature from the source ID image. The source image can be either:

Internal Image - The last scanned image (stored in the internal memory). Used only if SourceFileName string is empty.
External Image File - The full file name is given in SourceFileName parameter. If an external file is used as the source image, it must be a 24-bit image (true color) and have a resolution of 300 dpi. The source and file destination can be one of the following formats: BMP, TIFF, JPG, PCX, TGA, PNG, PSD. To set the image format, use the proper file extension.

Syntax

 GetSignImage(SourceFileName As String, DestFileName As String,
    stateId As Integer) As Long

Parameters

Parameter	Description
[in] SourceFileName	Null-terminated string that contains the full path of the scanned ID image. If empty, uses the internal image as the image source
[in] DestFileName	Null-terminated string that contains the full name of the destination
[in] stateId	State index value as defined in idLibDef.bas file

Return Values

Value	Description
ID_TRUE	Function succeeded
LICENSE_INVALID	License invalid; library not initialized
ID_ERR_FILE_OPEN	Failed to load source image (if SourceFileName is not empty)
INVALID_INTERNAL_IMAGE	No internal image loaded; image must first be scanned
ID_ERR_STATE_NOT_SUPPORTED	Requested state ID not supported
ID_BAD_DESTINATION_FILE	Bad destination path (could not create the destination file)
ID_FALSE	Internal processing error
ID_ERR_FACE_IMAGE_ NOT_FOUND	Can’t detect face image in the driver’s license image
ID_ERR_CANNOT_DELETE_ DESTINATION_IMAGE	A file with the same name as the destination file already exists and can’t be overwritten
ID_ERR_CANNOT_COPY_ TO_DESTINATION	Destination file can’t be opened for write

RefreshData

Loads library properties with recently detected data. This function should normally be called after the execution of the ProcState function.

Syntax

 RefreshData() As Long

Return Values

A non-zero value indicates that the data was successfully retrieved.

RefreshDataAu

Loads library properties with recently detected data. This function should normally be called after the execution of the ProcState function.

Syntax

 RefreshDataAu() As Long

Return Values

A non-zero value indicates that the data was successfully retrieved.

State2Id

This helper function is used to convert a state name (string) to its equivalent ID value. For example, passing the StateName loaded with the string California will return the value 4. The function converts the string to the ID even if the state is not supported by the library.

Syntax

 State2Id(StateName As String) As Long

Parameters

Parameter	Description
[in] StateName	A string that contains the state name

Return Values

Value	Description
ID_ERR_NO_MATCH	State ID if the StateName is a recognizable state name if the string contains an unrecognizable state name

See Also

Id2State(), LastStateIndex

Id2Country

Converts a country ID to the country name (string)

Syntax

 Id2Country(countryId As Integer, CountryName As String) As Long

Parameters

Parameter	Description
[in] countryId	An integer that contains the country ID value
[out] countryName	A string that is loaded by the function with the country name

Return Values

Value	Description
ID_TRUE	Function succeeded
ID_ERR_NO_MATCH	No country found with such ID

Id2State

Converts a state ID to the state name (string)

Example

Passing the stateId loaded with a value of 4 loads the string StateName with the string California. The function converts the string to the ID even if the state is not supported by the library.

Syntax

 Id2State(stateId As Integer, StateName As String) As Long

Parameters

Parameter	Description
[in] stateId	An integer that contains the state ID value
[out] StateName	A string that is loaded by the function with the state name

Return Values

Value	Description
ID_TRUE	Function succeeded
ID_ERR_NO_MATCH	No country found with such ID

See Also

State2Id(), LastStateIndex

StateIsSupported

Informs the application if the ID image of a given state can be processed

Syntax

 StateIsSupported(stateId As Integer) As Long

Return Values

Value	Description
ID_TRUE	State is supported and can be detected by the library
LICENSE_INVALID	License invalid; library not initialized
ID_ERR_STATE_NOT_SUPORTED	Requested state ID not supported

GetDetectAcuracy

This helper function checks the detected data values and returns a value that indicates the detection accuracy (in percentage). This function, combined with the RotateImage function is useful when implementing the auto-orientation feature in the application. This feature can be implemented by rotating the internal image and for each new position it executes the ProcState function. The operation success can be evaluated using GetDetectAcuracy, which determines whether the image is in the right orientation or if a new rotation-detection-inspection is needed.

Syntax

 GetDetectAcuracy() As Long

Return Values

Returns a number in the range 0–100 that estimates the detection accuracy percentage

CountySupportAutoDetect

Determines which countries can use the AutoDetectState function

Note: The state auto-detection feature is not implemented on all the supported countries.

Syntax

 CountySupportAutoDetect(countryId As Integer) As Long

Parameters

Parameter	Description
[in] countryId	An integer that contains the country ID value

Return Values

Value	Description
ID_TRUE	Country supports auto detection
ID_FALSE	Country does not support auto detection

idData library properties

The idData library stores the detected textual information in an internal data structure. This structure is refreshed in each RefreshData function call. Some of the properties are relevant to some states and some are irrelevant. For example, the Weight property is relevant to ID cards of states such as Arizona, California and Georgia but it does not exist in states such as Arkansas or Michigan. If a property is irrelevant to a particular state, or if the field is not detected, it clears to an empty string. Loading the properties is done using a simple string assignment. The Name field is parsed and generates four additional fields (First name, Middle name, Last name and Name suffix).

The supported properties are:

Name (as shown on card)	NameFirst	NameMiddle
NameLast	NameSuffix	ID
License	IssueDate	License
Address	ExperationDate	CSC
City	Eyes	Dup_Test
State	Hair	Endorsements
Zip	Height	Fee
County	Class	Restriction
DateOfBirth	Sex	SigNum
Type	Weight	Address2
Address3	Address4	Address5
Text1	Text2	Text3
Side

An additional property is LastStateIndex. It is useful when iterating in a loop between the entire state IDs from the first (index 0) to the last one.