IDKit - Fingerprint Identification SDK

Transcription

1 IDKit - Fingerprint Identification SDK Copyright (c) Innovatrics. All rights reserved.

2 IDKit - Fingerprint Identification SDK Table of Contents Overview 1 Usage Overview 1 Product Differences 2 Similarity Scores 3 Identification Speed 4 Database Connectivity 5 ODBC Data Source Configuration 6 Image Processing 7 API Reference 9 Functions 9 Initialization 9 IEngine_InitModule Function 9 IEngine_InitClient Function 10 IEngine_InitWithLicense Function 10 IEngine_TerminateModule Function 11 Connections 11 IEngine_InitConnection Function 11 IEngine_SelectConnection Function 12 IEngine_CloseConnection Function 12 IEngine_Connect Function 13 User Record 13 Allocation 13 IEngine_InitUser Function 14 IEngine_FreeUser Function 14 IEngine_ClearUser Function 15 IEngine_CopyUser Function 15 Add/Remove 16 IEngine_AddFingerprint Function 16 IEngine_AddFingerprintRAW Function 17 IEngine_AddFingerprintFromFile Function 18 IEngine_AddFingerprintFromUser Function 18 IEngine_SetFingerprint Function 19 IEngine_SetFingerprintRAW Function 20 IEngine_SetFingerprintFromFile Function 21 ii

3 IDKit - Fingerprint Identification SDK IEngine_SetFingerprintFromUser Function 21 IEngine_RemoveFingerprint Function 22 Properties 23 IEngine_GetFingerprintCount Function 23 IEngine_SetFingerPosition Function 23 IEngine_GetFingerPosition Function 24 IEngine_SetCustomData Function 25 IEngine_GetCustomData Function 25 IEngine_GetFingerprintImage Function 26 IEngine_SaveFingerprintImage Function 27 IEngine_AttachFingerprintImage Function 27 Biometry 28 IEngine_GetFingerprintQuality Function 28 IEngine_GetMinutiaePoints Function 29 IEngine_GetMinutiaeImage Function 29 IEngine_SaveMinutiaeImage Function 30 IEngine_GetDeltasAndCores Function 31 Import/Export 31 IEngine_SerializeUser Function 31 IEngine_DeserializeUser Function 32 IEngine_ExportUserTemplate Function 32 IEngine_ImportUserTemplate Function 33 Tags 34 IEngine_SetStringTag Function 34 IEngine_SetIntTag Function 35 IEngine_ClearTag Function 35 IEngine_GetStringTag Function 35 IEngine_GetIntTag Function 36 IEngine_HasTag Function 36 IEngine_GetTagCount Function 37 IEngine_GetTagName Function 37 Collections of Users 38 IEngine_InitCollection Function 38 IEngine_FreeCollection Function 38 IEngine_GetCollectionSize Function 39 IEngine_GetCollectionIDs Function 39 Database 39 IEngine_ClearDatabase Function 40 IEngine_GetUserCount Function 40 IEngine_GetAllUserIDs Function 40 IEngine_GetUserIDsByQuery Function 41 IEngine_GetUser Function 41 iii

4 IDKit - Fingerprint Identification SDK IEngine_RegisterUser Function 42 IEngine_RegisterUserAs Function 43 IEngine_UpdateUser Function 43 IEngine_RemoveUser Function 44 Identification 44 IEngine_FindUser Function 45 IEngine_FindUserInSelection Function 45 IEngine_FindUserInMemory Function 46 IEngine_FindUserByQuery Function 47 IEngine_FindFingerprint Function 47 IEngine_FindFingerprintInSelection Function 48 IEngine_FindFingerprintInMemory Function 49 IEngine_FindFingerprintByQuery Function 50 Verification 50 IEngine_MatchUser Function 50 IEngine_MatchUsers Function 51 IEngine_MatchFingerprint Function 52 IEngine_MatchFingerprints Function 53 Images 54 IEngine_ConvertBmp2RawImage Function 54 IEngine_ConvertRawImage2Bmp Function 55 IEngine_ConvertImage Function 56 Plugins - undocumented 56 IEngine_RegisterPlugin Function 57 IEngine_UnregisterPlugin Function 57 IEngine_GetPluginInfo Function 57 IEngine_ExtractPluginTemplate Function 57 IEngine_AddPluginTemplate Function 57 IEngine_SetPluginTemplate Function 58 IEngine_GetPluginTemplate Function 58 IEngine_RemovePluginTemplate Function 58 IEngine_GetPluginTemplateCount Function 58 Settings and Constants 58 IEngine_GetParameter Function 59 IEngine_SetParameter Function 59 IEngine_SetCryptKey Function 60 IEngine_GetUserLimit Function 60 IEngine_GetVersionInfo Function 61 IEngine_GetErrorMsg Function 61 IEngine_SetLogFile Function 61 IEngine_GetHardwareId Function 62 IEngine_GetLicenseInformation Function 62 iv

5 IDKit - Fingerprint Identification SDK IEngine_GetMemoryUsage Function 63 IEngine_CharacterizeScore Function 63 IEngine_GetProductString Function 64 Deprecated 64 IEngine_GetUserIDs Function 64 IEngine_GetVersion Function 65 Types, Structures, Enumerations 65 IENGINE_COLLECTION Type 66 IENGINE_CONFIG Enumeration 66 IENGINE_CONNECTION Type 68 IENGINE_FINGER_POSITION Enumeration 68 IENGINE_IMAGE_FORMAT Enumeration 69 IENGINE_MINUTIAE Structure 69 IENGINE_CRITICAL_POINT Structure 70 IENGINE_SCANNER_TYPE Enumeration 70 IENGINE_TEMPLATE_FORMAT Enumeration 70 IENGINE_USER Type 71 IENGINE_VERSION Structure 71 CRYPT_KEY_LENGTH Macro 72 MAX_MINUTIAE_COUNT Macro 72 MAX_CRITICAL_POINTS_COUNT Macro 72 IENGINE_PLUGIN_LOCATION Enumeration 72 IPLUGIN_DESCRIPTION_MAX_LEN Macro 72 Function Quick Reference 73 Error Codes 75.NET Connector Reference 77 Innovatrics.IEngine Namespace 77 Overview 77 Class Diagram 79 Classes 79 Fingerprint Class 79 Fingerprint Constructor 80 Fingerprint Methods 90 Fingerprint Properties 94 FingerprintCollection Class 95 FingerprintCollection Methods 96 FingerprintCollection Properties 96 CharacterizeScoreResult Class 97 CharacterizeScoreResult.CharacterizeScoreResult Constructor 98 v

