人形跟踪接口说明文档

文档版本	V1.0
修订日期	2026-08-17
对应头文件	`components/media/framework/api/include/api_human_track.h`
类型定义	`components/media/framework/api/include/api_human_track.h`（枚举/结构体） `components/media/framework/component_adapter/human_track/include/fw_human_track_define.h`（适配层类型）
适用模块	人形跟踪（human_track）
---

1 概述

本模块对外提供 hi_fw_human_track_* 系列接口，封装了人形/目标跟踪能力：创建/销毁跟踪任务、启停任务、动态调整检测间隔、独立注册/注销结果回调。底层基于 AIComponent SDK 的 ss_mpi_aidetect（HUMAN + FACE 两类目标跟踪），每帧从指定 VPSS 通道取帧、执行跟踪推理、通过回调把结果（目标 id + 坐标 + 置信度 + 跟踪状态）返回给上层调用方（如小车跟踪算法、zeroclaw）。

模型层次：

human_track 模块
  └─ hi_fw_human_track_handle（任务句柄，一个句柄对应一个跟踪任务/通道）
        └─ 结果回调 hi_fw_human_track_result_cb（每帧跟踪结果，含 id + 坐标）

运行模式：

DIRECT（直连）：同进程内通过 light_msg 与适配层同步通信，适配层 worker 线程取帧→推理→回调。
IPC CLIENT：通过 channel 与远端 server 通信，server 端执行实际跟踪，结果经 IPC 异步推送。

2 接口总览

编号	接口	模块	功能概述
1	`hi_fw_human_track_direct_init`	生命周期（直连）	初始化 DIRECT 模式（创建 light_msg 通道 + 适配层）
2	`hi_fw_human_track_direct_deinit`	生命周期（直连）	反初始化 DIRECT 模式
3	`hi_fw_human_track_client_init`	生命周期（IPC）	初始化 IPC CLIENT 模式（连接远端 server 并注册模块）
4	`hi_fw_human_track_client_deinit`	生命周期（IPC）	反初始化 IPC CLIENT 模式
5	`hi_fw_human_track_create_task`	任务管理	创建跟踪任务（指定模型、输入源、绘制配置）
6	`hi_fw_human_track_destroy_task`	任务管理	销毁跟踪任务并释放资源
7	`hi_fw_human_track_start_task`	任务管理	启动跟踪任务（worker 线程开始循环处理）
8	`hi_fw_human_track_stop_task`	任务管理	停止跟踪任务
9	`hi_fw_human_track_set_interval`	任务管理	动态调整检测间隔
10	`hi_fw_human_track_get_interval`	任务管理	查询当前检测间隔
11	`hi_fw_human_track_reg_cb`	回调管理	独立注册结果回调（media 模式，非 create 时传入）
12	`hi_fw_human_track_unreg_cb`	回调管理	注销结果回调

获取目标 id + 坐标的唯一途径：注册结果回调（reg_cb）后，组件每帧跟踪完成会调用回调 on_result，回调的返回值 hi_fw_human_track_result（或其参数 result）中携带目标 track_id（id）与 rect（坐标）。其余 12 个 API 返回值均为 TD_SUCCESS / TD_FAILURE 状态码，不携带 id + 坐标。详见 §3.11 与 §4.7。

3 API 参考

3.1 hi_fw_human_track_direct_init

【描述】

初始化 DIRECT（直连）模式：创建 light_msg 消息通道并实例化适配层（human_track_impl），为后续 create_task 等调用建立运行环境。幂等：重复调用不会重复初始化。

【语法】

td_s32 hi_fw_human_track_direct_init(td_void);

【参数】

无。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（light_msg 初始化失败等）。

【注意】

必须在 create_task 之前调用（仅 DIRECT 模式需要）。
DIRECT 与 CLIENT 模式互斥：一个进程内使用哪种模式由调用方决定，勿混用。

【举例】

if (hi_fw_human_track_direct_init() != TD_SUCCESS) {
    printf("direct init failed\n");
    return -1;
}

【相关主题】

hi_fw_human_track_direct_deinit、hi_fw_human_track_create_task。

3.2 hi_fw_human_track_direct_deinit

【描述】

反初始化 DIRECT 模式：销毁 light_msg 通道与适配层实例。幂等（未初始化时直接返回）。应在所有任务销毁后调用。

