顾客识别SDK使用文档

本文档主要针对服务端SDK调用者,创迹AI开放平台需要购买后,下载SDK进行使用。本文以“顾客识别”能力为例,指引您开启开发之旅 。

1、顾客识别SDK配置文档

1.1 环境要求

1.1.1 依赖库

①Windows 平台需安装 vcredist2013 (注意区分 32 位和 64 位与算法库保持一致)

②Linux 平台需安装 glibc 2.17 库依赖及以上

1.1.2 兼容性

①x86、x64、linux64 三个版本

②支持 Win7,CentOS7,Ubuntu14.04及以上

1.2、SDK下载

具体操作请参照[SDK下载-SDK下载],根据指南进行SDK下载。下载后进行解压路径如下:

|---libs
|     |---CustomerRecognizeSDK-1.0.0.jar 顾客识别SDK
|---CustomerRecognizeTest.java 代码演示文档

1.3、SDK接入配置

将CustomerRecognizeSDK-1.0.0.jar文件,放入项目中的libs文件夹中,并作为Library填入:

1.4、代码说明

文件解压后,找到其中的CustomerRecognizeTest.java文件,如下图:

接口依次有依赖关系,需权限认证通过,且初始化人脸引擎成功才可调用【顾客识别接口】,最后关闭人脸引擎:

①权限认证及初始化人脸引擎接口只需调用一次,不可重复调用

②顾客识别接口可重复调用

③关闭人脸引擎只调用一次,不可重复调用

1.5、注意事项

SDK是按照设备数来购买的,当一个设备使用成功后就减少一台次数,所以请合理安排设备,避免造成购买次数的浪费。

2、接口说明

2.1、鉴权接口

int authorizationOnline(String appKey, String secretKey, String serviceKey)
功能:进行权限认证。

参数名称 是否必选 数据类型 说明
appkey String 官网获取的APP_KEY
appSecret String 官网获取的APP_SECRET
serviceKey String 官网获取的SERVICE_KEY

2.2、人脸引擎初始化接口

int initEngine()
功能:进行人脸引擎初始化。

2.3、人脸特征提取接口

int extractFaceFeature(String imagePath, Feature out)
功能:给定一张图片地址进行人脸检测,并返回最主要的一张人脸特征。

参数:

参数名称 是否必选 数据类型 说明
imagePath String 图片地址
out Feature 特征向量作为返回值,用户需要接收此值

Feature详细信息:

参数名称 说明
data 图片中人脸面积最大的人脸特征值
featureID 人脸特征值,可用于用户作为主键来使用

int extractFaceFeature(byte[] imageByteData, Feature out)
功能:给定的图片的byte数组进行人脸检测,并返回最主要的一张人脸特征。

参数:

参数名称 是否必选 数据类型 说明
imageByteData byte[] 图片byte信息
out Feature 特征向量作为返回值,用户需要接收此值

Feature详细信息:

参数名称 说明
data 图片中人脸面积最大的人脸特征值
featureID 人脸特征值,可用于用户作为主键来使用

2.4、人脸比对接口

int compareFaceFeature(String sourceImagePath, String targetImagePath, Similar out)
功能:给定的两张图片的地址进行人脸检测,并返回两张人脸的相似度。

参数:

参数名称 是否必选 数据类型 说明
sourceImagePath String 待对比图片地址
targetImagePath string 另一张待对比图片地址
out Similar 人脸相似度作为返回值(区间值:0~1.0) 用户需接收此值

Similar详细信息:

参数名称 说明
score 人脸相似度分数值,区间值:0~1.0

int compareFaceFeature(byte[] sourceByteData, byte[] targetByteData, Similar out)
功能:给定的两张图片的byte数组进行人脸检测,并返回两张人脸的相似度。

参数:

