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

# 使用 sample_object_detection 检测目标

> sample_object_detection 是一个使用 QNN 进行模型推理的 Python 启动文件。它演示摄像头数据流传输、基于 AI 的推理以及目标检测结果的实时可视化。

Ultralytics YOLOv8 是一个可以预测图像中目标边界框、分割掩膜和类别的机器学习模型。

## `sample_object_detection` 的管线流程

下图展示了 `sample_object_detection` 的管线流程。

<Frame caption="sample_object_detection 的管线流程。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image50.svg" alt="Object detection pipeline from camera capture through YOLO preprocessing, inference, postprocessing, and overlay to the detection result topic." />
</Frame>

## `sample_object_detection` 管线中使用的 ROS 节点

下表列出了 `sample_object_detection` 管线中使用的 ROS 节点。

| 节点名                                                                              | 说明                                               |
| -------------------------------------------------------------------------------- | ------------------------------------------------ |
| [qrb ros camera](https://github.com/qualcomm-qrb-ros/qrb_ros_camera)             | Qualcomm ROS 2 包，按参数采集图像并将其发布到 ROS topic。        |
| [yolo preprocess](https://github.com/qualcomm-qrb-ros/qrb_ros_tensor_process)    | 订阅图像数据，对其进行重塑与缩放，然后重新发布到下游 topic。                |
| [qrb ros nn interface](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference) | 加载已训练的 AI 模型，接收预处理后的图像，执行推理，并发布结果。               |
| [yolo postprocess](https://github.com/qualcomm-qrb-ros/qrb_ros_tensor_process)   | 将推理输出与 yolo 标签文件进行匹配。                            |
| [yolo overlay](https://github.com/qualcomm-qrb-ros/qrb_ros_tensor_process)       | 订阅 yolo postprocess 和图像数据，通过 ROS topic 显示目标检测结果。 |

## `sample_object_detection` 管线中使用的 ROS topic

下表列出了 `sample_object_detection` 管线中使用的 ROS topic。

| ROS topic                     | 类型                                          | 发布者                               |
| ----------------------------- | ------------------------------------------- | --------------------------------- |
| `/camera/color/image_raw`     | `<sensor_msgs.msg.Image>`                   | `qrb_ros_camera`                  |
| `/qrb_inference_input_tensor` | `<qrb_ros_tensor_list_msgs.msg.TensorList>` | `yolo_preprocess_node`            |
| `/yolo_detect_result`         | `<vision_msgs.msg.Detection2DArray>`        | `nn_inference_node`               |
| `/yolo_detect_tensor_output`  | `<qrb_ros_tensor_list_msgs.msg.TensorList>` | `yolo_detection_postprocess_node` |
| `/yolo_detect_overlay`        | `<sensor_msgs.msg.Image>`                   | `yolo_detection_overlay_node`     |

## 前提条件

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

* 在主机上，您已根据 [qrb\_ros\_tensor\_process](https://github.com/qualcomm-qrb-ros/qrb_ros_tensor_process) 的 README 中的步骤下载并构建了 yolo 模型。

  <Note>
    下载 yolo 模型时，使用如下 `target-runtime` 和 `device`：
  </Note>

## 生成 YOLOv8 模型

<Steps>
  <Step title="在主机上设置 QAI-Hub。">
    a. 登录 [QAI-Hub](https://app.aihub.qualcomm.com/docs/hub/getting_started.html) 并获取您的 API token。

    b. 在主机上安装 QAI-Hub。

    ```bash theme={null}
     ## It is recommended to use python venv to avoid impacting the host environment.
     python3 -m venv venv_qaihub
     source venv_qaihub/bin/activate

     ## Install QAI-Hub related python packages.
     pip3 install qai-hub

     ## Configure QAI-Hub token, replacing xxx with your own token got from QAI-Hub page.
     qai-hub configure --api_token xxx

     pip3 install "qai-hub-models[yolov8-det]"
    ```
  </Step>

  <Step title="在主机上导出模型。">
    执行以下命令后，模型文件和 coco8.yaml 将在主机上生成。

    <CodeGroup>
      ```bash IQ-9075     theme={null}
      python -m qai_hub_models.models.yolov8_det.export --target-runtime "qnn_context_binary" --chipset "qualcomm-qcs9075" --skip-profiling --skip-inferencing

      # Push model files to the device's default path according to the preceding export log.

      # On the device, create the path if it doesn't exist.
      mkdir /opt/model


      # On the host computer, scp all model files to the device.
      scp <Host_Export_model_Path>/yolov8_det.bin ubuntu@<device_ip>:/opt/model

      sudo find / -name "coco8.yaml" -print -quit
      scp <label-file-path>/coco8.yaml ubuntu@<device_ip>:/opt/
      ```

      ```bash VENTUO Q (QCS8275)    theme={null}
      python -m qai_hub_models.models.yolov8_det.export --target-runtime "qnn_context_binary" --chipset "qualcomm-qcs8275" --skip-profiling --skip-inferencing

      # Push model files to the device's default path according to the preceding export log.

      # On the device, create the path if it doesn't exist.
      mkdir /opt/model

      # On the host computer, scp all model files to the device.
      scp <Host_Export_model_Path>/yolov8_det.bin ubuntu@<device_ip>:/opt/model

      sudo find / -name "coco8.yaml" -print -quit
      scp <label-file-path>/coco8.yaml ubuntu@<device_ip>:/opt/        
      ```
    </CodeGroup>
  </Step>
</Steps>

## 运行开箱即用的 `sample_object_detection`

在设备上，运行示例应用：

```bash Run the sample application theme={null}
source /opt/ros/jazzy/setup.bash
ros2 launch sample_object_detection launch_with_qrb_ros_camera.py model:=/opt/model/yolov8_det.bin
```

然后，您可以在 `rviz2` 中查看名为 `/yolo_detect_overlay` 的 ROS topic。

## 从 `sample_object_detection` 的源代码构建

<Note>
  请先运行 [前提条件](./detect-objects-with-sample_object_detection#prerequisites)，然后再执行以下步骤。
</Note>

在设备上，运行示例应用：

<Steps>
  <Step title="从 qrb_ros_samples 仓库下载源代码">
    ```bash Download the source code theme={null}
    mkdir -p ~/qrb_ros_ws/src && cd ~/qrb_ros_ws/src
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_samples.git
    ```
  </Step>

  <Step title="从源代码构建 sample_object_detection 示例应用">
    ```bash Build the sample application theme={null}
    cd ~/qrb_ros_ws/src/qrb_ros_samples/ai_vision/sample_object_detection
    colcon build
    source install/setup.bash
    ```
  </Step>

  <Step title="运行并测试示例应用">
    根据 [运行开箱即用的 `sample_object_detection`](./detect-objects-with-sample_object_detection#run-out-of-the-box-sample_object_detection) 的第 2–3 步运行并测试。
  </Step>
</Steps>