【语法】

td_void hi_fw_human_track_direct_deinit(td_void);

【参数】

无。

【返回值】

无（void）。

【注意】

需在全部 destroy_task 之后调用，否则任务句柄将失效。

【举例】

hi_fw_human_track_direct_deinit();

【相关主题】

hi_fw_human_track_direct_init。

3.3 hi_fw_human_track_client_init

【描述】

初始化 IPC CLIENT 模式：连接远端 server（默认 endpoint 为 API_HUMAN_TRACK_CLIENT_ENDPOINT），以 LIGHT_MSG_HUMAN_TRACK_MOD（0x00005000U）注册模块并注册异步结果回调。幂等：重复调用直接返回成功。

【语法】

td_s32 hi_fw_human_track_client_init(const td_char *endpoint);

【参数】

参数名称	输入/输出	类型	描述
`endpoint`	输入	`const td_char *`	server 端 socket 路径。传 `NULL` 或空串时使用默认 endpoint。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`TD_FAILURE (非0)`	失败（连接失败 / 模块注册被拒等）。

【注意】

server 端须已启动且 client_auth 已注册 human_track 模块（LIGHT_MSG_HUMAN_TRACK_MOD），否则 channel_client_register 返回鉴权错误。
该模式下 direct_init/deinit 为不支持的空操作（打印告警）。

【举例】

if (hi_fw_human_track_client_init(NULL) != TD_SUCCESS) {
    printf("client init failed\n");
    return -1;
}

【相关主题】

hi_fw_human_track_client_deinit、hi_fw_human_track_create_task。

3.4 hi_fw_human_track_client_deinit

【描述】

反初始化 IPC CLIENT 模式：使全部任务句柄失效、等待任务空闲、清理 server 端任务、注销回调并断开连接。幂等。

【语法】

td_s32 hi_fw_human_track_client_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`TD_FAILURE (非0)`	失败（断开连接失败等）。

【注意】

内部会清理全部未销毁的任务（调用 server 端 destroy），无需先手动销毁。

【相关主题】

hi_fw_human_track_client_init。

3.5 hi_fw_human_track_create_task

【描述】

创建一个人形跟踪任务：分配任务槽位（direct 模式最多 DIRECT_HUMAN_TRACK_MAX_CHN=8 个），按 attr 配置模型路径、输入源（VPSS 通道）、检测间隔、绘制配置，并启动独立 worker 线程。任务创建后处于就绪状态，需调用 start_task 开始处理。IPC 模式下通过 UDS_MSG_HUMAN_TRACK_CREATE_TASK 通知 server 创建。

【语法】

td_s32 hi_fw_human_track_create_task(const hi_fw_human_track_task_attr *attr,
                                     hi_fw_human_track_handle *handle);

【参数】

参数名称	输入/输出	类型	描述
`attr`	输入	`const hi_fw_human_track_task_attr *`	任务属性（model_path / interval_ms / src / draw）。不可为 NULL。
`handle`	输出	`hi_fw_human_track_handle *`	返回任务句柄。不可为 NULL。

hi_fw_human_track_task_attr 成员：

成员名称	描述
`model_path`	检测模型路径（如 `det_hvf_hor.bin`）。不可为空。
`interval_ms`	检测间隔（毫秒）。0 或未填时用默认值。
`src`	输入源：`HI_FW_HUMAN_TRACK_SOURCE_VPSS` + `vpss_grp`/`vpss_chn`。
`draw`	RGN/VGS 绘制配置（`enable=TD_FALSE` 时不绘制）。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功，`*handle` 为有效句柄。
`非0`	失败（未初始化 / 参数空 / 槽位耗尽 / 模型加载失败等）。

【注意】

DIRECT 模式：必须先 direct_init；适配层要求 get_frame/postproc/release_frame 三个回调齐全。
结果回调不在 create 时传入，需另行调用 reg_cb（media 模式约定）。
src.type 仅支持 HI_FW_HUMAN_TRACK_SOURCE_VPSS。
模型加载失败或通道创建失败时资源自动回滚。

【举例】

