全部产品

C-SDK Linux设备端 V4.x版开发指南

LinkFace C SDK封装了设备与物联网云平台的通讯协议,实现了人员信息增删查,人脸信息增删查和人脸检测/识别事件上云等功能。SDK采用C语言开发,对外提供静态库和动态库版本。

版本历史

详见《Linkface C SDK releases notes》

SDK头文件

具体源码如下:

#ifndef _LINKFACE_SDK_
#define _LINKFACE_SDK_

#ifdef __cplusplus
extern "C"
{
#endif

/// 人员角色。
typedef enum iotx_person_role_t {
    /*! 未知。 */
    PERSON_ROLE_UNKNOWN = -2,

    /*! 所有角色。 */
    PERSON_ROLE_ALL = -1,

    /*! 普通人员。 */
    PERSON_ROLE_NORMAL = 0,

    /*! 白名单人员。 */
    PERSON_ROLE_WHITE = 1,

    /*! 黑名单人员。 */
    PERSON_ROLE_BLACK = 2,

    /*! 非普通人员。 */
    PERSON_ROLE_NOT_NORMAL = 3,

    /*! 非白名单人员。 */
    PERSON_ROLE_NOT_WHITE = 4,

    /*! 非黑名单人员。 */
    PERSON_ROLE_NOT_BLACK = 5
} iotx_person_role_t;

/*注册人脸需要的字段*/
struct iotx_person_t {
    /*! 人员ID。 */
    char id[64];

    /*! 人员姓名。 */
    char name[1024];

    /*! 人员角色。 */
    enum iotx_person_role_t role;

    /*! 人脸图片数据大小。单位:字节。 */
    int faceimg_size;

    /*! 人脸图像数据。 */
    unsigned char *faceimg;

    /*! 人脸特征数据 */
    unsigned char **face_feature;

    /*! 人脸特征数据个数 */
    int face_feature_size;

    /*! 当wg_card_id为0时,使用此字段作为韦根门禁卡号 */
    unsigned long long long_card_id;

    /*! 身份证号码 */
    char id_card[36];

    /*! 有效期起始时间。从1970年1月1日0时0分0秒到截止时间的秒数(0表示不使用)。 */
    unsigned int term_start;

    /*! 有效期截止时间。从1970年1月1日0时0分0秒到截止时间的秒数(-1表示无限期,0表示永久失效)。 */
    unsigned int term;
};

/// 人脸比对状态。
enum iotx_match_status_t {
    /*! 比对失败。 */
    MATCH_STATUS_FAILED = -1,

    /*! 未进行比对。 */
    MATCH_STATUS_NULL = 0,

    /*! 比对成功。 */
    MATCH_STATUS_SUCCESS = 1,
};

/// 图片格式。
enum iotx_picture_format_t {
    /*! 未知 */
    PICTURE_FORMAT_NULL = -1,

    /*! Jpg。 */
    PICTURE_FORMAT_JPG = 0,
};

/// 性别。
enum iotx_sex_t {
    /*! 未知 */
    SEX_NULL = -1,

    /*! 男。 */
    SEX_MALE = 0,

    /*! 女。 */
    SEX_FEMALE = 1,
};

/*人脸对比上报*/
/*注册人脸需要的字段*/
struct iotx_matche_result_t {
    /*! 点位编号。 */
    char addr_id[32];

    /*! 点位名称。 */
    char addr_name[96];

    /*! 设备编号。 */
    char device_id[32];

    /*! 抓拍时间(秒)。 */
    unsigned int time_sec;

    /*! 抓拍时间(微秒)。 */
    unsigned int time_usec;

    /*! 实时抓拍标志。 */
    int is_realtime;

    /*! 比对状态。 必要字段。*/
    enum iotx_match_status_t match_status; //对比成功才会有人脸(即person_id,person_name,person_role,match_score)的值才有意义

    /*! 人脸比对到的人员ID。 抓拍成功时,必要字段。*/
    char person_id[64];

    /*! 人脸比对到的人员姓名。 抓拍成功时,必要字段。*/
    char person_name[255];

    /*! 人员角色。 抓拍成功时,必要字段。*/
    int person_role;

    /*! 对比相似度。 抓拍成功时,必要字段。*/
    int match_score;

    /*! 全景图大小。 */
    size_t panorama_img_size; //大小大于0时全景图的数据才有意义,否则全景图所有数据全部置空

    /*! 全景图格式。 */
    enum iotx_picture_format_t panorama_format;

    /*! 人脸位于全景图像的X坐标。 */
    unsigned short panorama_face_x;

    /*! 人脸位于全景图像的Y坐标。 */
    unsigned short panorama_face_y;

    /*! 人脸位于全景图像的宽度。 */
    unsigned short panorama_face_w;

    /*! 人脸位于全景图像的高度。 */
    unsigned short panorama_face_h;

    /*! 全景图数据。必要字段。 */
    char *panorama_img;

    /*! 全景图名称。 必要字段。 */
    char *panorama_img_name;

    /*! 特写图大小。 */
    int closeup_size; //大小大于0时特写图的数据才有意义,否则特写图所有数据全部置空

    /*! 特写图格式。 */
    enum iotx_picture_format_t closeup_format;

    /*! 人脸位于特写图像的X坐标。 */
    unsigned short closeup_face_x;

    /*! 人脸位于特写图像的Y坐标。 */
    unsigned short closeup_face_y;

    /*! 人脸位于特写图像的宽度。 */
    unsigned short closeup_face_w;

    /*! 人脸位于特写图像的高度。 */
    unsigned short closeup_face_h;

    /*! 特写图数据。 */
    char *closeup_img;

    /*! 性别。 */
    enum iotx_sex_t sex;

    /*! 年龄。 */
    unsigned char age;

    /*! 是否佩戴安全帽 */
    unsigned char hat;

    /*! 安全帽颜色 */
    unsigned char hat_color;

    /*! 人脸扭转角度。 */
    unsigned char turn_angle;

    /*! 人脸平面旋转角度。 */
    unsigned char rotate_angle;

    /* 备用字段*/
    unsigned char resv[3];

    /*! 注册图大小。 */
    int register_size;

    /*! 注册图格式。 */
    enum iotx_picture_format_t register_format;

    /*! 注册图数据。 */
    char *register_img;

    /*! 设备序列号,唯一标识符。 */
    char device_sn[32];

    /*! 身份证信息标志。 */
    int idcard_mark; //值为1才表示身份证信息相关的数据才有意义

    /*! 号码。 */
    char idcard_number[36];

    /*! 姓名。 */
    char idcard_name[64];

    /*! 出生日期。 */
    char idcard_data[18];

    /*! 性别。 */
    enum iotx_sex_t idcard_sex;

    /*! 民族。 */
    char idcard_nation[20];

    /*! 住址。 */
    char idcard_address[120];

    /*! 签发机关。 */
    char idcard_issue[44];

    /*! 有效期起始时间。 */
    char idcard_validityterm_start[18];

    /*! 有效期截止时间。 */
    char idcard_validityterm_end[18];

    /*! 韦根门禁卡号 */
    unsigned long long long_card_id;
};

/* SDK日志等级 */
enum iotx_log_level_t {
    /*! debug level */
    LF_LOG_DEBUG = 0,

    /*! info level */
    LF_LOG_INFO = 1,

    /*! warn level */
    LF_LOG_WARN = 2,

    /*! error level */
    LF_LOG_ERROR = 3,
};

/* SDK日志输出类型 */
enum iotx_log_dest_t {
    /*! 标准输出 */
    LF_STDOUT = 0,

    /*! 文件 */
    LF_FILE = 1,
};

/* 日志配置 */
struct iotx_log_cfg_t {

    /* 日志等级 */
    enum iotx_log_level_t lvl;

    /* 日志输出类型 */
    enum iotx_log_dest_t dst;

    /*! 日志文件保存路径 */
    char *log_path;

    /*! 日志存储目录大小Mb */
    int max_size_log_mb;
};

/* sdk配置信息 */
struct iotx_lf_config_t {

    /* 用公共实例, 该参数要设置为1. 若用独享实例, 要将该参数设置为0 */
    int8_t public_instance;

    /* 阿里云平台上海站点的域名后缀. 如果是企业实例, 要改成企业实例的接入点 */
    char *mqtt_url;

    /* 阿里云平台上海站点的http2域名后缀 */
    char *http2_url;

    /*! product_key: 三元组之一, 详见物联网平台官方文档. */
    char *product_key;

    /*! product_secret: 产品秘钥,一型一密时使用,否者填"", 详见物联网平台官方文档. */
    char *product_secret;

    /*! device_name: 三元组之一, 详见物联网平台官方文档. */
    char *device_name;

    /*! device_secret: 三元组之一, 详见物联网平台官方文档. */
    char *device_secret;

    /*! data_path: sdk会本地缓存一些配置信息,厂商需要确保此目录已存在且可写,预计占用物理空间2M以内。 */
    char *data_path;

    /*! 日志配置 */
    struct iotx_log_cfg_t cfg_log;

    /** 外部初始化LinkSDK,需要把dm_handle赋值给Linkface SDK */
    void *dm_handle;

};

/** 云端下发底库同步请求时,sdk会调用该接口将人脸底图信息逐个传递给厂商,厂商需要将该人脸添加到数据库中以
 * 进行人脸识别。
 * @brief   注册人脸数据接收回调函数格式定义。
 * @param   注册人脸结构体。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
typedef int (*add_person_data_callback)(const struct iotx_person_t *person, void *user);

/** 云端需要删除某个人脸底库时,sdk会调用该接口将人脸信息逐个传递给厂商,厂商需要将该人脸从数据库中删除,
 * 下次人脸检测时,该用户会因底库不存在该用户信息导致识别识别。
 * @brief   删除人脸数据接收回调函数格式定义。
 * @param   人脸id。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
typedef int (*delete_person_data_callback)(const char *person_id, void *user);

/** sdk调用本接口后,厂商需要清空人脸数据库。
 * @brief   全量删除人脸回调函数。
 * @param   用户数据。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
typedef int (*delete_all_data_callback)(void *user);

/** 注册添加人脸回调接口。
 * @param   callback 厂商需要实现的函数。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
void register_add_person(add_person_data_callback callback, void *user);

/** 注册删除人脸回调接口。
 * @param   callback 厂商需要实现的函数。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
void register_delete_person(delete_person_data_callback callback, void *user);

/** 注册全量删除人脸回调接口。
 * @param   callback 厂商需要实现的函数。
 * @param   user 用户参数,用户设置回调时指定的参数通过该参数再次回传给用户。
 */
void register_delete_all(delete_all_data_callback callback, void *user);

/**  当人脸门禁机检测到人脸后,无论是否能正确识别出该人脸,均需要调用本接口将识别结果上报到云端。
 * @param   result 识别结果,如果识别成功,需要包含已识别的人的基本信息。
 *
 * @return 成功返回0,其他值均为失败。
 */
int upload_match_result(const struct iotx_matche_result_t *result);

/**  iotx_lf_init 接口,必须首先调用,如果初始化失败,请sleep 1s后重试,直到成功。
 * @param   cfg: sdk配置信息
 * 成功返回1,失败返回-1。
 * */
int iotx_lf_init(struct iotx_lf_config_t *cfg);

/** 进程退出前,释放sdk资源。
 */
void iotx_lf_deinit();

#ifdef __cplusplus
}
#endif