6 IDKit - Fingerprint Identification SDK CharacterizeScoreResult Fields 98 IDKit Class 99 IDKit.IDKit Constructor 101 IDKit Fields 102 IDKit Methods 102 IDKit Properties 130 IEngineException Class 137 IEngineException Properties 138 LicenseInformation Class 140 LicenseInformation.LicenseInformation Constructor 140 LicenseInformation Fields 141 MatchResult Class 142 MatchResult Fields 143 SearchResult Class 145 SearchResult Methods 145 SearchResult Properties 146 User Class 147 User Constructor 148 User Methods 149 User Properties 158 Wsq Class 160 Wsq Methods 160 Structs, Records, Enums 163 Innovatrics.IEngine.FingerPosition Enumeration 163 Innovatrics.IEngine.IEngineExceptionCode Enumeration 164 Innovatrics.IEngine.ImageFormat Enumeration 165 Innovatrics.IEngine.Minutiae Structure 166 Innovatrics.IEngine.MinutiaeType Enumeration 166 Innovatrics.IEngine.CriticalPoint Structure 166 Innovatrics.IEngine.CriticalPointType Enumeration 167 Innovatrics.IEngine.ScannerType Enumeration 167 Innovatrics.IEngine.TemplateFormat Enumeration 167 Notes 169 Buffers () 169 Connections 170 Connection String 170 Corresponding Fingerprints 172 Custom Data String 172 External Database 173 vi

7 IDKit - Fingerprint Identification SDK FAR 173 FAR and Threshold 174 Fingerprint Template 174 FRR 175 Identification (one-to-many) 175 In-memory License 175 License 176 Quality 176 Score Consolidation 177 Selection 177 Similarity Score 177 Tag Query 178 Tags 179 Template Cache 180 Template Extraction 180 Threads 180 Threshold 181 Verification (one-to-one) 181 Index a vii

8 1.1 Usage Overview IDKit - Fingerprint Identification SDK 1 Overview 1.1 Usage Overview The IDKit library can be used in all types of applications requiring fingerprint recognition. User support The use of the SDK is made simple through the notion of user. A user is a collection of of fingerprint images from different fingers. This is very universal, as you can associate many fingerprint images with a particular user. You can for example create a user with 2 fingerprints per each finger, which makes 2x10 = 20 fingerprint images in total. Through verification functions you can directly compare two users without needing to explicitly combine similarity scores from different fingers - this is done automatically by the SDK. Database support In addition, database management functions are available that enable to store and retrieve user information in/from a database. In the database, you may optionally store both fingerprint templates and fingerprint images. Fingerprint templates contain fingerprint features necessary for fingerprint verification or identification. Fingerprint images are not required for fingerprint recognition but it may be an interesting option to store them in the database and display them when the user is verified/identified. Another very convenient option is the possibility to store for each user custom application specific data, such as username, address, , etc. For enhanced security, you may optionally switch on the database encryption. In this case, all fingerprint templates, images and custom data are automatically encrypted by AES (Advanced Encryption Standard) cipher when they are stored in the database. Verification The IDKit library compares fingerprint images and calculates their similarity scores. Verification is also called "1 to 1 matching". Various verification strategies are supported: comparison of two fingerprint images (verification of a probe fingerprint with a referenced fingerprint) comparison of multiple fingerprint impressions (views) of the same finger against one or multiple other fingerprint impressions comparison of fingerprints coming from multiple fingers against another set of fingerprint images Identification Sometimes, you need to find an unknown user in a database, knowing only one (or more) of its fingerprints. You may perform this through identification functions. Identification functions search for an unknown fingerprint image or set of images in the whole database. Identification search can be performed in different ways: identification of one particular fingerprint image identification of multiple fingerprint impressions (views) of the same finger identification of fingerprints coming from multiple fingers Identification was optimized for speed. Thanks to the automatic memory mapping of the database content, no additional database access time occurs when an identification search is performed. In addition, the IDKit library contains a proprietary high speed fingerprint identification algorithm], suitable for the most demanding applications. 1