hi_fw_human_track_task_attr attr = {0};
attr.model_path  = "/usr/lib/model/det_hvf_hor.bin";
attr.interval_ms = 33;
attr.src.type    = HI_FW_HUMAN_TRACK_SOURCE_VPSS;
attr.src.vpss.vpss_grp = 0;
attr.src.vpss.vpss_chn = 1;
attr.draw.enable = TD_FALSE;

hi_fw_human_track_handle handle = NULL;
if (hi_fw_human_track_create_task(&attr, &handle) != TD_SUCCESS) {
    printf("create task failed\n");
    return -1;
}

【相关主题】

hi_fw_human_track_destroy_task、hi_fw_human_track_start_task、hi_fw_human_track_reg_cb。

3.6 hi_fw_human_track_destroy_task

【描述】

销毁指定跟踪任务：使句柄失效、清空已注册回调、停止 worker 线程并释放 MPI 通道与资源。IPC 模式下通知 server 端销毁。

【语法】

td_s32 hi_fw_human_track_destroy_task(hi_fw_human_track_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	待销毁的任务句柄。不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（未初始化 / 句柄 NULL）。

【注意】

销毁后句柄不可再使用。
建议先 stop_task 再 destroy_task（destroy 内部会停 worker）。

【相关主题】

hi_fw_human_track_create_task。

3.7 hi_fw_human_track_start_task

【描述】

启动跟踪任务：通知 worker 线程进入运行状态，开始按 interval_ms 周期取帧→推理→回调。count 为处理帧数上限，传 -1 表示持续运行直到 stop。

【语法】

td_s32 hi_fw_human_track_start_task(hi_fw_human_track_handle handle, td_s32 count);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。
`count`	输入	`td_s32`	处理帧数上限；`-1` 表示不限（持续运行）。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（未初始化 / 句柄 NULL）。

【注意】

需在 create_task 之后调用。
达到 count 后任务自动回到就绪状态（可再次 start）。

【相关主题】

hi_fw_human_track_stop_task。

3.8 hi_fw_human_track_stop_task

【描述】

停止跟踪任务：置位停止标志，worker 线程退出当前轮后结束。

【语法】

td_s32 hi_fw_human_track_stop_task(hi_fw_human_track_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（未初始化 / 句柄 NULL）。

【相关主题】

hi_fw_human_track_start_task。

3.9 hi_fw_human_track_set_interval

【描述】

动态调整检测间隔（毫秒）。影响 worker 线程每轮处理后的等待时长。

【语法】

td_s32 hi_fw_human_track_set_interval(hi_fw_human_track_handle handle, td_u32 interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。
`interval_ms`	输入	`td_u32`	新的检测间隔（毫秒）。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（未初始化 / 句柄 NULL）。

【相关主题】

hi_fw_human_track_get_interval。

3.10 hi_fw_human_track_get_interval

【描述】

查询当前检测间隔（毫秒）。

【语法】

td_s32 hi_fw_human_track_get_interval(hi_fw_human_track_handle handle, td_u32 *interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。
`interval_ms`	输出	`td_u32 *`	返回当前间隔。不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功，`*interval_ms` 有效。
`非0`	失败（未初始化 / 句柄或输出 NULL）。

【相关主题】

hi_fw_human_track_set_interval。

3.11 hi_fw_human_track_reg_cb

【描述】

为指定任务独立注册结果回调（对齐 api_media venc/aenc/acap 的 reg_cb 模式）。回调在每帧跟踪完成后由组件调用，返回本次跟踪结果（含目标 id 与坐标），调用方据此驱动小车跟踪或喂给 zeroclaw。IPC 模式下通过 UDS_MSG_HUMAN_TRACK_REGISTER_CB 通知 server 端开始按需推送结果。

【语法】

td_s32 hi_fw_human_track_reg_cb(hi_fw_human_track_handle handle,
                                const hi_fw_human_track_callback *cb);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。
`cb`	输入	`const hi_fw_human_track_callback *`	回调结构（on_result + user_data）。`on_result` 不可为 NULL。

hi_fw_human_track_callback 成员：

成员名称	描述
`on_result`	每帧结果回调 `hi_fw_human_track_result_cb`（可空，注册前不触发）。
`user_data`	回调私有数据（小车/zeroclaw 上下文）。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	注册成功。
`非0`	注册失败（参数 NULL / 槽位无效等）。

注意区分两类"返回值"：

本接口 reg_cb 的返回值：仅为注册状态（TD_SUCCESS / 非0），不含目标数据；

目标 id + 坐标：注册后由组件每帧调用 on_result，回调的返回值（hi_fw_human_track_result）及参数 result 中携带 objs[i].track_id 与 objs[i].rect。调用方在回调体内读取即可。

【注意】

每个任务最多一个回调（静态数组按 task_id 索引，重复注册覆盖）。
回调返回值为 hi_fw_human_track_result（含 count 与 objs[]），调用方读取 objs[i].track_id 与 objs[i].rect。

【举例】

static hi_fw_human_track_result on_result(hi_fw_human_track_handle h,
                                          const hi_fw_human_track_result *result)
{
    if (result == NULL || result->count == 0) {
        hi_fw_human_track_result empty = {0};
        return empty;
    }
    printf("track id=%u rect=(%d,%d %ux%u)\n",
           result->objs[0].track_id,
           result->objs[0].rect.x, result->objs[0].rect.y,
           result->objs[0].rect.width, result->objs[0].rect.height);
    return *result;
}

hi_fw_human_track_callback cb = { .on_result = on_result, .user_data = ctx };
hi_fw_human_track_reg_cb(handle, &cb);

【相关主题】

hi_fw_human_track_unreg_cb。

3.12 hi_fw_human_track_unreg_cb

【描述】

注销指定任务的结果回调。注销后组件不再向该任务推送/触发结果回调。

【语法】

td_s32 hi_fw_human_track_unreg_cb(hi_fw_human_track_handle handle,
                                  const hi_fw_human_track_callback *cb);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_human_track_handle`	任务句柄。不可为 NULL。
`cb`	输入	`const hi_fw_human_track_callback *`	待注销的回调结构。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`非0`	失败（参数 NULL 等）。

【相关主题】

hi_fw_human_track_reg_cb。

4 数据类型

4.1 hi_fw_human_track_handle

【说明】

人形跟踪任务句柄（不透明指针），由 create_task 创建，其余接口均以其为操作对象。

【定义】

typedef struct hi_fw_human_track_task_opaque *hi_fw_human_track_handle;

【成员】

无（不透明类型）。

【注意事项】

句柄由 create_task 输出，销毁后不可再使用。

【相关数据类型及接口】

hi_fw_human_track_create_task、hi_fw_human_track_destroy_task。

4.2 hi_fw_human_track_class

【说明】

跟踪目标类别枚举（对齐 SDK ot_aidetect_class）。

【定义】

typedef enum {
    HI_FW_HUMAN_TRACK_CLASS_FACE          = 0,
    HI_FW_HUMAN_TRACK_CLASS_HUMAN         = 1,
    HI_FW_HUMAN_TRACK_CLASS_VEHICLE       = 2,
    HI_FW_HUMAN_TRACK_CLASS_PET           = 3,
    HI_FW_HUMAN_TRACK_CLASS_GARBAGE       = 4,
    HI_FW_HUMAN_TRACK_CLASS_BAG           = 5,
    HI_FW_HUMAN_TRACK_CLASS_WALLET        = 6,
    HI_FW_HUMAN_TRACK_CLASS_PHONE         = 7,
    HI_FW_HUMAN_TRACK_CLASS_HEAD_SHOULDER = 8,
    HI_FW_HUMAN_TRACK_CLASS_BICYCLE       = 9,
    HI_FW_HUMAN_TRACK_CLASS_MOTORCYCLE    = 10,
    HI_FW_HUMAN_TRACK_CLASS_PACKAGE       = 11,
    HI_FW_HUMAN_TRACK_CLASS_BUTT          = 12,
} hi_fw_human_track_class;

【成员】

成员名称	描述
`HI_FW_HUMAN_TRACK_CLASS_HUMAN`	人（跟踪主要目标）。
`HI_FW_HUMAN_TRACK_CLASS_FACE`	人脸。
其余	车辆 / 宠物 / 垃圾 / 包 / 钱包 / 手机 / 头肩 / 自行车 / 摩托车 / 包裹。
`HI_FW_HUMAN_TRACK_CLASS_BUTT`	枚举边界，非法值。

【注意事项】

当前组件默认配置跟踪 HUMAN + FACE 两类。

【相关数据类型及接口】

hi_fw_human_track_object、hi_fw_human_track_result。

4.3 hi_fw_human_track_track_status

【说明】

目标跟踪状态枚举（NEW/UPDATE/DIE/INVALID）。

【定义】

typedef enum {
    HI_FW_HUMAN_TRACK_STATUS_NEW     = 0,
    HI_FW_HUMAN_TRACK_STATUS_UPDATE  = 1,
    HI_FW_HUMAN_TRACK_STATUS_DIE     = 2,
    HI_FW_HUMAN_TRACK_STATUS_INVALID = 3,
    HI_FW_HUMAN_TRACK_STATUS_BUTT    = 4,
} hi_fw_human_track_track_status;

【成员】

成员名称	描述
`NEW`	新出现目标。
`UPDATE`	已跟踪目标更新。
`DIE`	目标消失/丢失。
`INVALID`	无效状态。
`BUTT`	边界。

【相关数据类型及接口】

hi_fw_human_track_object。

4.4 hi_fw_human_track_rect

【说明】

目标矩形坐标（像素）。

【定义】

typedef struct {
    td_s32  x;
    td_s32  y;
    td_u32  width;
    td_u32  height;
} hi_fw_human_track_rect;

【成员】

成员名称	描述
`x` / `y`	矩形左上角坐标。
`width` / `height`	矩形宽高。

【相关数据类型及接口】

hi_fw_human_track_object。

4.5 hi_fw_human_track_object

【说明】

单个跟踪目标：坐标框 + 置信度 + 类别 + id + 跟踪状态。

【定义】

typedef struct {
    hi_fw_human_track_rect          rect;
    td_float                        confidence;
    hi_fw_human_track_class         type;
    td_u32                          track_id;
    hi_fw_human_track_track_status  track_status;
} hi_fw_human_track_object;

【成员】

成员名称	描述
`rect`	目标坐标框。
`confidence`	检测置信度（0.0~1.0）。
`type`	目标类别。
`track_id`	跟踪目标唯一 id（小车跟踪算法据此关联目标）。
`track_status`	跟踪状态。

【相关数据类型及接口】

hi_fw_human_track_result、hi_fw_human_track_result_cb。

4.6 hi_fw_human_track_result

【说明】

单帧跟踪结果集合：目标数量 + 目标数组。该类型既作为结果回调 hi_fw_human_track_result_cb 的返回值，也作为其参数类型——是上层获取目标 id + 坐标的数据载体。

【定义】

typedef struct {
    td_u32                      count;
    const hi_fw_human_track_object *objs;
} hi_fw_human_track_result;

【成员】

成员名称	描述
`count`	本帧目标数量。
`objs`	目标数组（含 id + 坐标）。

【注意事项】

回调无目标时 count=0；回调必须返回合法结构（不能解引用空指针）。

【相关数据类型及接口】

hi_fw_human_track_object、hi_fw_human_track_result_cb。

4.7 hi_fw_human_track_result_cb

【说明】

结果回调函数指针类型：由组件在每帧跟踪完成后调用，返回本次跟踪结果。

【定义】

typedef hi_fw_human_track_result (*hi_fw_human_track_result_cb)(hi_fw_human_track_handle handle,
                                                                const hi_fw_human_track_result *result);

【参数】

参数名称	描述
`handle`	触发本次回调的任务句柄。
`result`	本次跟踪结果（非空）。

【返回值】

返回值	描述
`hi_fw_human_track_result`	本次跟踪结果（含目标 id + 坐标）。调用方读取 `result->objs[i].track_id`（id）与 `result->objs[i].rect`（坐标框）即可驱动小车跟踪 / zeroclaw。

核心设计：回调函数返回值类型即 hi_fw_human_track_result（与参数 result 同类型）。无目标帧（result==NULL 或 count==0）时返回空结构（{0}），不可返回未初始化的野结构。

【注意事项】

回调中可读取 result->objs[i].track_id 与 result->objs[i].rect。
无目标帧（result==NULL 或 count==0）须返回空结果结构。

【相关数据类型及接口】

hi_fw_human_track_result、hi_fw_human_track_object、hi_fw_human_track_callback、hi_fw_human_track_reg_cb。

4.8 hi_fw_human_track_callback

【说明】

结果回调注册结构（对齐 api_media venc/aenc/acap 的回调模式）。

【定义】

typedef struct {
    hi_fw_human_track_result_cb  on_result;   /* 每帧跟踪结果回调（可空，注册前不触发） */
    td_void                     *user_data;   /* 回调私有数据（小车/zeroclaw 上下文） */
} hi_fw_human_track_callback;

【成员】

成员名称	描述
`on_result`	每帧结果回调。
`user_data`	回调私有数据。

【相关数据类型及接口】

hi_fw_human_track_reg_cb、hi_fw_human_track_unreg_cb。

4.9 hi_fw_human_track_source_type / hi_fw_human_track_source_vpss / hi_fw_human_track_source

【说明】

任务输入源定义：当前仅支持 VPSS 通道取帧。

【定义】

typedef enum {
    HI_FW_HUMAN_TRACK_SOURCE_VPSS = 0,
    HI_FW_HUMAN_TRACK_SOURCE_BUTT
} hi_fw_human_track_source_type;

typedef struct {
    td_u32 vpss_grp;
    td_u32 vpss_chn;
} hi_fw_human_track_source_vpss;

typedef struct {
    hi_fw_human_track_source_type type;
    union {
        hi_fw_human_track_source_vpss vpss;
    };
} hi_fw_human_track_source;

【成员】

成员名称	描述
`type`	输入源类型（仅 VPSS）。
`vpss_grp` / `vpss_chn`	VPSS 组号 / 通道号（如 0 / 1）。

【相关数据类型及接口】

hi_fw_human_track_task_attr、hi_fw_human_track_create_task。

4.10 hi_fw_human_track_draw_cfg

【说明】

RGN/VGS 画面叠加配置（对齐适配层 fw_human_track_draw_cfg）。enable=TD_FALSE 时不绘制；各 0 值使用默认配置。

【定义】

typedef struct {
    td_bool     enable;
    td_u32      max_targets;
    td_u32      dst_mod_id;
    td_s32      dst_dev_id;
    td_s32      dst_chn_id;
    td_float    conf_threshold;
    td_u32      min_width;
    td_u32      min_height;
    td_u32      box_thick;
    td_u32      font_w;
    td_u32      font_h;
    td_u32      overlay_stride;
    td_bool     venc_chn_enable;
    td_s32      venc_chn_id;
} hi_fw_human_track_draw_cfg;

【成员】

成员名称	描述
`enable`	是否使能绘制（RGN ID 叠加 + VGS 画框）。
`max_targets`	最多叠加目标数（默认 8）。
`dst_mod_id`	RGN 挂载模块（默认 `OT_ID_VENC`）。
`dst_dev_id` / `dst_chn_id`	设备号 / 通道号（默认 0 / 1 = AI result stream）。
`conf_threshold`	置信度过滤（默认 0.50）。
`min_width` / `min_height`	最小检测框宽高（默认 30 / 40）。
`box_thick`	检测框线宽（默认 2）。
`font_w` / `font_h`	ID 字体宽高（默认 16 / 32）。
`overlay_stride`	ID 位图 stride（默认 128）。
`venc_chn_enable` / `venc_chn_id`	是否送 VENC 结果流 / VENC 通道号（默认关 / 1）。

【相关数据类型及接口】

hi_fw_human_track_task_attr。

4.11 hi_fw_human_track_task_attr

【说明】

任务创建属性（create_task 入参）。

【定义】

typedef struct {
    const td_char                  *model_path;
    td_u32                          interval_ms;
    hi_fw_human_track_source        src;
    hi_fw_human_track_draw_cfg      draw;
} hi_fw_human_track_task_attr;

【成员】

成员名称	描述
`model_path`	检测模型路径（如 det_hvf_hor.bin），不可为空。
`interval_ms`	检测间隔（毫秒），0 用默认。
`src`	输入源（VPSS 组/通道）。
`draw`	绘制配置（可选）。

【注意事项】

不支持初始 ROI/锚点字段（依赖组件首帧全图检测初始化跟踪）。

【相关数据类型及接口】

hi_fw_human_track_create_task。

4.12 关键常量

常量	取值	说明
`LIGHT_MSG_HUMAN_TRACK_MOD`	`0x00005000U`	human_track 消息模块基址（IPC 模块注册/消息 id 基址）。
`HUMAN_TRACK_MAX_CHN_NUM` / `DIRECT_HUMAN_TRACK_MAX_CHN`	8	最大并发任务数（适配层 / direct 层）。
`HUMAN_TRACK_RESULT_MAX_OBJ`	32	IPC 推送单帧最大目标数。
`HUMAN_TRACK_MODEL_PATH_MAX`	256	IPC 模型路径最大长度。
`HUMAN_TRACK_DEFAULT_CONFIDENCE_THRESHOLD`	0.50	默认置信度阈值。
`HUMAN_TRACK_DEFAULT_TRACK_MISS_FRAME_NUM`	30	默认丢失判定帧数。
`HUMAN_TRACK_DEFAULT_INTERVAL_MS`	33	默认检测间隔（毫秒）。

5 错误码

错误代码	宏定义	描述
`0x00000000`	`TD_SUCCESS`	操作成功。
`0xFFFFFFFF`	`TD_FAILURE`	通用失败（未初始化 / 句柄为空 / 同步消息失败等）。
适配层（内部）	`OT_ERR_AIDETECT_NULL_PTR`	输入参数空指针（适配层校验）。
适配层（内部）	`OT_ERR_AIDETECT_ILLEGAL_PARAM`	参数非法（model_path 为空 / 回调不完整）。
适配层（内部）	`OT_ERR_AIDETECT_UNEXIST`	任务槽位耗尽 / 目标不存在。
IPC（内部）	`CHN_EAUTH`	IPC 模块鉴权失败（server 端 client_auth 未注册 human_track 模块）。
IPC（内部）	`CHN_EINVALARG`	IPC 参数非法。

说明：对外 API 层主要返回 TD_SUCCESS / TD_FAILURE 二元结果；底层具体错误码（OT_ERR_AIDETECT_*、CHN_*）通过日志输出，不直接透传。

6 使用注意事项

句柄范围：句柄由 create_task 创建、destroy_task 释放；句柄在其所属模式（DIRECT/CLIENT）有效，跨模式不可混用。

时序依赖：遵循以下启停顺序（停止为逆序）：

启动（DIRECT 模式）：

hi_fw_human_track_direct_init()      // 初始化模式
  → hi_fw_human_track_create_task()  // 创建任务（模型/输入源/间隔/绘制）
  → hi_fw_human_track_reg_cb()       // 注册结果回调
  → hi_fw_human_track_start_task()   // 启动 worker
  → [循环] 回调 on_result（每帧结果：id + 坐标）

停止（逆序）：

hi_fw_human_track_stop_task()
  → hi_fw_human_track_unreg_cb()
  → hi_fw_human_track_destroy_task()
  → hi_fw_human_track_direct_deinit()

IPC CLIENT 模式：以 `client_init/client_deinit` 替代 `direct_init/direct_deinit`，其余时序一致。

资源配对：create_task 与 destroy_task 成对；reg_cb 与 unreg_cb 成对（未注销时 destroy 会自动清空回调槽位）。
属性语义：model_path、src、draw 为创建时静态属性（create 时一次确定）；interval_ms 为动态属性，可运行时通过 set_interval 调整。
模式差异：
- DIRECT：同进程 light_msg 同步通信，回调由适配层 worker 线程直接调用；支持 direct_init/deinit。
- IPC CLIENT：跨进程 channel 通信，结果经 UDS_MSG_HUMAN_TRACK_RESULT_PUSH 异步推送；direct_init/deinit 为不支持的空操作。
- 回调注册：两种模式均采用独立 reg_cb/unreg_cb（media 模式），而非 create 时传入。

7 附注 / 关联文档

组件源码：components/media/framework/（api/include/api_human_track.h、api/direct/human_track/、api/client/human_track/、api/ipc_bridge/human_track/、component_adapter/human_track/）。
消息模块基址：components/media/framework/api/ipc_bridge/common/inc/channel_api_msg.h（LIGHT_MSG_HUMAN_TRACK_MOD=0x00005000U）。
适配层类型：components/media/framework/component_adapter/human_track/include/fw_human_track_define.h。
绘制模块：components/media/framework/component_adapter/human_track/include/fw_human_track_draw.h。