参数名称 是否必选 数据类型 说明
sourceByteData Byte[] 待对比图片byte信息
targetByteData Byte[] 另一张待对比图片byte信息
out Similar 人脸相似度作为返回值(区间值:0~1.0) 用户需接收此值

Similar详细信息:

参数名称 说明
score 人脸相似度分数值,区间值:0~1.0

2.5、人脸搜索接口

int searchFaceFeature(String imagePath, List<Feature> featureList, int maxFaceNum, List<Search> out)
功能:提取给定图片主要一张人脸在人脸库查询相似度最高的人脸特征及特征ID;
支持1:N和M:N搜索(M最大支持5,N最大支持10000),人脸库:需要用户按照我们设定的规则封装人脸信息。

参数:

参数名称 是否必选 数据类型 说明
imagePath String 图片地址
featureList List<Feature> 封装人脸特征及特征ID集合
maxFaceNum Similar 想要检索的人脸数量(最大支持5张人脸)
out List<Search> 搜索出的最相似的人脸信息作为返回值用户需接收此值

List<Search> out详细信息:

名称 字段名称 描述
Search
Similar :相似度JavaBean score 相似度分数值
Feature :特征JavaBean data 人脸特征
featureID 人脸特征对应的唯一值;

int searchFaceFeature(byte[] imageByteData, byte[] featureList, int maxFaceNum, List<Search> out)
功能:提取给定图片中主要一张人脸在人脸库查询相似度最高的人脸特征及特征ID;
支持1:N和M:N搜索(M最大支持5,N最大支持10000),人脸库:需要用户按照我们设定的规则封装人脸信息。

参数:

参数名称 是否必选 数据类型 说明
imageByteData Byte[] 图片byte信息
featureList List<Feature> 封装人脸特征及特征ID集合
maxFaceNum Similar 想要检索的人脸数量(最大支持5张人脸)
out List<Search> 搜索出的最相似的人脸信息作为返回值用户需接收此值

List<Search> out详细信息:

名称 字段名称 描述
Search
Similar :相似度JavaBean score 相似度分数值
Feature :特征JavaBean data 人脸特征
featureID 人脸特征对应的唯一值;

2.6人脸验证接口

int verifyFaceFeature(String imagePath, List<Feature> featureList, Similar out)
功能:用于判断“某人是否是某人”;判断给定图片中的主要一张人脸,是否是给定的身份,需要用户按照我们设定的规则封装人脸信息。

参数:

参数名称 是否必选 数据类型 说明
imagePath String 图片地址
featureList List<Feature> 封装人脸特征及特征ID集合
out Similar 人脸相似度作为返回值(区间值:0~1.0)用户需接收此值

Similar详细信息:

名称 说明
score 人脸相似度分数值,区间值:0~1.0

int verifyFaceFeature(byte[] imageByteData, List<Feature> featureList, Similar out)
功能:用于判断“某人是否是某人”;判断给定图片中的主要一张人脸,是否是给定的身份,需要用户按照我们设定的规则封装人脸信息。

参数:

参数名称 是否必选 数据类型 说明
imageByteData byte[] 图片byte信息
featureList List<Feature> 封装人脸特征及特征ID集合
out Similar 人脸相似度作为返回值(区间值:0~1.0)用户需接收此值

Similar详细信息:

名称 说明
score 人脸相似度分数值,区间值:0~1.0

2.7、人脸引擎关闭接口

CloseEngine()
功能:关闭人脸引擎(关闭一次即可,开启引擎与关闭引擎一一对应)。

3、信息码

功能 Code返回码 返回码含义
授权功能 200 授权成功
300 授权失败
初始化人脸引擎功能 200 初始化成功
301 初始化失败
关闭人脸引擎功能 200 关闭成功
302 关闭失败
关闭人脸引擎功能 200 返回值成功
501 无人脸或非活体
502 图片size大于5MB,图片格式非PNG、JPG、JPEG、BMP
503 特征参数有误
504 缺少必要参数
509 未知错误