MI SED API

Version 2.07


1. 概述


1.1. 模块说明

SED(智能编码)模块主要提供智能编码通道的创建销毁开启和停止检测源图像计算结果并关联到指定的编码通道等功能。

智能编码的核心功能:

  • 先做图像的识别(识别图像中的物体有物体运动,或者识别图像中物体种类)

  • 再设置编码参数到venc module(当识别到物体有运动,可以控制venc 模块降低QP值,提高清晰度(sharpness),当识别图像是静止状态的话,控制venc模块增加QP值,减少传输代宽等)

大概检测算法流程是比较前后2张frame的差异来检测画面有无移动,提取出画面ROI和motion信息,给编码器设置ROI指定区域的QP指来编码。

检测算法有多种,下面会介绍我们平台使用到的有那些检测算法。

图1-1

通过SED 智能识别ROI,动态设置图像指定位置ROI的QP值 可以有效的降低代宽,同时保证图像的质量。

图1-2

1.1.1. 目前智能编码模块支持的图像检测算法

  1. E_MI_IVEOBJDETECT_ALGOPARAM 基于VDF/MD mode的运动物体检测,支持ROI 对像追踪

  2. E_MI_CNNOBJDETECT_ALGOPARAM 人非车检测可以检测的物体内容如下:bicycle,bus, car,motorbike, person)支持ROI 对像追踪

  3. E_MI_MOTIONDETECT_ALGOPARAM 基于IVE的动静检测,只支持for AVBR motion detection

以上三种检测算法可以同时支持,只需要创建不同的检测通道实例来实现即可。

1.1.2. sed的作用

负责使用Sigmastar or 第三方智能算法,识别ROI及motion信息。ROI 信息设置给VENC,motion信息用于自动调整ISP sharpness,etc

1.1.3. SED的数据来源

通过VPE获取yuv data来作智能检测(输入的yuv 分辨率是352*288)

1.1.4. Sed检测流程图如下

图1-3

1.1.5. Sed人非车检测功能支持的平台限制

人非车检测是基AI训练模型通过IPU来作检测,具体检测的准确度依赖于AI 模型训练的准确度

目前只有在Pudding平台才支持人非车检测,其他低阶平台目前还不支持。


