地平线人脸特征提取服务器接口 - housekeeper-software/soft GitHub Wiki

简介

人脸特征服务器只能用于提取人脸特征，使用websocket连接，目前测试服务器地址为:
ws://119.3.5.12:10888

连接方法

服务器不会主动断开连接，所以，可以在一个连接中发送多个请求，要求每个请求具有唯一的id标识。
服务器不会限制连接数目，所以，怎么连都可以。
服务器每隔60秒会发ping包，以实现连接的维护。客户端无需关心，这是websocket协议内部机制。

请求接口

请求接口为json格式，如下所示：  
{"id":"xxx","cmd":"feature","type":0,"content":"d:/1.jpg"} 或者  
{"id":"xxx","cmd":"feature","type":1,"content":"image base64 code"}  
其中要注意：  
id：每次请求都要不同，尤其在并行请求的时候，需要通过这个标识来关联请求。  
cmd:目前只能是feature，标识提取人脸特征，其他的留待以后扩展。  
type:0，表示提交的是文件，后面的content描述文件的绝对位置。  1：表示content中是文件流的base64编码数据。  
content:根据 type的不同，含义不同，如上所示。  
可选字段： 
predict_mode：integer,表示提取哪些特征，具体参考地平线的SDK。比如只需要提取人脸特征，或者还需要活体检测等等。有不同的掩码组合表示。  
max_face_count：integer，表示最大只提取几个人脸，对于照片录入，一般可以设置为1，不设置的时候返回全部人脸。 
**请求的文件base64数据流长度没有限制，但实践上不能太大，以提高传输效率。上传照片的一端需要对图像尺寸进行控制，类似其他的软件。记住，base64会将文件的尺寸增大1/3**

接口返回

接口返回为json格式，websocket类型为 TEXT，这就是说在浏览器可以直接显示返回结果。

