FP-200指纹识别算法使用手册
4. ActiveX控件参考
SDK分为1:1和1:N两个控件，其中接口属性和方法基本相同，而接口方法只有涉及1:N比对部分不同，因此以下综合说明两个控件，不同之处将分别标出和说明。
以下是语法说明，其中指纹模板Variant变量代表一维字节数组。
4.1属性
4.1.1 Active as Boolean
Read only
当前SensorIndex设定的指纹采集器是否准备就绪。
4.1.2 EngineValid as Boolean
Read only
指纹识别系统是否正常工作。调用过函数initEngine后会返回有效结果
4.1.3 EnrollIndex As Long
Read only
登记指纹时取样的序号，即表示当前手指登记已经取到的有效次数。
4.1.4 EnrollCount As Long
登记指纹时取样的次数，取值范围为1-4次
4.1.5 FPEngineVersion AS String
read only
指纹识别系统版本号
4.1.6 ImageHeight AS integer
Read only
指纹图像的高度
4.1.7 ImageWidth AS integer
Read only
指纹图像的宽度
4.1.8 IsRegister As Boolean
Read only
是否正登记指纹
4.1.9 OneToOneThreshold As Boolean
设定Biokey低速指纹1：1比对的识别阀值分数(1-100)，默认为10，值越大，误判率越低同时拒绝率变大
注意：1:1控件没有这个属性
4.1.10 RegTplFileName As String
设置当事件OnEnrollToFile发生时，保存指纹登记模板的文件名称。
4.1.11 SensorCount As Long
Read only
当前连接到计算机的指纹采集器的个数，当EngineValid无效时，返回0
4.1.12 SensorIndex AS Long
连接多个指纹采集器时，选择指纹头的序号，从0开始；小于零时指纹采集器不工作。
4.1.13 SensorSN As String
指纹采集器的硬件序列号
4.1.14 TemplateLen As Long
Read only
指纹登记模板的字节长度。
4.1.15 Threshold As Long
设定指纹识别系统比对识别阀值分数(1-100)，默认为10，值越大，误判率越低同时拒绝率变大
4.1.16 VerTplFileName As String
设置当事件OnCaptureToFile发生时，保存指纹验证模板的文件名称。
4.2 方法
1：1和1：N控件接口相同的方法：
4.2.1 Sub BeginEnroll()
开始登记指纹，登记结束后发生OnEnroll事件。
4.2.2 Sub CancelEnroll()
取消当前的指纹登记状态，即由 BeginEnroll开始的操作可由此函数中断。
4.2.3 Function DongleIsExist As Boolean
检查加密狗是否存在。
4.2.4 Function DongleSeed(Byval lp2 As Long, Byval p1, p2, p3, p4 As Integer) As Boolean
得到种子码lp2的四个16位整数(p1,p2,p3,p4)返回值，加密狗可以通过内部算法计算一个种子码，得到四个返回码。种子码算法是不公开的，可以通过检查返回码是否是期望的值来检查加密狗是否存在。
4.2.5 Function DongleUserID As Long
读出加密狗中的用户ID，用户ID不会重复相同。保存在加密狗内部特定位置。
4.2.6 Function DongleMemRead(Byval p1, p2 As Integer, buf) As Boolean
读出加密狗内存区位置p1开始的p2个字节到Variant变量buf(一维字节数组)。内存区共有24个字节，位置为0-23
4.2.7 Function DongleMemWrite(Byval p1, p2 As Integer, buf) As Boolean
写入Variant变量buf(一维字节数组)到加密狗内存区位置p1开始的p2个字节内。内存区共有24个字节，位置为0-23
4.2.8 Function GetTemplate()
得到最近一次获得的指纹模板。
4.2.9 Function GetFingerImage(Byval AFingerImage) As Boolean
得到最近一次获得的指纹图像(BMP 格式)。
4.2.10 Function InitEngine() As Long
初始化指纹识别系统。SensorCount、SensorSN、EngineValid、ImageHeight、ImageWidth等属性需在该函数被调用后才能返回正确结果。返回值:
0 初始化成功
1 指纹识别驱动程序加载失败
2 没有连接指纹识别仪
3 属性SensorIndex指定的指纹采集器不存在（注意：在调用之前设置属性SensorIndex）
可以使用方法EndEngine释放指纹设备系统
4.2. 11 Function VerFinger(byval regTemplate, verTemplate, AdoLearning As Boolean, byval AregFeatureChanged As Boolean) As Boolean
比对两枚指纹的特征模板是否匹配。其中regTemplate表示指纹登记特征模板，verTemplate表示现场采集的指纹验证特征模板，AdoLearning表示是否进行指纹特征模板学习更新。AregFeatureChanged表示登记模板regTemplate是否改变，两枚指纹匹配时返回 True，不匹配时返回 False
说明：
手指特征随时间可能会发生一定程度的变化，通常不会影响指纹的比对，但通过进行指纹特征模板学习更新，系统会综合得到新的模板，从而可以降低拒绝率。
4.2.12 Function VerFingerFromFile(regTemplateFile As String, verTemplateFile As String，AdoLearning As Boolean, byval AregFeatureChanged As Boolean) As Boolean
比对两枚指纹的特征模板文件是否匹配。其中regTemplateFile表示指纹登记特征模板文件，verTemplateFile表示现场采集的指纹验证特征模板文件，AdoLearning表示是否进行指纹特征模板学习更新。AregFeatureChanged表示登记模板文件regTemplateFile是否改变。两枚指纹匹配时返回 True，不匹配时返回 False
4.2.13 Function VerRegFingerFile(RegTemplateFile As String, verTemplate，AdoLearning As Boolean, byval AregFeatureChanged As Boolean) As Boolean
比对两枚指纹的特征模板是否匹配。其中regTemplate表示由 FileName 指定文件中的以前登记指纹特征模板，verTemplate表示现场采集的指纹的特征模板，AdoLearning表示是否进行指纹特征模板学习更新。AregFeatureChanged表示登记模板文件regTemplateFile是否改变。两枚指纹匹配时返回 True，不匹配时返回 False
4.2.14 Sub PrintImageAt(HDC As OLE_HANDLE, X As Long, Y As Long, aWidth As Long, aHeight As Long)
在由（x,y）指定的位置上按照（aWidth, aHeight）指定的大小显示指纹图像，HDC表示要显示指纹的窗口的设备描述表句柄
4.2.15 Sub PrintImageEllipseAt(HDC As OLE_HANDLE, X As Long, Y As Long, aWidth As Long, aHeight As Long, bkColor As OLE_COLOR)
在由（x,y）指定的位置上按照（aWidth, aHeight）指定的大小显示指纹图像，HDC表示要显示指纹的窗口的设备描述表句柄。这里的指纹图像被一椭圆形包围。
4.2.16 Sub SaveBitmap(FileName As String)
保存最后一次采集到的指纹的图像到 FileName 指定的位图文件中。
4.2.17 Sub SaveJPG(FileName As String)
保存最后一次采集到的指纹的图像到 FileName 指定的Jpeg文件中。
4.2.18 Function SaveTemplate(FileName As String, Template) As Boolean
保存Template指纹的特征模板到 FileName 指定的文件中。
4.2.19 function EncodeTemplate(ASour, var ADest As String) As Boolean
将控件使用的Variant模板ASour转换为BASE64格式的模板字符串ADest。
4.2.20 function DecodeTemplate(const ASour As String, ADest) As Boolean
将BASE64格式的模板字符串ASour转换为控件使用的Variant类型ADset模板。
以上两个方法主要用于模板的数据库保存，Variant类型模板是以二进制格式数组方式存放，在PB, VB等语言中操作比较困难，方法EncodeTemplate可以将Variant类型编码转换为字符串类型，方法DecodeTemplate可以将字符串类型编码转换为Variant类型，需要注意的是，模板变量BASE64编码为字符串后，模板长度将变长。
4.2.21 Sub BeginCapture()
设置当前指纹设备开始取像，可以使用方法CanncelCapture禁止当前指纹设备取像。
4.2.22 Sub EndEngine()
释放由方法InitEngine初始化的指纹设备，可以使用方法InitEngine重新初始化指纹设备。
1：N控件接口方法：
4.2.23 Function AddRegTemplateToFPCacheDB(fpcHandle As Long, FPID As Long, pRegTemplate) As Long
添加指纹登记模板pRegTemplate到指纹识别高速缓冲空间fpcHandle，FPID是要添加登记模板的标识。
4.2.24 Function AddRegTemplateFileToFPCacheDB(fpcHandle As Long, FPID As Long, pRegTemplateFile As String) As Long
添加由 pRegTemplateFile指定文件中的以前指纹登记特征模板到指纹识别高速缓冲空间fpcHandle，FPID是要添加登记模板的标识，必须>=0。返回值为1表示成功，0表示失败
4.2.25 Function CreateFPCacheDB As Long
创建指纹识别高速缓冲空间，进行1：N识别时必须首先调用该函数得到指纹识别缓冲空间句柄。
说明：
由于Biokey 1：1低速比对速度比较慢（在PII 233大约30ms）,所以使用AddRegTemplateToFPCache 函数加入到缓冲中的1：1指纹不能太多，否则影响比对速度。
通过IsOneToOneTemplate可以判断是否属于1：1指纹
可以同时创建多个缓冲区，用于分组比对等。
4.2.26 Sub FlushFPImages ()
清空当前指纹设备中的缓冲图像。
4.2.27 Sub FreeFPCacheDB( fpcHandle As Long)
释放指纹识别高速缓冲空间，fpcHandle是调用该函数CreateFPCacheDB得到指纹识别缓冲空间句柄。
4.2.28 Function IdentificationFromFileInFPCacheDB (fpcHandle As Long, pVerTemplateFile As String, Byval Score As Long, Byval ProcessedFPNumber As Long) As Long
将指纹验证模板文件pVerTemplateFile和指纹识别高速缓冲空间fpcHandle中所有登记模板进行比对，Score传出ProcessedFPNumber次比对中的最高分数，ProcessedFPNumber传出比对的次数，当识别成功时返回值指纹标识，失败返回-1。
注意：
在识别过程中如果比对分数大于等于属性Threshold，则认为比对成功，不再和缓冲空间中剩余的指纹登记模板进行比对，函数返回匹配成功的指纹登记模板的指纹标识；
当指纹验证模板和指纹识别高速缓冲空间中所有指纹登记模板进行比对的分数都没有超过设定的Threshold，但同时比对的最高分数大于等于Score，则认为比对也是匹配成功，函数返回比对最高分数的指纹登记模板的标识，推荐设定为9；
4.2.29 Function IdentificationInFPCacheDB (fpcHandle As Long, pVerTemplate, Byval Score As Long, Byval ProcessedFPNumber As Long) As Long
将指纹验证模板pVerTemplate和指纹识别高速缓冲空间fpcHandle中所有登记模板进行比对，Score传出ProcessedFPNumber次比对中的最高分数，ProcessedFPNumber传出比对的次数，当识别成功时返回值指纹标识，失败返回-1。
注意：
在识别过程中如果比对分数大于等于属性Threshold，则认为比对成功，不再和缓冲空间中剩余的指纹登记模板进行比对，函数返回匹配成功的指纹登记模板的指纹标识；
当指纹验证模板和指纹识别高速缓冲空间中所有指纹登记模板进行比对的分数都没有超过设定的Threshold，但同时比对的最高分数大于等于Score，则认为比对也是匹配成功，函数返回比对最高分数的指纹登记模板的标识，推荐设定为9；
4.2.30 Function IsOneToOneTemplate (ATemplate) As Boolean
判断当前指纹特征模板Atemplate是否为Biokey 1：1低速比对特征模板。
4.2.31 Function ModifyTemplate(byval Atemplate, AOneToOne As Boolean) As Boolean
根据AOneToOne修改指纹特征模板Atemplate为Biokey 1：1低速比对特征模板或者高速比对特征模板。
4.2.32 Function RemoveRegTemplateFromFPCacheDB (fpcHandle As Long, FPID As Long) As Long
删除指纹识别高速缓冲空间fpcHandle中，指纹标识为FPID的指纹登记模板。返回值为1表示成功，0表示失败
4.2.33 Sub CancelCapture()
禁止当前指纹设备取像，可以使用方法BeginCapture使指纹设备开始取像。
1：1控件接口方法：
4.2.34 Function AddBitmap(BitmapHandle As OLE_HANDLE, ValidRectX1 As Long, ValidRectY1 As Long, ValidRectX2 As Long, ValidRectY2 As Long, DPI As Long) As Boolean
使用由BitmapHandle指定的位图进行登记或比对。ValidRectX1、ValidRectY1、 ValidRectX2、ValidRectY2四个参数指定了图像的有效区域，如果指定的图像区域无效，将取图像取全部区域，DPI指定了图像的分辨率大小。
4.2.35 Function AddImageFile(FileName As String, DPI As Long) As Boolean
使用由FileName指定的指纹图像文件(支持BMP,TIFF,JPG,GIF等格式)进行登记或比对。DPI指定了图像的分辨率大小。
4.3 事件
4.3.1 OnCapture(ActionResult AS Boolean, ATemplate)
取到用于比对的指纹验证模板ATemplate， ActionResult =true 表示成功取到指纹模板；False 表示失败。
4.3.2 OnCaptureToFile(ActionResult AS Boolean)
取到用于比对的指纹验证模板，模板保存到文件中，文件名称为属性VerTplFileName设置， ActionResult =true 表示成功取到指纹模板；False 表示失败。
4.3.3 OnEnroll(ActionResult AS Boolean, ATemplate)
用户登记指纹结束时调用该事件， ActionResult =true 表示成功登记，用pTemplate属性可取得指纹特征模板；False 表示失败。
4.3.4 OnEnrollToFile(ActionResult AS Boolean)
用户登记指纹结束时调用该事件， ActionResult =true 表示成功登记，指纹特征模板保存到文件中，文件名称为属性RegTplFileName设置；False 表示失败。
4.3.5 OnFeatureInfo(AQuality As Long)
取得指纹初始特征，Quality表示该指纹特征的质量，有如下可能值：
0: 好的指纹特征
1: 特征点不够
2: 其它原因导致不能取到指纹特征
4.3.6 OnImageReceived(byval AImageValid As Boolean)
设备取到指纹图像或者通过AddImageFile和AddBitmap加入指纹图像时调用该事件，AImageValid表示是否进行模板提取，设置为False后，系统在取到指纹图像后返回，不进行模板提取。
5．工作流程说明
指纹采集器初始化进入工作状态后，调用BeginEnroll处于登记指纹状态，调用BeginCapture处于指纹验证状态。控件的工作方式是基于事件驱动，触发事件的顺序参考上面示意图。
指纹登记一般需要按同一手指1-4次，然后由识别系统综合处理得到一个指纹登记模板，按压登记指纹次数由控件属性EnrollCount设置，达到设定次数后会触发OnEnroll和OnEnrollToFile事件。
指纹验证时，按压手指后会触发OnCapture和OnCaptureToFile事件，此时可以调用VerFinger或者IdentificationInFPCacheDB进行1:1或者1:N比对。
需要注意每次按压手指都会触发OnFeatureInfo事件，如果按压手指的指纹模板质量不合格，则本次取像无效，需要重新按压手指。
6．常见问题说明
6.1 1：1和1：N控件区别
1：1控件主要用于需要进行1:1验证的开发项目，一般需要预先输入当前验证客户的标识，然后得到他已经登记的一个或几个模板进行验证；而1：N控件主要用于不输入客户标识，直接通过客户指纹从已经登记的指纹模板中找出自己。
1：1控件主要目标是高的通过率和相对高的准确率；1：N控件主要目标是高的比对速度和相对高的准确率.。
1：1控件的最大模板长度只有310字节，而1：N控件的最大模板长度是1152字节，由于1:N需要进行高速比对，而且要求对误判率要求很高，所以需要保存较多的模板特征信息。
6.2 数据库中指纹模板写入和读出
SDK中指纹模板是以Vairant变量的方式保存和传递，其存储的是一维二进制字节数组，不能像字符串一样直接用SQL语句写入和读出，有两种处理方法：
1、 EncodeTemplate和DecodeTemplate方法可以在Variant变量和字符串变量之间互相进行BASE64编码转换，缺点是转换为字符串后，模板长度会增加大约1/3。
2、直接操作Variant变量，下面是操作示例：
Delphi, CB：
procedure TFPProcess.SaveFPData(AQuery: TADOQuery; AFingerID: Integer; AFPData: OleVariant);
var
pData: PChar;
begin
with AQuery do begin
Close;
SQL.Clear;
SQL.Add('SELECT * FROM zkFingerPrint WHERE FingerID = ' + IntToStr(AFingerID));
Open;
if IsEmpty then
Append
else
Edit;
FieldByName('FingerID').Value := AFingerID;
//保存指纹模板
with TBlobStream(CreateBlobStream(FieldByName('Template'), bmWrite)) do begin
pData := VarArrayLock(AFPData);
try
Write(pData^, VarArrayHighBound(AFPData, 1) - VarArrayLowBound(AFPData, 1) + 1);
finally
VarArrayUnlock(AFPData);
end;
Free;
end;
Post;
Close;
end;
end;
procedure TFPProcess.GetFPData(AQuery: TADOQuery; AFingerID: Integer; var AFPData: OleVariant);
var
pData: PChar;
begin
with AQuery do begin
Close;
SQL.Clear;
SQL.Add('SELECT * FROM zkFingerPrint WHERE FingerID = ' + IntToStr(AFingerID));
Open;
//读取数据
if not IsEmpty then
with TBlobStream(CreateBlobStream(FieldByName('Template'), bmRead)) do begin
AFPData := VarArrayCreate([0, Size + 1], varByte);
pData := VarArrayLock(AFPData);
try
Read(pData^, Size);
finally
VarArrayUnlock(AFPData);
end;
Free;
end;
Close;
end;
end;
6.3 1：N高速缓冲空间的使用
在1：N比对时，需要对比对模板进行分类，同时为了得到最高速度，SDK需要创建内存空间，然后将已登记指纹加入到内存空间，高速缓冲空间实际上是内存空间，使用时需要首先用方法CreateFPCahceDB创建，然后用方法AddRegTemplateToFPCahceDB，RemoveRegTemplateFromFPCacheDB等加入或者删除指纹登记模板，最后可以使用方法FreeFPCacheDB释放内存空间。
可以同时创建多个高速缓冲空间以用于实现分组查询等功能。
6.4 指纹识别阀值的设定
在1：1控件中，属性Threshold推荐值为10，此时误判率大约0.01%，拒绝率大约1.5-2%之间。
在1：N控件中，属性Threshold推荐值为10，此时误判率大约0.001%，拒绝率大约3%，属性OneToOneThreshold的推荐值为10。
6.5 1：N识别中低质量指纹模板的处理方法
在1：N控件中，在指纹登记时系统自动将指纹模板按照质量的好坏分类标识和保存在模板中，质量差的登记模板称为Biokey 1：1低速比对特征模板，这里的1:1和1：1控件中的1:1是两个概念，不要混淆；质量好的登记模板称为Biokey 高速比对特征模板。
在一般的应用环境中，大约有5%的登记指纹模板会被标识为低速比对特征模板，可以用方法IsOneToOneTemplate判断是否是低速比对特征模板，用方法ModifyTemplate可以人为强行改变质量的好坏分类标识。
由于Biokey 1：1低速比对速度比较慢（在PII 233大约30ms）,所以使用方法AddRegTemplateToFPCache 加入到高速缓冲空间中的低速比对特征模板不能太多，否则影响比对速度。
在1：N控件中，使用IdentificationInFPCacheDB进行指纹识别的流程如下图：
IdentificationFromFileInFPCacheDB (fpcHandle As Long, pVerTemplateFile As String, Byval Score As Long, Byval ProcessedFPNumber As Long) As Long
6.6 连接多个指纹采集器
窗口中一个控件对应一个指纹采集器，使用SensorIndex设置不同指纹采集器，指纹采集器个数通过属性SensorCount得到，如果需要区分各个指纹采集器，使用属性SensorSN，每个指纹采集器的SensorSN是唯一的。