9 1.2 Product Differences IDKit - Fingerprint Identification SDK Supported image formats The IDKit library accepts as an input fingerprint images stored in different formats. It supports BMP, PNG, JPEG, GIF, TIFF and WSQ images. WSQ is a special format designed specially for efficient fingerprint image compression. Note: IDKit Mobile SDK supports only RAW and BMP images. 1.2 Product Differences This documentation covers following products. Product compatibility notices appear throughout this documentation wherever there are differences between IDKit SDK versions. IDKit PC SDK IDKit PC SDK is simple to use and straightforward. Thanks to the database support, the programmer does not have to worry about storing fingerprint images or templates. Database is automatically loaded and mapped in memory, enabling extremely fast fingerprint matching. IDKit PC SDK is suitable for developing fingerprint identification applications ranging from a few up to thousands of users. IDKit PC SDK supports a wide range of input formats (RAW, PNG, BMP, JPEG, JPEG 2000, GIF, WSQ, TIF) and is compatible with fingerprint images from various fingerprint scanners, (optical, capacitive, thermal based). IDKit PRO SDK IDKit PRO SDK is an extended version of IDKit PC SDK that is intended for use in client/server environments. In addition to features included in IDKit PC SDK, it contains support for ODBC connection to database and support for connecting to ExpressID AFIS. IDKit Mobile SDK IDKit Mobile SDK is essentially IDKit PC SDK running under Windows Mobile. In addition to IDKit PC SDK functionality, IDKit Mobile SDK can connect to ExpressID AFIS over network just like IDKit PRO SDK. IDKit Mobile SDK supports only RAW and BMP image format and valid identification speed range is 0-7. IDKit Embedded SDK IDKit Embedded SDK is port of IDKit PC SDK for embedded platforms based on embedded Linux. It is built upon customer request using specific toolchain (contains cross-compiler) which should be provided by the customer. IDKit Embedded SDK usually supports only RAW and BMP image format, valid identification speed range is 0-7 and has no ExpressID AFIS connection possibility. Related Products This documentation doesn't cover several other products that can be used together with IDKit SDK. These products have their own documentation. They are briefly described below. IEngine Core IDKit SDK is based on IEngine(tm) Core - Innovatrics proprietary fingerprint recognition module. IEngine(tm) Core is a powerful fingerprint matching and identification library. It is a highly reliable solution based on advanced algorithms. The IEngine(tm) Core library is both reliable and fast. The reliability of the extractor allows it to recognize even low quality fingerprint images. The extremely high speed of the matcher enables an instant search of the correct candidate throughout large databases. 2

10 1.3 Similarity Scores IDKit - Fingerprint Identification SDK ExpressID AFIS Innovatrics ExpressID AFIS is a separate product for building centralized matching servers. IDKit PRO SDK and IDKit Mobile SDK can connect to ExpressID AFIS in order to perform fingerprint identification. IScanners SDK IScanners SDK provides unified API to access several types of fingerprint sensors. It is provided as an add-on for IDKit SDK. For this reason, IDKit SDK itself doesn't contain any functionality for accessing fingerprint sensors. Fingerprint images acquired using IScanners SDK can be directly used by IDKit SDK. ANSI/ISO SDK Innovatrics ANSI/ISO SDK can extract and match templates conforming to ANSI/INCITS 378 or ISO/IEC standard. IDKit SDK can export ANSI and ISO templates to be used in ANSI/ISO SDK. It is not possible to convert ANSI or ISO template back to IDKit SDK template. 1.3 Similarity Scores Due to different positioning, deformations, random noise, finger humidity and sensor conditions it is impossible for two images of the same finger, acquired in different sessions, to coincide exactly. For this reason, the matching is performed by an algorithm which calculates global similarity score. This similarity score has to be compared with the similarity threshold: When similarity score is greater than the similarity threshold, the system claims that the two samples coincide. Sometimes the output of biometric systems can be incorrect; the main system errors are usually measured in terms of: FAR ( see page 173) (False Acceptance Rate ( see page 173)) - The frequency of fraudulent accesses due to impostors claiming a false identity FRR ( see page 175) (False Rejection Rate ( see page 175)) - The frequency of rejections relative to people who should be correctly verified FAR ( see page 173) and FRR ( see page 175) depend on the similarity threshold, which is set to obtain the desired security level. FAR ( see page 173) and FRR ( see page 175) are strictly related to each other. More precisely, FRR ( see page 175) is an increasing function of the similarity threshold and FAR ( see page 173) is a decreasing function of the similarity threshold. If the similarity threshold setting is increased to make it harder for impostors to gain access (lower FAR ( see page 173)), some authorized people may find it harder to gain access (higher FRR ( see page 175)). The range of returned similarity scores is between 0 (no similarity) and (highest similarity). As for distribution of scores, scores between 0 and correspond to a very low similarity (even no similarity). The correspondance between fingerprint images is generally reflected by similarity scores greater than Default similarity threshold value (12300) roughly corresponds to FAR ( see page 173)=10^-5. Depending on the type of scanner, the size of fingerprint images, the size of the database and the desired security level of your application, you may need to select a different threshold. To modify the default similarity threshold, call function IEngine_SetParameter ( see page 59) with parameter CFG_SIMILARITY_THRESHOLD ( see page 66). 3

11 1.5 Database Connectivity IDKit - Fingerprint Identification SDK Please contact Innovatrics Technical Support for more details about setting the correct similarity threshold. 1.4 Identification Speed Identification algorithm speed is measured in number of fingerprint matchings per second. Note that this is not the same as number of user matchings per second, because each user may contain more corresponding fingerprints. Performance of identification functions included in this library depends on general settings of the library - more precisely on two particular parameters set through IEngine_SetParameter ( see page 59) function: maximum permitted rotation between fingerprints and selected identification speed level. From theoretical point of view, the time complexity of the library's identification functions is given as T = a.n + b where T is the total identification time, n is the number of compared fingerprints (database size) and a, b are constant coefficients. Coefficient b represents the functions' initialization overhead and it is typically smaller than 50 milliseconds. As n grows larger, the a.n term dominates and b becomes irrelevant. Identification speeds listed here are measured for very large databases where b coefficient can be ignored. Performance may vary with population and hardware. When measuring identification speed of your system, it is recommended to use bigger databases in order to avoid the negative influence of the b coefficient. IDKit PC SDK, IDKit PRO SDK The following table contains average identification speed as measured on an Intel Core2 Duo processor. The identfication speed test was done on a database with 1 million fingerprints. All fingerprints were acquired by optical sensor. The speed, reported as the number of fingerprint matchings per second, depends on two parameters: selected speed level and maximum rotation. Speed level Max.Rotation=30 Max.Rotation=50 Max.Rotation= ExpressID AFIS In ExpressID AFIS Enterprise, there is a single matching server which achieves speeds identical to speeds of IDKit SDK. In ExpressID AFIS Government, there can be one or more matching nodes. Every node has matching speed identical to IDKit SDK. Speed of the whole ExpressID AFIS Government cluster is the sum of speeds of cluster nodes. IDKit Mobile SDK Identification speed in IDKit Mobile SDK is fingerprints per second on commonly available mobile devices. 4