{"cmd":"feature","content":[{"age":{"classification":-1,"score":-1.0},"gender":{"classification":-1,"score":-1.0},"glass":{"classification":-1,"score":-1.0},"hat":{"classification":-1,"score":-1.0},"landmark":[{"visible":1,"x":163.24066162109375,"y":127.78402709960938},{"visible":1,"x":241.04730224609375,"y":139.86962890625},{"visible":1,"x":167.68768310546875,"y":183.26382446289062},{"visible":1,"x":150.4934539794922,"y":213.8031463623047},{"visible":1,"x":223.34616088867188,"y":226.90687561035156}],"liveness_score":0.0,"metric":"-232.4047088623047,-1161870180352,-271.306640625,4.104614794536607e-21,-4.09588183836067e+34,1.1859033079191694e-37,-1.7110523067853656e-12,1.748934940937274e+24,-7.682517716550948e-34,-1.6580275350491605e-23,902.4913940429688,2.2508216148677296e-27,3.934345095639467e+25,136.77410888671875,9.809110364611992e+32,-1.1782873629752664e+24,-9.925815617665403e-30,-1.6972581130957862e-29,-4.315256774134468e-06,-1.449309650070063e-07,-1.0796648916144396e-28,3975919.75,-3.144137172297022e-14,1.5223307916334038e-18,-.35914233326911926,1.7753591929903223e-09,-.0004247376346029341,7.833501700719417e-34,-2166013184,-.003581049619242549,103568.953125,-2.5901308027364476e+34,-50.50948715209961,8.043328360696156e-34,-8.921081782954384e+24,5.3702912071722925e-14,9.185515639692905e-27,893975925769600200000,-1.1041916877729818e-05,-1.1441589009564268e-07,6.652079049607045e-22,3.515038439467257e-32,-4.2003355446695337e+36,-1.1237694802490594e-11,1.486913716983076e-15,-3.0371587814896164e-27,3.035019338713113e-13,1.4014112719556594e+29,7.206357906242022e-13,543229888,-2.634064197540283,5652.2236328125,-.061390746384859085,7.272928485398177e-38,-88935090880512,6.298415105646548e-32,-.007175377570092678,-2.3849660179087654e-29,1.452801696641721e-32,-1.1296903828519021e-15,7.174409228695708e-29,4.502720606740964e-17,-16.766706466674805,4.879463414528846e-31,1.7145074919987408e-18,15922.0048828125,-1.3313132975393217e-31,-4.09927160833043e+30,-29825478656,1.1792906087513807e+27,9.170282703727407e+22,2.5992189325724153e-22,-4.505827936408525e+24,1.6950106692620284e+25,2.430913586523285e-17,-5.079223610863154e+22,4.9477130051757057e-17,-2.34692426347477e-37,-262519200,-6.107336950763147e+33,85118402560,9.377199243592712e-20,35883013111808,2.6968243673763936e-06,3.9658995433850973e-35,-3.3345152387307146e-15,.00048035054351203144,263.3865966796875,-9.702421015344461e+35,2.5594804053952203e-10,1.3854594987272337e-33,-.0010517816990613937,-7.127421917114809e-31,1.5827499935888087e-34,-.42641428112983704,5.354999415551922e+25,5.5720900305920515e-14,-92300315588818900000,.05678434669971466,3.2089612813767515e-14,7.755179393744891e-32,1.1230743979240287e-07,3585663303680,180006977149905930000,-2.613875389099121,-1.5838994233316401e-27,-2.4119063924070125e-30,-1.4951414654370405e+24,-113566040457216,-5.256416041609292e-28,10507249,1.590091673288834e-27,1.3264610949557099e-20,25745588224,-1.523568055571134e-13,-8.388871819420274e-10,268448770398617600,2.403642025800167e+24,1.7051220762632393e-30,-1.124002927188004e-16,7.021953257881171e-34,1.8791343191036817e+37,5.097712714714095e+26,-820073.75,6.95598409039252e+34,-.00019418845477048308,-2.915701597375926e-22,1.1966992587206638e-33,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","pose":{"pitch":-10.8984375,"roll":10.469970703125,"yaw":22.642822265625},"quality":{"brightness":0,"scores":".09199206531047821,.005377097986638546,.04094146937131882,.009209909476339817,.00631742924451828,.05320620536804199,.0333525612950325,.8784186244010925,.05347742885351181,.03173859417438507,.0066572376526892185,.012112065218389034,.032070379704236984"},"quality_score":0.0,"rect":{"score":1.05078125,"x1":126.53556823730469,"x2":308.4056396484375,"y1":59.55720901489258,"y2":277.27838134765625}}],"id":"xxx","result":0}

返回的json中包含 id, cmd, result,以及content。
id：就是请求的id
cmd：就是请求的cmd
result：为0表示成功，其他任何值表示失败。只有result=0的时候，content才有意义。
content包含一个或者多个人脸的特征数据。是一个数组类型。每个element中包含人脸的各种特征数据。这些可以参考SDK中的数据结构。json中的信息由SDK中的数据结构序列化输出产生。
其中比较重要的是metric字段。其中包含256个浮点数。按照SDK说明，因为SDK加载的模型是128个点，所以，只有前面128个数据是有效的。但SDK中的数据长度为256，这里原样输出，以便保持对未来的扩展能力。
其他的比如 age, liveness_score等字段，需要在predict_mode 设置响应的位才可能有结果。比如要想同时输出活体检测结构，就必须在predict_mode中指定相关的位，结果中的liveness_score字段才有意义。

返回的错误代码

0：表示成功，其他为失败。
大于0：为地平线SDK的错误代码，可以参考SDK
小于0: 为服务器错误代码，具体为：

-1：json格式错误  
-2: json中指定的文件没找到  
-3: sdk检测没有任何结果，为何会发生这种情况，谁也不知道。

地平线的错误代码：

