> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# qtivoverlay

> 硬件加速的就地视频叠加插件

# 概述

**qtivoverlay** 元素是一个硬件加速的就地绘制与位块传输(blitting)插件,旨在将可视化叠加对象直接渲染到传入的视频帧(如 YUV 或 RGB 缓冲区)之上。通过将叠加内容直接合成到帧数据上,处理后的视频可以以极小的额外开销显示在屏幕上或转发用于编码。这使其非常适合对性能和低延迟要求较高的实时视频应用。

该元素支持多种叠加内容,包括用户自定义的图形和标注,例如徽标、边界框、自定义标签、日期和时间、缓冲区时间戳、隐私遮罩以及其他可视化指示。此外,**qtivoverlay** 还可以渲染 **GstMeta** 中携带的动态叠加信息,这种方式通常用于将 AI 或分析结果附加到每一帧,以便进行后处理和可视化。

为了实现高效的叠加渲染,**qtivoverlay** 将基于 CPU 的绘制与基于 GPU 的混合相结合:

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

这种混合方式有助于降低内存占用并提升整体性能,尤其是在处理高分辨率或高帧率视频流的流水线中。

该元素支持的叠加可以通过两种方式描述:

**通过元素属性**

这些是由用户手动配置的叠加,包括:

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

**通过缓冲区元数据**

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

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

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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_arch.png" alt="qtivoverlay_arch" />

## 示例流水线

