RV1126 NO.50: rockx常见的API
RockX框架提供了一套完整的人脸检测API接口，包括人脸检测、识别、特征提取等功能。核心函数包括：rockx_create创建句柄，支持多种模块选择；rockx_face_detect进行人脸检测；rockx_face_recognize提取人脸特征值；rockx_face_feature_similarity计算人脸相似度；rockx_face_masks_detect检测戴口罩情况。框架支持
一.rockx人脸检测使用的API
rockx框架提供了一系列的人脸识别、检测的API，开发者使用它的API能够快速开发出人脸相关的功能。我们来看看在人脸检测中需要用到的API。
1.1.rockx_create函数的定义
rockx_ret_t rockx_create(rockx_handle_t *handle, rockx_module_t m, void *config, size_t config_size);函数解释：rockx_create创建rockx的句柄rockx_handle_t。rockx_handle_t也是管理整个rockx人脸检测、人脸识别的最重要结构体
第一个参数：rockx_handle_t的结构体指针
第二个参数：rockx_module_t的结构体，rockx_module_t是一个枚举类型，设置当前rockx的处理类型。具体的如下：
typedef enum {
ROCKX_MODULE_FACE_DETECTION = 1, ///< Face Detection with 320x320 input: retinaface, pure u8-quant,with same mean value(117)
ROCKX_MODULE_FACE_LANDMARK_68 = 2, ///< Face Landmark (68 KeyPoints)
ROCKX_MODULE_FACE_RECOGNIZE = 3, ///< Face Recognition
ROCKX_MODULE_FACE_ANALYZE = 4, ///< Face Attribute(Gender and Age) Analyze
ROCKX_MODULE_OBJECT_DETECTION = 5, ///< Object Detection(91 Classes)
ROCKX_MODULE_POSE_BODY = 6, ///< Body Pose(14 KeyPoints)
ROCKX_MODULE_POSE_FINGER_21 = 7, ///< Finger Landmark(21 KeyPoint)
ROCKX_MODULE_FACE_LANDMARK_5 = 8, ///< Face Landmark(5 KeyPoints)
ROCKX_MODULE_HEAD_DETECTION = 9, ///< Head Detection
ROCKX_MODULE_CARPLATE_DETECTION = 10, ///< Car Plate Detection
ROCKX_MODULE_CARPLATE_ALIGN = 11, ///< Car Plate Correct Alignment
ROCKX_MODULE_CARPLATE_RECOG = 12, ///< Car Plate Recognition
ROCKX_MODULE_OBJECT_TRACK = 13, ///< Object Track
ROCKX_MODULE_POSE_FINGER_3 = 14, ///< Finger Landmark(3 KeyPoint)
ROCKX_MODULE_FACE_MASKS_DETECTION = 16, ///< Face Mask Detection
ROCKX_MODULE_FACE_DETECTION_V2 = 18, ///< Face Detection V2
ROCKX_MODULE_BODY_MASK = 19, ///< Body mask
ROCKX_MODULE_POSE_BODY_V2 = 20, ///< Body Pose(17 KeyPoints)
ROCKX_MODULE_FACE_DETECTION_V3 = 22, ///< Face Detection with 320x320 input: retinaface, input/output node is uint8,others is int16
ROCKX_MODULE_FACE_DETECTION_V3_LARGE = 23, ///< Face Detection with 640x640 input
ROCKX_MODULE_PERSON_DETECTION = 24, ///< Person Detection with 320x320 input
ROCKX_MODULE_FACE_LANDMARK_106 = 25, ///< Face Landmark(106 KeyPoints)
ROCKX_MODULE_FACE_BEAUTY = 26, ///< Face beauty score
ROCKX_MODULE_FACE_SMILE_DETECT = 27, ///< Face Smile Detect
ROCKX_MODULE_FACE_MASK_CLASSIFIER = 28, ///< FACE Mask Classifier
ROCKX_MODULE_PERSON_DETECTION_V2 = 29, ///< Person Detection with input: 532X320
ROCKX_MODULE_PERSON_DETECTION_V3 = 30, ///< Person Detection
} rockx_module_t;
ROCKX_MODULE_FACE_DETECTION：人脸检测模块
ROCKX_MODULE_FACE_LANDMARK_68：人脸68个特征点检测
ROCKX_MODULE_FACE_RECOGNIZE：人脸识别模块
ROCKX_MODULE_FACE_ANALYZE： 人脸分析模块
ROCKX_MODULE_OBJECT_DETECTION：目标检测模块
ROCKX_MODULE_POSE_BODY： 人体姿态检测模块，14个关键点
ROCKX_MODULE_POSE_FINGER_21：手指检测模块，21个关键点
ROCKX_MODULE_FACE_LANDMARK_5：人脸5个特征点检测
ROCKX_MODULE_HEAD_DETECTION： 人体头部检测模块
ROCKX_MODULE_CARPLATE_DETECTION： 车牌检测模块
ROCKX_MODULE_CARPLATE_ALIGN：车牌对齐模块
ROCKX_MODULE_CARPLATE_RECOG：车牌识别模块
ROCKX_MODULE_OBJECT_TRACK：物体追踪模块
ROCKX_MODULE_POSE_FINGER_3：手指检测模块， 支持3个关键点
ROCKX_MODULE_FACE_MASKS_DETECTION：人脸口罩检测，检测这个人是否戴口罩
ROCKX_MODULE_FACE_DETECTION_V2：人脸检测模块，Version2版本
ROCKX_MODULE_BODY_MASK：人体身体遮挡检测，主要是检测当前人体是否有遮挡物
ROCKX_MODULE_POSE_BODY_V2：人体姿态检测，V2是Version2，最多能够检测17个关键点
ROCKX_MODULE_FACE_DETECTION_V3：人脸检测模块，V3是Version3，它只能检测320 * 320的人脸
ROCKX_MODULE_FACE_DETECTION_V3_LARGE：人脸检测模块加强版，V3是Version3，Large能够检测640 * 640的人脸
ROCKX_MODULE_PERSON_DETECTION：行人检测模块，主要是检测当前图像中是否有行人
ROCKX_MODULE_FACE_LANDMARK_106：人脸关键点检测模型，总共能检测出106个关键点
ROCKX_MODULE_FACE_BEAUTY：人脸漂亮指数检测模型，主要是检测人的漂亮指数是多少
ROCKX_MODULE_FACE_SMILE_DETECT：人脸微笑检测模型，检测当前人是否微笑
ROCKX_MODULE_FACE_MASK_CLASSIFIER：人脸口罩分类检测模型，主要是检测当前口罩的类型是什么
ROCKX_MODULE_PERSON_DETECTION_V2：行人检测模型，V2是Version2，它只能检测532 * 320的行人图像
ROCKX_MODULE_PERSON_DETECTION_V3：行人检测模型，V3是Version3，它可以检测多尺寸的行人图像
第三个参数：rockx_config_t结构体指针，主要是配置rockx的基本参数，它的创建是用rockx_add_config来创建
第四个参数：config_size，默认是0就可以
第三个参数：rockx_config_t结构体指针，主要是配置rockx的基本参数，它的创建是用rockx_add_config来创建
第四个参数：config_size，默认是0就可以
1.2.rockx_add_config函数的定义
rockx_ret_t rockx_add_config(rockx_config_t *config, const char *key, const char *value);函数解释：添加rockx的config配置
第一个参数：rockx_config_t结构体指针，rockx_config_t的创建是用rockx_create_config来分配，如：rockx_config_t *config = rockx_create_config();
第二个参数：config的key, 最常见的KEY是ROCKX_CONFIG_DATA_PATH(ROCKX的配置路径)
第三个参数：config的value, 跟Key一一对应, 比方说Key是ROCKX_CONFIG_DATA_PATH, 那它的value就是对应的rockx的具体路径，如:/userdata/rockx_data/。
示例：
rockx_config_t *config = rockx_create_config();
rockx_add_config(config, ROCKX_CONFIG_DATA_PATH, "/userdata/rockx_data/");
1.3.rockx_face_detect函数的定义
函数解释：这个API主要是对人脸进行检测，得到人脸检测的位置信息
rockx_ret_t rockx_face_detect(rockx_handle_t handle, rockx_image_t *in_img, rockx_object_array_t *face_array, rockx_async_callback *callback);第一个参数：rockx_handle_t的结构体指针
第二个参数：rockx_image_t的结构体指针，这个是输入的图像，需要检测的图像，也可以是每一帧视频流。
第三个参数：rockx_object_array_t的结构体指针，主要是输出检测结果，这个检测结果的结构体如下：
typedef struct rockx_object_array_t {
int count; ///< Array Count(0 <= count < 128)
rockx_object_t object[128]; ///< Objects
} rockx_object_array_t;count：检测的人脸数量
rockx_object_t：检测的具体信息，具体的成员变量如下：
typedef struct rockx_object_t {
int id; ///< Track id
int cls_idx; ///< Class index
rockx_rect_t box; ///< Object Region
float score; ///< Object confidence score
} rockx_object_t;id：object的id号
cls_idx：object的index索引
box：rockx的区域信息，rockx_rect_t结构体。
typedef struct rockx_rect_t {
int left; ///< Most left coordinate
int top; ///< Most top coordinate
int right; ///< Most right coordinate
int bottom; ///< Most bottom coordinate
} rockx_rect_t;left：区域左边缘的x坐标，其实就是x轴数据
top: 区域顶的y坐标，其实就是Y轴数据
right：区域右边缘的x坐标，其实就是left + width
bottom：区域底的Y坐标，其实就是 top + height
score：object物体信任分数(根据经验值去填)
第四个参数：config_size，默认是0就可以
1.4.rockx_face_recognize函数的定义
函数定义：这个API主要是对人脸进行识别，并提取人脸数据
rockx_ret_t rockx_face_recognize(rockx_handle_t handle, rockx_image_t *in_img, rockx_face_feature_t *out_feature);第一个参数：rockx_handle_t的结构体指针
第二个参数：rockx_image_t的结构体指针，这个是输入的图像，需要检测的图像，也可以是每一帧视频流。
第三个参数：rockx_face_feature_t的结构体指针，rockx_face_feature_t结构体主要是存储人脸的特征值和长度，我们来看看这个结构体的组成
typedef struct rockx_face_feature_t {
int version; ///< Face recognition algorithm version
int len; ///< Feature length
float feature[512]; ///< Feature data
} rockx_face_feature_t;
version：人脸识别版本
len：人脸识别的长度
feature[512]：人脸识别的数据，512的float数组，这个值是存储一个二进制数据
1.5.rockx_face_feature_similarity函数的定义
函数的定义：这个API主要是对比两个人脸，并计算两个人脸的对比数值
rockx_ret_t rockx_face_feature_similarity(rockx_face_feature_t *in_feature1, rockx_face_feature_t *in_feature2, float *out_similarity);第一个参数：in_feature1，需要对比的人脸特征值1
第一个参数：in_feature2，需要对比的人脸特征值2
第三个参数：in_feature1和in_feature2对比的相似度值，一般小于1.0可以判断为同一个人
1.6.rockx_face_align函数的定义
函数的定义：这个API主要是对目前检测的人脸进行对齐，这个对齐一般是用face_landmark检测人脸关键点进行对齐
rockx_ret_t rockx_face_align(rockx_handle_t handle, rockx_image_t *in_img, rockx_rect_t *in_box, rockx_face_landmark_t *in_landmark, rockx_image_t *out_img);第一个参数：rockx_handle_t的结构体
第二个参数：in_img输入的图像
第三个参数：in_box是人脸检测的区域，用矩形来表示，我们来看看rockx_rect_t的结构体成员变量
typedef struct rockx_rect_t {
int left; ///< Most left coordinate
int top; ///< Most top coordinate
int right; ///< Most right coordinate
int bottom; ///< Most bottom coordinate
} rockx_rect_t;left：表示矩形左边缘的X坐标。
top：表示矩形顶部的y坐标
right：表示矩形右边缘的x坐标
bottom：表示矩形底部的y坐标。
第四个参数：rockx_face_landmark_t 的结构体指针，主要是检测人脸关键点，我们来看看这个结构体的成员变量
第五个参数:out_image是输出后的图像，经过人脸对齐后的图像
typedef struct rockx_face_landmark_t {
int image_width; ///< Input image width
int image_height; ///< Input image height
rockx_rect_t face_box; ///< Face region
int landmarks_count; ///< Landmark points count
rockx_point_t landmarks[128]; ///< Landmark points
float score; ///< Score (Only 5 points has score)
} rockx_face_landmark_t;
image_width：图像的长度
image_height：图像的高度
face_box：人脸的检测区域，用矩形表示
landmarks_count：关键点个数
landmarks[128]：具体的人脸关键点，rockx_point_t来表示，它本质上就是x,y的点
typedef struct rockx_point_t {
int x; ///< X Coordinate
int y; ///< Y Coordinate
} rockx_point_t;1.7.rockx_face_filter函数的定义
函数的定义：这个API主要是过滤人脸，过滤图像中不符合人脸的图像
rockx_ret_t rockx_face_filter(rockx_handle_t handle, rockx_image_t *in_img, rockx_rect_t *in_box, int *is_false_face);第一个参数：rockx_handle_t的结构体指针
第二个参数：in_img是输入的图像
第三个参数：in_box人脸检测区域，是一个矩形
第四个参数：is_falas_face判断当前检测的图像是否是人脸，是人脸就等于true，否则false
1.8.rockx_face_masks_detect函数的定义
函数解释：这个API主要是检测当前人脸是否有戴口罩
rockx_ret_t rockx_face_masks_detect(rockx_handle_t handle, rockx_image_t *in_img, rockx_face_mask_array_t *face_mask_array,rockx_async_callback *callback);第一个参数：rockx_handle_t的结构体指针
第二个参数：in_img是输入的图像
第三个参数：face_mask_array存放口罩的数据，我们来看看这个结构体的数据
typedef struct rockx_face_mask_array_t {
int count; ///< Face masks count
rockx_face_mask_t face_masks[128]; ///< Face masks
} rockx_face_mask_array_t;第一个参数：count，口罩的数量
第二个参数：rockx_face_mask_t，具体的口罩参数，如下
typedef struct rockx_face_mask_t {
rockx_rect_t face_box; ///< Face region
float mask_score; ///< Mask score
int hasMask; ///< Mask flag
} rockx_face_mask_t;第一个参数：face_box是口罩的区域，用矩形表示
第二个参数：mask_score，口罩的分数
第三个参数：hasMask，是否有戴口罩
火山引擎开发者社区是火山引擎打造的AI技术生态平台，聚焦Agent与大模型开发，提供豆包系列模型（图像/视频/视觉）、智能分析与会话工具，并配套评测集、动手实验室及行业案例库。社区通过技术沙龙、挑战赛等活动促进开发者成长，新用户可领50万Tokens权益，助力构建智能应用。
更多推荐
8
0- 0
已为社区贡献26条内容
所有评论(0)