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. 图像检测算法¶
目前智能编码模块支持的图像检测算法:
-
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的数据来源¶
通过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检测属性指针 输入 -
返回值
-
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 (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的通道属性 -
相关数据类型及接口
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算法灵敏度。 -
相关数据类型及接口
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文件的路径和文件名。 -
相关数据类型及接口
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_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 动静识别算法参数 -
注意事项
目前暂不支持第三方算法
-
相关数据类型及接口
3.16. MI_SED_TargetAttr_t¶
-
说明
定义最终生效的编码目标属性。
-
定义
typedef struct MI_SED_TargetAttr_s
{
MI_S32 s32RltQp;
} MI_SED_TargetAttr_t;
-
成员
成员名称 描述 s32RltQp ROI相对Qp值 -
相关数据类型及接口
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最终生效的目标控制属性 -
相关数据类型及接口
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
。