概述

qtivoverlay 元素是一个硬件加速的就地绘制与位块传输(blitting)插件,旨在将可视化叠加对象直接渲染到传入的视频帧(如 YUV 或 RGB 缓冲区)之上。通过将叠加内容直接合成到帧数据上,处理后的视频可以以极小的额外开销显示在屏幕上或转发用于编码。这使其非常适合对性能和低延迟要求较高的实时视频应用。该元素支持多种叠加内容,包括用户自定义的图形和标注,例如徽标、边界框、自定义标签、日期和时间、缓冲区时间戳、隐私遮罩以及其他可视化指示。此外,qtivoverlay 还可以渲染 GstMeta 中携带的动态叠加信息,这种方式通常用于将 AI 或分析结果附加到每一帧,以便进行后处理和可视化。为了实现高效的叠加渲染,qtivoverlay 将基于 CPU 的绘制与基于 GPU 的混合相结合:

使用 Cairo 的 CPU 渲染:叠加内容首先使用开源 Cairo 图形库绘制到紧凑、内存高效的叠加缓冲区中。
GPU 硬件混合:随后使用 GPU 硬件加速将这些渲染好的叠加缓冲区与主视频帧混合。

这种混合方式有助于降低内存占用并提升整体性能,尤其是在处理高分辨率或高帧率视频流的流水线中。该元素支持的叠加可以通过两种方式描述: 通过元素属性 这些是由用户手动配置的叠加,包括:

静态图像或徽标
边界框
日期和/或时间
缓冲区时间戳
自定义文本
隐私遮罩

通过缓冲区元数据 这些叠加以元数据形式附加到每个输入帧上,通常由 qtimetamux 插件添加。该元数据用于绘制与机器学习相关的叠加,例如:

检测叠加,包括边界框
分割叠加,例如语义掩码或掩码图像
分类叠加,例如标签或用户文本
姿态图叠加

总而言之,qtivoverlay 是一个硬件加速的就地图像绘制与位块传输插件,用于在视频帧上叠加可视化标注。它同时支持手动配置的叠加和元数据驱动的叠加,适用于视频分析、AI 推理可视化和隐私遮罩等使用场景。

示例流水线

下载所需文件

文件	下载	保存为
YOLOX W8A8 模型	Qualcomm AI Hub — YOLOX	`yolo_x_w8a8.tflite`
检测标签	yolov8.json	`yolov8.json`
示例视频	输入视频	`Draw_1080p_180s_30FPS.mp4`

将文件复制到设备

# Replace $HOME to the appropriate device path before running the commands.
# For QLI:    /root
# For Ubuntu: /home/ubuntu
# Modify this based on your platform and ensure files are copied to the correct location on the device.
# Run from your host machine — replace <user> and <device-ip>

ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels,media,media/output}"
scp yolo_x_w8a8.tflite          <user>@<device-ip>:$HOME/models/
scp yolov8.json                  <user>@<device-ip>:$HOME/labels/
scp Draw_1080p_180s_30FPS.mp4   <user>@<device-ip>:$HOME/media/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels,media,media/output}
export MODEL_NAME=yolo_x_w8a8.tflite
export LABELS_NAME=yolov8.json
export SRC_VIDEO_NAME=Draw_1080p_180s_30FPS.mp4

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
filesrc location=$HOME/media/$SRC_VIDEO_NAME ! qtdemux ! h264parse ! \
v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! \
tee name=t ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimltflite model=$HOME/models/$MODEL_NAME delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
  external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME \
  settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

层级结构

GObject
   GstObject
      GstElement
         GstBaseTransform
            qtivoverlay

Pad 模板

sink

能力(Capabilities)
`video/x-raw`	`format: { NV12, NV21, YUY2, RGBA, BGRA, ARGB, ABGR, RGBx, BGRx, xRGB, xBGR, RGB, BGR, NV12_Q08 }` `width: [1, 2147483647]` `height: [1, 2147483647]` `framerate: [0/1, 2147483647/1]`
可用性:Always
方向:sink

src

能力(Capabilities)
`video/x-raw`	`format: { NV12, NV21, YUY2, RGBA, BGRA, ARGB, ABGR, RGBx, BGRx, xRGB, xBGR, RGB, BGR, NV12_Q08 }` `width: [1, 2147483647]` `height: [1, 2147483647]` `framerate: [0/1, 2147483647/1]`
可用性:Always
方向:source

