MI SED API

REVISION HISTORY¶

Revision No.	Description	Date
3.0	Initial release	06/16/2021

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. 图像检测算法¶

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

E_MI_IVEOBJDETECT_ALGOPARAM 基于VDF/MD mode的运动物体检测,支持ROI 对像追踪
E_MI_CNNOBJDETECT_ALGOPARAM 人非车检测可以检测的物体内容如下：bicycle，bus， car，motorbike， person）支持ROI 对像追踪
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的数据来源¶

通过SCL获取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检测属性指针输入
返回值
- 0成功。
- 非0失败，参照错误码。
依赖
- 头文件：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) 输入
返回值
- 0成功。
- 非0失败，参照错误码。
依赖
- 头文件：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 (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;

成员

成员名称 描述

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。

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

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

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

成员名称	描述
u32VdfChn	SED内部使用的VDF通道号。
u8Sensitivity	SED算法灵敏度。

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

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

成员名称	描述
u32RectCount	矩形框的数量
stRect	矩形框的信息