#endif

接口总览

SDK包内容介绍

tree -L 3
.
├── CMakeLists.txt               ---------演示如何链接linkface和linkkit的库,如何编译sample
├── LinkFace
│   ├── samples                  ---------linkface的库和使用的样例
│   │   ├── aiot.jpg             ---------模拟人脸抓拍事件上云图片
│   │   ├── linkface_demo        ---------演示可执行文件
│   │   ├── linkface_demo.c      ---------sample代码
│   │   ├── linksdk_adapter.c    ---------自定义集成linkkit的上云能力
│   │   ├── log_util.c
│   │   └── log_util.h
│   └── sdk
│       ├── liblinkface.a       ----------linkface动态库
│       ├── liblinkface.so      ----------linkface静态库
│       └── linkface_sdk.h      ----------linkface头文件
└── third_party
    ├── release
    │   ├── LinkSDK-v2x         ----------依赖的LinkSDK2.x版本,后续会去掉
    │   ├── LinkSDK-v4x         ----------依赖的LinkSDK4.x版本
    │   ├── cJSON
    │   └── oss_sdk_linkface
    └── source
        ├── LinkSDK-v2x.tar.gz
        ├── LinkSDK-v4x.tar.gz
        └── cJSON-1.7.7.tar.gz

快速使用指南

下面来基于Ubuntu 16.04的环境来描述如何运行官方Sample。

  • 解压

tar zxvf link_face_xxx_.tar.gz
  • 编译

我们提供了CMakeLists.txt来演示如何使用sdk,若单独使用sdk,请参考CMakeLists.txt来完成库的链接。

cd link_face_xxx_
mkdir build
cd build
cmake ../
make
  • 运行

cp linkface_demo ../LinkFace/samples
./linkface_demo ${Product_Key} ${Device_Name} ${Device_Secret} ./
${Product_Key} ${Device_Name} ${Device_Secret} 分别替换成在物联网平台上申请的三元组即可。