元素属性

属性	描述
`bboxes`	手动设置多个自定义边界框,以 GstStructure 列表形式提供,每项包含唯一名称和三个参数:`position`、`dimensions` 和 `color`。对于新条目,`position` 和 `dimensions` 是必填项。 `Type: String` `Default: "{ }"` `Flags: readable/writable` `Example:` `{(structure)\"Box1,position=<100,100>,dimensions=<640,480>;\", (structure)\"Box2,position=<1000,100>,dimensions=<300,300>,color=0xFF0000FF;\"}`
`images`	手动设置多个自定义 BGRA 图像,以 GstStructure 列表形式提供,每项包含唯一名称和三个必填参数:`path`、`resolution` 和 `destination`。 `Type: String` `Default: "{ }"` `Flags: readable/writable` `Example:` `{(structure)\"Image1,path=/data/image1.bgra,resolution=<480,360>,destination=<0,0,640,480>;\", (structure)\"Image2,path=/data/image2.bgra,resolution=<240,180>,destination=<100,100,480,360>;\"}`
`masks`	手动设置多个遮罩,以 GstStructure 列表形式提供,每项包含唯一名称、`color` 参数,以及 `circle=<X, Y, RADIUS>` 或 `rectangle=<X, Y, WIDTH, HEIGHT>` 之一(也支持 polygon)。 `Type: String` `Default: "{ }"` `Flags: readable/writable` `Example:` `{(structure)\"Mask1,color=0xRRGGBBAA,circle=<400,400,200>;\",(structure)\"Mask2,color=0xRRGGBBAA,rectangle=<0,0,20,10>;\",(structure)\"Mask3,color=0xRRGGBBAA,polygon=<<2,2>,<2,4>,<4,4>>;\"}`
`strings`	手动设置多个自定义字符串,以 GstStructure 列表形式提供,每项包含唯一名称和四个参数:`contents`、`fontsize`、`position` 和 `color`。对于新条目,`contents` 字段是必填项。 `Type: String` `Default: "{ }"` `Flags: readable/writable` `Example:` `{(structure)\"Text1,contents=\\\"Example\ 1\\\",fontsize=12,position=<0,0>,color=0xRRGGBBAA;\"}`
`timestamps`	使用 GstStructure 手动设置时间戳。使用 `Date/Time` 显示格式化的日期和时间,可选参数为 `format`、`fontsize`、`position` 和 `color`。使用 `PTS/DTS` 显示缓冲区时间戳,可选参数为 `fontsize`、`position` 和 `color`。 `Type: String` `Default: "{ }"` `Flags: readable/writable` `Example:` `{(structure)\"Date/Time,format=\\\"%d/%m/%Y\ %H:%M:%S\\\",fontsize=12,position=<0,0>,color=0xRRGGBBAA;\", (structure)\"PTS/DTS,fontsize=12,position=<0,0>,color=0xRRGGBBAA;\}`

元数据(AI 后处理信息)

传入的视频缓冲区可能以 GstMeta 的形式包含额外的元数据。该元素会检查每个缓冲区中支持的元数据类型,并将检测到的任何元数据直接渲染到对应的图像帧之上。每种受支持的元数据类型都会按照其自身的可视化表示方式进行处理和显示。

支持的元数据类型

GstVideoRegionOfInterestMeta

该元数据描述帧内的感兴趣区域(ROI),通常表示一个对象,例如人、车辆、键盘或任何其他被检测到的物体。系统会使用指定的 X/Y 坐标、宽度和高度在 ROI 周围绘制一个矩形。矩形以可见边框和透明内部的方式渲染,使区域内的对象保持可见。 GstVideoRegionOfInterestMeta

GstVideoLandmarksMeta

该元数据描述一组关键点(landmark),可以表示人体姿态关键点、面部特征、手部关节或其他相互连接的兴趣点。各个点以及连接相关点的线条都会绘制在图像上,从而清晰地可视化关键点结构。 GstVideoLandmarksMeta

GstVideoClassificationMeta

该元数据包含针对整幅图像的可能标签或分类列表。所有关联标签都会渲染在帧的左上角,使分类结果一目了然。 GstVideoClassificationMeta

