ModelBox开发指南 - 流数据功能单元

本文将使用一个行人检测与跟踪的案例，介绍ModelBox中流数据功能单元的特性，案例效果如下所示：

本案例所需资源（代码、模型、测试数据等）已做成模板放到华为云上，查看和下载模板可以使用如下命令：

• Windows PC版本请使用solution.bat工具：

PS ███\modelbox>: .\solution.bat -l
...

Solutions name:
...
pedestrian_tracking_yolox
...

结果中的pedestrian_tracking_yolox即为行人检测与跟踪模板，可使用如下命令下载模板：

PS ███\modelbox>: .\solution.bat -s pedestrian_tracking_yolox
...

• Linux开发板版本请使用solution.py脚本：

rock@rock-3a:~/███/modelbox$ ./solution.py -l
...

Solutions name:
...
pedestrian_tracking_yolox
...

结果中的pedestrian_tracking_yolox即为行人检测与跟踪模板，可使用如下命令下载模板：

rock@rock-3a:~/███/modelbox$ ./solution.py -s pedestrian_tracking_yolox
...

solution.bat/solution.py工具的参数中，-l 代表list，即列出当前已有的模板名称；-s 代表solution-name，即下载对应名称的模板。下载下来的模板资源，将存放在ModelBox核心库的solution目录下。

如果对ModelBox AI应用开发还不熟悉，请先阅读ModelBox 端云协同AI开发套件（RK3568）上手指南，或者ModelBox 端云协同AI开发套件（博时特EC02）上手指南。

模型准备

本案例使用的是YOLOX模型进行人体检测，与ModelBox sdk中自带的car_det模板使用的模型相同。在下载的资源包中，已经包含了转换好的rknn模型或者onnx模型，可以在对应的平台上直接使用。当然，开发者也可以直接使用car_det模板中的YOLOX模型。
原始模型是通过PyTorch框架训练得到的，训练工程可参考此项目，感兴趣的开发者可使用该项目自行训练模型。
如果想体验rknn模型的转换过程，rknpu版本可参考RK1808模型转换验证案例，rknpu2版本可参考RK3568模型转换验证案例。

应用开发

打开VS Code，连接到ModelBox sdk所在目录或者远程开发板，开始进行行人检测与跟踪应用开发。下面以RK3568（rknpu2）版本为例进行说明，其他版本与之类似。

1）创建工程

使用create.py创建pedestrian_tracking工程（Windows PC版本请使用create.bat）：

rock@rock-3a:~/███/modelbox$ ./create.py -t server -n pedestrian_tracking -s pedestrian_tracking_yolox
sdk version is modelbox-rk-aarch64
success: create pedestrian_tracking in /home/rock/███/modelbox/workspace

将会用行人检测与跟踪模板创建出一个pedestrian_tracking工程。

2）查看跟踪功能单元

跟踪模块的功能单元，它根据当前帧的检测结果和保存下来的历史跟踪目标，进行新一轮的跟踪匹配，最后更新到跟踪目标中。它在工程目录的etc/flowunit/object_tracker文件夹下：

打开object_tracker.toml配置文件，可以看到功能单元属性部分：

# 工作模式，以下配置项默认全为false，表示通用功能单元；且配置项之前互斥，即最多只能设置其中一个为true
stream = true     # 是否是Stream类型功能单元，此处设置为true，即表示object_tracker是一个stream功能单元
condition = false # 是否是条件功能单元
collapse = false  # 是否是合并功能单元
expand = false    # 是否是展开功能单元

这些属性全部为false时表示通用功能单元，通用功能单元在处理数据时，只针对当前数据，并不关心数据之间的关联，也不记录任何状态。对于同一个数据流内的数据，它在一次process调用中并不保证这些数据处理的先后（当然数据处理完毕后会由框架重新收集排序），甚至一次process调用中可能包含来自多个流的数据。例如，图像缩放功能单元（resize）在处理当前图像时，处理过程和输出结果只跟当前输入图像相关，并不需要关心其他图像的状态，因此它是一个通用功能单元。本案例中的模型后处理功能单元yolox_post也是一个通用功能单元，因为YOLOX模型的后处理结果只跟当前帧的推理结果相关。

object_tracker功能单元属性部分的stream属性设置成了true，即object_tracker被设置成一个流数据功能单元。流数据功能单元在处理数据时，一次process调用中处理的都是来自同一个数据流的数据，且这些数据会顺序的进入process，开发者无需关心数据之前是否是有序的，在process此处，已经由框架保证顺序。例如，object_tracker功能单元在处理当前帧时，需要依赖来自同一数据流的历史跟踪目标，且当前帧一定要在上一帧处理完之后才能处理，因此，object_tracker需要被设置成一个流数据功能单元。
除了通用功能单元的open/close/process等函数外，流数据功能单元还需要实现data_pre/data_post函数，用于一个数据流中状态数据的初始化和释放。因此，object_tracker功能单元中，跟踪器的初始化就放在data_pre函数中：

    def data_pre(self, data_context):
        # 视频流开始前的初始化动作，跟踪器的初始化放在此处
        # self.tracker = Sort(self.init_hits, self.max_age, self.min_iou)  # 可以选用sort跟踪算法
        self.tracker = EasyTracker(self.init_hits, self.max_age, self.min_iou)
        return modelbox.Status()

object_tracker中使用的是简单的IoU匹配做新的检测目标与历史跟踪目标的关联（详见easy_tracker.py），开发者也可以尝试更复杂的跟踪策略。
关于流数据功能单元的更细致介绍，详见ModelBox介绍。

