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

# QRB ROS Samples

[`qrb_ros_samples`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples) 是一个**参考示例**目录，它将 QNN 推理以及（在适用时）零拷贝传输连接到可直接运行的 ROS 2 launch 文件中。该仓库采用 **BSD‑3‑Clause** 许可证。`main` 分支为活跃开发分支；稳定发布请跟踪 `jazzy-rel` 分支。

<Note>
  这些是起点和参考——**并非**使用 Qualcomm 机器人平台的唯一受支持方式。相同的原语（QNN delegate、[`qrb_ros_transport`](./qrb-ros-transport) 以及来自 [Qualcomm AI Hub](https://aihub.qualcomm.com) 的模型）可以直接与标准 ROS 2 / 社区软件包组合。[NPU 工作流程](./npu-workflows)就是这种从零开始方式的示例，面向相同的 NPU。
</Note>

<CardGroup cols={2}>
  <Card title="AI 示例" icon="brain" href="#ai-samples">
    视觉和音频流水线——深度、姿态、分割、检测、语音识别。推理通过 QNN 在 NPU 上运行。
  </Card>

  <Card title="机器人示例" icon="robot" href="#robotics-samples">
    AMR 运动、2D 激光雷达 SLAM、Nav2、AprilTag、跟随（follow-me）、抓取放置。设备端和 Gazebo 仿真兼有。
  </Card>
</CardGroup>

## 阅读支持矩阵

<AccordionGroup>
  <Accordion title="复选框是什么意思？" icon="circle-question">
    上游 README 没有为其支持列定义图例，并且各示例的 README 有时与顶层表格不一致。本页对数据的解读如下：

    | 列                           | 含义                                                                                                                                                      |
    | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **IQ‑9075 / IQ‑8 Beta EVK** | <Icon icon="square-check" color="#10b981" /> = 上游已在该套件上验证过该示例。<Icon icon="square" color="#9ca3af" /> = **上游未验证**——这将"无法工作"和"仅仅是未测试"合并在一起。上游没有提供区分它们的信号。 |
    | **加速器**                     | 该示例面向的主要计算模块：`NPU`（通过 QNN 的 Hexagon HTP）、`CPU`（Gazebo 仿真或纯 CPU 流水线）或 `GPU`。                                                                             |

    此目录中列出的每个示例都**可以在 Qualcomm® IoT 平台的 Ubuntu 镜像上从源码构建**。仅能通过 Qualcomm Linux / QIRP SDK 工具链获取的示例已被排除。
  </Accordion>
</AccordionGroup>

<Warning>
  空复选框 <Icon icon="square" color="#9ca3af" /> **并不表示"不支持"**——仅表示"上游未验证"。在某个套件上投入时间使用某示例之前，请查看该示例自身的 README（从"示例"列链接），以获取权威的按套件支持列表。当各示例的 README 与此目录不一致时，请以各示例的 README 为准。
</Warning>

## AI 示例

<Tip>
  大多数视觉示例从 `qrb_ros_camera`（Qualcomm CSI/GMSL）采集。要改用 USB 网络摄像头运行这些示例，请将摄像头节点替换为 `v4l2_camera`——端到端示例参见 [NPU 工作流程](./npu-workflows)。
</Tip>

各行按上手难易程度排序——所需额外硬件最少的在前。

| 示例                                                                                                                                     | 所需硬件                                            | 加速器 |                  IQ‑9075 EVK                 |                 IQ‑8 Beta EVK                | 描述                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --- | :------------------------------------------: | :------------------------------------------: | ------------------------------------------------------------------------------------------------------------- |
| [语音识别（RT rosnode）](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_audio/sample_speech_recognition_rt_rosnode)        | USB 麦克风                                         | NPU |    <Icon icon="square" color="#9ca3af" />    |    <Icon icon="square" color="#9ca3af" />    | 使用 [Whisper‑Tiny‑En](https://aihub.qualcomm.com/iot/models/whisper_tiny_en?domain=Audio) 通过 USB 麦克风进行实时语音转文字。 |
| [`sample_object_detection`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_object_detection)           | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 通过 [YOLOv8‑Detection](https://aihub.qualcomm.com/iot/models/yolov8_det) 进行实时目标检测。                             |
| [`sample_object_segmentation`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_object_segmentation)     | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 通过 [YOLOv8‑Segmentation](https://aihub.qualcomm.com/iot/models/yolov8_seg) 进行实时实例分割。                          |
| [`sample_resnet101`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_resnet101)                         | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 通过 [ResNet101Quantized](https://huggingface.co/qualcomm/ResNet101Quantized) 在 ImageNet 上进行图像分类。               |
| [`sample_depth_estimation`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_depth_estimation)           | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> |    <Icon icon="square" color="#9ca3af" />    | 通过 [Depth Anything V2](https://aihub.qualcomm.com/iot/models/depth_anything_v2) 获得逐像素深度。                      |
| [`sample_hrnet_pose_estimation`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_hrnet_pose_estimation) | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> |    <Icon icon="square" color="#9ca3af" />    | 通过 [HRNetPose](https://aihub.qualcomm.com/iot/models/hrnet_pose) 进行高精度人体姿态估计。                                 |
| [人脸检测](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_face_detection)                                  | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> |    <Icon icon="square" color="#9ca3af" />    | 使用 [MediaPipe‑Face‑Detection](https://huggingface.co/qualcomm/MediaPipe-Face-Detection) 输出边界框和关键点。            |
| [手部检测](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_hand_detection)                                  | 任何兼容的 CSI/GMSL 摄像头（或通过 `v4l2_camera` 的 USB 摄像头） | NPU | <Icon icon="square-check" color="#10b981" /> |    <Icon icon="square" color="#9ca3af" />    | 使用 [MediaPipe‑Hand‑Detection](https://huggingface.co/qualcomm/MediaPipe-Hand-Detection) 输出边界框和姿态骨架。           |

<Note>
  想基于这些示例所包装的相同原语从零构建推理流水线？请参阅 [NPU 工作流程](./npu-workflows)，其中有一个直接使用 QNN TFLite delegate 手工构建的深度估计示例。
</Note>

## 机器人示例

各行按上手难易程度排序——仿真在前，其次是基于摄像头的示例，然后是特定供应商的外设。

| 示例                                                                                                                                                  | 所需硬件         | 加速器     |                  IQ‑9075 EVK                 |                 IQ‑8 Beta EVK                | 描述                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------- | :------------------------------------------: | :------------------------------------------: | ---------------------------------------------------------- |
| [`simulation_sample_amr_simple_motion`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/robotics/simulation_sample_amr_simple_motion) | 无（仿真）        | CPU（仿真） | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 通过向 `/qrb_robot_base/cmd_vel` 发布消息来指挥 AMR 简单运动的 Python 节点。 |
| [`simulation_sample_pick_and_place`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/robotics/simulation_sample_pick_and_place)       | 无（仿真）        | CPU（仿真） | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 使用 MoveIt2 运动规划和 Gazebo 物理引擎的 C++ 抓取放置。                    |
| [`sample_apriltag`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/robotics/sample_apriltag)                                         | 任何兼容的摄像头     | CPU     | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | AprilTag 流水线——NV12 摄像头 → 颜色转换 → 校正 → 标签检测 → `/tf`。         |
| [`sample_followme`](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/robotics/sample_followme)                                         | Orbbec 深度摄像头 | NPU     | <Icon icon="square-check" color="#10b981" /> | <Icon icon="square-check" color="#10b981" /> | 能检测、跟踪并跟随移动人员的真实世界 AMR。                                    |

## 系统要求

根据上游：**面向 Qualcomm IoT 平台的 Canonical Ubuntu**。参见[在 Qualcomm IoT 平台上安装 Ubuntu](https://ubuntu.com/download/qualcomm-iot) 和[安装 ROS Jazzy](https://docs.ros.org/en/jazzy/index.html)。对于 Qualcomm Linux 目标，请改用 [QIRP SDK](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-265/introduction_1.html?vproduct=1601111740013072\&version=1.4\&facet=Qualcomm%20Intelligent%20Robotics%20Product%20\(QIRP\)%20SDK)。