MI SED API


1. 概述


1.1. 模块说明

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

智能编码的核心功能:

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

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

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

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

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

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.1.5. Sed人非车检测功能支持的平台限制

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

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


1.2. 关键词说明

  • VDF(Video Detection Framework)

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

  • IVE (Intelligent Video Engine)

    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区域供用户同时使用。

    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。

  • 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发生时,利用前期节省的带宽来尽可能的提高图像质量,达到同时兼顾带宽和图像质量的目的。这种方法通常会让用户输入最大码率和最小码率,静止时,码率稳定在最小码率,运动时,码率大于最小码率,但是又不超过最大码率。

  • ABR (Average Bit Rate)

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

  • AVBR(Adaptive Variable Bit Rate)

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

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

  • IOU(Intersection Over Union)

    交并比(IoU),目标检测中使用的一个概念,是产生的候选框(candidate bound)与原标记框(ground truth bound)的交叠率,即它们的交集与并集的比值。

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


2. API 参考


2.1. 功能模块API

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

2.2. MI_SED_CreateChn

  • 功能

    创建SED通道。

  • 语法

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

    参数名称 描述 输入/输出
    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);
    
  • 形参

    参数名称 描述 输入/输出
    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);
    
  • 参数

    参数名称 描述 输入/输出
    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);
    
  • 参数

    参数名称 描述 输入/输出
    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);
    
  • 参数

    参数名称 描述 输入/输出
    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);
    
  • 参数

    参数名称 描述 输入/输出
    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)
    
  • 参数

    参数名称 描述 输入/输出
    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)
    
  • 参数

    参数名称 描述 输入/输出
    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. 数据类型定义

数据类型 定义
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_InputAttr_t 定义SED输入端属性
MI_SED_IveObjDetect_Algo_t 定义基于IVE的算法参数
MI_SED_CNNObjDetect_Algo_t 定义神经网络算法的参数
MI_SED_MontionObjDetect_Algo_t 动静识别算法的参数
MI_SED_Rect_t 定义SED算法获取的矩阵
MI_SED_RectInfo_t SED检测出的所有矩形框
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 (64)
    

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;
    
  • 成员

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

3.9. 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;
    
  • 成员

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

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.10. MI_SED_IveObjDetect_Algo_t

  • 说明

    定义基于IVE的算法参数。

  • 定义

    typedef struct MI_SED_IveObjDetect_Algo_s
    {
        MI_U32          u32VdfChn;
        MI_U8           u8Sensitivity;
    } MI_SED_IveObjDetect_Algo_t;
    
  • 成员

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

    MI_SED_CreateChn

    MI_SED_AlgoAttr_t


3.11. MI_SED_CNNObjDetect_Algo_t

  • 说明

    定义神经网络算法的参数。

  • 定义

    typedef struct MI_SED_CNNObjDetect_Algo_s
    
    {
    
        MI_U32 u32MaxVariableBufSize;
    
        MI_U32 u32IPUChnId;
    
        MI_U8 *u8FwImagePath;
    
        MI_U8 *u8ModelImagePath;
    
    } MI_SED_CNNObjDetect_Algo_t;
    
  • 成员

    成员名称 描述
    u32MaxVariableBufSize IPU算法需要的最大内存。
    u32IPUChnId IPU的通道号。
    u8FwImagePath 指定IPU需要加载的fireware文件的路径和文件名。
    u8ModelImagePath 指定IPU 需要加载的AI Model文件的路径和文件名。
  • 相关数据类型及接口
    

    MI_SED_CreateChn

    MI_SED_AlgoAttr_t


3.12. MI_SED_MontionObjDetect_Algo_t

  • 说明

    动静识别算法的参数。

  • 定义

    typedef struct MI_SED_MotionObjDetect_Algo_s
    
    {
    
        MI_IVE_HANDLE iveHandle;
    
    }MI_SED_MotionObjDetect_Algo_t;
    
  • 成员

    成员名称 描述
    iveHandle IVE 的handle 目前默认设置为0

