前言

概述

本文档为使用IVS进行_识别_分析方案开发的程序员而写，目的是供您在开发过程中查阅IVS支持的各种参考信息，包括API、头文件、错误码等。

产品版本

与本文档相对应的产品版本如下。

产品名称

产品版本

SS928

V100

SS927

V100

读者对象

本文档（本指南）主要适用于以下工程师：

  • 技术支持工程师

  • 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号

说明

表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。

表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。

表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。

用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。

“须知”不涉及人身伤害。

对正文中重点信息的补充说明。

“说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本

发布日期

修改说明

00B01

2025-09-15

第1次临时版本发布

概述

概述

IVS（Intelligent Video Surveillance）比IVE（Intelligent Video Engine，识别加速引擎）更高层次的识别视频采集应用API。用户基于IVS可以快速开发出相关识别应用。当前IVS支持的识别应用有：MD（Motion Detection，移动侦测）。

MD

功能描述

移动侦测

移动侦测通过检测视频的亮度变化，侦测视频的运动状态，得出视频侦测分析结果。

基本概念

  • MD 算法

    MD 算法包含帧差法（MD_ALG_MODE_REF）和背景法（MD_ALG_MODE_BG）两种。

    • 帧差法（MD_ALG_MODE_REF）

      直接以用户指定的图像为参考帧，得出视频侦测分析结果的算法，称为帧差法。

    • 背景法（MD_ALG_MODE_BG）

      在MD 处理的过程中，将产生当前视频的背景图像。然后以背景图像为参考帧，得出视频侦测分析结果的算法，称为背景法。

  • 背景更新权重

    当MD 算法选择为背景法时，每次MD 处理都会产生静止部分图像，这部分图像和背景会作一次像素值叠加，新背景 = （静止部分图像的叠加权重x×静止部分图像 + 动态部分图像的叠加权重y× 旧背景）>> 16。

须知： 如果是使用64位操作系统，需要使用到的MMZ地址必须是在一个4GB空间内，否则会出现异常。

API 参考

MD API提供了初始化、退出、获取句柄、释放句柄、获取背景和侦测处理基本接口。

该功能模块提供以下API：

  • ss_ivs_md_init：初始化。

  • ss_ivs_md_exit：退出。

  • ss_ivs_md_create_chn：创建MD通道。

  • ss_ivs_md_destroy_chn：销毁MD通道。

  • ss_ivs_md_set_chn_attr：设置MD通道属性。

  • ss_ivs_md_get_chn_attr：获取MD通道属性。

  • ss_ivs_md_get_bg：获取背景。

  • ss_ivs_md_proc：侦测处理。

ss_ivs_md_init

【描述】

移动侦测初始化。

【语法】

td_s32 ss_ivs_md_init(td_void)；

【参数】

无。

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 调用MD其他接口前必须先调用此接口进行初始化，而且只需调用一次即可，否则返回错误。

  • 该接口必须和ss_ivs_md_exit配套使用。

【举例】

无。

【相关主题】

ss_ivs_md_exit

ss_ivs_md_exit

【描述】

移动侦测退出。

【语法】

td_s32 ss_ivs_md_exit(td_void);

【参数】

无。

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

必须先调用ss_ivs_md_init初始化才能调用此接口退出，否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_init

ss_ivs_md_create_chn

【描述】

创建MD通道。

【语法】

td_s32 ss_ivs_md_create_chn(ot_md_chn md_chn, ot_md_attr *md_attr);

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

md_attr

通道信息指针。

不能为空。

输入

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

必须先调用ss_ivs_md_init初始化，否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_destroy_chn

【描述】

销毁MD通道。

【语法】

td_s32 ss_ivs_md_destroy_chn(ot_md_chn md_chn);

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 必须先调用ss_ivs_md_init初始化，否则返回错误。

  • md_chn必须为ss_ivs_md_create_chn已创建的通道号,否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_set_chn_attr

【描述】

设置MD通道属性。

【语法】

td_s32 ss_ivs_md_set_chn_attr(ot_md_chn md_chn, ot_md_attr *md_attr);

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

md_attr

通道信息指针。

不能为空

输入

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 必须先调用ss_ivs_md_init初始化，否则返回错误。

  • md_chn必须为ss_ivs_md_create_chn已创建的通道号,否则返回错误。

  • 通道静态属性(alg_mode、sad_mode、width、height)不能更改，必须与创建通道时相等，否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_get_chn_attr

【描述】

获取MD通道属性。

【语法】

td_s32 ss_ivs_md_get_chn_attr(ot_md_chn md_chn, ot_md_attr *md_attr);

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

md_attr

通道信息指针

不能为空

输出

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 必须先调用ss_ivs_md_init初始化，否则返回错误。

  • md_chn必须为ss_ivs_md_create_chn已创建的通道号,否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_get_bg

【描述】

获取移动侦测背景。

【语法】

td_s32 ss_ivs_md_get_bg(ot_md_chn md_chn, ot_svp_dst_img *bg);

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

bg

背景图像指针；不能为空。

详细定义请参见《IVE API参考》的3.1章节

输出