typedef enum {
  ErrorCode_OK = 0,                // 正确
  ErrorCode_Uninit = 1,            // 未初始化
  ErrorCode_ParamError = 2,        // 参数错误
  ErrorCode_NoImg = 3,             // 没有图片
  ErrorCode_BadRects = 4,          // 人脸框质量太差
  ErrorCode_RectTooSmall = 5,      // 人脸太小
  ErrorCode_NoRect = 6,            // 没有人脸框
  ErrorCode_NotLiveness = 7,       // 没有活体
  ErrorCode_NoMetric = 8,          // 没有提出特征
  ErrorCode_NoKeypoint = 9,        // 没有提出关键点
  ErrorCode_PoseError = 10,         // 姿态过歪
  ErrorCode_NoModel = 11,           // 模型缺失
  ErrorCode_BadQuality = 12,           // 图片质量太低
  ErrorCode_ConfigError = 13,           // 读取配置文件失败
  ErrorCode_LicenseError = 14,          // 读取授权文件失败
  ErrorCode_LengthTooShort = 15,     // 预分配字符串长度过小

  ErrorCode_Other = 100       // 其他错误
} HobotXFaceErrorCode;

人脸特征提取参数 predict_mode参数

typedef enum {
  PredictMode_None = 0,
  PredictMode_Rect = 1 << 0,        // 人脸框
  PredictMode_Affine = 1 << 1,      // affine转换
  PredictMode_Lmk = 1 << 2,        // 关键点
  PredictMode_Metric = (1 << 3) + PredictMode_Lmk,      // 特征提取

  PredictMode_Liveness = 1 << 4,    // 活体
  PredictMode_Pose = 1 << 5,        // 姿态
  PredictMode_Quality = (1 << 6) + PredictMode_Lmk,     // 图片质量
  PredictMode_Age = (1 << 7) + PredictMode_Lmk,         // 浮点年龄属性模型
  PredictMode_Multi = 1 << 8,       // 定点多属性模型，包括性别、年龄
  PredictMode_Gender = PredictMode_Age,      // 浮点性别属性模型
  PredictMode_Glass = 1 << 10,       // 浮点眼镜属性模型
  PredictMode_Hat = 1 << 11,        // 浮点帽子属性模型
  PredictMode_NormalizeDetect = 1 << 12,  // 只做人脸检测，并输出192*192 只有Y通道的YUV图片
  PredictMode_ImgColor = 1 << 13     // 灰度图/彩色图 检测，只适用于单人脸图片
  // 2的n次方，使用 | 来构造
} HobotXFaceMode;

不提供的话，默认就是： PredictMode_Metric | PredictMode_Quality

服务器配置

服务器应用程序为faceserver，目录结构如下：
1.faceserver：可执行文件
2.models_bits：目录，人脸模型数据，SDK中提供
3.face.json：程序配置。

#face.json
格式如下：

{
   "console_log_level": 0, //正式运营，改成2，表示只输出错误  
   "ws_pump_interval_ms":10,
   "ws_port":10888, //可以改服务器端口  
   "ws_options":0,
   "ws_protocol_name":"ws",
   "model_conf":"models_bit8/model_conf.json", //可以用相对路径，或者绝对路径  
   "param":{  //这些参数参考地平线SDK文档，可以增删修改。不需要设置的可以删掉，或者置空 ""  
      "face_quality":"2", //这个需要问地平线  
      "alphadet_instance_count":"4", //这个值越大，占用内存越高，SDK是这么讲的，我这里默认给4，如服务器配置太低，可以调成1，请参数SDK说明  
      "min_area":"100",
      "min_face_width":"80",
      "min_face_height":"80",
      "face_keypoint":"1",
      "face_metric_feature":"1",
      "feature_instance_count":"4",
      "pose_pitch_min":"-90.0",
      "pose_pitch_max":"-90.0",
      "pose_yaw_min":"-90.0",
      "pose_yaw_max":"90.0",
      "pose_roll_min":"-180.0",
      "pose_roll_max":"180.0",
      "face_liveness":"1"
   }
}