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

# Detect faces with sample_face_detection

The `sample_face_detection` sample application detects faces and locates facial landmarks from images using the Python-based ROS 2 node `sample_face_detection`, which uses Qualcomm® AI Engine Direct SDK (QNN) for model inference.

The models are sourced from Qualcomm AI-hub. It captures the `face_image.jpg` as input and publishes the result to the `/mediaface_det_image` topic.

<Note>
  **Note**

  * For model information, see [MediaPipe-Face-Detection - Qualcomm AI Hub](https://aihub.qualcomm.com/iot/models/mediapipe_face?searchTerm=Media).

  * For details about the sample application, see [sample\_fact\_detection](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/ai_vision/sample_face_detection) on GitHub
</Note>

<video
  autoPlay
  muted
  loop
  playsInline
  width={768}
  height={432}
  src="https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/sample_face_detection_result.mp4?fit=max&auto=format&n=EDJV-hu6qJhZi4pm&q=85&s=8e025c1432d38f664a0d491fe1f3fe3d"
  style={{
width: "70%",
display: "block",
margin: "0 auto" }}
  data-path="SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/sample_face_detection_result.mp4"
/>

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  Figure: Sample effects of `sample_face_detection`
</p>

## Pipeline flow for `sample_face_detection`

<img src="https://mintcdn.com/qualcomm-prod/IP0o0G5fE3MFmCJ8/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/ga1.6-face-detection.drawio.svg?fit=max&auto=format&n=IP0o0G5fE3MFmCJ8&q=85&s=968fbb739ef1194448e337f36518f9ac" style={{width: "100%"}} width="1243" height="325" data-path="SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/ga1.6-face-detection.drawio.svg" />

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  Figure: Pipeline flow for `sample_face_detection`
</p>

## ROS nodes used in `sample_face_detection`

| **ROS node**            | **Description**                                                                                                                                                                                                                                       |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qrb_ros_face_detector` | The `qrb_ros_face_detector` is a Python-based ROS 2 jazzy package that processes face images. This ROS node subscribes to an image topic, and publishes the face image result topic after pre/post processing.                                        |
| `image_publisher`       | `image_publisher` is a ROS 2 Jazzy package. It publishes the `image` ROS topic with a local path. For more information, see [image\_publisher](https://github.com/ros-perception/image_pipeline).                                                     |
| `qrb_ros_nn_inference`  | `qrb_ros_nn_inference` is a ROS 2 package that performs neural network model, providing AI-based perception for robotics applications. For more information, see [qrb\_ros\_nn\_inference](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference). |
| `qrb ros camera`        | `qrb ros camera` is a ROS 2 package that captures images with parameters and publishes them to ROS topics. For more information, see [qrb\_ros\_camera](https://github.com/qualcomm-qrb-ros/qrb_ros_camera).                                          |

## ROS topics used in `sample_face_detection`

| **ROS Topic**                  | **Type**                                  | **Published By**        |
| :----------------------------- | :---------------------------------------- | :---------------------- |
| `/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`  |

## Prerequisites

You have completed the settings in [Set up the environment for running sample applications](./set-up-env-for-sample-app).

## Run out-of-the-box `sample_face_detection`

<Accordion title="Try me">
  <Steps>
    <Step title="Run the sample on the development kit">
      ```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>
        **Note**

        This sample application supports JPG images only. You can test it using one of your own images with a different filename.
      </Note>
    </Step>

    <Step title="View the results on the host computer">
      1. Start the `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. Select the following buttons in sequence:
         **Plugins** --> **Visualization** --> **Image View**
      3. Select `mediaface_det_image` to see the results.
    </Step>
  </Steps>
</Accordion>

## Build and run `sample_face_detection`

The following steps build the `sample_face_detection` package using Dragonwing IQ-9075 Evaluation Kit as an example.

<Accordion title="Try me">
  <Steps>
    <Step title="Build and package on the host computer">
      1. Build the sample application project.
         ```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. Package and push the sample application to the device.
         ```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="Install and run on the development kit">
      1. Install the sample application.
         ```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. Run the sample application with the steps in [Run out-of-the-box sample\_face\_detection](#run-out-of-the-box-sample_face_detection).
    </Step>
  </Steps>
</Accordion>