> ## 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.

# 使用 qrb_ros_video 编解码视频

> qrb_ros_video 是一个 ROS 包，为 Qualcomm 机器人平台提供硬件加速的视频处理。

`qrb_ros_video` 示例应用提供以下功能：

* 使用 Qualcomm 视频处理单元 (VPU) 进行硬件加速的 H.264/H.265 视频编解码

* 用于高性能视频处理的零拷贝内存管理

* 与 ROS 2 生态系统和摄像头管道的集成

* 支持实时视频流传输和文件 I/O 操作

## `qrb_ros_video` 的管道流程

下图展示了 `qrb_ros_video` 的管道流程。

<Frame caption="qrb_ros_video 管道。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image21.png" alt="Camera node, image reader, and compressed reader feeding the encoder and decoder nodes, which output to the compressed writer, image writer, and display." />
</Frame>

* **Video encoder node**：使用 Qualcomm VPU 硬件将原始图像转换为压缩的 H.264/H.265 流。

* **Video decoder node**：将压缩视频流解码回原始图像帧。

* **Camera support**：接受来自 QRB ROS Camera 包的零拷贝传输输入。

* **File I/O components**：实现 `CompressedWriter` 和 `ImageWriter` 用于将视频数据保存到文件。

* **Hardware acceleration**：利用 Qualcomm 视频处理单元 (VPU) 进行高效的编解码。

* **Memory management**：使用 DMA 缓冲区和 `qrb_ros_transport` 进行零拷贝操作。

## `qrb_ros_video` API

`qrb_ros_video` 节点公开了 ROS 接口和 ROS 参数。使用它们向编码器或解码器提供帧并配置视频格式。

### ROS 接口

下表列出了编码器话题，包括每个话题的消息类型和内容。

| 话题        | 消息类型                                | 说明                  |
| --------- | ----------------------------------- | ------------------- |
| `/input`  | `qrb_ros::transport::type::Image`   | 未压缩的 YUV 帧          |
| `/output` | `sensor_msgs::msg::CompressedImage` | 压缩的 H.264/H.265 视频流 |

下表列出了解码器话题，包括每个话题的消息类型和内容。

| 话题        | 消息类型                                | 说明                        |
| --------- | ----------------------------------- | ------------------------- |
| `/input`  | `sensor_msgs::msg::CompressedImage` | 表示压缩的 H.264/H.265 视频流的输入。 |
| `/output` | `qrb_ros::transport::type::Image`   | 表示解码后的 YUV 帧输出。           |

### ROS 参数

下表列出了视频编码器参数，包括每个参数的类型、默认值和用途。

| 参数             | 类型       | 默认值        | 说明                                    |
| -------------- | -------- | ---------- | ------------------------------------- |
| `format`       | `string` | `h264`     | 视频编解码格式（`h264`/`h265`）                |
| `pixel_format` | `string` | `nv12`     | 输入像素格式（`nv12`/`p010`）                 |
| `width`        | `int`    | `1920`     | 视频宽度                                  |
| `height`       | `int`    | `1080`     | 视频高度                                  |
| `framerate`    | `int`    | `30`       | 每秒帧数                                  |
| `bitrate`      | `int`    | `5000000`  | 目标比特率（比特/秒）                           |
| `rate_control` | `string` | `variable` | 码率控制模式（`variable`/`cbr`）              |
| `profile`      | `string` | `main`     | 编解码 profile（`baseline`/`main`/`high`） |
| `level`        | `string` | `4.1`      | 编解码 level                             |

下表列出了视频解码器参数，包括每个参数的类型、默认值和用途。

| 参数             | 类型       | 默认值    | 说明         |
| -------------- | -------- | ------ | ---------- |
| `format`       | `string` | `h264` | 表示输入编解码格式。 |
| `pixel-format` | `string` | `nv12` | 表示输出像素格式。  |

## 前提条件

* 你已根据[安装 QIR SDK](./install-the-qir-sdk)完成设备设置，并在设备上安装了 ROS2 Jazzy 和 Qualcomm Intelligent Robotics (QIR) SDK。

* 你已将设备连接到显示器。

## 开箱即用运行 `qrb_ros_video`

<Steps>
  <Step title="安装 qrb_ros_video 包">
    ```bash Install the packages theme={null}
    sudo apt install ros-jazzy-qrb-ros-video ros-jazzy-qrb-ros-video-test
    ```
  </Step>

  <Step title="启动本地视频文件录制">
    ```bash Start the encoder theme={null}
    mkdir -p /data
    sudo chmod 777 /data
    source /opt/ros/jazzy/setup.bash
    # push YUV sample file 1920_1080_nv12.yuv to /data/ directory
    scp <path of 1920_1080_nv12.yuv> IP@ubuntu:/home/ubuntu
    sudo mv /home/ubuntu/1920_1080_nv12.yuv /data
    ros2 launch qrb_ros_video encoder_launch.py
    ```
  </Step>

  <Step title="启动本地视频文件播放">
    ```bash Start the decoder theme={null}
    mkdir -p /data
    sudo chmod 777 /data
    source /opt/ros/jazzy/setup.bash
    # push YUV sample file 1920_1080.mp4 to /data/ directory
    scp <path of 1920_1080.mp4> IP@ubuntu:/home/ubuntu
    sudo mv /home/ubuntu/1920_1080.mp4 /data
    ros2 launch qrb_ros_video decoder_launch.py
    ```
  </Step>
</Steps>

## 从源码构建

<Steps>
  <Step title="安装依赖">
    ```bash Install the dependencies theme={null}
    sudo apt install build-essential cmake pkg-config
    # Install GStreamer development packages
    sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-devs
    # Install ROS2 Jazzy (if not already installed)
    # Follow instructions at https://docs.ros.org/en/jazzy/Installation.html
    sudo apt install ros-jazzy-rclcpp ros-jazzy-rclcpp-components ros-jazzy-ament-cmake-auto ros-jazzy-std-msgs ros-jazzy-sensor-msgs ros-jazzy-qrb-ros-transport-image-type
    ```
  </Step>

  <Step title="下载源码并使用 colcon 构建">
    ```bash Build the package theme={null}
    source /opt/ros/jazzy/setup.bash
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_video qrb_ros_video
    colcon build --packages-select qrb_ros_video
    ```
  </Step>

  <Step title="运行和调试">
    ```bash Run the encoder theme={null}
    source install/setup.bash
    # push YUV sample file 1920_1080_nv12.yuv to /data/ directory
    ros2 launch qrb_ros_video encoder_launch.py
    ```
  </Step>
</Steps>