人脸识别云服务

1. 云端人脸识别API接口服务

商米提供云端人脸识别API接口服务，用户可以用标准的HTTP请求来获取人脸检测框和人脸特征。其中，人脸特征可用于批量构建人脸底库，使用sqlite数据库进行人脸库的存储，其构建表结构如下：

CREATE TABLE SUNMI_FACE (
AUTOID INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, 
                 "ID VARCHAR(64), "
                 "NAME VARCHAR(64), "
                 "IMG_ID VARCHAR(64), "
                 "FEATURE BLOB,"
                 "CreatedTime TimeStamp NOT NULL DEFAULT CURRENT_TIMESTAMP);

数据表中各个字段的赋值，需注意以下几点：

  • ID是用户的唯一标识，同一个用户ID相同，不用用户ID不同。
  • NAME是用户姓名，允许重复。
  • IMG_ID是对应人脸图片在数据库中的唯一标识，不可重复，需要采用UUID0算法生成唯一不重复的uuid。
  • FEATURE是通过人脸API服务获取的人脸特征。

1.1. 人脸检测-请求参数

url地址：请联系商米获取云服务的url 地址

参数名称是否必选类型默认值说明
image是string/图片信息 (总数据大小应小于2M)，图片上传方式根据image_type来判断
image_type是string/图片类型 BASE64:图片的base64值。base64编码后的图片数据，其图片大小不超过2M；URL:图片的 URL地址(可能由于网络等原因导致下载图片时间过长)；
max_face_count否int1最多处理人脸的数目，默认值为1，仅检测图片中人脸置信度最高的那个人脸；最大值为10，检测图片中面积最大的几张人脸。
predict_mode否int7 参考下面的预测模式定义。7即为默认人脸检测+人脸特征+人脸属性。（年龄和性别都包含在人脸属性中）

预测模式定义示例代码如下：

typedef enum {
    PredictMode_None = 0,
    PredictMode_Detect = 1 ‹‹ 0,                                // face detect
    PredictMode_Feature = (1 ‹‹ 1) + PredictMode_Detect,        // face detect and extract features
    PredictMode_Age = (1 ‹‹ 2) + PredictMode_Detect,            // face detect and age predict
    PredictMode_Gender = PredictMode_Age,                       // face detect and gender predict
} SunmiFaceMode;

1.2. 人脸识别API–返回数据

字段必选类型说明
face_num是int检测到的图片中的人脸数量
face_list是array人脸信息列表，具体参数参考下面的列表
+location是array人脸在图片中的位置
++left是double人脸框左上角x坐标
++top是double人脸框左上角y坐标
++width是double人脸框宽度
++height是double人脸框高度
+ face_probability是double人脸置信度
+ angle是array人脸旋转角度
++ yaw是double左右旋转角[-90(左), 90(右)]
++ pitch是double俯仰旋转角[-90(上), 90(下)]
++ roll是double平面内旋转角[-90(逆时针), 90(顺时针)]
+ landmark是array5个关键点位置，左眼中心、右眼中心、鼻尖、左嘴角，右嘴角。
+ liveness_score是double2D活体检测得分，值越高说明是真人的概率高
+ feature是array人脸256维特征值

返回结果如为json格式，如以下示例：

{
    "face_num": 1,
    "face_list": [
        {
            "location": {
                "left": 216.1408233642578,
                "top": 157.1695556640625,
                "width": 90.74900817871094,
                "height": 115.81448364257812
            },
            "face_probability": 0.9972383975982666,
            "angle": {
                "yaw": 5.858273506164551,
                "pitch": 19.634262084960938,
                "roll": -1.6777983903884888
            },
            "landmark": [
                {
                    "x": 239.48606872558594,
                    "y": 203.29200744628906
                },
                {
                    "x": 280.5645446777344,
                    "y": 203.55821228027344
                },
                {
                    "x": 258.20745849609375,
                    "y": 226.3636016845703
                },
                {
                    "x": 242.2882080078125,
                    "y": 243.4677734375
                },
                {
                    "x": 276.392333984375,
                    "y": 243.5858917236328
                }
            ],
            "liveness_score": 0.9542617797851562,
            "gender_info": {
                "gender": "female",
                "score": 1.0
            },
            "age_info": {
                "age": 25,
                "score": 0.8857287168502808
            },
            "feature": [
                0.0012834692606702447,
                0.027195502072572708,
                -0.1606169044971466,
                -0.1035875454545021,
                -0.055142492055892944,
                …
                0.043723493814468384,
                0.07170124351978302,
                -0.10330264270305634
            ]
        }
    ]
}

1.3. 人脸识别API–返回状态码

因API不提供自定义配置参数设置，如SDK中的人脸姿态阈值、光照阈值等，在API中均采用默认值，而FACE_CODE_BAD_ILLUMINATION，FACE_CODE_POSE_ERROR等依赖配置参数，所以下表提供的返回值仅针对默认配置参数。

人脸姿态可直接根据返回的json中的“angle”字段进行判断，人脸大小可根据“location”字段判断。

商米人脸识别状态码如下表所示：

枚举成员状态码说明
FACE_CODE_OK0正确
FACE_CODE_UNINIT1SDK没有初始化
FACE_CODE_EMPTY_IMAGE2图片为空
FACE_CODE_NO_MODEL3无加载模型文件
FACE_CODE_CONFIG_ERROR4配置错误
FACE_CODE_BAD_ILLUMINATION5光线条件不好
FACE_CODE_POSE_ERROR6面部位置不符合要求
FACE_CODE_SMALL_FACE_SIZE7人脸尺寸太小
FACE_CODE_LOW_IMAGE_QUALITY8人脸图像模糊
FACE_CODE_NOT_LIVENESS9非活体人脸图像
FACE_CODE_LICENSE_ERROR10授权文件无效
FACE_CODE_LICENSE_EXPIRED11授权文件过期
FACE_CODE_IMAGE_ID_ERROR101删除时图像id不存在
FACE_CODE_OTHER_ERROR1000其他错误

2. Python示例代码

2.1. 图片采用BASE64格式

对于BASE64格式的图片，使用如下示例进行API接口的调用：

import numpy as np
import cv2
import requests
import base64
import json
​
if __name__ == '__main__':
    url = "http://face-recognition.sunmi.com/v1/face/recognition"
    with open("test.jpg", "rb") as f:
        base64_data = base64.b64encode(f.read())
    data = {"image": base64_data, "image_type": "BASE64", "max_face_count": 1}
    r = requests.post(url, data=data)
    s = json.loads(r.content)
    print(s['msg'])

2.2. 图片采用URL格式

对于URL格式的图片，使用如下示例进行API接口的调用：

import numpy as np
import cv2
import requests
import base64
import json
​
if __name__ == '__main__':
    url = "****"
    data = {"image": "https://wifi.cdn.sunmi.com/UAT/IMG/FACE/AM4RDZ2LP5HWTIJ8G70KN8NFNY0766WK1", "image_type": "URL", "max_face_count": 1}
    r = requests.post(url, data=data)
    s = json.loads(r.content)
    print(s['msg'])