IBSDK Programmers Guide for Windowsjournoportfolio.s3-website-eu-west-1.amazonaws.com/... ·...

IBSDK Programmer’s Guide for Windows

IB-SDK-00003 Ver. 3.0.0

2012-04-04


Copyright @2012, lntegrated Biometrics LLC. All Rights Reserved


Table of Contents 1 Introduction ..................................................................................................... 4 1.1 Overview .................................................................................................................... 4 1.2 About Images and IB User Templates ....................................................................... 4 1.3 Template Data Formats ............................................................................................. 5 1.4 Installation, Files, and Folders ................................................................................... 6

1.4.1. System Requirements ......................................................................................... 6 1.4.2. Installation ............................................................................................................ 6 1.4.3. Installation Files ................................................................................................... 8

1.5 Best Practices Suggestions ....................................................................................... 9 1.5.1. Template / Memory / Database Size Considerations .......................................... 9 1.5.2. Recommended Enrollment Procedure ................................................................ 9

1.6 BISDK Configuration ................................................................................................ 10 1.7 NFIQ Image Quality ................................................................................................. 11 1.8 Security Level Settings ............................................................................................ 11

1.8.1. Matching 404 vs. 404, & 404 vs. 9456, and 9456 vs. 9456 (Indexing Level 0) . 11 1.8.2. Testing Platform ................................................................................................. 12 1.8.3. Matching Speed ................................................................................................. 12 1.8.4. Indexing Level Setting ....................................................................................... 12 1.8.5. C Programming ................................................................................................. 13

2 C Function Library ........................................................................................ 14 2.1 Configuration of Shared DLL (BioNetAcsDLL.dll) .................................................... 14