参数名称

支持图像类型

地址对齐

分辨率

bg

OT_SVP_IMG_TYPE_U8C1

16 byte

64x64～1920x1080

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 必须先调用ss_ivs_md_init初始化，否则返回错误。

  • md_chn必须为ss_ivs_md_create_chn已创建的通道号，否则返回错误。

  • 只有背景法时，才能获取背景数据，否则返回错误。

【举例】

无。

【相关主题】

ss_ivs_md_proc

【描述】

移动侦测处理。

【语法】

td_s32 ss_ivs_md_proc(ot_md_chn md_chn, ot_svp_src_img *cur, ot_svp_src_img *ref, ot_svp_dst_img *sad, ot_svp_dst_mem_info *blob)；

【参数】

参数名称

描述

输入/输出

md_chn

通道号，有效范围：[0, 63]

输入

cur

当前帧图像指针；不能为空。

详细定义请参见《IVE API参考》的3.1章节。

输入

ref

参考帧图像指针；不能为空。

详细定义请参见《IVE API参考》的3.1章节。

输入

sad

Sad指针。

根据md_attr-> sad_out_ctrl，若需要输出则不能为空。

详细定义请参见《IVE API参考》的3.1章节。

输出

blob

区域信息指针。

不能为空。

详细定义请参见《SVPx.0 API参考》的1.4章节。

输出

参数名称

支持图像类型

地址对齐

分辨率

cur

OT_SVP_IMG_TYPE_U8C1

16 byte

64x64～1920x1080

ref

OT_SVP_IMG_TYPE_U8C1

16 byte

64x64～1920x1080

sad

OT_SVP_IMG_TYPE_U8C1/ OT_SVP_IMG_TYPE_U16C1

16byte

根据md_attr->sad_mode，对应 4x4、8x8、16x16 分块模式，高、宽分别为cur的1/4、1/8、1/16。

blob

─

16 byte

─

【返回值】

返回值

描述

0

成功。

非0

失败，参见错误码。

【需求】

  • 头文件：ot_common_svp.h、ot_common_md.h、ss_ivs_md.h

  • 库文件：libss_md.a

【注意】

  • 必须先调用ss_ivs_md_init初始化，否则返回错误。

  • md_chn必须为ss_ivs_md_create_chn已创建的通道号，否则返回错误。

  • 最多输出区域信息个数为254，区域信息请参见《IVE API参考》第3章节数据类型中的ot_ive_ccblob。ot_ive_ccblob的成员info中的cur_area_threshold是分块后的面积阈值信息。在这里输出的连通区域信息是连续储存。

  • 在同一个线程中，完成初始化和通道创建之后，对同一通道只调用一次ss_ivs_md_proc接口。

【举例】

无。

【相关主题】

MD数据类型

ot_md_alg_mode

【说明】

定义MD算法模式。

【定义】

typedef enum {
    OT_MD_ALG_MODE_BG	= 0x0,/*Base on background img*/
    OT_MD_ALG_MODE_REF	= 0x1,/*Base on reference img*/
    OT_MD_ALG_MODE_BUTT
}ot_md_alg_mode;

【成员】

成员名称

描述

OT_MD_ALG_MODE_BG

背景法。

OT_MD_ALG_MODE_REF

帧差法。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_md_attr

【说明】

定义MD通道属性。

【定义】

typedef struct {
         ot_md_alg_mode                alg_mode;            /*Md algorithm mode*/
         ot_ive_sad_mode               sad_mode;            /*Sad mode*/
         ot_ive_sad_out_ctrl           sad_out_ctrl;        /*Sad output ctrl*/
         td_u32                        width;               /*Img width*/
         td_u32                        height;              /*Img height*/
         td_u16                        sad_threshold;       /*Sad thresh*/
         ot_ive_ccl_ctrl               ccl_ctrl;            /*Ccl ctrl*/
         ot_ive_add_ctrl               add_ctrl;            /*Add ctrl*/
}ot_md_attr

【成员】

成员名称

描述

alg_mode

算法模式。

sad_mode

Sad模式，详细定义请参见《IVE API参考》的3.3章节。

sad_out_ctrl

Sad输出控制，详细定义请参见《IVE API参考》的3.3章节。

只支持OT_IVE_SAD_OUT_CTRL_16BIT_BOTH、OT_IVE_SAD_OUT_CTRL_8BIT_BOTH、OT_IVE_SAD_OUT_CTRL_THRESHOLD输出控制。

width

图像宽，必须为宏块宽的偶数倍，范围：[64, 1920]

height

图像高，必须为宏块高的偶数倍，范围：[64, 1080]

sad_threshold

Sad阈值。

取值依赖sad_out_ctrl：

  1. OT_IVE_SAD_OUT_CTRL_8BIT_BOTH，取值[0, 255]
  2. OT_IVE_SAD_OUT_CTRL_16BIT_BOTH和OT_IVE_SAD_OUT_CTRL_THRESHOLD，取值[0, 65535]

ccl_ctrl

Ccl控制参数，详细定义请参见《IVE API参考》的3.3章节。Ccl控制参数成员信息都是针对分块后的图。

