> ## 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_hand_detection 检测手部

> sample_hand_detection 使用基于 Python 的手部识别 ROS 节点来检测手部及手部动作。它使用 Qualcomm AI Engine Direct SDK (QNN) 进行模型推理。

模型来源于 MediaPipe Hand Landmark Detector，这是一个用于预测图像中手部边界框和姿态骨架的机器学习管线。该示例应用允许您输入一张名为 `input_image.jpg` 的图像，然后以 ROS topic `handlandmark_result` 发布结果。它使用 [Qualcomm AI Engine Direct SDK (QNN)](https://www.qualcomm.com/developer/software/neural-processing-sdk-for-ai) 进行模型推理。

<Note>
  有关模型信息，请参见 [MediaPipe-Hand-Detection](https://huggingface.co/qualcomm/MediaPipe-Hand-Detection)。

  有关更多信息，请参见 [sample\_hand\_detection](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_hand_detection) GitHub 仓库。
</Note>

下图展示了手部检测结果的示例。

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image35.png" alt="Hand detection result showing an open palm with a skeletal overlay and bounding boxes drawn around the hand and the palm." />
</Frame>

## `sample_hand_detection` 的管线流程

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

<Frame caption="sample_hand_detection 管线。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/GA1.6-hand-detection.svg" alt="Hand detection pipeline from the image publisher through the hand detector node to the published hand landmark result topic." />
</Frame>

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

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

| ROS 节点                  | 说明                                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `qrb_ros_hand_detector` | `qrb_ros_hand_detector` 节点是一个基于 Python 的 ROS Jazzy 包，用于实现图像分类。它使用 QNN SDK 进行模型推理。该 ROS 节点订阅图像 topic，并在预处理和后处理之后发布分类结果 topic。             |
| `image_publisher`       | `image_publisher` 是一个 ROS Jazzy 包。它使用本地路径发布图像 ROS topic。有关更多信息，请参见 [image\_publisher](https://github.com/ros-perception/image_pipeline)。 |

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

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

| ROS topic              | 类型                      | 发布者                     |
| ---------------------- | ----------------------- | ----------------------- |
| `/handlandmark_result` | `sensor_msgs.msg.Image` | `qrb_ros_hand_detector` |
| `/image_raw`           | `sensor_msgs.msg.Image` | `image_publisher`       |

## 前提条件

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

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

<Steps>
  <Step title="为运行示例应用创建必要的目录">
    ```bash Create the output directories theme={null}
    sudo mkdir -p /opt/ros/jazzy/share/sample_hand_detection/output_MediaPipeHandDetector/
    sudo chmod 777 /opt/ros/jazzy/share/sample_hand_detection/output_MediaPipeHandDetector/
    sudo mkdir -p /opt/ros/jazzy/share/sample_hand_detection/output_MediaPipeHandLandmarkDetector
    sudo chmod 777 /opt/ros/jazzy/share/sample_hand_detection/output_MediaPipeHandLandmarkDetector
    sudo chmod 777 -R /opt/ros/jazzy/share/sample_hand_detection/
    ```
  </Step>

  <Step title="在开发套件上运行以下命令">
    ```bash Launch the sample application theme={null}
    export ROS_DOMAIN_ID=123
    source /opt/ros/jazzy/setup.bash
    ros2 launch sample_hand_detection launch_with_image_publisher.py
    ```
  </Step>

  <Step title="在主机上运行以下命令">
    a. 启动 `rqt`。

    ```bash theme={null}
    # YOUR_HOST_IP is the IP address of the Host where you want to view the sample output.
    export DISPLAY=YOUR_HOST_IP:0
    export ROS_DOMAIN_ID=123
    rqt
    ```

    b. 依次选择以下按钮：

    ```text theme={null}
    Plugins --> Visualization --> Image View
    ```

    c. 选择 `handlandmark_result` 查看结果。
  </Step>
</Steps>