快速上手¶

本文介绍如何完成AI Express开发环境的搭建，以及完成内置人脸识别参考方案Demo的运行。

环境准备¶

AI Express主要是面向地平线芯片的边缘应用开发，相关环境准备包括开发机器环境准备和开发板准备。

1. 开发环境准备

安装cmake 2.8+以上版本
安装芯片交叉编译工具gcc-linaro-6.5.0-2018.12-x86_64_aarch64-linux-gnu,路径:/opt/

备注：如需要更新升级交叉编译工具链，请修改根目录CMakeLists.txt中配置如下：

set(CMAKE_C_COMPILER /opt/${工具链目录名}/bin/aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER /opt/${工具链目录名}/bin/aarch64-linux-gnu-g++)

2. 开发板准备

AI Express内置支持96board和2610面板机两种板卡.板卡支持固件版本为：

96board：disk_96board_CP_1.1.1_0929.img
2610：disk_HSP2610V-Linux-101-V12.tar.xz

备注：芯片板卡间区别主要影响了XProto::VIO数据输入模块,对XStream智能结构化模块无影响,参见@todo如何适配多版卡。

软件包获取¶

AI Express Github开源还在内部申请流程中，当前还是采用版本发布方式来向客户提供，请联系地平线商务或在地平线开发者社区进行留言申请。

软件包解析¶

AI Express软件发布包为一个tar.gz的压缩包，解压以后整个软件包结构如下：

1. 目录结构

├─deps
|  ├─bpu_predict
|  ├─gtest
|  ├─hobot
|  ├─hobotlog
|  ├─ipc_tracking
|  ├─jsoncpp
|  ├─libjpeg-turbo
|  ├─libyuv
|  ├─opencv
|  ├─protobuf
|  ├─x2_prebuilt
|
├─source
|  ├─common
|  |  ├─xproto
|  |  |  ├─framework
|  |  |  ├─msgtype
|  |  |  ├─plugins
|  |  ├─xstream
|  |  |  ├─framework
|  |  |  ├─imagetools
|  |  |  ├─methods
|  |  |  ├─vision_type
|  |  ├─third_party_build
|  ├─solutions
|  |  ├─solution_example
|  |  ├─face
|  |  ├─body
|  |  ├─vehicle
|  |  ├─face_body_multisource
|  |  ├─third_party_build
|
├─doc 
|  ├─doctrees
|  ├─html
|  |  ├─index.html
|
├─models
|  ├─faceMultitask
|  ├─personMultitask
|  ├─vehicleSolutionModels
|  ├─faceID
|
├─README.md
├─build.sh
├─CMakeLists.txt
├─run.sh
├─deploy.sh

2. deps (二进制形式)

gtest：第三方开源库，google test框架;
jsoncpp：第三方开源库，用于json解析;
libjpeg-turbo：第三方开源库，用于jpeg格式图像处理;
libyuv：第三方开源库，用于yuv格式图像处理;
opencv：第三方开源库，主要用于计算机视觉处理;
protobuf：第三方开源库，多平台或者多模块间消息交互协议;
x2_prebuilt：内部库，x2平台底层系统库或者hbdk基础库等;
bpu_predict：内部库，地平线bpu预测驱动库;
hobotsdk：内部库，另一种基于数据流的编程框架;
hobotlog：内部库，日志系统，支持不同的优先级控制等特性;
ipc_tracking:内部库，基于IOU的多目标跟踪（MOT）策略库;

3. source (源代码形式)

common: 为整个基础框架和内置算法模块和功能组件。
common/xstream-framework: 一套基于数据流的编程框架;
common/xstream-imagetools: XStream提供的Image处理工具;
common/xstream-methods: 基于xstream-framework开发、沉淀的模型处理或者算法策略模块;
common/xstream-vision_type: vision type是AI视觉方案常用数据结构定义，如BBox， landmark、PyramidImage;
common/xproto_framework: 消息订阅与分发的编程框架，每个基础组件以插件（plugin）的形式管理;
common/xproto_msgtype: 定义了xproto基础消息类型;
common/xproto_plugins: 基于XProto框架开发、沉淀的一系列基础组件，如VIO处理模块（VioPlugin）、智能处理模块(SmartPlugin)等，基础组件以插件的形式管理;
solutions: 基于地平线中间件构建的不同场景的解决方案池;
solutions/solution_example: solution开发的样例;
solutions/solution_face：人脸抓拍/识别解决方案案例;
solutions/solution_body：人体骨骼检测解决方案案例;
solutions/solution_vehicle：车辆相关解决方案案例;
solutions/solution_face_body_multisource：AI盒子场景参考方案案例:

4. doc (html格式文档)

doc/html/index.html html格式文档入口,请用浏览器打开。

5. models (模型)

faceMultitask: source/solution/face所用到的模型: 人脸多任务模型,可实现人脸检测,人脸抓拍,人脸识别等。
personMultitask: source/solution/body所用到的模型: 人体多任务模型。
vehicleSolutionModels: source/solution/vehicle所用到的模型: 车辆相关模型。
faceID: source/solution/face所用到的模型: 人脸特征提取模型。

6. README.md (Markdown格式README文档)

工程简要介绍README文档

7. build.sh (bash shell脚本文件)

