> ## 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_face_detection 检测人脸

`sample_face_detection` 示例应用使用基于 Python 的 ROS 2 节点 `sample_face_detection` 从图像中检测人脸并定位面部关键点，该节点使用 Qualcomm® AI Engine Direct SDK (QNN) 进行模型推理。

模型来自 Qualcomm AI-hub。它以 `face_image.jpg` 作为输入并将结果发布到 `/mediaface_det_image` topic。

<Note>
  **注意**

  * 有关模型信息，请参见 [MediaPipe-Face-Detection - Qualcomm AI Hub](https://aihub.qualcomm.com/iot/models/mediapipe_face?searchTerm=Media)。

  * 有关示例应用的详细信息，请参见 GitHub 上的 [sample\_fact\_detection](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_face_detection)
</Note>

<video
  autoPlay
  muted
  loop
  playsInline
  width={768}
  height={432}
  src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/sample_face_detection_result.mp4"
  style={{
width: "70%",
display: "block",
margin: "0 auto" }}
/>

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图：`sample_face_detection` 的示例效果
</p>

## `sample_face_detection` 的流水线流程

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/ga1.6-face-detection.drawio.svg" style={{width: "100%"}} />

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图：`sample_face_detection` 的流水线流程
</p>

## `sample_face_detection` 中使用的 ROS 节点

| **ROS 节点**              | **说明**                                                                                                                                                          |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qrb_ros_face_detector` | `qrb_ros_face_detector` 是一个处理人脸图像的基于 Python 的 ROS 2 Jazzy 包。该 ROS 节点订阅一个图像 topic，在预处理/后处理后发布人脸图像结果 topic。                                                       |
| `image_publisher`       | `image_publisher` 是一个 ROS 2 Jazzy 包。它使用本地路径发布 `image` ROS topic。有关更多信息，请参见 [image\_publisher](https://github.com/ros-perception/image_pipeline)。                |
| `qrb_ros_nn_inference`  | `qrb_ros_nn_inference` 是一个执行神经网络模型的 ROS 2 包，为机器人应用提供基于 AI 的感知能力。有关更多信息，请参见 [qrb\_ros\_nn\_inference](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference)。 |
| `qrb ros camera`        | `qrb ros camera` 是一个 ROS 2 包，使用参数捕获图像并将其发布到 ROS topic。有关更多信息，请参见 [qrb\_ros\_camera](https://github.com/qualcomm-qrb-ros/qrb_ros_camera)。                        |

## `sample_face_detection` 中使用的 ROS topic

| **ROS topic**                  | **类型**                                    | **发布者**                 |
| :----------------------------- | :---------------------------------------- | :---------------------- |
| `/mediaface_det_image`         | `sensor_msgs.msg.Image`                   | `qrb_ros_face_detector` |
| `/image_raw`                   | `sensor_msgs.msg.Image`                   | `image_publisher`       |
| `/face_detector_input_tensor`  | `qrb_ros_tensor_list_msgs.msg.TensorList` | `qrb_ros_face_detector` |
| `/face_detector_output_tensor` | `qrb_ros_tensor_list_msgs.msg.TensorList` | `qrb_ros_nn_inference`  |
| `/face_landmark_input_tensor`  | `qrb_ros_tensor_list_msgs.msg.TensorList` | `qrb_ros_face_detector` |
| `/face_landmark_output_tensor` | `qrb_ros_tensor_list_msgs.msg.TensorList` | `qrb_ros_nn_inference`  |

## 前提条件

你已完成 [设置运行示例应用的环境](./set-up-env-for-sample-app) 中的设置。

## 开箱即用运行 `sample_face_detection`

<Accordion title="试一试">
  <Steps>
    <Step title="在开发套件上运行示例">
      ```bash title="SSH Session" theme={null}
      # Set up the runtime environment
      source /usr/share/qirp-setup.sh -m
      # Set the ROS_DOMAIN_ID
      export ROS_DOMAIN_ID=xx # Value range of ROS_DOMAIN_ID: [0, 232]
      # Launch the sample face detection node with an image publisher, You can replace 'image_path' with the path to your desired image.
      ros2 launch sample_face_detection launch_with_image_publisher.py image_path:=/usr/ros/jazzy/share/sample_face_detection/face_image.jpg
      # Launch the sample face detection node with qrb ros camera
      ros2 launch sample_face_detection launch_with_qrb_ros_camera.py
      ```

      <Note>
        **注意**

        此示例应用仅支持 JPG 图像。你可以使用不同文件名的自有图像进行测试。
      </Note>
    </Step>

    <Step title="在主机计算机上查看结果">
      1. 启动 `rqt`。
         ```bash title="SSH Session" 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=xx # same as the preceding ID
         rqt
         ```
      2. 依次选择以下按钮：
         **Plugins** --> **Visualization** --> **Image View**
      3. 选择 `mediaface_det_image` 以查看结果。
    </Step>
  </Steps>
</Accordion>

## 构建并运行 `sample_face_detection`

以下步骤以 Dragonwing IQ-9075 Evaluation Kit 为例构建 `sample_face_detection` 包。

<Accordion title="试一试">
  <Steps>
    <Step title="在主机计算机上构建并打包">
      1. 构建示例应用项目。
         ```bash theme={null}
         cd <decompressed_workspace>/images/iq-9075-evk/qirpsdk_artifacts/iq-9075-evk/
         tar -zxvf qirp-sdk_<qirp_version>.tar.gz
         cd qirp-sdk
         source setup.sh
         # build sample
         cd <qirp_decompressed_path>/qirp-samples/ai_vision/sample_face_detection
         colcon build
         ```
      2. 打包并将示例应用推送到设备。
         ```bash theme={null}
         # package and push build result of sample
         cd <qirp_decompressed_path>/qirp-samples/ai_vision/sample_face_detection/install/sample_face_detection
         tar -czvf sample_face_detection.tar.gz lib share
         scp sample_face_detection.tar.gz root@[ip-addr]:/opt/
         ```
    </Step>

    <Step title="在开发套件上安装并运行">
      1. 安装示例应用。
         ```bash title="SSH Session" theme={null}
         # Install sample package
         tar --no-overwrite-dir --no-same-owner -zxf /opt/sample_face_detection.tar.gz -C /usr/ros/jazzy/
         ```
      2. 按照 [开箱即用运行 sample\_face\_detection](#run-out-of-the-box-sample_face_detection) 中的步骤运行示例应用。
    </Step>
  </Steps>
</Accordion>