1.2. 关键名词说明

  • VDF(Video detection function)

    MI_VDF实现MD,OD,VG视频通道的初始化,通道管理,视频检测结果的管理和通道销毁等功能。

  • IVE (Intelligent video coding)

    IVE模块负责图像数据的处理和计算,可以通过MI_IVE_Sad获取两张图片的SAD值,可以通过MI_IVE_Hist来执行直方图统计任务数据等做对笔,来做图像的动静检测

  • IPU(AI Process Unit)

    AI模型处理和计算单元,MI IPU模块实现了网络模型的快速推理功能,为每个通道独立配置网络模型,管理输入和输出数据的获取和释放。

  • ROI(Region Of Interest)

    ROI编码,感兴趣区域编码,启用ROI功能后,重要的或者移动的区域将会进行高质量无损编码,而对那些不移动,不被选择的区域降低其码率和图像质量,进行标准清晰度视频压缩,甚至是不传输这部分区域视频,从而最终达到节省网络带宽占用和视频存储空间,用户可以通过配置ROI区域,对该区域的图像Qp进行限制,从而实现图像中该区域的Qp与其他图像区域的差异化。系统支持H264和H265编码设置ROI,且提供16个ROI区域供用户同时使用。

    图1-4

    16个ROI区域可以互相叠加,且叠加时的优先级按照0~15的索引号依次提高,也即叠加区域的Qp最终判定只按最高优先级的区域处理。ROI区域可以配置绝对Qp与相对Qp两种模式。

    绝对Qp:ROI区域的Qp为用户设定的Qp值

    相对Qp:ROI区域的Qp为码率控制产生的Qp与用户设定的Qp偏移值的和

    以下示例编码图像采用FixQp模式,设置图像Qp为30,即图像所有宏块Qp值为30。ROI区域0设置为绝对Qp模式,Qp值为20,索引为0;ROI区域1设置为相对Qp模式,Qp为-15,索引为1。因为ROI区域0的index小于ROI区域1的index,所以在发生重叠的图像区域按高优先级的ROI区域1的Qp设置。除了重叠部分的ROI区域0的Qp值为20,区域1的Qp值为30-15=15。

    图1-5

  • Motion信息

    包含图像的SAD 信息。

  • QP (Quantization Parameter)

    QP值对应量化步长的序号,值越小,量化步长越小,量化的精度就越高,画质也就越好,编码出来的size也越大。

  • MD

    运动检测(Motion detect)用在拍摄影片中检测物体移动,被实际应用到安全监控等。

  • OD

    遮挡检测(Occlusion detection)功能用于检测接收到的影片是否出现遮挡,并输出遮挡检测結果。

  • VG

    虚拟线段用于检测是否有物体穿越设置的警报线。

    区域入侵用于检测是否有物体穿越设置的警报区域。

  • SAD

    即Sum of Absolute Differences,就是差的绝对值的和。此算法常用于图像块匹配,将每个像素对应数值之差的绝对值求和,据此评估两个图像块的相似度。可以看出这个算法很快速、但并不精确,通常用于多级处理的初步筛选。

    SAD值的取值范围为[0, 255],所有SAD值被分为16个区间:

    [0,10),[10,15),[15,20),[20,25),[25,30),[30,40),[40,50),[50,60),[60,70),[70,80), [80,90),[90,100),[100,120),[120,140),[140,160),[160, 255]。

    此处统计一帧中所有MB(8*8)落入以上区间的占总的MB数量的比例。

    值越大,表示画面越静止。

  • CBR(Constant Bit Rate)

    以恒定比特率方式进行编码,有Motion发生时,由于码率恒定,只能通过增大QP来减少码字大小,图像质量变差,当场景静止时,图像质量又变好,因此图像质量不稳定。这种算法优先考虑码率(带宽)。

  • VBR(Variable Bit Rate)

    动态比特率其码率可以随着图像的复杂程度的不同而变化,因此其编码效率比较高,Motion发生时,马赛克很少。码率控制算法根据图像内容确定使用的比特率,图像内容比较简单则分配较少的码率(似乎码字更合适),图像内容复杂则分配较多的码字,这样既保证了质量,又兼顾带宽限制。这种算法优先考虑图像质量。

  • CVBR(Constrained VariableBit Rate)

    VBR的一种改进方法。但是Constrained又体现在什么地方呢?这种算法对应的Maximum bitRate恒定或者Average BitRate恒定。这种方法的兼顾了以上两种方法的优点:在图像内容静止时,节省带宽,有Motion发生时,利用前期节省的带宽来尽可能的提高图像质量,达到同时兼顾带宽和图像质量的目的。这种方法通常会让用户输入最大码率和最小码率,静止时,码率稳定在最小码率,运动时,码率大于最小码率,但是又不超过最大码率。比较理想的模型如下:

    图1-6

  • ABR (Average Bit Rate)

    在一定的时间范围内达到设定的码率,但是局部码率峰值可以超过设定的码率,平均码率恒定。

  • AVBR(Adaptive Variable Bit Rate)

    AVBR(Adaptive Variable Bit Rate)可变比特率,即允许在码率统计时间内编码码率波动,从而保证编码图像质量平稳。码率控制内部会检测当前场景的运动静止状态,在运动时用较高码率编码,在静止时主动降低目标码率。以H.264编码为例,VENC模块提供用户可设置MaxBitrate,ChangePos 和MinStillPercent。MaxBitrate 表示运动场景下的最大码率,MaxBitrate*ChangePos*MinStillPercent表示静止情况下的最小码率。

    根据运动程度的不同目标码率会在最大码率和最小码率间调整。MaxQp,MinQp用于控制图像的质量范围,码率控制以QP钳位为最高优先级,超出MinQp,MaxQp范围内码率控制将失效。

  • IOU(Intersection Over Union)

    交并比(Intersection-over-Union,IoU),目标检测中使用的一个概念,是产生的候选框(candidate bound)与原标记框(ground truth bound)的交叠率,即它们的交集与并集的比值。(更祥细的内容请参考:http://172.19.30.188:8090/pages/viewpage.action?pageId=1216493

    图1-7

    最理想情况是完全重叠,即比值为1。

    图1-8


2. API 参考


2.1. 功能模块API

表2-1

API名 功能
MI_SED_CreateChn 创建SED通道
MI_SED_DestroyChn 销毁SED通道
MI_SED_StartDetector 开始检测指定的通道
MI_SED_StopDetector 停止检测
MI_SED_AttachToVencChn 关联到指定的编码通道
MI_SED_DetachFromVencChn 取消对指定编码通道的关联
MI_SED_GetRect 获取SED检测出的矩形框数据
MI_SED_SetDbgLevel 设置SED Module 的debug Level

2.2. MI_SED_CreateChn

  • 功能

    创建SED通道。

  • 语法

    MI_S32 MI_SED_CreateChn(MI_SED_CHN SedChn,MI_SED_DetectorAttr_t * pstAttr);
    
  • 形参

    表2-2

    参数名称 描述 输入/输出
    SedChn SED通道号
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
    pstAttr SED检测属性指针 输入
  • 返回值

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    库文件:libmi_sed.a


2.3. MI_SED_DestroyChn

  • 功能

    销毁SED通道。

  • 语法

    MI_S32 MI_SED_DestroyChn(MI_SED_CHN SedChn);
    
  • 形参

    表2-3

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
  • 返回值

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.4. MI_SED_StartDetector

  • 功能

    开始检测指定通道。

  • 语法

    MI_S32 MI_SED_StartDetector(MI_SED_CHN SedChn);
    
  • 参数

    表2-4

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.5. MI_SED_StopDetector

  • 功能

    停止检测指定通道。

  • 语法

    MI_S32 MI_SED_StopDetector(MI_SED_CHN SedChn);
    
  • 参数

    表2-5

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.6. MI_SED_AttachToVencChn

  • 描述

    关联到指定的编码通道

  • 语法

    MI_S32 MI_SED_AttachToChn(MI_SED_CHN SedChn,MI_SED_TARGET_CHN TargetChn);
    
  • 参数

    表2-6

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
    TargetChn 目标编码通道号。
    取值范围:[0,VENC_MAX_CHN_NUM)
    输入
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.7. MI_SED_DetachFromVencChn

  • 描述

    取消对指定编码通道的关联。

  • 语法

    MI_S32 MI_SED_DetachFromChn(MI_SED_CHN SedChn,MI_SED_TARGET_CHN TargetChn);
    
  • 参数

    表2-7

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
    TargetChn 目标编码通道号。
    取值范围:[0,VENC_MAX_CHN_NUM)
    输入
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.8. MI_SED_SetDbgLevel

  • 描述

    设置SED Module 的debug Level。

  • 语法

    MI_S32 MI_SED_SetDbgLevel(MI_DBG_LEVEL_e eLevel)
    
  • 参数

    表2-8

    参数名称 描述 输入/输出
    eLevel Debug Level值。
    取值范围:[0, MI_DBG_ALL]
    输入
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 依赖头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


2.9. MI_SED_GetRect

  • 描述

    获取SED检测出的矩形框数据。

  • 语法

    MI_S32 MI_SED_GetRect(MI_SED_CHN SedChn,MI_SED_RectInfo_t *pstRectInfo)
    
  • 参数

    表2-9

    参数名称 描述 输入/输出
    SedChn SED通道号。
    取值范围:[0, SED_MAX_CHN_NUM)
    输入
    pstRectInfo 矩阵 输出
  • 返回值

    • MI_OK成功。

    • 非MI_OK失败,参照错误码

  • 依赖

    • 头文件:mi_common.h、mi_sed.h

    • 库文件:libmi_sed.a


3. SED 数据类型


3.1. 数据类型定义

表3-1

数据类型 定义
SED_MAX_CHN_NUM 定义SED最大通道数
SED_MAX_ROI_NUM_PER_CHN 定义每路编码通道最多可设置ROI个数
SED_MAX_TARGET_CHN_NUM_PER_CHN 定义每个SED通道最多可同时作用编码通道数
SED_MAX_CUS_DEF_ALGOPARAM_NUM 定义SED最多支持的第三方算法数量
MI_SED_CHN 定义SED通道号
MI_SED_TARGET_CHN 定义SED通道映射对应的目标VENC编码通道号
MI_SED_AlgoType_e 定义SED算法属性
MI_SED_MdMbMode_e 定义MD宏块类型
MI_SED_InputAttr_t 定义SED输入端属性
MI_SED_Default_AlgoParam_t 定义SDK内置的算法参数
MI_SED_CusDef_AlgoParam_t 定义第三方算法的参数
MI_SED_AlgoAttr_t 定义SED算法属性
MI_SED_TargetAttr_t 定义最终生效的编码目标属性
MI_SED_DetectorAttr_t 定义SED检测属性

3.2. SED_MAX_CHN_NUM

  • 说明

    定义最大SED通道个数。

  • 定义

    #define SED_MAX_CHN_NUM (4)
    

3.3. SED_MAX_ROI_NUM_PER_CHN

  • 说明

    定义每路编码通道可以最多使用ROI的个数。

  • 定义

    #define SED_MAX_ROI_NUM_PER_CHN (16)
    

3.4. SED_MAX_TARGET_CHN_NUM_PER_CHN

  • 说明

    定义每个SED通道最多可同时作用编码通道数。

  • 定义

    #define SED_MAX_TARGET_CHN_NUM_PER_CHN (8)
    

3.5. SED_MAX_CUS_DEF_ALGOPARAM_NUM

  • 说明

    定义SED最多支持的第三方算法数量。

  • 定义

    #define SED_MAX_CUS_DEF_ALGOPARAM_NUM (10)
    

3.6. MI_SED_CHN

  • 说明

    定义SED通道号。

  • 定义

    typedef MI_S32 MI_SED_CHN;
    

3.7. MI_SED_TARGET_CHN

  • 说明

定义SED通道映射对应的目标VENC编码通道号。

  • 定义
    typedef MI_S32 MI_SED_TARGET_CHN;
    

3.8. MI_SED_AlgoType_e

  • 说明

    定义SED算法类型。

  • 定义

    typedef enum
    
    {
    
        E_MI_DEFAULT_ALGOPARAM = 0x0,
    
        E_MI_CUSDEF_ALGOPARAM = 0x1,
    
        E_MI_DEFAULT_ALGOPARAM_MAX,
    
    } MI_SED_AlgoType_e;
    
  • 成员

    表3-2

    成员名称 描述
    E_MI_DEFAULT_ALGOPARAM 使用SDK内置的算法
    E_MI_CUSDEF_ALGOPARAM 使用第三方的算法

3.9. MI_SED_MdMbMode_e

  • 说明

    定义MD宏块类型。

  • 定义

    typedef enum
    
    {
    
        E_MI_MDMB_MODE_MB_4x4 = 0x0,
    
        E_MI_MDMB_MODE_MB_8x8 = 0x1,
    
        E_MI_MDMB_MODE_MB_16x16 = 0x2,
    
        E_MI_MDMB_MODE_MAX
    
    } MI_SED_MdMbMode_e;
    
  • 成员

    表3-3

    成员名称 描述
    E_MI_MDMB_MODE_MB_4x4 使用4×4的宏块
    E_MI_MDMB_MODE_MB_8x8 使用8×8的宏块
    E_MI_MDMB_MODE_MB_16x16 使用16×16的宏块

3.10. MI_SED_InputAttr_t

  • 说明

    定义SED输入端属性。

  • 定义

    typedef struct MI_SED_InputAttr_s
    
    {
    
        MI_U32 u32Width;
    
        MI_U32 u32Height;
    
        MI_U32 u32FrameRateNum;
    
        MI_U32 u32FrameRateDen;
    
        MI_SYS_ChnPort_t stInputPort;
    
    } MI_SED_InputAttr_t;
    
  • 成员

    表3-4

    成员名称 描述
    u32Width 输入YUV的宽
    u32Height 输入YUV的高
    u32FrameRateNum 输入YUV的帧率分子部分
    u32FrameRateDen 输入YUV的帧率分母部分
    stInputPort 输入YUV的通道属性
  • 相关数据类型及接口

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.11. MI_SED_Default_AlgoParam_t

  • 说明

    定义SDK内置的算法参数。

  • 定义

    typedef struct MI_SED_Default_AlgoParam_s
    
    {
    
        MI_U32 u32VdfChn;
    
        MI_U8 u8Sensitivity;
    
        MI_SED_MdMbMode_e eMdMbMode;
    
    } MI_SED_Default_AlgoParam_t;
    
  • 成员

    表3-5

    成员名称 描述
    u32VdfChn SED内部使用的VDF通道号
    u8Sensitivity SED算法灵敏度
    eMdMbMode MD使用的宏块类型
  • 相关数据类型及接口

    MI_SED_CreateChn

    MI_SED_AlgoAttr_t


3.12. MI_SED_CusDef_AlgoParam_t

  • 说明

    定义第三方算法的参数。

  • 定义

    typedef struct MI_SED_CusDef_AlgoParam_s
    
    {
    
        MI_U32 u32ParamNum;
    
        MI_U32
        u32CusDefAlgoParam[SED_MAX_CUS_DEF_ALGOPARAM_NUM];
    
    } MI_SED_CusDef_AlgoParam_t;
    
  • 成员

    表3-6

    成员名称 描述
    u32ParamNum 有效参数数量
    u32CusDefAlgoParam 参数数组
  • 相关数据类型及接口
    

    MI_SED_CreateChn

    MI_SED_AlgoAttr_t


3.13. MI_SED_AlgoAttr_t

  • 说明

    定义SED算法属性。

  • 定义

    typedef struct MI_SED_CusAlgoAttr_s
    
    {
    
        MI_SED_AlgoType_e eType;
    
        union
    
        {
    
            MI_SED_Default_AlgoParam_t stDefaultAlgoParam;
    
            MI_SED_CusDef_AlgoParam_t stCusDefAlgoParam;
    
        };
    
    } MI_SED_AlgoAttr_t;
    
  • 成员

    表3-7

    成员名称 描述
    eType SED使用的算法类型
    stDefaultAlgoParam 默认算法参数
    stCusDefAlgoParam 第三方算法参数
  • 注意事项

    目前暂不支持第三方算法

  • 相关数据类型及接口

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.14. MI_SED_TargetAttr_t

  • 说明

    定义最终生效的编码目标属性。

  • 定义

    typedef struct MI_SED_TargetAttr_s

    {

    MI_S32 s32RltQp;
    

    } MI_SED_TargetAttr_t;

  • 成员

    表3-8

    成员名称 描述
    s32RltQp ROI相对Qp值
  • 相关数据类型及接口

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.15. MI_SED_DetectorAttr_t

  • 说明

    定义SED检测属性。

  • 定义

    typedef struct MI_SED_DetectorAttr_s
    
    {
    
        MI_SED_InputAttr_t stInputAttr;
    
        MI_SED_AlgoAttr_t stAlgoAttr;
    
        MI_SED_TargetAttr_t stTargetAttr;
    
    } MI_SED_DetectorAttr_t;
    
  • 成员

    表3-10

    成员名称 描述
    stInputAttr SED输入部分的属性
    stAlgoAttr SED算法相关的属性
    stTargetAttr SED最终生效的目标控制属性
  • 注意事项

  • 相关数据类型及接口

    MI_SED_CreateChn


4. 错误码

表4-1视频编码API错误码

错误代码 宏定义 描述
0x00000000 MI_SUCCESS success
0xA01E2002 MI_ERR_SED_INVALID_CHNID invalid channel ID
0xA01E2003 MI_ERR_SED_ILLEGAL_PARAM at lease one parameter is illegal
0xA01E2004 MI_ERR_SED_EXIST channel exists
0xA01E2005 MI_ERR_SED_UNEXIST channel unexist
0xA01E2006 MI_ERR_SED_NULL_PTR using a NULL point
0xA01E200c MI_ERR_SED_NOMEM failure caused by malloc memory
0xA01E2013 MI_ERR_SED_CHN_NOT_STARTED channel not start
0xA01E2014 MI_ERR_SED_CHN_NOT_STOPPED channel not stop
0xA01E2017 MI_ERR_SED_NOT_ENABLE Channel not enable

5. 构建和运行 Demo


5.1. Build Sed module and demo code

Build Demo code:

cd sdk/verify/mi_demo/alderaan$

make

5.2. Get sed bin & Demo Test bin

最后生成的mixer bin会在如下目录下:

sdk\verify\mi_demo\out\demo\app\prog_sed

参考如下:标红部分mac地址设置为你自己的分机号,ip地址请替换为自己的测试IP地址

ifconfig eth0 hw ether 00:70:08:00:00:01; ifconfig eth0 172.19.24.178 netmask
255.255.255.0;

route add default gw 172.19.24.254;

mount -t nfs -o nolock 172.19.24.221:/Home/gavin.yuan/debug /mnt;

export LD_LIBRARY_PATH=/mnt:\$LD_LIBRARY_PATH

cd /mnt

./prog_sed

5.3. Sed Demo code示例

具体参考如下:

http://hcgit04-master:9080/#/c/mstar/alkaid/sdk/+/68242/