> ## 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 节点，使用 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)。
</Note>

下图展示了人脸检测结果的示例。

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image40.gif" style={{width: "60%"}} alt="Face detection result with a bounding box and a green facial landmark mesh overlaid on a person in a live camera view." />
</Frame>

## `sample_face_detection` 的管线流程

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

<Frame caption="sample_face_detection 管线。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image42.svg" alt="Face detection pipeline from image capture through the face detector, neural network inference, and landmark postprocessing to the result topic." />
</Frame>

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

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

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

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

下表列出了 `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_node`、`camera_node` |
| `/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`               |

## 前提条件

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

## 从人脸检测的源代码构建

当您需要修改示例代码时，可以从源代码构建人脸检测示例。设备端步骤包括安装依赖项、克隆源代码仓库并构建软件包。

### 设备端步骤

<Steps>
  <Step title="下载示例人脸检测模型">
    ```bash Download the models theme={null}
    mkdir -p /opt/model && cd /opt/model
    sudo wget https://huggingface.co/qualcomm/MediaPipe-Face-Detection/resolve/0dd669a326ec24a884e51b82741997299d937705/MediaPipeFaceDetector.bin -O MediaPipeFaceDetector.bin
    sudo wget https://huggingface.co/qualcomm/MediaPipe-Face-Detection/resolve/0dd669a326ec24a884e51b82741997299d937705/MediaPipeFaceLandmarkDetector.bin -O MediaPipeFaceLandmarkDetector.bin
    sudo wget https://raw.githubusercontent.com/zmurez/MediaPipePyTorch/65f2549ba35cd61dfd29f402f6c21882a32fabb1/anchors_face.npy -O anchors_face.npy
    ```
  </Step>

  <Step title="安装依赖项">
    ```bash Install the dependencies theme={null}
    sudo apt install ros-dev-tools
    sudo apt install ros-jazzy-qrb-ros-camera
    ```
  </Step>

  <Step title="从 qrb_ros_sample 仓库下载源代码并构建">
    ```bash Download and build 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
    cd ai_vision/sample_face_detection
    rosdep install -i --from-path src --rosdistro jazzy -y
    colcon build
    ```
  </Step>

  <Step title="运行 sample_face_detection 示例应用">
    ```bash Run the sample application theme={null}
    source install/setup.bash
    # You can use the default face image file
    ros2 launch sample_face_detection launch_with_image_publisher.py model_path:=/opt/model/
    # You can also replace this with a custom image file
    ros2 launch sample_face_detection launch_with_image_publisher.py image_path:=/opt/resource/xxx.jpg model_path:=/opt/model/
    # You can launch with qrb ros camera
    ros2 launch sample_face_detection launch_with_qrb_ros_camera.py  model_path:=/opt/model/
    ```
  </Step>
</Steps>