Fingerprint Identification SDKsmackbio.mycomb.cn/web/smackbio/files/SFESpecification.pdf · Fingerprint Identification SDK ... Set a fingerprint feature data into the internal database

Fingerprint Identification SDK

“Smack Finger SDK 3.0” Specification 1.3

Beijing Smackbio Technology Co., Ltd.

2008. 6

Copyright 2004-2008 Beijing Smackbio Technology Co., Ltd. “Smack Finger SDK3.0” Specification 1.3

- - 2

Contents

CONTENTS ............................................................................................................................................................................2

1. OPERATING ENVIRONMENT ......................................................................................................................................3

2. SPECIFICATION...............................................................................................................................................................3

3. INTERFACE FUNCTION.................................................................................................................................................4

4. FUNCTION LIST...............................................................................................................................................................5

5. ERROR CODE ...................................................................................................................................................................8

6. FUNCTION DESCRIPTION ............................................................................................................................................9

7. DIAGRAM ........................................................................................................................................................................26

7.1 ENROLLMENT.................................................................................................................................................................26

7.2 1 : 1 / 1 : N MATCHING.................................................................................................................................................27

8. CONSIDERATION ..........................................................................................................................................................28

9. LIMITATION...................................................................................................................................................................29


- - 3

1. Operating Environment

CPU Pentium 4 (Recommend above 2GHz)

OS Windows 2000 / XP/Vista, Linux(kernel ver. 2.6.X)

RAM About 2Mbytes, and storage for enrollment database

Sensor See customer-specific document. (Usually SB1000U)

2. Specification

Item spec.

Engine version “SmackFinger” V3.0 Module File Format Dynamic Link(Shared) Library

Module File Name SFE.dll(for Windows) / sfe.so(for Linux)

Database Capacity See customer-specific document. (5K / 10K / 100K / 300K / 1000K fingerprints)

Number of inputs for a fingerprint enrollment 3 times

Size 1404 Bytes Fingerprint Template

Endianness Little-endian Image Dimension 256 × 256 pixels (403 dpi)

Speed See customer-specific document. (It depends on database capacity and doesn’t exceed 1 second on the case of 1000K enrollment, P4 2.4GHz)

FRR < 0.01% Accuracy

FAR < 0.00001%


- - 4

3. Interface Function

Function fp

int FuncNo IN Function number

long Param1 IN/OUT Parameter 1

long Param2 IN/OUT Parameter 2 Parameter

long Param3 IN/OUT Parameter 3

Return int

Description

All functions of the engine are called through this function.

According to the function, the meaning of every parameter is

different.

For the meaning of every parameter of a function, refer to the

description about the function.

In case that a parameter’s type isn’t “long”, its type must be

changed to “long”.


- - 5

4. Function List

Function

Function

Number

Description

Open 1 Initialization.

Close 2 Completion.

GetEnrollCount 5 Get the count of enrolled fingerprints

(in the internal database).

GetEmptyPos 6 Get the empty position (in the internal

database) for a new enrollment.

IsEnrolledPos 7 Check whether a position has been

used or not.

SetFpdata 11 Set fingerprint feature data (template)

into the internal database.

GetFpdata 12 Read fingerprint feature data (template)

from the internal database.

Convert256 13 Convert raw image to 256*256 image

FpCheck256 14 Check whether the 256*256 image is a

fingerprint image or not.

Process256 22 Process 256x256 fingerprint image, get

the fingerprint feature data.


- - 6

EnrollStart 31 Start an enrollment by three

fingerprints.

EnrollNth256 33 Process Nth 256x256 fingerprint image

and set Nth fingerprint enroll data for

the enrollment.

EnrollNthFpdata 34 Set Nth fingerprint enroll data for the

enrollment.

EnrollMerge 35 Compound three fingerprints’ enroll

data to a fingerprint feature data (one

template).

IdentifyFpdata 43 1 to N matching between a fingerprint

feature data and the internal database.

VerifyFpdata 44 1 to 1 matching between a fingerprint

feature data and the specified

fingerprint data in the internal

database.

IdentifyImage256 45 1 to N matching between the 256x256

fingerprint image and the internal

database.

VerifyImage256 46 1 to 1 matching between the 256x256

fingerprint image and the specified

fingerprint data in the internal

database.

Delete 51 Delete a fingerprint data from the


- - 7

internal database.

DeleteAll 52 Delete all fingerprint data from the

internal database.

ConvertFpdata

Endian

56 Reverse the endianness of a fingerprint

feature data (a template).

SenAdjust 60 Adjust the sensor’s brightness.

SenCapture 61 Capture an image using SB1000U.

SenIsFinger 62 Check whether the captured image is a

fingerprint image or not.

SenGetImg 63 Read the captured image from