GstCvOptclFlowMeta

该元数据表示光流运动矢量,用于描述两个连续视频帧之间像素的运动。这些矢量指示运动方向和幅度,便于可视化视频流中的帧间运动。 GstCvOptclFlowMeta

通过属性配置用户自定义叠加对象

除缓冲区元数据外,该插件还支持可通过属性配置的用户自定义叠加对象。这些叠加可以在运行时添加、更新或移除。配置完成后,每个叠加会持续显示在每个传入的视频帧上,直到用户显式将其移除。

支持的属性类型

静态图像

可以使用 images 属性添加静态图像,例如徽标、图标或水印。通过该属性提供的所有图像必须为原始 RGBA 格式。属性载荷遵循 GStreamer structure 布局,首次设置时需要以下必填参数:

参数	描述
`path`	图像文件的 URL 或路径
`resolution`	图像的宽度和高度(以像素为单位)
`destination`	图像放置位置的左上角 X/Y 坐标,以及其最终渲染尺寸

"{(structure)"Image1,path=/data/logo1.rgba,resolution=<480,360>,destination=<0,0,640,480>;", (structure)"Image2,path=/data/logo2.rgba,resolution=<240,180>,destination=<100,100,480,360>;"}"

	描述
Image1	分辨率 480×360,目标坐标 X=0、Y=0,渲染尺寸 640×480
Image2	分辨率 240×180,目标坐标 X=100、Y=100,渲染尺寸 480×360

自定义文本

可以使用 strings 属性设置文本叠加,例如字幕、标题、标注或标签。属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

参数	描述
`contents`	要显示的文本内容
`fontsize`	文本的字体大小
`position`	文本显示位置的左上角 X/Y 坐标
`color`	文本颜色(RGBA 十六进制格式)

"{(structure)"Text1,contents=\"Example 1\",fontsize=48,position=<50,50>,color=0x0000FFFF;", (structure)"Text2,contents=\"Example 2\",fontsize=64,position=<1620,520>,color=0xFF0000FF;"}"

	描述
Text1	字体大小 48,位置 X=50、Y=50,蓝色
Text2	字体大小 64,位置 X=1620、Y=520,红色

时间戳

可以使用 timestamps 属性显示时间戳,例如当前日期/时间或缓冲区时间戳。属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

参数	描述
`format`	日期/时间格式化字符串。不适用于 `PTS/DTS`
`fontsize`	时间戳的字体大小
`position`	时间戳放置位置的左上角 X/Y 坐标
`color`	时间戳颜色(RGBA 十六进制格式)

"{(structure)"Date/Time,format=\"%d/%m/%Y %H:%M:%S\",fontsize=48,position=<50,50>,color=0xFFFFFFFF;", (structure)"PTS/DTS,fontsize=64,position=<50,920>,color=0xFF0000FF;"}"

	描述
Date/Time	格式为日/月/年时:分:秒,字体大小 48,位置 X=50、Y=50,白色
PTS/DTS	缓冲区时间戳,字体大小 64,位置 X=50、Y=920,红色

隐私遮罩

可以使用 masks 属性,通过隐私遮罩来遮挡图像中的特定区域。属性载荷遵循 GStreamer structure 布局,需要一个唯一名称、一个 color 值以及以下受支持的形状定义之一:

形状	语法	描述
`circle`	`circle=<X, Y, RADIUS>`	以指定的 X/Y 位置为圆心、按给定半径绘制圆形遮罩
`rectangle`	`rectangle=<X, Y, WIDTH, HEIGHT>`	使用指定的坐标和尺寸绘制矩形遮罩
`polygon`	`polygon=<X1, Y1, X2, Y2, X3, Y3, ...>`	绘制由多个坐标点定义的多边形遮罩

附加参数:

参数	描述
`color`	遮罩颜色(RGBA 十六进制格式)

"{(structure)"Mask2,color=0xFF0000FF,circle=<1520,730,50>;", (structure)"Mask1,color=0x0000FFFF,rectangle=<1280,860,100,150>;", (structure)"Mask3,color=0x00FF00FF,polygon=<<910,510>,<860,740>,<1140,760>,<1160,520>>;"}"

	描述