3.13. MI_SED_Rect_t

  • 说明

    定义SED算法获取的矩阵。

  • 定义

    typedef struct MI_SED_Rect_s
    
    {
    
        MI_U32 u32Left;
    
        MI_U32 u32Top;
    
        MI_U32 u32Width;
    
        MI_U32 u32Height;
    
    } MI_SED_Rect_t;
    
  • 成员

    成员名称 描述
    u32Left 矩形框左上角的列坐标
    u32Top 矩形框左上角的行坐标
    u32Width 矩形框的宽
    u32Height 矩形框的高

3.14. MI_SED_RectInfo_t

  • 说明

    SED检测出的所有矩形框。

  • 定义

    typedef struct MI_SED_RectInfo_s
    
    {
    
        MI_U32 u32RectCount;
    
        MI_SED_Rect_t stRect[SED_MAX_ROI_NUM_PER_CHN];
    
    } MI_SED_RectInfo_t;
    
  • 成员

    成员名称 描述
    u32RectCount 矩形框的数量
    stRect 矩形框的信息
  • 相关数据类型及接口

    MI_SED_Rect_t

    MI_SED_GetRect


3.15. MI_SED_AlgoAttr_t

  • 说明

    定义SED算法属性。

  • 定义

    typedef struct MI_SED_CusAlgoAttr_ s
    
    {
    
        MI_SED_AlgoType_e eType;
    
        Union
    
        {
    
            MI_SED_IveObjDetect_Algo_t stIveObjDetectAlgo;
    
            MI_SED_CNNObjDetect_Algo_t stCNNObjDetectAlgo;
    
            MI_SED_MotionObjDetect_Algo_t stMotionObjDetectAlgo;
    
        };
    
    } MI_SED_AlgoAttr_t;
    
  • 成员

    成员名称 描述
    eType SED使用的算法类型
    stIveObjDetectAlgo IVE算法参数
    stCNNObjDetectAlgo 神经网络物体识别算法参数
    stMotionObjDetectAlgo 动静识别算法参数
  • 注意事项

    目前暂不支持第三方算法

  • 相关数据类型及接口

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.16. MI_SED_TargetAttr_t

  • 说明

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

  • 定义

    typedef struct MI_SED_TargetAttr_s

    {

    MI_S32 s32RltQp;
    

    } MI_SED_TargetAttr_t;

  • 成员

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

    MI_SED_CreateChn

    MI_SED_DetectorAttr_t


3.17. 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;
    
  • 成员

    成员名称 描述
    stInputAttr SED输入部分的属性
    stAlgoAttr SED算法相关的属性
    stTargetAttr SED最终生效的目标控制属性
  • 相关数据类型及接口

    MI_SED_CreateChn


4. 错误码

错误代码 宏定义 描述
0x00000000 MI_SUCCESS 成功
0xA01E2002 MI_ERR_SED_INVALID_CHNID 通道号无效
0xA01E2003 MI_ERR_SED_ILLEGAL_PARAM 参数不合法
0xA01E2004 MI_ERR_SED_EXIST 通道已经创建
0xA01E2005 MI_ERR_SED_UNEXIST 通道未创建
0xA01E2006 MI_ERR_SED_NULL_PTR 空指针
0xA01E200c MI_ERR_SED_NOMEM 分配内存失败
0xA01E2013 MI_ERR_SED_CHN_NOT_STARTED 通道未开启
0xA01E2014 MI_ERR_SED_CHN_NOT_STOPPED 通道未停止
0xA01E2017 MI_ERR_SED_NOT_ENABLE 通道未使能

5. Demo

编译Demo code:

cd sdk/verify/mi_demo/alderaan$
make

最后生成的可执行程序在sdk\verify\mi_demo\out\demo\app\prog_sed