SB1000U.

SenGetFeature 64 Get the fingerprint feature data of the

captured image from SB1000U.

SenSetImg 69 Send 256x256 fingerprint image to

SB1000U.

GetLibraryVersion 100 Get the version number of the library.

GetMatchData 1000 Get the buffer address of the internal

database.


- - 8

5. Error Code

Error Value Description

IMAGE_ERR -1 Error occurred in processing an

image.

FPDATA_ERR -2 The buffer for the feature among

parameters is NULL.

ID_ERR -3 ID or Position is invalid.

OVER_ERR -4 Internal database overflow.

BUFFER_ERR -6 The parameter for a buffer is NULL.

SENSOR_ERR -7 Error occurred in capturing or

communicating with the device.

NTH_ERR -8

EnrollNth256 or EnrollNthFpData

(Function No 33, 34) is called in

invalid order.

MERGE_ERR -9

Error occurred in compounding the

three fingerprint enroll data by

EnrollMerge(Function No 35).

NOT_FINGER -11 A fingerprint isn’t being placed.

DEV_ERR -100 Device (SB1000U or dongle) error.


- - 9

6. Function description

FuncNo 1 Alias Open

Param1

Param2

Param3

See customer-specific document.

If there isn’t any attention, all three parameters haven’t special

meaning and call with zero value.

0 Success. Return

< 0 Error.

Description Initialize the engine, the device and clear the internal database.

Before using other functions, you have to call this function.

FuncNo 2 Alias Close

Param1 0 No meaning

Param2 0 No meaning

Param3 0 No meaning

0 Success. Return

< 0 Error.

Description

Finalize the engine and the device.

When the application finishes using of the library, you should

call this function.


- - 10

FuncNo 5 Alias GetEnrollCount

Param1 0 No meaning

Param2 0 No meaning

Param3 0 No meaning

>= 0 The count of fingerprint data enrolled in

the internal database. Return

< 0 Error.

Description

Get the count of fingerprint data enrolled in the internal

database.

FuncNo 6 Alias GetEmptyPos

Param1 0 No meaning

Param2 0 No meaning

Param3 0 No meaning

0 ~ Database

capacity - 1

The empty position in the internal

database. Return

< 0 Error.

Description

Get the empty (no fingerprint data is enrolled) position in the

internal database. The position has the value between 0 to

Database capacity - 1.


- - 11

FuncNo 7 Alias IsEnrolledPos

Param1(IN) nPos A position value

Param2 0 No meaning

Param3 0 No meaning

1 Yes, the position has been used.

0 No, the position hasn’t been used.. Return

ID_ERR nPos value is invalid.

Description Check whether a position has been used or not.


- - 12

FuncNo 11 Alias SetFpdata

Param1(IN) pFpData Buffer address of the fingerprint feature

data to be set.

Param2(IN) nPos Setting position in the internal database.

Param3 0 No meaning.

0 Success. Return

< 0 Error.

Description

Set a fingerprint feature data into the internal database. If

another one exists already in the position, it is overwritten.

FuncNo 12 Alias GetFpdata

Param1(OUT) pFpData Buffer address for the fingerprint feature

data to be gotten.

Param2(IN) nPos Getting position in the internal database.


0 Success. Return

< 0 Error.

Description Get a fingerprint feature data from the internal database. Buffer

size must be greater than 1404 bytes.


- - 13

FuncNo 13 Alias Convert256

Param1(IN) pImageRaw Address of the raw fingerprint image data.

Param2(OUT) pImage256 Address of the 256x256 fingerprint image

data.

Param3 0 No meaning

0 Success. Return

<0 Error.

Description Convert raw image to 256x256 image..

FuncNo 14 Alias FpCheck256

Param1(IN) pImage256 Address of the 256x256 fingerprint image

data.


Param3 0 No meaning

>=0 Percent of the fingerprint area in the image.Return

NOT_FINGER A fingerprint isn’t being placed.

Description Check whether a fingerprint is placed or not in an image.


- - 14

FuncNo 22 Alias Process256


data.

Param2(OUT) pFpData Buffer address for fingerprint feature data

to be extracted.


0 Success. Return

< 0 Error.

Description Process the 256x256 fingerprint image, extract the fingerprint

feature data.

FuncNo 31 Alias EnrollStart




Return 0 Success.

Description Start an enrollment by three fingerprints.


- - 15

FuncNo 33 Alias EnrollNth256


data.

Param2(IN) Nth Enroll order.


0 Success.

< 0 Error.

Return

> 0

The position of the duplicated fingerprint

data in the internal database, 1~Database

capacity.

Description

Process Nth 256x256 fingerprint image and set fingerprint

enroll data for an enrollment.

For calculating of a fingerprint enrollment data (one template),

