onvif osd

几个月前写了篇介绍OSD坐标系统的文章：《》，但没有涉及接口，因为当时并不懂。后面发现网络上除了ONVIF官网外，基本没有什么资料介绍ONVIF的OSD功能。于是抽空去了解一下，形成此文。本文只对OSD部分字段做解释，详细具体的参考文后给出的官网地址。

与OSD有关的命令有：CreateOSD、DeleteOSD、GetOSDs、GetOSD、SetOSD、GetOSDOptions。下面根据实际编程经验使用的顺序逐一介绍。

GetOSDOptions：

获取当前相机具备的OSD选项。如字体大小范围、OSD总数、日期时间格式，等等。下面介绍其中的字段。
MaximumNumberOfOSDs，最大OSD叠加数量字段。如果支持不同类型的OSD，如Image、PlainText、DateAndTime等，要返回这些类型的最大数量。比如一般相机都有日期时间，则DateAndTime为1。
Type，叠加类型，如'Text'、'Image'、'Extended'。
PositionOption，叠加位置选项。固定的有左上，右上、左下、右下，即UpperLeft、UpperRight、LowerLeft、LowerRight。不过最多还是使用Custom自定义坐标。
TextOption，叠加文字选项。其中有类型、字体大小范围、字体颜色、字体透明程度、背景颜色。如果当前叠加的文字是日期时间，则类型为DateAndTime；如果是普通文字，则其类型为PlainText。
另外TextOption还有可选的Extension。比如某些型号相机会叠加相机通道(如"Camera 01")，则使用扩展字段表示当然的叠加文字是Channel。
ImageOption，图像选项，目前未研究，不表。
注：在实践中，还有字体颜色范围、颜色空间的字段，我见过的颜色空间一般用YUV，即颜色空间值为""。不过在ONVIF官网的WSDL中看不到，可能还没更新吧。

GetOSDs：

获取当前相机所有OSD项目。包括OSDtoken、叠加类型、字体大小、字体颜色、字体空间、背景颜色，等。
注意，使用这个接口时，必须传入视频源配置token(VideoSourceConfigurationToken)。每个视频源配置都有对应的OSD。比如相机有3路视频输出，则每路都可以叠加独立的字符，不互相干扰。返回值是一个vector，每个元素都是一个叠加的字符及其属性。

GetOSD：

基本同getOSDs。但传入参数是OSDtoken，而不是视频源配置token。

CreateOSD：

创建OSD，成功后会返回设备上标识的OSD token。——首次接触这个接口时，曾经一度纠结为什么我指定的token不生效，原来真正的token是由相机返回的。
创建的OSD属性参考上面所述。在实际编程中这个接口比较繁琐，因为要视频源配置token，还有字符内容、字符位置、字体大小、颜色，另外，其使用的结构体也要注意内存空间的分配，因为很多个字段都是指针，是没有空间的。
一般设备会有自己OSD的管理机制，比如固定的token：osd_0、osd_1、osd_2，等等，如果已经存在osd_0、osd_2时，则该命令创建时，会返回osd_1。

SetOSD：

设置OSD。与CreateOSD基本一样，但该命令使用的是相机已经存在的OSDtoken。因为这个命令描述为“修改OSD”更妥当一些。

DeleteOSD：

删除OSD，传入的OSDToken是相机已经存在的。

注：token是ONVIF中应用比较广的一个概念。可以理解为标识符。OSD模块有token，视频源配置有token，编码配置也有token，等等。接触ONVIF这么久，实然发现，ONVIF编程除了编码麻烦之外，需要理解其概念之外，也没有什么难搞的地方。

由于ONVIF可参考资料较少，文中难免有错漏之处，欢迎指正，一起学习，共同进步。

参考资料：