add_ctrl

Add控制参数，详细定义请参见《IVE API参考》的3.3章节。

【注意事项】

无。

【相关数据类型及接口】

无。

错误码

IVS的错误码与IVE的错误码大部分共用，IVS 错误码表所示中前面部分与《IVE API参考》中相同，其他特殊的列在表后面。

表 1 IVS 错误码

错误代码

宏定义

描述

0xa01d8001

OT_ERR_IVE_INVALID_DEV_ID

设备ID超出合法范围

0xa01d8003

OT_ERR_IVE_INVALID_CHN_ID

通道组号错误或无效区域句柄

0xa01d8007

OT_ERR_IVE_ILLEGAL_PARAM

参数超出合法范围

0xa01d8008

OT_ERR_IVE_EXIST

重复创建已存在的设备、通道或资源

0xa01d8009

OT_ERR_IVE_UNEXIST

试图使用或者销毁不存在的设备、通道或者资源

0xa01d800a

OT_ERR_IVE_NULL_PTR

函数参数中有空指针

0xa01d800b

OT_ERR_IVE_NOT_CFG

模块没有配置

0xa01d800c

OT_ERR_IVE_NOT_SUPPORT

不支持的参数或者功能

0xa01d800d

OT_ERR_IVE_NOT_PERM

该操作不允许，如试图修改静态配置参数

0xa01d8014

OT_ERR_IVE_NO_MEM

分配内存失败，如系统内存不足

0xa01d8015

OT_ERR_IVE_NO_BUF

分配缓存失败，如申请的图像缓冲区太大

0xa01d8016

OT_ERR_IVE_BUF_EMPTY

缓冲区中无图像

0xa01d8017

OT_ERR_IVE_BUF_FULL

缓冲区中图像满

0xa01d8018

OT_ERR_IVE_NOT_READY

系统没有初始化或没有加载相应模块

0xa01d8021

OT_ERR_IVE_BAD_ADDR

地址非法

0xa01d8022

OT_ERR_IVE_BUSY

系统忙

0xa01d8040

OT_ERR_IVE_SYS_TIMEOUT

IVE系统超时

0xa01d8041

OT_ERR_IVE_QUERY_TIMEOUT

Query查询超时

0xa01d8042

OT_ERR_IVE_BUS_ERR

总线错误

0xa01d8043

OT_ERR_IVE_OPEN_FILE

打开文件失败

0xa01d8044

OT_ERR_IVE_READ_FILE

读文件失败

0xa0308003

OT_ERR_ODT_INVALID_CHN_ID

ODT通道组号错误或无效区域句柄

0xa0308008

OT_ERR_ODT_EXIST

重复创建已存在的设备、通道或资源

0xa0308009

OT_ERR_ODT_UNEXIST

试图使用或者销毁不存在的设备、通道或者资源

0xa030800d

OT_ERR_ODT_NOT_PERM

该操作不允许，如试图修改静态配置参数

0xa0308018

OT_ERR_ODT_NOT_READY

ODT没有初始化

0xa0308022

OT_ERR_ODT_BUSY

ODT系统忙

Proc调试信息

概述

调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。

【文件目录】

/proc/umap

【信息查看方法】

  • 在控制台上可以使用cat命令查看信息，cat /proc/umap/md 可以查看MD的proc信息；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/md ./，将文件拷贝到当前目录。

  • 在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。

说明： 参数在描述时有以下2种情况需要注意：

  • 取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。

  • 取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义。

MD Proc信息说明

【调试信息】

~ # cat /proc/umap/md
[MD] Version: [Vx.x.x.x B0xx Release], Build Time[Feb 20 2020, 16:42:49]

---------------------------md chn attr-----------------------------------
no.    w    h   alg   sad_mode  sad_out_ctrl   sad_thr    ccl_mode  ccl_init_thr   
0     720   576   0         0           0         200         1      16 
ccl_step    xwt      ywt        frm_rate  cost_tm_per_frm
4          32768     32768          0          2625

【调试信息分析】

记录MD的工作状态信息。

【参数说明】

参数

描述

md chn attr

通道属性

no.

通道号。

w

通道宽度（单位：像素）。

h

通道高度（单位：像素）。

alg

工作算法。

0：背景法；

1：帧差法。

sad_mode

Sad模式。

0：4x4宏块；

1：8x8 宏块；

2：16x16 宏块。

sad_out_ctrl

Sad输出控制。

0：OT_IVE_SAD_OUT_CTRL_16BIT_BOTH；

1：OT_IVE_SAD_OUT_CTRL_8BIT_BOTH；

4：OT_IVE_SAD_OUT_CTRL_THRESHOLD。

sad_thr

Sad阈值。

ccl_mode

Ccl 模式。

0：4连通；

1：8连通。

ccl_init_thr

Ccl初始阈值。

ccl_step

Ccl步长。

xwt

背景法更新X权重。

ywt

背景法更新Y权重。

frm_rate

帧率。

cost_tm_per_frm

每帧耗时(单位us)。

注意：帧率及每帧耗时，每10s统计一次。