1. 中控指纹识别服务器简介

中控指纹识别服务器是一个全功能的指纹识别服务器。它集成了业界领先的中控指纹识别算法ZKFinger 10.0 版，具有非常优秀的识别率和识别性能。

中控指纹识别服务器具有如下功能:

• 指纹特征提取
• 人员指纹数据维护（登记、删除、修改、查询）
• 1：1比对
• 1：N识别

中控指纹识别服务器通过http协议监听默认的18001端口，提供业界标准的 Web Service API 接口，供其他程序进行调用。

2. Web Service API

ZKFPEngine Web API 调用遵循 RESTful 约定。系统执行了对应功能后以json格式返回执行的结果数据；若对应功能不能正常执行，则返回如下json形式的错误信息:

{ error_code: ...,  message: "... ..."}

其中，error_code 为错误代码， message 为错误信息。

系统仅仅处理8位灰度图像，可以是Bitmap格式，也可以是无如何格式的Raw Image，图像以二进制方式传送到服务器。系统接口中，无论是传送给服务器的指纹模板，还是服务器返回的指纹模板，均采用 base64 不换行编码模式。

2.1. 系统信息

调用方法与地址:

GET http://zkfpserver:18001/zkfinger/info

此接口用于读取系统信息。

服务器返回:

字段名	值
db_template_count	数据库中的指纹模板数
db_template_limit	数据库中的指纹模板数上限
server_version	服务器版本号
fp_engine_version	指纹识别算法版本号
start	服务器启动时间

示例:

$ curl http://localhost:18001/zkfinger/info
{
 db_template_limit: 50000,
 db_template_count: 10292,
 start: "2012-03-09 11:12:10",
 server_version: "10.0",
 fp_engine_version: "10.0",
}

2.2. 提取特征模板

调用方法与地址:

POST http://zkfpserver:18001/zkfinger/extract?height=<height>&width=<width>

此接口用于从指纹图像中提取出指纹模板。支持256级灰度图像，可以是Bitmap格式和RAW格式。RAW格式时，必须用height参数指定图像高度，用width参数指定图像宽度，Bitmap格式不需指定这两个参数。

服务器返回:

字段名	值
length	模板的长度（base64编码前）
template	从图像中提取的指纹模板，以base64方式编码

示例:

$ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/extract
{length: 930, template: " ... ... "}

2.3. 保存(登记或修改)

调用方法与地址:

POST http://zkfpserver:18001/zkfinger/db/<id>?height=<height>&width=<width>

保存指纹模板到数据库。<id>是一个由字母、数字、减号和下划线等组成的一个有效标识符，其最大长度为100. 若指定id对应的指纹模板在数据库中不存在，则新增，否则修改已经存在的对应指纹模板。

POST 的内容可以是图像，也可以是指纹模板。若是图像，则先对图像提取特征模板，在保存到数据库中，图像的格式和参数参考 提取特征模板 。若POST是指纹模板，则每一行是一个指纹模板，可以有最多5个指纹模板，这些指纹模板会被合成成为一个指纹模板再存到数据库中。注意，多个指纹模板必须是同一指纹的图像上提取的。

服务器返回:

字段名	值
count	1

示例:

$ curl --data-binary @richard_1.ftmp http://localhost:18001/zkfinger/db/richard_1
{ count: 1 }

2.4. 查询

调用方法与地址:

GET http://zkfpserver:18001/zkfinger/db/<id>

查询数据库中的指纹模板。

服务器返回:

字段名	值
length	模板的长度（base64编码前）
template	对应的指纹模板，以base64方式编码

示例:

$ curl http://localhost:18001/zkfinger/db/richard_1
{length: 922, template: " ... ... "}

2.5. 删除

调用方法与地址:

DELETE http://zkfpserver:18001/zkfinger/db/<id>

此接口用于从数据库中删除指定的指纹模板

服务器返回:

字段名	值
count	1

示例:

$ curl -X DELETE http://localhost:18001/zkfinger/db/richard_1
{ count: 1 }

2.6. 清空数据库

调用方法与地址:

DELETE http://zkfpserver:18001/zkfinger/clear

清空数据库中登记的全部指纹。

服务器返回:

字段名	值
count	被删除的数据库中的指纹数

示例:

$ curl -X DELETE http://localhost:18001/zkfinger/clear
{ count: 2019202 }

2.7. 比对两个模板

调用方法与地址:

POST http://zkfpserver:18001/zkfinger/verify

该函数把两个模板发送到服务器上进行1:1比对。post数据中，两个模板分为两行（即他们之间用 ‘\n’ 分隔）。

服务器返回:

字段名	值
score	指纹模板之间的匹配分数

示例:

$ curl --data-binary @c1.txt http://localhost:18001/zkfinger/verify
{score: 100}

2.8. 1：1 比对

调用方法与地址:

POST http://zkfpserver:18001/zkfinger/verify/<id>?height=<height>&width=<width>

该函数把一个指纹图像或模板发送到服务器上进行1:1比对。<id>用于指定同数据库中的那一个指纹模板进行比对。服务器自动判断发送的是图像还是模板，若发送的是图像，则会先提取模板再进行比对。图像的格式和参数参考 提取特征模板 。

服务器返回:

字段名	值
score	指纹模板之间的匹配分数

示例:

$ curl --data-binary @fp1.ftmp http://localhost:18001/zkfinger/verify/richard_1
{score: 91}

$ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/verify/richard_1
{score: 91}

$ curl --data-binary @fp1.raw http://localhost:18001/zkfinger/verify/richard_1?height=360&width=256
{score: 91}

2.9. 1：N 识别

调用方法与地址:

POST http://zkfpserver:18001/zkfinger/identify?height=<height>&width=<width>&max_return=<max_return>&min_score=<min_score>

该函数把一个指纹图像或模板发送到服务器上进行1:N识别。服务器自动判断发送的是图像还是模板，若发送的是图像，则会先提取模板再进行识别。图像的格式和参数参考 提取特征模板 。参数 max_return 用于指定返回最为相似的前几名指纹模板，默认为1，最大为20；参数min_score 表示识别时最小匹配分数，默认值为60.

服务器返回:

字段名	值
ids	匹配中满足最低分数阈值的列表，按照相似度降序排列
.id	匹配的指纹id
.score	相似度分数

示例:

$ curl --data-binary @fp1.ftmp http://localhost:18001/zkfinger/identify?min_score=20
{ids:[
      {id: "richard_1", score: 91},
      {id: "smith", score: 21}
]}

$ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/identify
{ids:[
      {id: "richard_1", score: 91}
]}

$ curl --data-binary @fp1.raw http://localhost:18001/zkfinger/verify/richard_1?height=360&width=256
{ids:[
      {id: "richard_1", score: 91}
]}