<Steps>
  <Step title="下载所需文件">
    | 文件            | 下载                                                                                                                           | 保存为                         |
    | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
    | YOLOX W8A8 模型 | [Qualcomm AI Hub — YOLOX](https://aihub.qualcomm.com/iot/models/yolox)                                                       | `yolo_x_w8a8.tflite`        |
    | 检测标签          | <a href="/SDKs/IMSDK/labels/yolov8.json" download="yolov8.json">yolov8.json</a>                                              | `yolov8.json`               |
    | 示例视频          | <a href="https://github.com/qualcomm/sample-apps-for-qualcomm-linux/raw/refs/heads/main/artifacts/videos/video.mp4">输入视频</a> | `Draw_1080p_180s_30FPS.mp4` |
  </Step>

  <Step title="将文件复制到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # 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/
      ```
    </CodeGroup>
  </Step>

  <Step title="连接到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # Run from your host machine — replace <user> and <device-ip>
      ssh <user>@<device-ip>
      ```
    </CodeGroup>
  </Step>

  <Step title="设置环境变量">
    在设备上运行以下命令

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="运行流水线">
    ```bash theme={null}
    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.
    ```
  </Step>
</Steps>

# 层级结构

[GObject](https://docs.gtk.org/gobject/)<br />
   <Icon icon="arrow-turn-down-right" iconType="solid" />[GstObject](https://gstreamer.freedesktop.org/documentation/gstreamer/gstobject.html?gi-language=c)<br />
      <Icon icon="arrow-turn-down-right" iconType="solid" />[GstElement](https://gstreamer.freedesktop.org/documentation/gstreamer/gstelement.html?gi-language=c)<br />
         <Icon icon="arrow-turn-down-right" iconType="solid" />[GstBaseTransform](https://gstreamer.freedesktop.org/documentation/base/gstbasetransform.html?gi-language=c)<br />
            <Icon icon="arrow-turn-down-right" iconType="solid" />qtivoverlay

# Pad 模板

### sink

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

# 元素属性

| 属性           | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bboxes`     | 手动设置多个自定义边界框,以 GstStructure 列表形式提供,每项包含唯一名称和三个参数:`position`、`dimensions` 和 `color`。对于新条目,`position` 和 `dimensions` 是必填项。<br /><br />`Type: String`<br />`Default: "{ }"`<br />`Flags: readable/writable`<br />`Example:`<br />`{(structure)\"Box1,position=<100,100>,dimensions=<640,480>;\", (structure)\"Box2,position=<1000,100>,dimensions=<300,300>,color=0xFF0000FF;\"}`                                                                      |
| `images`     | 手动设置多个自定义 BGRA 图像,以 GstStructure 列表形式提供,每项包含唯一名称和三个必填参数:`path`、`resolution` 和 `destination`。<br /><br />`Type: String`<br />`Default: "{ }"`<br />`Flags: readable/writable`<br />`Example:`<br />`{(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)。<br /><br />`Type: String`<br />`Default: "{ }"`<br />`Flags: readable/writable`<br />`Example:`<br />`{(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` 字段是必填项。<br /><br />`Type: String`<br />`Default: "{ }"`<br />`Flags: readable/writable`<br />`Example:`<br />`{(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`。<br /><br />`Type: String`<br />`Default: "{ }"`<br />`Flags: readable/writable`<br />`Example:`<br />`{(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 周围绘制一个矩形。矩形以可见边框和透明内部的方式渲染,使区域内的对象保持可见。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_roi.jpg" alt="GstVideoRegionOfInterestMeta" />

### GstVideoLandmarksMeta

该元数据描述一组关键点(landmark),可以表示人体姿态关键点、面部特征、手部关节或其他相互连接的兴趣点。

各个点以及连接相关点的线条都会绘制在图像上,从而清晰地可视化关键点结构。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_landmark.jpg" alt="GstVideoLandmarksMeta" />

### GstVideoClassificationMeta

该元数据包含针对整幅图像的可能标签或分类列表。

所有关联标签都会渲染在帧的左上角,使分类结果一目了然。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_class.jpg" alt="GstVideoClassificationMeta" />

### GstCvOptclFlowMeta

该元数据表示光流运动矢量,用于描述两个连续视频帧之间像素的运动。

这些矢量指示运动方向和幅度,便于可视化视频流中的帧间运动。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_optical.png" alt="GstCvOptclFlowMeta" />

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

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

## 支持的属性类型

### 静态图像

可以使用 **images** 属性添加静态图像,例如徽标、图标或水印。
通过该属性提供的所有图像必须为原始 **RGBA** 格式。

属性载荷遵循 GStreamer structure 布局,首次设置时需要以下必填参数:

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

```bash theme={null}
"{(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 |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_static.jpg" alt="StaticImage" />

### 自定义文本

可以使用 **strings** 属性设置文本叠加,例如字幕、标题、标注或标签。

属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

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

```bash theme={null}
"{(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,红色 |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_custom.jpg" alt="CustomText" />

### 时间戳

可以使用 **timestamps** 属性显示时间戳,例如当前日期/时间或缓冲区时间戳。

属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

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

```bash theme={null}
"{(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,红色         |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_time.jpg" alt="Timestamp" />

### 隐私遮罩

可以使用 **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 十六进制格式) |

```bash theme={null}
"{(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) |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_privacy.jpg" alt="Privacy" />

### 边界框

可以使用 **bboxes** 属性配置用于突出显示帧内某个区域或对象的矩形。

属性载荷遵循 GStreamer structure 布局,首次设置时需要以下参数:

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

```bash theme={null}
"{(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,红色 |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/IMSDK/plugin-reference/images/qtivoverlay_box.jpg" alt="BoundingBox" />

# 用法

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

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

```mermaid theme={null}
flowchart LR
    A[qticamsrc]  --> C[qtivoverlay
masks + strings]  --> E[waylandsink]
```

```bash theme={null}
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** 插件渲染为叠加内容,并显示在输出视频上。

```mermaid theme={null}
flowchart LR
    A[qticamsrc] --> T{{tee}}
    T --> MM[qtimetamux]
    T --> VC[qtimlvconverter] --> QNN[qtimltflite] -->  PP[qtimlpostprocess] -->|text/x-raw| MM
    MM --> OVL[qtivoverlay] --> WS[waylandsink]
```

<Steps>
  <Step title="下载所需文件">
    | 文件            | 下载                                                                              | 保存为                 |
    | ------------- | ------------------------------------------------------------------------------- | ------------------- |
    | YOLOX W8A8 模型 | [Qualcomm AI Hub — YOLOX](https://aihub.qualcomm.com/iot/models/yolox)          | `yolox_w8a8.tflite` |
    | 检测标签          | <a href="/SDKs/IMSDK/labels/yolov8.json" download="yolov8.json">yolov8.json</a> | `yolov8.json`       |

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

  <Step title="将文件复制到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # 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/
      ```
    </CodeGroup>
  </Step>

  <Step title="连接到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # Run from your host machine — replace <user> and <device-ip>
      ssh <user>@<device-ip>
      ```
    </CodeGroup>
  </Step>

  <Step title="设置环境变量">
    在设备上运行以下命令

    ```bash theme={null}
    mkdir -p $HOME/{models,labels}
    export MODEL_NAME=yolox_w8a8.tflite
    export LABELS_NAME=yolov8.json
    ```
  </Step>

  <Step title="运行流水线">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

### 应用静态图像作为叠加

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

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

```mermaid theme={null}
flowchart LR
    A[qticamsrc] -->|NV12
    1920x1080| B[qtivoverlay
    images=logo.bgra] -->|NV12
    1920x1080| C[waylandsink]
```

<Steps>
  <Step title="准备所需文件">
    | 文件   | 描述                        | 保存为         |
    | ---- | ------------------------- | ----------- |
    | 徽标图像 | 原始 BGRA 格式图像文件(例如公司徽标或水印) | `logo.bgra` |
  </Step>

  <Step title="将文件复制到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # 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/
      ```
    </CodeGroup>
  </Step>

  <Step title="连接到设备">
    <CodeGroup>
      ```bash SCP (SSH) theme={null}
      # Run from your host machine — replace <user> and <device-ip>
      ssh <user>@<device-ip>
      ```
    </CodeGroup>
  </Step>

  <Step title="设置环境变量">
    在设备上运行以下命令

    ```bash theme={null}
    mkdir -p $HOME/media
    ```
  </Step>

  <Step title="运行流水线">
    ```bash theme={null}
    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 位置以及渲染的宽度 × 高度 |
  </Step>
</Steps>

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

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

```mermaid theme={null}
flowchart LR
    A[qticamsrc] -->|NV12
    1920x1080| B[qtivoverlay
    timestamps] -->|NV12
    1920x1080| C[waylandsink]
```

```bash theme={null}
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` 属性,应用多个不同形状的隐私遮罩——一个**圆形**和一个**菱形**(多边形)——以遮挡视频帧中的敏感区域。两个遮罩会在每一帧上同时渲染。

```mermaid theme={null}
flowchart LR
    A[qticamsrc] -->|NV12
    1920x1080| B[qtivoverlay
    masks=circle+rhombus] -->|NV12
    1920x1080| C[waylandsink]
```

```bash theme={null}
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` | 由四个顶点定义的菱形                |

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

***