12 1.5 Database Connectivity IDKit - Fingerprint Identification SDK 1.5 Database Connectivity IDKit SDK can access fingerprints from several data sources: integrated SQLite database stored in one file, relational ODBC-compatible database like MySQL, MSSQL, or Oracle, ExpressID AFIS accessed over network through SOAP-based protocol, and memory area which is filled with fingerprint data the application needs to search. ODBC databases are supported only in IDKit PRO SDK. ExpressID AFIS connections are supported in IDKit PRO SDK and IDKit Mobile SDK. Selecting Database Database connection is made using function IEngine_Connect ( see page 13). This function takes a string parameter which describes the data source. Once connected, all IDKit SDK functions work identically with all data sources. The same API is used to access all types of databases. When connecting to ExpressID AFIS, there is an additional option of acquiring client license from ExpressID AFIS. This feature makes it easier to deploy large numbers of clients. In order to make use of server-side licenses, function IEngine_InitClient ( see page 10) is called instead of IEngine_InitModule ( see page 9). IEngine_InitClient ( see page 10) acquires license from server and it also opens connection to ExpressID AFIS just like IEngine_Connect ( see page 13). There is no need to call IEngine_Connect ( see page 13) after IEngine_InitClient ( see page 10). Case 1: SQLite Database In the first case, biometric data can be stored in local file 'idkit.db' in SQLite database. IDKit SDK is initialized with this code: IEngine_InitModule( IEngine_Connect( "idkit.db" Case 2: ODBC Accessible Database In the second case, suppose that biometric data is stored in some database other than SQLite. If this DBMS supports ODBC, like Oracle, MSSQL, MySQL, PostreSQL and others, IDKit SDK can connect to this data source. If appropriate DSN (Data Source Name) is configured on the computer from which IDKit SDK is making connection, the following code serves the purpose: IEngine_InitModule( IEngine_Connect( "Type=ODBC; DSN=idkit" Case 3: Remote Identification In the third case, there is an ExpressID AFIS installation on separate computer that takes care of biometrics data and performs identification instead of the client. Following code will connect to ExpressID AFIS: IEngine_InitModule( IEngine_Connect( "Type=Service; Server=myserver.mydomain" 5

13 1.6 ODBC Data Source Configuration IDKit - Fingerprint Identification SDK Alternatively, to make use of server-side licenses, following code can be used: IEngine_InitClient( "Type=Service; Server=myserver.mydomain" Case 4: No Database If the application is designed to store biometric data in its own database, IDKit SDK can be instructed to use biometric data loaded by the application into memory. IDKit SDK is initialized to use memory database: IEngine_InitModule( IEngine_Connect( "Type=Memory" This initializes an empty memory database for storing biometric data. Application can then use function IEngine_RegisterUserAs ( see page 43) to fill the memory database with user records obtained from application database. Any modifications of user records in memory database will be lost when application terminates. Application should save any modified records back into application database. Another option is to avoid calls to IEngine_Connect ( see page 13) entirely and use identification and verification functions that can work with templates from external database ( see page 173). 1.6 ODBC Data Source Configuration Storing biometric data in a data source accessible through ODBC interface requires specific configuration steps to be performed on the DBMS. Particular actions depend on the choice of the DBMS and it is not possible to describe instructions for each data source due to the potentially unlimited number of different DBMS. In general, the tasks required to perform can be summarized as follows, create a database and its structure, create a user account with read/write privileges on the created tables. Each DBMS provides its own administration tools and procedures to perform these tasks. Administrator of DBMS deployed in customer's site should be knowledgeable of the tools and procedures. Note: Structure of the database is described by the SQL script found in the IDKit PRO SDK installation folder in "SQL Scripts" under installation folder. Provided are SQL scripts for various DBMS. If there is no script for your DBMS, it is usually easy to derive one from provided scripts by database administrator. In order to access prepared database by IDKit PRO SDK, it is necessary to install corresponding ODBC driver and ODBC data source has to be defined. Note: For instructions on how to install ODBC driver for a DBMS consult documentation provided with that DBMS. Also note that not all DBMS provide ODBC driver to access them or the driver is provided by 3rd party and might not be supported. Before choosing particular DBMS, check the availability of ODBC driver for that particular DBMS. The best practice is to check the driver availability in advance, however, the best-known and used DBMS like Oracle, MSSQL, MySQL and PostgreSQL usually provide the driver. ODBC Data Source Configuration IDKit PRO SDK uses an ODBC Data Source Name (DSN) to access the database. DSN has associated parameters specifying what database to access and how to access it. MS Windows On Microsoft Windows platform, the ODBC Data Source Administrator contains list of available DSNs and it is used to add, remove, and configure DSNs. To define new DSN for the database, first ensure that the appropriate ODBC driver is installed on the computer. Run ODBC Data Source Administrator located in [Start Menu] -> [Control Panels] -> [Administrative Tools] -> [Data Sources (ODBC)]. Following image shows ODBC Data Source Administrator. 6

14 1.7 Image Processing IDKit - Fingerprint Identification SDK Clicking "Add..." button opens a list of installed ODBC drivers. Choose a driver and fill in appropriate parameters according to the database settings the database administrator has made. GNU/Linux, UNIX, BSD UnixODBC is an open source project that implements the ODBC API. The code is provided under the GNU GPL license and can be built and used on many different operating systems, including most versions of Unix, GNU/Linux, Mac OS X, IBM OS/2. Most GNU/Linux distributions provide unixodbc package in default repositories (Debian/Ubuntu: apt-get install unixodbc, Red Hat/Fedora: yum install unixodbc). If you want to add DSN, ensure first that the appropriate ODBC driver is installed and specified in '/etc/odbcinst.ini'. Afterwards define DSN in /etc/odbc.ini. You can use command line program 'isql' in order to check functionality of previously configured DSN. 1.7 Image Processing This section deals with various issues related to working with images. Supported Formats Supported image formats are enumerated in IENGINE_IMAGE_FORMAT ( see page 69) () and ImageFormat ( see page 165) (.NET). In addition, IDKit SDK supports RAW image format through functions IEngine_ConvertRawImage2Bmp ( see page 55) and IEngine_ConvertBmp2RawImage ( see page 54) () or methods IDKit.ConvertRaw2Bmp ( see page 104) and IDKit.ConvertBmp2Raw ( see page 103) (.NET). Image Conversions Images can be supplied to IDKit SDK and requested from IDKit SDK in any supported format. IDKit SDK performs image format conversion whenever necessary. Image conversion is sometimes enforced by IDKit SDK. ExpressID AFIS always sends images to IDKit Mobile SDK in BMP format to support interoperability between IDKit Mobile SDK and IDKit PC SDK. IDKit SDK and ExpressID AFIS always store images in database in PNG format. If different image format is supplied, it is converted to PNG format upon write to database. If PNG format is not supported on some platform, BMP is used as the default format for storing images in database (for example in IDKit Embedded SDK). In.NET, Fingerprint object has properties Image and Wsq. These properties always contain the same image, just in different formats. If Image is set, Wsq is generated by converting the image to WSQ format. If Wsq is set, Image is generated by converting the image to BMP format. Image conversion is always performed at the last moment it is needed, usually upon first read from Image or Wsq property. Once the conversion is performed, the converted image is cached and further access 7

15 1.7 Image Processing IDKit - Fingerprint Identification SDK to the Image or Wsq property is cheap. WSQ Support in.net.net Connector generally uses.net Framework class System.Drawing.Image for manipulating images. WSQ is supported through class Wsq implemented by.net Connector. All methods taking Image input accept also Wsq input. Wsq class performs no compression nor decompression. It is merely a container for serialized WSQ image. Wsq objects therefore don't need to be disposed. Memory Management in.net Performance and memory usage can be improved by using Dispose method of System.Drawing.Image. Care should be taken when combining Dispose calls on Image object and its containing Fingerprint object and User object. User.Dispose automatically disposes all Fingerprint objects contained in User. Fingerprint.Dispose automatically disposes Image object in Fingerprint, but only if this Image was created by the Fingerprint object. If the Image object is passed to Fingerprint from outside, either through Fingerprint constructor or Image property setter, this externally provided Image is not disposed. It is always safe to dispose Fingerprint.Image as far as the application doesn't try to make further use of the Fingerprint.Image property. 8

16 2.1 Functions IDKit - Fingerprint Identification SDK Initialization 2 API Reference Functions Name Initialization ( see page 9) Connections ( see page 11) User Record ( see page 13) Collections of Users ( see page 38) Database ( see page 39) Identification ( see page 44) Verification ( see page 50) Plugins - undocumented ( see page 56) Settings and Constants ( see page 58) Deprecated ( see page 64) 2.1 Functions The following table lists functions in this documentation. Images Name IEngine_ConvertBmp2RawImage ( see page 54) Converts BMP image into raw image IEngine_ConvertRawImage2Bmp ( see page 55) Converts raw image into BMP image IEngine_ConvertImage ( see page 56) Converts an image into another image format Initialization Functions Name IEngine_InitModule ( see page 9) Initializes the library IEngine_InitClient ( see page 10) Initializes the library with the software license from central ExpressID AFIS. IEngine_InitWithLicense ( see page 10) Initializes the library with selected license IEngine_TerminateModule ( see page 11) Terminates the use of the library IEngine_InitModule Function Initializes the library IDKIT_API int IEngine_InitModule( This function initializes and checks the integrity of the library and verifies the validity of the license ( see page 176). It should be called prior to any other function from the library. 9

17 2.1 Functions IDKit - Fingerprint Identification SDK Initialization IENGINE_OK IENGINE_E_BADLICENSE IENGINE_E_EXPIREDLICENSE IENGINE_E_MISSINGDLL No error occurred. Provided license is not valid, or no license was found. Provided license has expired. At least one required DLL could not be loaded. Related Topics IEngine_TerminateModule ( see page 11), IEngine_GetVersion ( see page 65) IEngine_InitClient Function Initializes the library with the software license from central ExpressID AFIS. IDKIT_API int IEngine_InitClient(char * connectionstring This function is used to initialize IDKit SDK as a client of ExpressID AFIS. If client is accepted by central ExpressID AFIS, IDKit SDK is successfully initialized. In this scenario, no license ( see page 176) is required on the local machine (client computer). However, if the lirary is initialized using IEngine_InitClient, you won't be able to connect to a local databse file or to ODBC source. Only connections to matching servers will be allowed. char * connectionstring [in] Specifies the connection string ( see page 170) used to connect to ExpressID AFIS. IENGINE_OK IENGINE_E_MAXCLIENTS IENGINE_E_MISSINGDLL IENGINE_E_SRVFAILED No error occurred. Maximum allowed clients reached. At least one required DLL could not be loaded. Unable to contact ExpressID AFIS. Compatibility Supported in IDKit PRO SDK and IDKit Mobile SDK. Related Topics IEngine_TerminateModule ( see page 11), IEngine_Connect ( see page 13) IEngine_InitWithLicense Function Initializes the library with selected license IDKIT_API int IEngine_InitWithLicense(unsigned char * license, int length unsigned char * license [in] Buffer containing an in-memory license ( see page 175). int length [in] Length of the buffer containing license data. 10

18 2.1 Functions IDKit - Fingerprint Identification SDK Connections IENGINE_OK IENGINE_E_BADLICENSE IENGINE_E_EXPIREDLICENSE No error occurred. Provided license is not valid. Provided license has expired. This function initializes and checks the integrity of the library and verifies validity of the provided in-memory license ( see page 175). It should be called prior to any other function from the library. Related Topics IEngine_TerminateModule ( see page 11), IEngine_InitModule ( see page 9) IEngine_TerminateModule Function Terminates the use of the library IDKIT_API int IEngine_TerminateModule( This function releases all resources allocated by the library. It should be called as the very last function of the library. IENGINE_OK No error occurred. Related Topics IEngine_InitModule ( see page 9) Connections Functions Name IEngine_InitConnection ( see page 11) Initializes new connection to database or ExpressID AFIS. IEngine_SelectConnection ( see page 12) Selects active connection for the current thread. IEngine_CloseConnection ( see page 12) Closes a connection and releases all resources held by the connection. IEngine_Connect ( see page 13) Connects to a database containing fingerprint data IEngine_InitConnection Function Initializes new connection to database or ExpressID AFIS. IDKIT_API IENGINE_CONNECTION IEngine_InitConnection( Returns Handle to the newly created connection or NULL on error. Applications that need only one connection never need to call this function, because the default connection is created and selected automatically. Applications that need multiple connections ( see page 170) can call this function multiple times to create as many connections as they need. 11

19 2.1 Functions IDKit - Fingerprint Identification SDK Connections The new connection is not initially selected for any thread ( see page 180). Use IEngine_SelectConnection ( see page 12) to select it for the current thread. The connection is initially in disconnected state. Call IEngine_Connect ( see page 13) to establish connection to a database or ExpressID AFIS. Connections may be left in disconnected state in which case they are useful as a container for connection-specific parameters. Every thread can then have a different set of global parameters. Compatibility Supported in IDKit PC SDK and IDKit PRO SDK. IDKit Mobile SDK doesn't support multiple simultaneous connections. Related Topics IEngine_SelectConnection ( see page 12), IEngine_Connect ( see page 13), IEngine_CloseConnection ( see page 12) IEngine_SelectConnection Function Selects active connection for the current thread. IDKIT_API int IEngine_SelectConnection(IENGINE_CONNECTION connection IENGINE_CONNECTION connection Returns [in] Connection to be selected or NULL to select default connection. If the function succeeds, the return value is zero. If the function fails, the return value is nonzero. For a list of error codes, see section Error Codes ( see page 75). Every thread ( see page 180) has its selected connection ( see page 170). All API functions operate on the currently selected connection. Only one connection can be selected by a given thread, but multiple threads can share the same connection. By default, all threads have selected default connection. You can call this function with connection handle returned from IEngine_InitConnection ( see page 11) to select non-default connection or with NULL parameter to select default connection again. Compatibility Supported in IDKit PC SDK and IDKit PRO SDK. IDKit Mobile SDK doesn't support multiple simultaneous connections. Related Topics IEngine_InitConnection ( see page 11), IEngine_Connect ( see page 13), IEngine_CloseConnection ( see page 12) IEngine_CloseConnection Function Closes a connection and releases all resources held by the connection. IDKIT_API int IEngine_CloseConnection(IENGINE_CONNECTION connection IENGINE_CONNECTION connection Returns [in] Connection to be closed. If the function succeeds, the return value is zero. If the function fails, the return value is nonzero. For a list of error codes, see section Error Codes ( see page 75). 12

20 2.1 Functions IDKit - Fingerprint Identification SDK User Record This function should be called when connection ( see page 170) created by IEngine_InitConnection ( see page 11) is no longer needed. The connection doesn't have to be selected by the current thread. If any API call is executed while the destroyed connection is still selected, the API function returns error. Compatibility Supported in IDKit PC SDK and IDKit PRO SDK. IDKit Mobile SDK doesn't support multiple simultaneous connections. Related Topics IEngine_InitConnection ( see page 11), IEngine_SelectConnection ( see page 12) IEngine_Connect Function Connects to a database containing fingerprint data. IDKIT_API int IEngine_Connect(char * connectionstring This function connects IDKit SDK to the database specified in connection string ( see page 170). For local databases, it also fills template cache ( see page 180). char * connectionstring [in] Specifies the connection string ( see page 170) used to connect to database or to ExpressID AFIS. IENGINE_OK IENGINE_E_INIT IENGINE_E_DBOPEN IENGINE_E_DBFAILED IENGINE_E_DBFULL IENGINE_E_MEMORY IENGINE_E_SRVFAILED IENGINE_E_BADCRYPTKEY No error occurred. Library was not initialized. Could not connect to database. Unexpected database failure occurred. For ODBC connection, this error occurs if the database has an invalid structure. Exceeded database user limit. Memory allocation failed. Unable to contact ExpressID AFIS. Invalid cipher key. Data CRC check failed after decryption. Compatibility Connections to ExpressID AFIS are supported in IDKit PRO SDK and IDKit Mobile SDK. Connections to ODBC database are supported in IDKit PRO SDK. Related Topics IEngine_ClearDatabase ( see page 40), IEngine_InitConnection ( see page 11) User Record Allocation 13

21 2.1 Functions IDKit - Fingerprint Identification SDK User Record Functions Name IEngine_InitUser ( see page 14) Initializes an empty user structure IEngine_FreeUser ( see page 14) Releases user structure IEngine_ClearUser ( see page 15) Clears all information from user structure IEngine_CopyUser ( see page 15) Copies user structure IEngine_InitUser Function Initializes an empty user structure IDKIT_API IENGINE_USER IEngine_InitUser( This function initializes an empty user structure and returns an initialized IENGINE_USER type. Aftewards, you may use the returned user structure and associate fingerprints to this structure (IEngine_AddFingerprint ( see page 16)). Warning After use, don't forget to free the returned user structure by calling IEngine_FreeUser ( see page 14). NULL IENGINE_USER Memory error - could not allocate memory. An initialized empty IENGINE_USER structure. Example... IENGINE_USER user=iengine_inituser( IEngine_AddFingerprintFromFile(user,0,"image.bmp" err=iengine_registeruser(user, &userid if(err!=0) printf("error occurred during registration\n" else printf("user was registered under ID %d\n",userid IEngine_FreeUser(user Related Topics IEngine_FreeUser ( see page 14), IEngine_ClearUser ( see page 15), IEngine_AddFingerprint ( see page 16) IEngine_FreeUser Function Releases user structure IDKIT_API int IEngine_FreeUser(IENGINE_USER user This function releases input user structure. All data from the input user structure will be released. IENGINE_USER user [in] An initialized user structure IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER No error occurred. Library was not initialized. User parameter is not valid. 14

22 2.1 Functions IDKit - Fingerprint Identification SDK User Record Related Topics IEngine_InitUser ( see page 14) IEngine_ClearUser Function Clears all information from user structure IDKIT_API int IEngine_ClearUser(IENGINE_USER user This function deletes all information from input user structure. All fingerprint templates and fingerprint images are deleted from the input user structure, custom data of the user is also cleared. After calling this function, returned user structure will be an initialized empty IENGINE_USER structure. IENGINE_USER user [in] An initialized user structure IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_MEMORY No error occurred. Library was not initialized. User parameter is not valid. Memory allocation failed. Related Topics IEngine_InitUser ( see page 14), IEngine_FreeUser ( see page 14) IEngine_CopyUser Function Copies user structure IDKIT_API int IEngine_CopyUser(IENGINE_USER srcuser, IENGINE_USER dstuser, bool withimages This function copies source user structure (fingerprint templates, images, custom data and tags) into destination user structure. Destination user structure is not cleared before copy, so you can use this method even for user structures joining. IENGINE_USER srcuser [in] source user structure IENGINE_USER dstuser [in] destination user structure withimage [in] boolean indicating whether the fingerprint images are subject of copying too. IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_MEMORY No error occurred. Library was not initialized. One of user parameters is not valid. Memory allocation failed. Related Topics IEngine_InitUser ( see page 14), IEngine_FreeUser ( see page 14), IEngine_ClearUser ( see page 15), IEngine_AddFingerprint ( see page 16) 15

23 2.1 Functions IDKit - Fingerprint Identification SDK User Record Add/Remove Functions Name IEngine_AddFingerprint ( see page 16) Adds fingerprint to user structure, fingerprint image is read from memory IEngine_AddFingerprintRAW ( see page 17) Adds fingerprint to user structure, fingerprint raw image is read from memory IEngine_AddFingerprintFromFile ( see page 18) Adds fingerprint to user structure, fingerprint image is read from file IEngine_AddFingerprintFromUser ( see page 18) Adds fingerprint to user structure from another user structure. IEngine_SetFingerprint ( see page 19) Replaces fingerprint at specified index, fingerprint image is read from memory IEngine_SetFingerprintRAW ( see page 20) Replaces fingerprint at specified index, fingerprint raw image is read from memory IEngine_SetFingerprintFromFile ( see page 21) Replaces fingerprint at specified index, fingerprint image is read from file IEngine_SetFingerprintFromUser ( see page 21) Replaces fingerprint at specified index with fingerprint taken from another user structure. IEngine_RemoveFingerprint ( see page 22) Removes fingerprint at specified index IEngine_AddFingerprint Function Adds fingerprint to user structure, fingerprint image is read from memory IDKIT_API int IEngine_AddFingerprint(IENGINE_USER user, IENGINE_FINGER_POSITION fingerposition, unsigned char * fingerprintimage This function adds an additional fingerprint to an initialized user structure. You may add as many fingerprints as needed to one user. You may even associate more fingerprint images issued from the same finger to the same user. This helps to improve the recognition accuracy. Even if some of the fingerprints are not recognized due to high noise or deformation, other samples of the same fingerprint may still be found. This feature is also useful for multi-finger matching/identification. If you use two fingers for identification instead of one finger,the error rate will be lower. Input fingerprint image is directly read from memory. Each fingerprint contained in user structure has its own index. Index numbers are given automatically in ascending order, beginning at 0 (index of the first added fingerprint is 0). Note: If your fingerprint image is stored in raw format, please use IEngine_AddFingerprintRAW ( see page 17) or IEngine_ConvertRawImage2Bmp ( see page 55) before calling this function When you call this function,the fingerprint image is processed and the fingerprint template is extracted from the original image. IENGINE_USER user [in] An initialized user structure IENGINE_FINGER_POSITION fingerposition [in] Parameter specifying the finger position of the current fingerprint unsigned char * fingerprintimage [in] Pointer to an image stored in memory. Image format must be one of supported image formats (Image Processing ( see page 7)). IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_BADIMAGE IENGINE_E_BLANKIMAGE No error occurred. Library was not initialized. User parameter is not valid. Invalid image or unsupported image format. Image is blank or contains non-recognizable fingerprint. 16

24 2.1 Functions IDKit - Fingerprint Identification SDK User Record IENGINE_E_MEMORY Memory allocation failed. Related Topics IEngine_AddFingerprintRAW ( see page 17), IEngine_AddFingerprintFromFile ( see page 18), IEngine_AddFingerprintFromUser ( see page 18), IEngine_RemoveFingerprint ( see page 22), IEngine_InitUser ( see page 14), IEngine_ConvertRawImage2Bmp ( see page 55) IEngine_AddFingerprintRAW Function Adds fingerprint to user structure, fingerprint raw image is read from memory IDKIT_API int IEngine_AddFingerprintRAW(IENGINE_USER user, IENGINE_FINGER_POSITION position, unsigned char * rawimage, int width, int height This function adds an additional fingerprint to an initialized user structure. You may add as many fingerprints as needed to one user. You may even associate more fingerprint raw images issued from the same finger to the same user. This helps to improve the recognition accuracy. Even if some of the fingerprints are not recognized due to high noise or deformation, other samples of the same fingerprint may still be found. This feature is also useful for multi-finger matching/identification. If you use two fingers for identification instead of one finger,the error rate will be lower. Input raw fingerprint image is directly read from memory. Each fingerprint contained in user structure has its own index. Index numbers are given automatically in ascending order, beginning at 0 (index of the first added fingerprint is 0). When you call this function,the fingerprint image is processed and the fingerprint template is extracted from the original raw image. IENGINE_USER user [in] An initialized user structure unsigned char * rawimage [in] Pointer to raw image stored in memory. int width [in] The number of pixels indicating the width of the raw image int height [in] The number of pixels indicating the height of the raw image fingerposition [in] Parameter specifying the finger position of the current fingerprint IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_BADIMAGE IENGINE_E_BLANKIMAGE IENGINE_E_MEMORY No error occurred. Library was not initialized. User parameter is not valid. Invalid image or unsupported image format. Image is blank or contains non-recognizable fingerprint. Memory allocation failed. Related Topics IEngine_AddFingerprint ( see page 16), IEngine_AddFingerprintFromFile ( see page 18), IEngine_AddFingerprintFromUser ( see page 18), IEngine_RemoveFingerprint ( see page 22), IEngine_InitUser ( see page 14), IEngine_ConvertRawImage2Bmp ( see page 55) 17

25 2.1 Functions IDKit - Fingerprint Identification SDK User Record IEngine_AddFingerprintFromFile Function Adds fingerprint to user structure, fingerprint image is read from file IDKIT_API int IEngine_AddFingerprintFromFile(IENGINE_USER user, IENGINE_FINGER_POSITION fingerposition, const char * filename This function adds an additional fingerprint to an initialized user structure. You may add as many fingerprints as needed to one user. You may even associate more fingerprint images issued from the same finger to the same user. This helps to improve the recognition accuracy. Even if some of the fingerprints are not recognized due to high noise or deformation, other samples of the same fingerprint may still be found. This feature is also useful for multi-finger matching/identification. If you use two fingers for identification instead of one finger,the error rate will be lower. Input fingerprint image is read from the file specified on input. Each fingerprint contained in the user structure has its own index. Index numbers are given automatically in ascending order, beginning at 0 (index of the first added fingerprint is 0). When you call this function,the fingerprint image is processed and the fingerprint template is extracted from the original image. IENGINE_USER user [in] An initialized user structure IENGINE_FINGER_POSITION fingerposition [in] Parameter specifying finger position of the current fingerprint const char * filename [in] Name of the file containing fingerprint image. Image format must be one of supported image formats (Image Processing ( see page 7)). IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_BADIMAGE IENGINE_E_BLANKIMAGE IENGINE_E_FILE IENGINE_E_MEMORY No error occurred. Library was not initialized. User parameter is not valid. Invalid image or unsupported image format. Image is blank or contains a non-recognizable fingerprint. Error occurred while opening/reading file. Memory allocation failed. Related Topics IEngine_AddFingerprint ( see page 16), IEngine_AddFingerprintRAW ( see page 17), IEngine_AddFingerprintFromUser ( see page 18), IEngine_RemoveFingerprint ( see page 22), IEngine_InitUser ( see page 14) IEngine_AddFingerprintFromUser Function Adds fingerprint to user structure from another user structure. IDKIT_API int IEngine_AddFingerprintFromUser(IENGINE_USER user, IENGINE_USER fromuser, int fromindex, bool withimage This function adds an additional fingerprint to an initialized user structure. You may add as many fingerprints as needed to one user. This helps to improve the recognition accuracy. Even if some of the fingerprints are not recognized due to high noise or deformation, other samples of the same fingerprint may still be found. This feature is also useful for multi-finger matching/identification. If you use two fingers for identification instead of one finger,the error rate will be lower. 18

26 2.1 Functions IDKit - Fingerprint Identification SDK User Record Each fingerprint contained in the user structure has its own index. Index numbers are given automatically in ascending order, beginning at 0 (index of the first added fingerprint is 0). When you call this function, one fingerprint template, its position and eventually corresponding fingerprint image is get from source user structure and added into destination user structure. IENGINE_USER user [in] An initialized destination user structure IENGINE_USER fromuser [in] An initialized source user structure int fromindex [in] Index of the fingerprint in 'fromuser' user structure that will be added into 'user' user structure. bool withimage [in] Boolean indicating whether the fingerprint image is subject of addition too. IENGINE_OK IENGINE_E_INIT IENGINE_E_BADUSER IENGINE_E_BADINDEX IENGINE_E_MEMORY No error occurred. Library was not initialized. User parameter is not valid. Specified fingerprint index is not valid. Memory allocation failed. Related Topics IEngine_AddFingerprint ( see page 16), IEngine_AddFingerprintRAW ( see page 17), IEngine_AddFingerprintFromFile ( see page 18), IEngine_RemoveFingerprint ( see page 22), IEngine_InitUser ( see page 14) IEngine_SetFingerprint Function Replaces fingerprint at specified index, fingerprint image is read from memory IDKIT_API int IEngine_SetFingerprint(IENGINE_USER user, int fingerprintindex, IENGINE_FINGER_POSITION fingerposition, unsigned char * fingerprintimage This function replaces one of the fingerprints in an existing user structure by a new fingerprint. Previously attached fingerprint will be discarded. Input fingerprint image is read from memory. Fingerprint that will be replaced is defined by the fingerprintindex parameter. Each fingerprint contained in the user structure has its own index. Index numbers are given automatically when fingerprints are added to the user structure. Index numbers are given in ascending order, beginning at 0 (the index of the first added fingerprint is 0). When you call this function, fingerprint image is processed and fingerprint template is extracted from the original image. IENGINE_USER user [in] An initialized user structure int fingerprintindex [in] Index of fingerprint that will be replaced IENGINE_FINGER_POSITION fingerposition [in] Parameter specifying the finger position of the new fingerprint unsigned char * fingerprintimage [in] Pointer to an image stored in memory. Image format must be one of supported image formats (Image Processing ( see page 7)). 19