Mask2	红色圆形遮罩 — X=1520、Y=730、R=50
Mask1	蓝色矩形遮罩 — X=1280、Y=860、宽度=100、高度=150
Mask3	绿色多边形遮罩 — 顶点:(910,510)、(860,740)、(1140,760)、(1160,520)

边界框

可以使用 bboxes 属性配置用于突出显示帧内某个区域或对象的矩形。属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

参数	描述
`position`	矩形放置位置的左上角 X/Y 坐标
`dimensions`	矩形的宽度和高度
`color`	矩形颜色(RGBA 十六进制格式)

"{(structure)"Box1,position=<100,100>,dimensions=<640,480>;", (structure)"Box2,position=<1000,100>,dimensions=<300,300>,color=0xFF0000FF;"}"

	描述
Box1	位置 X=100、Y=100,尺寸 640×480
Box2	位置 X=1000、Y=100,尺寸 300×300,红色

用法

用户自定义叠加与实时相机预览

以下示例流水线在视频帧(来自相机的实时预览)的左上角显示用户自定义文本,同时应用一个圆形隐私遮罩来遮挡图像中选定的区域。

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! queue ! \
qtivoverlay \
masks='{(structure)"Mask1,color=0xff0011ff,inverse=false,circle=<500,500,50>;"}' \
strings='{(structure)"Text1,contents=\"Example\ 1\",fontsize=40,position=<0,0>,color=0xFF00FFFF;"}' \
! queue ! waylandsink fullscreen=true sync=false

带叠加的单阶段 AI 推理

以下示例流水线包含一个单阶段 AI 推理,对视频帧执行目标检测。AI 阶段以字符串格式生成 ROI 元数据并将其附加到主帧上。随后,该元数据由 qtivoverlay 插件渲染为叠加内容,并显示在输出视频上。

下载所需文件

文件	下载	保存为
YOLOX W8A8 模型	Qualcomm AI Hub — YOLOX	`yolox_w8a8.tflite`
检测标签	yolov8.json	`yolov8.json`

如果下载的任何文件是 .zip 压缩包,请在复制之前先在主机上解压: unzip filename.zip

将文件复制到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels}"
scp yolox_w8a8.tflite   <user>@<device-ip>:$HOME/models/
scp yolov8.json         <user>@<device-ip>:$HOME/labels/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels}
export MODEL_NAME=yolox_w8a8.tflite
export LABELS_NAME=yolov8.json

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! queue ! tee name=t_split \
t_split. ! queue ! metamux. \
t_split. ! queue ! qtimlvconverter ! queue ! qtimltflite model=$HOME/models/$MODEL_NAME delegate=external external-delegate-path=libQnnTFLiteDelegate.so external-delegate-options="QNNExternalDelegate,backend_type=htp,log_level=(string)1;" ! queue ! qtimlpostprocess results=6 module=yolov8 labels=$HOME/labels/$LABELS_NAME ! text/x-raw ! queue ! metamux. \
qtimetamux name=metamux ! queue ! qtivoverlay ! queue ! waylandsink fullscreen=true sync=false

应用静态图像作为叠加

该流水线演示如何使用 qtivoverlay 的 images 属性,将一张静态图像(例如公司徽标或水印)位块传输到实时视频流上。图像在流水线启动时加载一次,并以指定的位置和尺寸合成到每一帧上。

图像文件必须为原始 BGRA 格式。在运行此流水线之前,请将图像保存为 logo.bgra。

准备所需文件

文件	描述	保存为
徽标图像	原始 BGRA 格式图像文件(例如公司徽标或水印)	`logo.bgra`

将文件复制到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip> "mkdir -p $HOME/media"
scp logo.bgra  <user>@<device-ip>:$HOME/media/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/media

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! \
qtivoverlay \
images='{(structure)"Image1,path=$HOME/media/logo.bgra,resolution=<480,360>,destination=<0,0,640,480>;"}' \
! waylandsink fullscreen=true sync=false

参数	值	说明
`path`	`$HOME/media/logo.bgra`	原始 BGRA 图像文件的绝对路径
`resolution`	`<480,360>`	源图像的原始宽度 × 高度
`destination`	`<0,0,640,480>`	X、Y 位置以及渲染的宽度 × 高度

应用时间戳 — 以文本叠加形式显示 DD/MM/YY 和时间