three successful calls of this function (with setting Param2 to 1,

2 and 3) are required in order.

If a duplicated data is detected in the internal database, return

its position. This position is (real position + 1) to distinguish

from the success return value 0.


- - 16

FuncNo 34 Alias EnrollNthFpData

Param1(IN) pFpData Buffer address of the fingerprint feature

data.

Param2(IN) Nth Enroll order.


0 Success.

< 0 Error.

Return

> 0

The position of the duplicated fingerprint

data in the internal database. 1~Database

capacity

Description

Set Nth fingerprint enroll data for an enrollment.

For calculating of a fingerprint enrollment data (one template),

three successful calls of this function (with setting Param2 to 1,

2 and 3) are required in order.

If a duplicated data is detected in the internal database, return

its position. This position is (real position + 1) to distinguish

from the success return value 0.


- - 17

FuncNo 35 Alias EnrollMerge

Param1(OUT) pFpData

Address of the buffer, which the calculated

(merged) fingerprint feature data will be

stored into.



0 Success. Return

< 0 Error.

Description Compound (merge) three fingerprints enroll data into one.

FuncNo 43 Alias IdentifyFpdata

Param1(IN/OUT) pFpData Buffer address of the fingerprint feature

data to be matched.

Param2(OUT) pnSimilarity Address of the similarity variable (“long”).


> 0

Success, the position of the matched

fingerprint data in the internal database.

This value is (real position + 1), that is,

1~Database capacity.

0 Matching failure.

Return

< 0 Error.

Description

1 to N matching with the internal database. Because our engine

uses adaptation procedure, the fingerprint feature data returned

after successful 1:1 or 1:N matching(Function Number 43, 44,

45, 46) must be saved into the database for the next matching.


- - 18

FuncNo 44 Alias VerifyFpdata

Param1(IN/OUT) pFpData Buffer address of the fingerprint feature

data to be matched.

Param2(IN) nPos Position of fingerprint data in the internal

database.


1 Success.

0 Matching failure. Return

< 0 Error.

Description 1 to 1 matching of the fingerprint feature data with the

specified fingerprint data in the database.

FuncNo 45 Alias IdentifyImage256


data.

Param2(OUT) pFpData Buffer address for the matched fingerprint

feature data.

Param3(OUT) pnSimilarity Address of the similarity variable (“long”).

> 0

Success, the position of the matched

fingerprint data in the internal database.

This value is (real position + 1), that is,

1~Database capacity

0 Matching failure.

Return

< 0 Error.

Description 1 to N matching of the 256x256 fingerprint image.


- - 19

FuncNo 46 Alias VerifyImage256


data.

Param2(IN) nPos Position of fingerprint data in the internal

database.

Param3(OUT) pFpData Buffer address for the matched fingerprint

feature data.

1 Success.

0 Matching failure. Return

< 0 Error.

Description 1 to 1 matching of the 256x256 fingerprint image with the

specified fingerprint data in the database.


- - 20

FuncNo 51 Alias Delete

Param1(IN) nPos Position of a fingerprint feature data to be

deleted in the internal databases.



0 Success. Return

< 0 Error.

Description Delete the specified fingerprint data from the internal database.

FuncNo 52 Alias DeleteAll




Return 0 Success.

Description Delete all the fingerprint data from the internal database.

FuncNo 56 Alias ConvertFpdataEndian

Param1 pFpdataSrc The address of the source template.

Param2 pFpDataDst The address of the destination template.


Return 0 Success

Description Reverse the endianness of the template.


- - 21

FuncNo 60 Alias SenAdjust




0 Success. Return

< 0 Error.

Description

Adjust the sensor (of SB1000U)’s brightness.

Adjusted brightness value is saved in persistent storage of

SB1000U.

After then, SB1000U uses the adjusted brightness value.

The manufacturer must adjust the sensor just before packing.

The customer shouldn’t adjust the sensor, but if he (she) changes

the sensor, the sensor must be adjusted.

Before adjustment, the user must clean the sensor, place the

sensor in dark environment (obstruct any lights). This is

important.

If the sensor wasn’t adjusted, SB1000U uses standard brightness

value.


- - 22

FuncNo 61 Alias SenCapture




0 Success. Return

< 0 Error.

Description Capture an image. (The captured image is stored in the internal

memory of SB1000U.)

FuncNo 62 Alias SenIsFinger




>= 0 Percent of the fingerprint area in the image. Return

< 0 Error.

Description

Check whether a fingerprint is being placed in the image

(captured by SenCapture) or not. If a fingerprint is being placed,

return its percent in the image. Strong recommended minimum

percent value is 30%. If the percent value is greater than 50%,

the image is a good fingerprint image.


- - 23

FuncNo 63 Alias SenGetImg