执行 build.sh, 可以编译整个开发环境。
如果没有权限，请使用chmod +x ./build.sh赋予执行权限。
build.sh 默认使用bash执行，如果您的环境中bash不是默认shell, 请使用sudo bash build.sh执行脚本。

6. CMakeLists.txt (cmake文件)

整个工程使用cmake编译，请安装cmake 2.8+以上版本。
build.sh中会调用cmake根据CMakeLists.txt执行编译。

编译部署¶

AI Express发布包采用源码发布，编译主要是针对${发布包}/source目录的基础框架和内置的solutions进行编译。用户也可以参考solutions/solution_example实现方式，完成自定义solutionn开发与编译。

编译：直接运行sh build.sh，完成整个开发包的编译，编译后的中间结果输出在${发布包}/build目录下。
打包：直接运行sh deploy.sh,针对编译后的内容进行打包发布，打包发布在${发布包}/deploy目录下。
部署：将deploy发布包进行压缩，传递到开发板文件系统中，并进行解压完成部署。
运行：deploy中run.sh可以在96board和2610板卡上运行内置solution。 usage: sh run.sh [ face | face_recog | body | vehicle | face_body_multisource ] [ 96board | 2610 ]"

实例解析¶

这里采用人脸抓拍实例进行实例解析。deploy/face_solution实现了一个标准的人脸抓拍任务流程。

它支持对视频图片帧进行人脸框，人脸关键点，人脸姿态检测，并对检测到人进行跟踪，打分与抓拍，其中涉及到算法和策略模块包括FasterRCNNMethod,MOTMethod,GradingMethod和SnapShotMethod，对应的XStream关系图如下：

构建该solution的workflow配置文件deploy/face_solution/configs/face_solution.json内容如下：

{
    "inputs":[
        "image"
    ],
    "outputs":[
        "image",
        "face_bbox_list",
        "snap_list"
    ],
    "workflow":[
        {
            "thread_count":1,
            "method_type":"FasterRCNNMethod",
            "unique_name":"multi_task",
            "inputs":[
                "image"
            ],
            "outputs":[
                "rgb_face_box",
                "rgb_lmk",
                "rgb_pose"
            ],
            "method_config_file":"face_pose_lmk.json"
        },
        {
            "method_type":"MOTMethod",
            "thread_count":1,
            "unique_name":"face_mot",
            "inputs":[
                "rgb_face_box"
            ],
            "outputs":[
                "face_bbox_list",
                "rgb_face_disappeared_track_id_list"
            ],
            "method_config_file":"iou_method_param.json"
        },
        {
            "method_type":"GradingMethod",
            "unique_name":"grading",
            "inputs":[
                "face_bbox_list",
                "rgb_pose",
                "rgb_lmk"
            ],
            "outputs":[
                "select_score_list"
            ],
            "method_config_file":"grading.json"
        },
        {
            "method_type":"SnapShotMethod",
            "unique_name":"snapshot",
            "inputs":[
                "image",
                "face_bbox_list",
                "select_score_list",
                "rgb_face_disappeared_track_id_list",
                "rgb_pose",
                "rgb_lmk",
                "face_bbox_list"
            ],
            "outputs":[
                "snap_list"
            ],
            "method_config_file":"snapshot.json"
        }
    ]
}

其中：

inputs: image表示整个workflow外部输入只有图片帧。
outputs: 表示整个workflow输出，输出原始图片帧，人脸结构化数据以及抓拍图。
workflow：通过复用XStream内部四个Method来构建上述数据流，每个Method可以指定input，output，thread_count，以及Method相关模型配置信息。

对于上述由XStream构建的Workflow，可以通过XProto进行调用，并在芯片上进行运行，调用关键代码deploy/face_solution/main.cpp如下：

    auto vio_plg = std::make_shared<VioPlugin>(vio_config_file);
    auto smart_plg = std::make_shared<SmartPlugin>(smart_config_file);
    vio_plg->Init();
    smart_plg->Init();
    vio_plg->Start();
    smart_plg->Start();

XProto::VioPlugin为芯片板卡视频流输入模块，通过Init/Start以后，会持续在XProto消息总线中注入视频图片帧数据，并被XProto::SmartPlugin消费和结构化处理，其中smart_config_file参数即为上述的workflow配置文件。

在板卡上运行sh run.sh face，输出结果如下：

root@X2_96BOARD:/userdata/deploy# sh run.sh face 96boards
(xpluginasync.cpp:58): XPluginAsync() cons
(xpluginasync.cpp:58): XPluginAsync() cons
(smartplugin.cpp:184): smart config file:./face_solution/configs/face_solution.json
....
(convert.cpp:35): Input Frame ID = 0, Timestamp = 21291
(convert.cpp:51): input name:image
(convert.cpp:35): Input Frame ID = 1, Timestamp = 21292
(convert.cpp:51): input name:image
(convert.cpp:35): Input Frame ID = 2, Timestamp = 21293
(convert.cpp:51): input name:image
(vioproduce.cpp:423): Vio TimeStamp: 21294
(vioproduce.cpp:466): Push Drop message!!!
(MOTMethod.cpp:73): MOTMethod::DoProcess
................................
................开始处理图片帧数据