hri_face_detect

A ROS4HRI-compiant ROS node to perform fast face detection using YuNet face detector and Mediapipe Face Mesh. The former performs well at greater distances (depending on image resolution and image scaling applied) and extracts 5 keypoints. The latter works only at close distances and extracts all the ROS4HRI-defined landmarks.

Installing dependencies

If you are running this package outside PAL, first install all the dependencies:

pip install -r requirements.txt

ROS API

Parameters

All parameters are loaded in the lifecycle configuration transition.

• processing_rate (int, default: 30): Image processing logic execution rate in Hertz.

• image_compressed (bool, default: false): Selects the compressed image transport.

• face_mesh (bool, default: true): It enables the additional Mediapipe Face Mesh detection.

• confidence_threshold (double, default: 0.75): Candidate face detections with confidence lower that this threshold are not published.

• image_scale (double, default: 0.5): The YuNet face detector accepts input image of dynamic size. This parameter controls the rescale factor applied to the input image before running the YuNet face detector. Lower image scale results in less processing time required and lower detection confidences. The output data (e.g., RoI) is invariant with this parameter and always refers to the original input image size.

• filtering_frame (string, default: “camera_color_optical_frame”): The reference frame the estimated face pose should be transformed to before performing the filtering operations. Due to the proximity between the camera frame and the detected faces, and considering that cameras can be mounted on frequently moving robot’s components (e.g., robot’s head), directly filtering a face pose expressed in camera optical frame might reduce the filtering quality.

• deterministic_ids (bool, default: false): If true the face ids start from “f00000” and increases by one for each new face. If false it is a random five letters sequence.

• debug (bool, default: false): If true opens a windows showing the input image with face detections overlayed.

Topics

This package follows the ROS4HRI conventions (REP-155). If the topic message type is not indicated, the ROS4HRI convention is implied.

Subscribed

• image (sensor_msgs/msg/Image): only if image_compressed is false
• image/compressed (sensor_msgs/msg/CompressedImage): only if image_compressed is true; note that the suffix /compressed is added after the remapping is resolved, so you should remap only image regardless of the image_compressed value.
• camera_info (sensor_msgs/msg/CameraInfo)

Published

• /humans/faces/<faceID>/roi
• /humans/faces/<faceID>/landmarks
• /humans/faces/<faceID>/cropped
• /humans/faces/<faceID>/aligned
• /humans/faces/tracked
• /diagnostics (diagnostic_msgs/msg/DiagnosticArray)

Execution

ros2 launch hri_face_detect hri_face_detect.launch.py

Example

For an example of usage, execute in different terminals:

• USB camera:
  1. apt install ros-humble-usb-cam
  2. ros2 run usb_cam usb_cam_node_exe --ros-args -p pixel_format:="mjpeg2rgb"
• HRI face detect:
  1. apt install ros-humble-hri-face-detect

File truncated at 100 lines see the full file

Changelog for package hri_face_detect

2.2.2 (2025-07-09)

• Add diagnostic analyzers
• Contributors: Noel Jimenez

2.2.1 (2025-05-02)

• shutdown the whole launch file on crash
• Contributors: Séverin Lemaignan

2.2.0 (2024-12-05)

• use consistent default image topic
• Contributors: Luka Juricic

2.1.0 (2024-12-04)

• use uncompressed images by default
• use launch file with pal args
• add compressed image support
• Readme
• Pip requirements for running the package outside PAL
• Contributors: Luka Juricic, Oscar Martinez

2.0.10 (2024-09-16)

• use python3-mediapipe-pip on non-PAL environments While here, add missing dep on cv_bridge
• Contributors: Séverin Lemaignan

2.0.9 (2024-09-09)

• fixed quality of service camera-related subscribers
• Contributors: lorenzoferrini

2.0.8 (2024-08-19)

• rename diagnostics msg to match documentation (and diagnostic_aggregator) categories
• Contributors: Séverin Lemaignan

2.0.7 (2024-07-04)

• linting
• Contributors: Séverin Lemaignan

2.0.6 (2024-07-04)

• launch: use get_pal_configuration from launch_pal
• expose the 'deterministic_ids' in the _with_args launch file
• Contributors: Séverin Lemaignan

2.0.5 (2024-05-24)

• Removed quotes from topic values
• Contributors: Raquel Ros

2.0.4 (2024-05-23)

• fix configuration node name
• fix get _pal_configuration
• Contributors: Luka Juricic

2.0.3 (2024-05-08)

• [launch] impl logic to load overlaid parameters This commit:

  • add (and install) default parameters values in config/00-defaults.yml
  • rename (unchanged) launch/face_detect.launch.py to launch/face_detect_with_args.launch.py

  - add a new launch/face_detect.launch.py that implements the PAPS-007 logic to fetch possible parameters, remappings and node arguments via ament_index

• Contributors: Séverin Lemaignan

2.0.2 (2024-04-24)

• add pal module
• Contributors: Luka Juricic

2.0.1 (2024-02-06)

• fix image calibration K name to lowercase k. This caused the publication of TF frames to be broken.
• assign default score detection in case of mesh detection
• add usage example to README
• Contributors: Luka Juricic

2.0.0 (2024-01-18)

• port to ROS 2 Humble
• change license to apache2
• change folder structure
• Contributors: Luka Juricic

File truncated at 100 lines see the full file