3）查看流程图

工程的默认流程图为graph/pedestrian_tracking.toml（以RK3568开发板版本为例）：

# Copyright (c) Huawei Technologies Co., Ltd. 2022. All rights reserved.

[driver]
# 功能单元的扫描路径，包含在[]中，多个路径使用,分隔
# ${HILENS_APP_ROOT} 表示当前应用的实际路径
# ${HILENS_MB_SDK_PATH} 表示ModelBox核心库的实际路径
dir = [
    "${HILENS_APP_ROOT}/etc/flowunit",
    "${HILENS_APP_ROOT}/etc/flowunit/cpp",
    "${HILENS_APP_ROOT}/model",
    "${HILENS_MB_SDK_PATH}/flowunit",
]
skip-default = true

[profile]
# 通过配置profile和trace开关启用应用的性能统计
profile = false                       # 是否记录profile信息，每隔60s记录一次统计信息
trace = false                         # 是否记录trace信息，在任务执行过程中和结束时，输出统计信息
dir = "${HILENS_DATA_DIR}/mb_profile" # profile/trace信息的保存位置

[flow]
desc = "pedestrian detection and tracking example using yolox for local video or rtsp video stream" # 应用的简单描述

[graph]
format = "graphviz" # 流程图的格式，当前仅支持graphviz
graphconf = """digraph pedestrian_tracking {
    node [shape=Mrecord]
    queue_size = 4
    batch_size = 1

    # 定义节点，即功能单元及其属性
    input1[type=input, flowunit=input, device=cpu, deviceid=0]
    data_source_parser[type=flowunit, flowunit=data_source_parser, device=cpu, deviceid=0]
    video_demuxer[type=flowunit, flowunit=video_demuxer, device=cpu, deviceid=0]
    video_decoder[type=flowunit, flowunit=video_decoder, device=rknpu, deviceid=0, pix_fmt="bgr"]
    image_resize[type=flowunit, flowunit=resize, device=rknpu, deviceid=0, image_width=512, image_height=288]
    ped_detection[type=flowunit, flowunit=yolox_infer, device=rknpu, deviceid=0, batch_size = 1]
    yolox_post[type=flowunit, flowunit=yolox_post, device=cpu, deviceid=0]
    object_tracker[type=flowunit, flowunit=object_tracker, device=cpu, deviceid=0]
    video_out[type=flowunit, flowunit=video_out, device=rknpu, deviceid=0]

    # 定义边，即功能间的数据传递关系
    input1:input -> data_source_parser:in_data
    data_source_parser:out_video_url -> video_demuxer:in_video_url
    video_demuxer:out_video_packet -> video_decoder:in_video_packet
    video_decoder:out_video_frame -> image_resize:in_image
    image_resize:out_image -> ped_detection:input
    ped_detection:output -> yolox_post:in_feat
    video_decoder:out_video_frame -> object_tracker:in_image
    yolox_post:out_data -> object_tracker:in_bbox
    object_tracker:out_image -> video_out:in_video_frame
}"""

该流程图对于某个视频流，经过视频解码、图像缩放、行人检测、目标跟踪与画图等一系列操作后，将结果保存下来。

工程的任务配置文件bin/mock_task.toml中设置了输入输出源，内容为：

# 任务输入配置，当前支持以下几种输入方式：
# 1. rtsp摄像头或rtsp视频流：type="rtsp", url="rtsp://xxx.xxx"
# 2. 设备自带摄像头或者USB摄像头：type="url"，url="${摄像头编号}" （需配合local_camera功能单元使用）
# 3. 本地视频文件：type="url"，url="${视频文件路径}" （请使用${HILENS_APP_ROOT}宏，表示当前应用的实际路径）
# 4. http服务：type="url", url="http://xxx.xxx"（指的是任务作为http服务启动，此处需填写对外暴露的http服务地址，需配合httpserver类的功能单元使用）
[input]
type = "url"
# url = "0"
url = "${HILENS_APP_ROOT}/data/ped_test.mp4"

# 任务输出配置，当前支持以下几种输出方式：
# 1. rtsp视频流：type="local", url="rtsp://xxx.xxx"
# 2. 本地屏幕：type="local", url="0:xxx" （设备需要接显示器，系统需要带桌面）
# 3. 本地视频文件：type="local"，url="${视频文件路径}" （请使用${HILENS_APP_ROOT}宏，表示当前应用的实际路径）
# 4. http服务：type="webhook", url="http://xxx.xxx"（指的是任务产生的数据上报给某个http服务，此处需填写上传的http服务地址）
[output]
type = "local"
# url = "0:pedestrian_tracking"
url = "${HILENS_APP_ROOT}/hilens_data_dir/tracking_result.mp4"

测试视频为data/ped_test.mp4，流程图使用这一视频进行人检测与跟踪，跟踪结果绘制后保存为hilens_data_dir/tracking_result.mp4文件。

4）运行应用

在工程路径下执行build_project.sh进行工程构建（以RK3568开发板版本为例）：

rock@rock-3a:~/███/modelbox/workspace/pedestrian_tracking$ ./build_project.sh

build success: you can run main.sh in ./bin folder

rock@rock-3a:~/███/modelbox/workspace/pedestrian_tracking$

执行bin/main.sh（Windows PC版本请使用bin\main.bat）运行应用，运行结束后在hilens_data_dir目录下生成了tracking_result.mp4文件，可以下载到PC端查看。