2.1.1. Basic Properties (Get and Set functions ............................................................ 15 2.1.2. IBI SDK Setting Functions ................................................................................. 15 2.1.3. Example of Internal Algorithm Setting Functions ............................................... 20 2.1.4. Fingerprint Acquisition Order ............................................................................. 21 2.1.5. Size of Fingerprint Image (Width & Height) ....................................................... 22 2.1.6. Fingerprint Acquisition Related Functions ......................................................... 24 2.1.7. Fingerprint Matching Process Flow ................................................................... 29 2.1.8. Fingerprint Enrollment Process Flow ................................................................. 30

2.2 Fingerprint Template Generation and Matching ...................................................... 31 3 Programming ................................................................................................. 35 3.1 Visual C++ 6.0 ......................................................................................................... 35 3.2 64-Bit application development for Visual C++ ........................................................ 37

3.2.1. 64-Bit development overview ............................................................................ 37 3.2.2. 64-Bit development procedure .......................................................................... 37


Microsoft Visual Basic 6.0 ................................................................................................. 39 3.2.3. DLL Declaration ................................................................................................. 39 3.2.4. Utilizing DLL function ......................................................................................... 39 Microsoft .NET (Both C# and Visual Basic .NET) ......................................................... 40 3.2.5. DLL Declaration ................................................................................................. 40 3.2.6. Calling the SDK functions .................................................................................. 40 3.2.7. Developing .NET applications for 64-bit Windows ............................................. 40 Using WOW64 ............................................................................................................... 40


1 Introduction

1.1 Overview

The IBISDK is developed for use with Light Emitting Sensor Film (LES) scanners from Integrated Biometrics. This SDK provides the ability to add fingerprint biometric capability to applications where you need the highest confidence in user identification.. This includes initial and secondary authentication of the user, and also re-authentication events. The result is the highest level of security, which maximizes the return on your investment. You can also create valid audit trails to monitor high-value user activities in all application workflows. All hardware and software elements of this product have been developed internally and Integrated Biometrics (IB) owns the entire design process. IB also has complete control over the support and maintenance teams. The LES hardware imaging qualities—as well as the algorithms for template generation, image processing and matching—represent the highest performance available in the world. This claim is based on independent certification and testing events, including FBI Appendix F Certification, National Biometric Security Project Certification, Transportation & Security Administration (TSA) Certification and FVC Algorithm competitions.

1.2 About Images and IB User Templates

Using this SDK, the developer can store both user templates and fingerprint images. However, you don’t need to store images to perform enrolled user matching. For applications where images will be stored in the database1, we strongly recommend that users approve this procedure PRIOR to enrollment. Please note: re-creation of original fingerprint images from IB User Templates is NOT possible.

The image generation, image processing, user template generation and matching algorithms included with this SDK are the very latest versions. If you have been using previous versions, please contact IB technical support for guidance on upgrading to the latest release.

The templates generated using IBISDK are proprietary and unique to Integrated Biometrics. The primary goal during algorithm development was to ensure the highest levels of security, user convenience and matching efficiency, while avoiding the legacy constraints usually encountered by AFIS algorithms being used in non-AFIS applications. The algorithm designs

1 Note that image file size is currently 101,376 (99k) bytes.


consider the real world habits of users, including inconsistent finger placement on the sensor (which is common in unattended applications). The result is maximum convenience for users, while achieving superior False-Reject-Rate and False-Accept-Rate performance.

1.3 Template Data Formats

There are two template-size options included with this SDK: 404 bytes and 9456 bytes. These two template formats can be used interchangeably. The 404-byte template includes only the raw data extracted from the fingerprint image, while the 9456 template includes the fully processed raw data. Althought the pre-processing of the raw data reduces the processing necessary for template matching, it does increase the memory storage requirements. We recommend that you consider that available system resources when choosing the template size. Typically, the 9456 template is found in PC based applications, and the 404 template is used in smaller, embedded systems.

The 9456 byte template consists of 9052 bytes of the fully processed raw data plus the 404 bytes of raw data. This design permits interchangeable use of these template formats when deploy mulitple devices into a mixed environement.

NOTE: Calls or descriptions of 9052 in this document refer to the 9456 byte template. The template structure is represented in the figure below.

9052 bytes

eees 404 bytes

9456 = 9052 +

404


1.4 Installation, Files, and Folders

1.4.1. System Requirements

Item Requirements

Operating System Windows 2000 / XP / XPe / 2003 / VISTA / 7

CPU Pentium or higher

Hardware Scanning Device Curve or eCurve USB Scanner

1.4.2. Installation

After installation of the IBISDK, you’ll find several folders in the Start Menu, as shown in the figure below.

Windows 7


Windows XP


1.4.3. Installation Files

Main Sub Description

Library folder BioNetAcsDll Header file that proclaim C functions

BioNetAcsDLL A LIB file consisting of C functions. This file is required to implement C programming.

BioNetAcsDLL A lib file composed of C functions. This file is required to implement C programming.

Sample Source folder

C Sharp

Visual C++

Visual C++ 6.0 sample source code ( requires Visual C++ 6.0 program)

Visual Basic Visual Basic sample source code (requires Visual Basic program.)

Driver folder

X86 32 Bit

X86 64 Bit

USB Driver Install.exe

DPInst Installation Application

usbfpdrv Security Catalog

UsbFpDrv Setup Information

UsbFpDrv System File

WdfCoInstaller01007.dll Application Extension

Sample Application folder

IBICaptureSampleForVB

IBICaptureSampleForVC

IBI Get Image Sample for VC

IBI SDK Sample for C#

IBI SDK Sample for VB

IBI SDK Sample for VC

A fingerprint recognition algorithm demo program created using DLL

Help Folder IBI SDK English manual

Table 2


1.5 Best Practices Suggestions

1.5.1. Template / Memory / Database Size Considerations

• For PC based applications where extra memory (RAM) is available for buffering, we recommend the use of the 9456 byte template for best performance.

• We recommend the 404-byte template for mobile platforms or hardware environments with limited memory resources available .

• The matching process for the 404-byte template does require more processing than the 9056 byte template. But for “small” databases, the impact on speed of matching will be negligible.

1.5.2. Recommended Enrollment Procedure

• Record each fingerprint to be enrolled in the database, especially if you are performing administered enrollments.

• A common practice is to enroll at least two fingers for each enrollee. At least one from each hand is best.

• Capture three images for each finger, and require the enrollee to lift and re-place finger after each image capture Note: the benefit of this procedure is that you are likely to capture a larger area of the finger since the enrollee will not position the finger in exactly the same location each time.

• Display the images so that either the enroller and/or enrollee can see the images. Note: refer to the enrollment guide for best practices.

• Use the NFIQ scoring tool to establish minimum acceptance thresholds for image quality. This will increase usability and user satisfaction.

• Perform a matching security level check during the enrollment. You should use the Matching Security Level setting planned for your application. Taking this step will ensure accurate and convenient system performance for the enrollee. If the score is below threshold acceptance levels, then reject it and request re-enrollment of the same or different finger. Since each fingerprint is unique, some inconsistencies may happen occasionally.

• The use of indexing is recommended if you expect the number of enrolled templates to exceed 50,000.

• If you don’t use the fingerprint scanner opened by the OpenNetAccessDevice() function, you should remove the device handle from memory by calling the CloseNetAccessDevice() function. Always run this function when all programming related to the device is concluded.


1.6 BISDK Configuration

OS

Device Driver

SDK

Various Language (Visual C++, Visual Basic, …)


1.7 NFIQ Image Quality

The NFIQ fingerprint image quality algorithm perform analysis on the fingerprint images and assigns an integer quality value to the image in the range of 1 (highest quality) down to 5 (lowest quality). The higher quality images produce significantly better overall matching performance (lower real world FRR), and also better user satisfaction and matching performance. Although developed primarily for use with AFIS systems, we recommend using the NFIQ score to establish minimum thresholds for image quality in commercial applications.

We include this scoring feature in the SDK to support of best practices for enrollment. The default setting is level 3, but level 4 will result in acceptable performance for most commercial applications.

NOTE: the NFIQ image score has no impact on the matching security level settings and related FAR / FRR performance. Statistically, the matching performance is determined solely by security level setting and associated matching parameters incorporated in the IB matching algorithm.

1.8 Security Level Settings

1.8.1. Matching 404 vs. 404, & 404 vs. 9456, and 9456 vs. 9456 (Indexing Level 0)

In the table below, we list the seven Security Level settings:

Level FAR FRR 1 0.02713% 0.00273% 2 0.00857% 0.00478% 3 0.00178% 0.00682%

4(default) 0.00071% 0.00819% 5 0.00036% 0.01228% 6 0.00000% 0.02252% 7 0.00000% 0.03684%

Table 3


1.8.2. Testing Platform

Tests performed in the lab environment given in Table 4 produced the FAR and FRR values that we present in Table 3. Although these are machine-related statistical values, they have been validated in product testing with independent testing organizations in real world applications.

Item Description Test PC Specifications Pentium IV Core2Duo 3 GHz, 4GB DDRRAM,

5400 rpm SATA Hard Disk No. of Fingerprint Images 12,000 Image Rotation Allowance -30º ~ + 30º

Table 4

1.8.3. Matching Speed

In an environment similar to that shown in Table 4, using default security settings, the IB matching algorithm will perform 30,000 matching cycles per second typical (on average 32.4 milliseconds per match, with the templates stored in system RAM). It’s important to realize that host computer specifications, security level settings, and host application design will affect the performance .

1.8.4. Indexing Level Setting

The IB SDK provides features for recognizing and recording fingerprint image feature traits common in fingerprints into the IB User Template. For larger template database sizes (>50,000) one-to-many comparisons, an incremental increase in search speed will reduce overall average matching speed. Speeds for Index Level settings are represented in Table 5.

Template to Template Comparison Speed by Indexing Levels

Level 9456 x 9456 404 x 9456 404 x 404

0(default) 0.0457 ms 0.0698 ms 0.0886 ms 1 0.0367 ms 0.0493 ms 0.0614 ms

Table 5


NOTE: The matching performance is linear and does not vary with increasing template database size. Average matching performance for a given database size will be one-half the total calculated value (i.e. comparing 9456 x 9456 templates with a database of 10,000 templates will require 0.457 seconds to perform a compare on the entire database. On average a match will be found after processing only half of the record set, resulting in an average matching performance of 0.228 seconds for a database of 10,000 templates).

NOTE: The image capture and feature extraction sequence using the LES USB scanner requires approximately 400ms. Feature extraction is performed on the host.

1.8.5. C Programming

IBISDK provides a DLL containing many C functions. If you go to the Lib Folder, you will find BioNetAcsDLL.dll, BioNetAcsDLL.lib (see the section, Installation, Files, & Folders).


2 C Function Library

2.1 Configuration of Shared DLL (BioNetAcsDLL.dll)

If you are building an application that employs a library of C functions, you must load and use the BioNetAcsDLL.dll in IBISDK.

The functions in this DLL are largely divided into several functional categories, (a) basic properties, (b) the acquisition of fingerprints, and (c) the authorization of fingerprints. We describe each of these in the subsections below.

DLL Library

(BioNetAcsDLL.dll)

Fingerprint Acquisition

Related Functions

Template Generation &

Matching Functions

Basic Properties

(Get & Set Functions)

Figure 3


2.1.1. Basic Properties (Get and Set functions

Here is a table enumerating all of the Get and Set functions:

Function short GetImgWidth() short GetImgHeight() long GetImgSize() long GetUSBKey() short GetUSN(char *usn) short GetUSNList(char *usnlist) short IsOperatingUsbMode() short GetFeatSize() const char* GetSDKVersion() void PutSecurityLevel404vs404(short nLevel) void PutSecurityLevel404vs9052(short nLevel) void PutSecurityLevel9052vs9052(short nLevel) short GetSecurityLevel404vs404() short GetSecurityLevel404vs9052() short GetSecurityLevel9052vs9052() void PutIndexingLevel(short nLevel) short GetIndexingLevel()

Table 6

Below we provide a description of each function.

2.1.2. IBI SDK Setting Functions

GetImgWidth

Prototype short GetImgWidth()

Description Returns the width size of the fingerprint image acquired by the LES USB Scan.

Return Returns the width size of the fingerprint image, 352 (pixels)

References 6.1.5 Size of Fingerprint Image (Width & Height)


GetImgHeight

Prototype short GetImgHeight()

Description Returns the height size of the fingerprint image acquired by the Fingerprint USB Scanner.

Return Returns the height size of the fingerprint image, 288 (pixels)

References 6.1.5 Size of Fingerprint Image (Width & Height)

GetImgSize

Prototype long GetImgSize()

Description Returns the data size of the fingerprint image acquired by the Fingerprint USB Scanner.

Return Returns the byte size (288 x 352 = 101,376 bytes) of the fingerprint image

GetUSBKey

Prototype long GetUSBKey()

Description A unique USB Key can be stored in the LES USB scanner prior during manufacture if there is a customer need beyond that provided by the Unique Serial Number. This is the function to run if you want to learn the embedded USB key value. The value must be displayed in the “%u” unsigned long type.

Return Returns the value of the USB key

GetUSN

Prototype Short GetUSN(CHAR *usn)

Description Each LES USB Scanner has an embedded unique USN (Unique Serial Number). This is the function to run if you want to learn the embedded USN value of the device.

Return Returns 1 for success, 0 for fail


GetUSNList

Prototype Short GetUSNList(CHAR *usnlist)

Description Each LES USB Scanner has an embedded unique USN (Unique Serial Number). This is the function to run if you want to learn the USN value of connected devices .

Return Returns count of connected devices (1 - 8) for success, 0 for fail. Example: If three devices are connected to a computer, the value of USN are saved in usnlist parameter as “USN1,USN2,USN3” (separated by “,”).

IsOperatingUsbMode

Prototype short IsOperatingUsbMode()

Description The Fingerprint USB Scanner supports both USB 1.1 and 2.0 Modes This is the function to run if you want to know whether the device is connected to USB High Speed 2.0 port or Low Speed 1.1 port.

Return USB 2.0 if NA2_USB_HIGH (1) USB 1.1 if NA2_USB_LOW (0)

GetFeatSize

Prototype short GetFeatSize()

Description Lets you know the size of the feature data of the fingerprint authorization algorithm that is currently in use.

Return Returns the size (9456 bytes) of the fingerprint feature.

References 5.3 Feature Data

GetSDKVersion

Prototype void GetSDKVersion(byte[ ] ver)

Description This function lets you know the version data of BioNetAcsDLL.dll. If received in the character string, you will find three types of version data. The first one is the version of BioNetAcsDLL.dll, the second is the Image Capture algorithm version being used and the third is the Matching Algorithm version in use.

Return Returns the character-string BioNetAcsDLL.dll version data and algorithm version data related to fingerprint acquisition and authorization included in this DLL.

Example Return String: IBISDK ver 2.2.0 (20110317)


PutSecurityLevel404vs404

Prototype void PutSecurityLevel404vs404(short newLevel)

Description This function is used to set up the security level when matching two 404-byte fingerprint template data.

Parameter newLevel – specify the value of the level shown in Table 3 above.

References 5.7 Security Level Setting



Description This function is used to set up the security level when matching one 404-byte template data with another 9,052-byte fingerprint template data.





Description This function is used to set up the security level when matching two 9,052-byte fingerprint template data.



GetSecurityLevel404vs404

Prototype short GetSecurityLevel404vs404()

Description Returns the value of the security level set using PutSecurityLevel404vs404 function (or the default value – currently 4)

Return The returned value becomes one of the level values illustrated in Table 3 above.





Description Returns the value of the security level set using PutSecurityLevel404vs9052 function (or the default value – currently 4)





Description Returns the value of the security level set up using PutSecurityLevel9052vs9052 Function



PutIndexingLevel

Prototype void PutIndexingLevel(short nLevel)

Description When you have a match with the #2 fingerprint template, the indexing level should be used.

Parameter nLevel – specify the value of the level shown in Table 5 above.

References 5.7.1 Index Level Setting

GetIndexingLevel

Prototype short GetIndexingLevel()

Description Returns the indexing level value that is set by PutIndexing Level function.


References 5.7.1 Index Level Setting


2.1.3. Example of Internal Algorithm Setting Functions

CString CCOMSampleDlg::ExcuteOtherFunctions()

{ CString szInfo; char szVersion[1024]; char szUSBkey[20];

short nImgWsize,nImgHsize,nFeatureSize;

short SecurityLevel9052 = 4,SecurityLevel404 = 4;

long lImgSize;

unsigned long lUSBkey;

unsigned char USBkey[4]={0};

nImgWsize=ImageWidth(); // Get Image Width

nImgHsize=ImageHeight(); // Get Image Height

lImgSize=ImageSize(); // Get Image Size

nFeatureSize=GetFeatureSize(); // Get Feature Size

strcpy (szVersion, GetSDKVersion()); // Get SDK Version Info

lUSBkey=GetUSBKey(); // Get USB Key Value

PutSecurityLevel9052vs9052(SecurityLevel9052);

// Set 9052 Security Level

PutSecurityLevel404vs404(SecurityLevel404);

// Set 404 Security Level

SecurityLevel9052 = GetSecurityLevel9052vs9052();

// View 9052 Security Level

SecurityLevel404 = GetSecurityLevel404vs404();

// View 404 Security Level

memcpy(USBkey,&lUSBkey,4);

sprintf(szUSBkey,"%x,%x,%x,%x",USBkey[0],

USBkey[1],USBkey[2],USBkey[3]);

szInfo.Format("W:%dxH:%d=%d\nFeature:%d\nUSBKey:%s=%u\Version:\n%s

\n\nSecurityLevel9052=%d\nSecurityLevel404=%d\nSecurityLevel9052=%d\nSecurityLevel404=%d", nImgWsize, nImgHsize, lImgSize, nFeatureSize, szUSBkey, lUSBkey, szVersion, SecurityLevel9052,

SecurityLevel404); return szInfo;

}


Figure 4

2.1.4. Fingerprint Acquisition Order

If you want to acquire fingerprints through DLL Interface, you must call upon the aforementioned functions in the following order:

Return > 0 Device Online

Return > 1 (Good Print)

Return > 0 Device Online

Return > 1 (Good Print)

GetDeviceStatus()

PutSecurityLevel()

START

Return <= 1 (No/Bad Scan)

Return <= 0 (Device not ready)

OpenNetAccessDevice() or OpenNetAccessDeviceByUSN()

CloseNetAccessDevice()

END

ControlTOUCH() (Auto On feature)

GetNetAccessImage

()

ControlLED() – Prompt to scan finger.

ControlLED() – Prompt to remove finger.


2.1.5. Size of Fingerprint Image (Width & Height)

NOTE: The following is left in place for instructional purposes, but functionality is now available through the DLL as the functions InvertImage() and RotateImage().

The Fingerprint USB Scanner produces an image size of 352 ⅹ 288 pixels, having a width of 352 pixels and length of 288 pixels. Note: the original image output is has an orientation that is 90º clockwise from finger placement in the scanner platen (see Figure 5).

The sample program above will produce a fingerprint image 288 pixels wide and 352 pixels in height. Please refer to the Make288x352ImgFunction as follows.

Figure 5


Example

The following code example will display an image vertically, such that you do not have to rotate the image every time. Keep in mind that, when extracting a feature template of the fingerprint, you must insert the raw image produced by the GetNetAccessImage() function into ExtractFeature() function as a parameter.

The next function rotates the raw image with a width of 352 pixels and length of 288 pixels counterclockwise to make a 24-bit bitmap image (excluding the bitmap header) with a width of 288 pixels and length of 352 pixels. However, the image has been flipped horizontally once to have a Device Independent Bitmap (DIB) structure (not included in BioNetAcsCOM.dll or BioNetAcsDLL.dll).

BOOL Make288x352Img(unsigned char *p352x288Img, LPSTR lp288x352Img)

{

int x, y;

BYTE result;

if(!lp288x352Img) return(FALSE);

for(x=0; x<352 ; x++)

{ for(y=287 ; y>=0 ; y--)

{result = *(p352x288Img + 352*y +x);

//result = ~result; // background color is white.

* lp288x352Img ++ = result;



}

}

return(TRUE);

}


2.1.6. Fingerprint Acquisition Related Functions


Functions

short OpenNetAccessDevice() short OpenNetAccessDeviceByUSN(char *pUSN) short CloseNetAccessDevice() short GetNetAccessImage(unsigned char *pSourceImg)

short GetDeviceStatus()

short ControlLED(unsigned char R, unsigned char G, unsigned char B)

short ControlTOUCH(unsigned char OnOff)

int IB_comp_nfiq(char *pSourceImg, char *pOnfiq)

int IB_WSQCompressImage(char *pSourceImg, char *pCompressed)

int IB_WSQExpandImage( [in] char *pCompressed, [in] int ImgLength, [out] char *pExpandedImg)

void Extract404From9456Template([in] char *p9456, [out] char *p404)

void InvertImage(char *pImage)

void RotateImage(char *pInImage, char *pOutImage, char invert)

void EnhanceImage(char *pInImage, char *pOutImage)

Table 7 Below we provide a description of each function.

OpenNetAccessDevice

Prototype short OpenNetAccessDevice()

Description This is an initialization function for starting the default USB fingerprint scanner

Return Returns 1 for success, 0 for fail.

OpenNetAccessDeviceByUSN

Prototype short OpenNetAccessDeviceByUSN(char *pUSN)


Description This is an initialization function for starting a particular USB fingerprint scanner that is specified by serial number (USN).


CloseNetAccessDevice

Prototype short CloseNetAccessDevice()

Description If not using the device handle opened by OpenNetAccessDevice()Function any longer, you should remove the device handle using this function. ALWAYS run this function when all programming related to the device is concluded.


GetNetAccessImage

Prototype short GetNetAccessImage(unsigned char *pSourceImg)

Description This is the function used to obtain fingerprints at the Fingerprint USB Scanner. If you insert the pointer of the image data (352x288) to become a parameter, this function will return the value of the image status.

Parameter pSourceImg - To obtain fingerprint image data. An image data pointer with a size of 352x288 bytes and black background color. A feature must be extracted with the pSourceImg data after running this function. Example: GetImageStatus(pImgData) ExtractFeature(pImgData , pFeatData)

Return -1 The Fingerprint USB Scanner is not connected (disconnected). 0 The finger is not touching the sensor. 1 The finger is touching the sensor, but the image is not good (do not

use this image). 2, 3, or 4 The finger is touching the sensor, and the image is good. The higher

the value, the better the quality.

GetDeviceStatus

Prototype short GetDeviceStatus()

Description Returns the connection status between the Fingerprint USB Scanner and host system.

Return Returns 1 if the Fingerprint USB Scanner is connected; returns 0 otherwise.


ControlLED

Prototype short ControlLED (unsigned char R, unsigned char G, unsigned char B)

Description You can control LED to ON or OFF on the Fingerprint USB Scanner.

Parameter R = 1 RED LED turns on. R = 0 RED LED turns off. G = 1 GREEN LED turns on. G = 0 GREEN LED turns off. B = 1 BLUE LED turns on. B = 0 BLUE LED turns off.


ControlTOUCH

Prototype short ControlTOUCH(unsigned char TOUCH_ONOFF)

Description You can control touch sensor to ON or OFF on the Fingerprint USB Scanner.

Parameter TOUCH_ONOFF = 1 Touch sensor on. TOUCH_ONOFF = 0 Touch sensor off.


IB_comp_nfiq

Prototype int IB_comp_nfiq(char *pSourceImg, char *pOnfiq)

Description Calculates an NFIQ image quality score for a given image.

Parameter pSourceImg A data pointer to the fingerprint image to be evaluated. Onfiq A secondary scoring value using an alternate calculation.

Return Returns 1, 2, 3, 4, or 5 for a successfully calculated NFIQ Quality Score. Returns 0 for failure to evaluate image. But a secondary scoring may be available in pOnfig.

IB_WSQCompressImage

Prototype int IB_WSQCompressImage(char *pSourceImg, char *pCompressed)


Description Performs WSQ compression on an image.

Parameter pSourceImg A data pointer to the fingerprint image to be compressed. pCompressed A pointer to the WSQ compressed byte array.

Return Returns a non-zero integer for the length of the compressed value; returns 0 for failure.

IB_WSQExpandImage

Prototype int IB_WSQExpandImage([in] char *pCompressed, [in] int ImgLength, [out] char *pExpandedImg)

Description Uncompresses an image in WSQ format.

Parameter pCompressed A data pointer to the WSQ compressed image to be expanded. ImgLength Length of the WSQ byte array to be expanded. pExpandedImg A pointer to the newly expanded image array.

Return Returns a non-zero integer for the length of the expanded image.; returns 0 for failure.

Extract404From9456Template

Prototype void Extract404From9456Template([in] char *p9456, [out] char *p404)

Description Extracts the 404 byte array (making up the 404 template) from a full-sized template.

Parameter p9456 A data pointer to the full-sized template. p404 A pointer to the newly extracted 404-byte template.

InvertImage

Prototype void InvertImage(char *pImage)

Description Built-in helper function to turn the black background image into a more standard white background image.

Parameter pImage A data pointer to the image to be inverted.


RotateImage

Prototype void RotateImage([in] char *pInImage, [out] char *pOutImage, char invert)

Description Built-in helper function to rotate (and invert) an image into a more standard orientation (and with a white background). The rotation is 90 degrees counter-clockwise.

Parameter pInImage A data pointer to the original image to be modified. pOutImage A data pointer to the returned rotated (and inverted) image.

invert 0 value does not change original colors, 1 inverts.

EnhanceImage

Prototype void EnhanceImage(char *pInImage, char *pOutImage)

Description Helper function that calls an IB enhanced image function. It typically makes light images darker, but also increases the contrast between the light and dark areas.

Parameter pInImage A data pointer to the original image to be modified. pOutImage A data pointer to the returned rotated (and inverted) image.


Figure 6

2.1.7. Fingerprint Matching Process Flow

START

End (Match)

AlgoInit()

ExtractFt(Image1,

Feature1)

Return > 0 ; Extraction Success

1

ExtractFt(Image2, Feature2) or pull enrolled feature template from a data

CompareFt9052vs9052 (Feature1, Feature2)

Return > 0; Extraction Success

End (No Match) End (Image Error)

Return > Matching Score Threshold

Return <= Matching Score Threshold

Return <= 0 (Extraction Error)

2

source.


2.1.8. Fingerprint Enrollment Process Flow

Figure 7

START

End (Success)

AlgoInit()

ExtractFt(Image,

Feature)

Return > 0 Extraction Success In

EnrollSingleTemplate (Image1,Image2,Image3,

Feat1,Feat2,Feat3,

ResultFeatureTemplate)

Good Image Count = 3 Extraction Success

End (Failure)

Capture 3 Good Images (see Fingerprint Acquisition Order Flowchart)

Increment Good Image Count


Good Image Count < 3

Return > 0 Extraction Success In



2.2 Fingerprint Template Generation and Matching


C dll Function

short AlgoInit() short ExtractFt(unsigned char * pImg, unsigned char *pFp) long CompareFt404vs404( unsigned char* pOne404 , unsigned char* pTwo404) long CompareFt404vs9052( unsigned char* pOne404 , unsigned char* pTwo9052) long CompareFt9052vs9052( unsigned char* pOne9052 , unsigned char* pTwo9052) short Enroll_SingleTemplate( unsigned char Img1[], unsigned char Img2[], unsigned char Img3[], unsigned char Fea1[], unsigned char Fea2[], unsigned char Fea3[], unsigned char ResultTemplate[])

Table 8 Below we provide a description of each function.

AlgoInit

Prototype short AlgoInit()

Description The AlgoInit function allocates memory necessary for the live image template feature data extraction and matching process. This function call is only required at the beginning of the fingerprint extracting & matching process.

Parameter pCompressed A data pointer to the WSQ compressed image to be expanded. ImgLength Length of the WSQ byte array to be expanded. pExpandedImg A pointer to the newly expanded image array.



ExtractFt

Prototype short ExtractFt(unsigned char * pImg, unsigned char *pFp)

Description This is the function that extracts the feature data using our fingerprint matching algorithm on the 352x288 fingerprint image.

Parameter pImg A fingerprint image data pointer with a 352ⅹ288 size and black background color to extract the feature data (see 2.3.5 GetImageStatus Parameter)

pFp Buffer with 9,456-byte memory

Return Returns 1 for success, 0 for fail, < 0 for access violation at address

CompareFt404vs404

Prototype long CompareFt404vs404(unsigned char* pOne404 , unsigned char* pTwo404)

Description This is a function that performs the matching between two 404-byte fingerprint feature data, and returns the matching score value afterwards.

Parameter pOne404 404-byte Fingerprint Feature Data pTwo404 404-byte Fingerprint Feature Data

Return Returns 1 for successful authorization, 0 for failure, -1 for access violation at address, -2 for minimum feature num error, -3 for invalid feature, -4 for other failure

CompareFt404vs9052

Prototype long CompareFt404vs9052(unsigned char* pOne404 , unsigned char* pTwo9052)

Description This is a function that performs the matching between one 404-byte fingerprint feature data and another 9,052-byte fingerprint feature data, and returns the matching score value afterwards.

Parameter pOne404 404-byte Fingerprint Feature Data pTwo9052 9052- or 9456-byte Fingerprint Feature Data

Return Returns > 0 for successful authorization, 0 for failure, -1 for access violation at address, -2 for minimum feature num error, -3 for invalid feature, -4 for other failure


CompareFt9052vs9052

Prototype long CompareFt9052vs9052(unsigned char* pOne9052, unsigned char* pTwo9052)

Description This is a function that performs the matching between one 404-byte fingerprint feature data and another 9,052-byte fingerprint feature data, and returns the matching score value afterwards.

Parameter pOne404 404-byte Fingerprint Feature Data pTwo9052 9052- or 9456-byte Fingerprint Feature Data

Return Returns > 0 for successful authorization, 0 for failure, -1 for access violation at address, -2 for minimum feature num error, -3 for invalid feature, -4 for other failure


Enroll_SingleTemplate

Prototype short Enroll_SingleTemplate(unsigned char Img1[], unsigned char Img2[], unsigned char Img3[], unsigned char Fea1[], unsigned char Fea2[], unsigned char Fea3[], unsigned char ResultTemplate[])

Description This is a function is used for template generation during enrollment. It requires three fingerprint images (byte array), and four 9,456-byte fingerprint feature data arrays (three for each individual image template and one for a composite template). The function returns three types of values: successful registration, failed registration, and bifurcation caused by multiple feature registrations. If the registration was successful, the fingerprint feature data 1, 2 and 3 are integrated to produce an optimal feature dataset returned through the ResultTemplate parameter. Individual templates are captured in Fea1, Fea2 and Fea3, but are rarely kept as permanent data.

Parameter Img1 The 1st fingerprint image data pointer is 352x288 in size and has a black background color to extract the feature data (see 2.3.5 GetImageStatus Parameter)

Img2 The 2nd fingerprint image data pointer is 352x288 in size and has a black background color to extract the feature data (see 2.3.5 GetImageStatus Parameter)

Img3 The 3rd fingerprint image data pointer is 352x288 in size and has a black background color to extract the feature data (see 2.3.5 GetImageStatus Parameter)

Fea1 Buffer with 9,456-byte memory making pImage1 and Img1 a pair Fea2 Buffer with 9,456-byte memory making pImage1 and Img2 a pair Fea3 Buffer with 9,456-byte memory making pImage1 and Img3 a pair

ResultTemplate Buffer with 9,456-byte memory to save the registration results

Return 1 Successfully registered by supplementing the information on the 2nd and 3rd fingerprints based on the 1st fingerprint image.

2 Successfully registered by supplementing the information on the 1st and 3rd fingerprints based on the 2nd fingerprint image.

3 Successfully registered by supplementing the information on the 1st and 2nd fingerprints based on the 3rd fingerprint image.

0 Failed to register -1 Error condition. No template made (retry).

References See 6.1.8 Fingerprint Registration Algorithm Execution Order


3 Programming

3.1 Visual C++ 6.0

To do Visuall C++ developerment, start by copying the BioNetAcsDLL.lib and BioNetAcsDLL.dll inside the Lib of IBISDK, and paste them to the working path. Statically load the algorithm library as shown in Figure 8.

Also, copy BioNetAcsDll.h inside the Lib of IBISDK, and paste it to the working path. Include the BioNetAcsDll.h file, which is the prototype of the functions declared in BioNetAcsDll.lib.

#include “BioNetAcsDll.h”

Example of Function Application m_nImageSize = GetImgSize(); m_nImageYsize = GetImgHeight(); m_nImageXsize = GetImgWidth();

Figure 8


3.2 64-Bit application development for Visual C++

3.2.1. 64-Bit development overview

32-bit Biometric applications run properly on an AMD 64-bit Windows computer that has WOW64 enabled. We recommend this method because the installation procedures are simpler, and the 32-bit executables are smaller and faster. However, special cases require 64 bit software development:

• Running on systems without WOW64

• Very large application memory requirements

3.2.2. 64-Bit development procedure

Copy the files BioNetAcsDLL.lib and BioNetAcsDLL.dll from the Lib\Lib64 folder of IBISDK, and paste them to the working path. Reference the algorithm library from project settings as shown in Figure 8.

Figure 9


Copy BioNetAcsDll.h from the Lib\Lib64 folder of IBISDK and paste it to the working path. Include the BioNetAcsDll.h, which is the prototype of the functions declared in BioNetAcsDll.lib. Figure 9 shows the project properties page once the reference has been added.

Note: The header file BioNetAcsDll.h is the same for both 32-bit and 64-bit development.


Microsoft Visual Basic 6.0

3.2.3. DLL Declaration

DLL file : BioNetAcsDll.dll

File path : Locate DLL file in Visual Basic folder or system file folder.

Declare at common module (Global Module):

Public Declare Function GetSDKVersion Lib "BioNetAcsDll.dll" (ByRef lbyte_ver As Byte) As Integer Public Declare Function GetImgWidth Lib "BioNetAcsDll.dll" () As Integer … Public Declare Function GetNetAccessImage Lib "BioNetAcsDll.dll" (ByRef lbyte_img As Byte) As Integer

3.2.4. Utilizing DLL function

Here’s an example:

On Error GoTo err_label

Dim ls_str As String

Dim lbyte_usn() As Byte

ReDim lbyte_usn(0 To 100) As Byte

Dim ii_ret As Integer

ii_ret = GetUSN(lbyte_usn(0)) ‘ DLL function

For i = 0 To 100

If lbyte_usn(i) = 0 Then Exit For

ls_str = ls_str + Chr(lbyte_usn(i))

Next

Text2.Text = Trim(ls_str)

Exit Sub

err_label:

MsgBox Str(Err.Number) + vbCrLf + Err.Description


Microsoft .NET (Both C# and Visual Basic .NET)

3.2.5. DLL Declaration

DLL file : BioNetAcsDll.dll

Procedure: simply copy the DLL file to the BIN \ Debug and Release folders in the solution.

3.2.6. Calling the SDK functions

Add the file BioNetACSDLL.cs from the sample C# project, then call the public functions. Optionally, also use the component iBioNetACS.cs from the C# sample program. This component implements the multiple-finger enrollment template.

3.2.7. Developing .NET applications for 64-bit Windows

Change the file BioNetACSDLL.cs from the sample C# project to reference BioNetACS64.dll, then call the public functions. Be sure to set a target CPU of x64 from Build / Configuration manager, and select ‘x64’ as the target platform.

Using WOW64

Applications developed with the BioNetAcs.Dll interface will run on 64-bit Windows under .NET as 32-bit runtimes under WOW64, but with the restriction that the module that calls the BioNetAcs.Dll functions must be designated for 32-bit code. The default setting of “Any CPU” for .NET projects will result in a “Just In Time” compile of 64-bit code at run time. This will fail to load the 32-bit DLL. However, if the .NET code targets the ‘x86’ CPU, the resulting 32-bit “Just In Time” runtime code will correctly load the BionetAcs.Dll code.

Set the ‘x86’ target from Build / Configuration manager, and select ‘x86’ as the target platform.

Applications developed with these settings will run on both 32-bit systems and AMD64 systems with WOW64 enabled.

© 2012 Integrated Biometrics LLC.

Integrated Biometrics LLC.

121 Broadcast Drive

Spartanburg SC 29303

phone: (864) 990-3711

toll free: (888) 840-8034

fax: (864) 631-1719

http://www.integratedbiometrics.com

IBSDK Programmers Guide for Windowsjournoportfolio.s3-website-eu-west-1.amazonaws.com/... ·...

Documents

Transcript of IBSDK Programmers Guide for Windowsjournoportfolio.s3-website-eu-west-1.amazonaws.com/... ·...