Param1(OUT) pImg256 The address of the buffer, which the

256×256 image to be stored into.



0 Success. Return

< 0 Error.

Description

Read the image (captured and stored in the internal memory of

SB1000U by SenCapture) and store into the specified buffer.

Buffer size must be greater than 256×256bytes.

FuncNo 64 Alias SenGetFeature

Param1(OUT) pFeature The address of the buffer, witch the

fingerprint feature to be stored into.



0 Success. Return

< 0 Error.

Description

Extract a fingerprint feature from the image (captured and stored

in the internal memory of SB1000U by SenCapture) and store

into the specified buffer. Buffer size must be greater than

1404bytes.


- - 24

FuncNo 69 Alias SenSetImg

Param1(OUT) pImg256 The address of the buffer of 256×256 image.



0 Success. Return

< 0 Error.

Description

Send the image (256x256) to SB1000U. Buffer size must be

greater than 256×256bytes.

This function is useful only in SB1000U-based mode.

See “9.Limitation”


- - 25

FuncNo 100 Alias GetLibVersion

Param1 pdwReleaseDate

0-No get release date, otherwise the address

of DWORD variable to get library release

date.

Param2 pdwLibCapacity

0-No get the library capacity, otherwise

(LSB) 30-0 bits – represents database

capacity.

(MSB) 31 bit – represents mode.

0 – PC-based fingerprint processing.

1 – SB1000U-based fingerprint processing.


Return dwVer Unsigned long type value that represents the

library version.

Description

Get the version number of the library.

The customer-specific document specifies the values of the

version, the release date and the library capacity.

FuncNo 1000 Alias GetMatchData

Param1 0 No meaning

Param2 0 No meaning

Param3 0 No meaning

Return The address of the enrollment database.

Description

Get the address of the enrollment database.

This function is useful for advanced operations of the database.

See demo application source.


- - 26

7. Diagram

7.1 Enrollment.

EnrollMerge

EnrollStart

No

SenCapture

SenIsFinger ?

Yes

Yes

NoEnrollNthFpData(1)

SenGetFeature ? No

Yes

No

SenCapture

SenIsFinger ?

Yes

Yes


SenGetFeature ? No

Yes

No

SenCapture

SenIsFinger ?

Yes

Yes


SenGetFeature ? No

Yes


- - 27

7.2 1 : 1 / 1 : N Matching.

※ Note: Because our engine uses adaptation procedure, the fingerprint feature data

returned after 1:1 or 1:N matching must be saved into the database for the next

matching.

Start

End

SaveFpData

No

SenCapture

SenIsFinger ?

Yes

Yes

NoVerifyFpdata/ IdentifyFpdata

SenGetFeature ? No

Yes

Yes


- - 28

8. Consideration

SB1000U is used to capture images and protect the SFE library, so that this device

must be connected to PC before using the library. Otherwise, that is, if the application

uses other sensor, the hardware dongle must be connected to PC before using the library.

Because SB1000U has a small internal memory, the captured (by SenCapture)

image data in the memory is invalid after call of SenGetFeature. So the functions

SenIsFinger and SenGetImg perform valid actions only from a successful calling of

SenCapture until calling of SenGetFeature.

SenGetImg is needed to read the image (in the SB1000U’s internal memory) and

doesn’t affect SenGetFeature function. And internally SenGetFeature checks whether a

fingerprint is presented or not in the image, so the feature extraction can be performed

by SenCapture and following SenGetFeature. But, from starting to press his(her) finger

on the sensor, the percent of the fingerprint area in the image is increased for a while.

Therefore, for the better performance, it’s recommended to check the quality of the

image by SenIsFinger prior to SenGetFeature.


- - 29

9. Limitation

If the database capacity is 1, the application has to use the module only for scanning and

extracting of the feature data.

Forbidden functions are IdentifyFpdata and IdentifyImage256, that is, the application

cannot use 1:N matching functions.

If the application uses other sensor (no SB1000U), SenAdjust, SenCapture, SenIsFinger,

SenGetImg, SenGetFeature, SenSetImg are forbidden.

If the mode of library is SB1000U-based, most fingerprint processing operations take

place in SB1000U hardware. In this case, forbidden functions are FpCheck256,

Process256, EnrollNth256, IdentifyImage256, VerifyImage256.

That is, in SB1000U-based mode, if the application is going to operate an image, the

application must send the image to SB1000U by SenSetImg, and then get the template

by SenGetFeature. After then, the application should operate with the gotten template.

See demo sources.

The calling of forbidden functions returns DEV_ERR.

Documents

Fingerprint Identification SDKsmackbio.mycomb.cn/web/smackbio/files/SFESpecification.pdf · Fingerprint Identification SDK ... Set a fingerprint feature data into the internal database