该流水线演示如何使用 qtivoverlay 的 timestamps 属性,将 DD/MM/YYYY 格式的当前日期和当前时间作为实时文本叠加渲染到每个视频帧上。时间戳会在每个缓冲区上自动更新。

gst-launch-1.0 -e \
qticamsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! \
qtivoverlay \
timestamps='{(structure)"Date/Time,format=\"%d/%m/%Y\ %H:%M:%S\",fontsize=60,position=<200,200>,color=0xFFFFFFFF;"}' \
! waylandsink sync=false fullscreen=true

参数	值	说明
`format`	`%d/%m/%Y %H:%M:%S`	日/月/年时:分:秒 — 例如 `16/04/2025 14:35:07`
`fontsize`	`60`	字体大小(以磅为单位)
`position`	`<200,200>`	帧上的 X、Y 像素坐标
`color`	`0xFFFFFFFF`	白色文本(RGBA 十六进制格式)

应用圆形和菱形隐私遮罩

该流水线演示如何使用 qtivoverlay 的 masks 属性,应用多个不同形状的隐私遮罩——一个圆形和一个菱形(多边形)——以遮挡视频帧中的敏感区域。两个遮罩会在每一帧上同时渲染。

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! \
qtivoverlay \
masks='{(structure)"Mask1,color=0xff0011ff,inverse=false,circle=<500,500,50>;",(structure)"Mask2,color=0xff0011f0,polygon=<<100,50>,<150,100>,<100,150>,<50,100>>;"}' \
! waylandsink sync=false fullscreen=true

遮罩	形状	参数	`color`	说明
Mask 1	`circle`	`circle=<500,500,50>`、`inverse=false`	`0xff0011ff`	圆心位于 X=500、Y=500,R=50 的圆形
Mask 2	`polygon`	`polygon=<<100,50>,<150,100>,<100,150>,<50,100>>`	`0xff0011f0`	由四个顶点定义的菱形

可以在单个 masks 属性中组合多个遮罩,方法是以逗号分隔列出多个 GStreamer structure。每个遮罩独立渲染,并且可以使用不同的形状、位置和颜色。

Introduction

Architecture

Key Documents

Technologies

System

Release Notes

qtivoverlay

概述

示例流水线

层级结构

Pad 模板

sink

src

元素属性

元数据(AI 后处理信息)

支持的元数据类型

GstVideoRegionOfInterestMeta

GstVideoLandmarksMeta

GstVideoClassificationMeta

GstCvOptclFlowMeta

通过属性配置用户自定义叠加对象

支持的属性类型

静态图像

自定义文本

时间戳

隐私遮罩

边界框

用法

用户自定义叠加与实时相机预览

带叠加的单阶段 AI 推理

应用静态图像作为叠加

应用时间戳 — 以文本叠加形式显示 DD/MM/YY 和时间

应用圆形和菱形隐私遮罩

​概述

​示例流水线

​层级结构

​Pad 模板

​sink

​src

​元素属性

​元数据(AI 后处理信息)

​支持的元数据类型

​GstVideoRegionOfInterestMeta

​GstVideoLandmarksMeta

​GstVideoClassificationMeta

​GstCvOptclFlowMeta

​通过属性配置用户自定义叠加对象

​支持的属性类型

​静态图像

​自定义文本

​时间戳

​隐私遮罩

​边界框

​用法

​用户自定义叠加与实时相机预览

​带叠加的单阶段 AI 推理

​应用静态图像作为叠加

​应用时间戳 — 以文本叠加形式显示 DD/MM/YY 和时间

​应用圆形和菱形隐私遮罩

概述

示例流水线

层级结构

Pad 模板

sink

src

元素属性

元数据(AI 后处理信息)

支持的元数据类型

GstVideoRegionOfInterestMeta

GstVideoLandmarksMeta

GstVideoClassificationMeta

GstCvOptclFlowMeta

通过属性配置用户自定义叠加对象

支持的属性类型

静态图像

自定义文本

时间戳

隐私遮罩

边界框

用法

用户自定义叠加与实时相机预览

带叠加的单阶段 AI 推理

应用静态图像作为叠加

应用时间戳 — 以文本叠加形式显示 DD/MM/YY 和时间

应用圆形和菱形隐私遮罩