Guía de detección de puntos de referencia facial para Python

La tarea de MediaPipe Face Landmarker te permite detectar puntos de referencia faciales y expresiones faciales en imágenes y videos. Puedes usar esta tarea para identificar expresiones faciales humanas y aplicar filtros y efectos faciales para crear un avatar virtual. En esta tarea, se usan modelos de aprendizaje automático (AA) que pueden funcionar con imágenes individuales o una transmisión continua de imágenes. La tarea genera puntos de referencia faciales en 3 dimensiones, puntuaciones de formas de combinación (coeficientes que representan la expresión facial) para inferir superficies faciales detalladas en tiempo real y matrices de transformación para realizar las transformaciones necesarias para la renderización de efectos.

La muestra de código que se describe en estas instrucciones está disponible en GitHub. Para obtener más información sobre las funciones, los modelos y las opciones de configuración de esta tarea, consulta la descripción general.

Ejemplo de código

El código de ejemplo de Face Landmarker proporciona una implementación completa de esta tarea en Python como referencia. Este código te ayuda a probar esta tarea y comenzar a compilar tu propio marcador de rostros. Puedes ver, ejecutar y editar el código de ejemplo de Face Landmarker solo con tu navegador web.

Si implementas el detector de puntos de referencia faciales para Raspberry Pi, consulta la app de ejemplo para Raspberry Pi.

Configuración

En esta sección, se describen los pasos clave para configurar tu entorno de desarrollo y codificar proyectos específicamente para usar Face Landmarker. Para obtener información general sobre cómo configurar tu entorno de desarrollo para usar tareas de MediaPipe, incluidos los requisitos de la versión de la plataforma, consulta la Guía de configuración de Python.

Paquetes

La tarea de MediaPipe Face Landmarker requiere el paquete mediapipe de PyPI. Puedes instalar y importar estas dependencias con lo siguiente:

$ python -m pip install mediapipe

Importaciones

Importa las siguientes clases para acceder a las funciones de tareas de Face Landmarker:

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

Modelo

La tarea de MediaPipe Face Landmarker requiere un modelo entrenado que sea compatible con esta tarea. Para obtener más información sobre los modelos entrenados disponibles para Face Landmarker, consulta la sección Modelos de la descripción general de la tarea.

Selecciona y descarga el modelo, y guárdalo en un directorio local:

model_path = '/absolute/path/to/face_landmarker.task'

Usa el parámetro model_asset_path del objeto BaseOptions para especificar la ruta de acceso del modelo que se usará. Para ver un ejemplo de código, consulta la siguiente sección.

Crea la tarea

La tarea de MediaPipe Face Landmarker usa la función create_from_options para configurar la tarea. La función create_from_options acepta valores para que las opciones de configuración los controlen. Para obtener más información sobre las opciones de configuración, consulta Opciones de configuración.

En el siguiente código, se muestra cómo compilar y configurar esta tarea.

En estos ejemplos, también se muestran las variaciones de la construcción de tareas para imágenes, archivos de video y transmisiones en vivo.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.IMAGE)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face landmarker instance with the video mode:
options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.VIDEO)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
FaceLandmarkerResult = mp.tasks.vision.FaceLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face landmarker instance with the live stream mode:
def print_result(result: FaceLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('face landmarker result: {}'.format(result))

options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

Para ver un ejemplo completo de cómo crear un marcador de rostro para usarlo con una imagen, consulta el ejemplo de código.

Opciones de configuración

Esta tarea tiene las siguientes opciones de configuración para aplicaciones de Python:

Preparar los datos

Prepara tu entrada como un archivo de imagen o un array de numpy y, luego, conviértela en un objeto mediapipe.Image. Si tu entrada es un archivo de video o una transmisión en vivo desde una cámara web, puedes usar una biblioteca externa, como OpenCV, para cargar tus fotogramas de entrada como arrays de numpy.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

Ejecuta la tarea

El detector de puntos de referencia faciales usa las funciones detect, detect_for_video y detect_async para activar inferencias. En el caso de la detección de puntos de referencia de rostros, esto implica el procesamiento previo de los datos de entrada y la detección de rostros en la imagen.

En el siguiente código, se muestra cómo ejecutar el procesamiento con el modelo de tareas.

# Perform face landmarking on the provided single image.
# The face landmarker must be created with the image mode.
face_landmarker_result = landmarker.detect(mp_image)
    

# Perform face landmarking on the provided single image.
# The face landmarker must be created with the video mode.
face_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform face landmarking.
# The results are accessible via the `result_callback` provided in
# the `FaceLandmarkerOptions` object.
# The face landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)
    

Ten en cuenta lo siguiente:

• Cuando se ejecuta en el modo de video o en el modo de transmisión en vivo, también se debe proporcionar a la tarea de Face Landmarker la marca de tiempo del fotograma de entrada.
• Cuando se ejecuta en el modelo de imagen o video, la tarea de Face Landmarker bloquea el subproceso actual hasta que termina de procesar la imagen o el fotograma de entrada.
• Cuando se ejecuta en el modo de transmisión en vivo, la tarea de Face Landmarker se muestra de inmediato y no bloquea el subproceso actual. Invocará al objeto de escucha de resultados con el resultado de la detección cada vez que termine de procesar un fotograma de entrada. Si se llama a la función de detección cuando la tarea de Face Landmarker está ocupada procesando otro fotograma, la tarea ignorará el nuevo fotograma de entrada.

Para ver un ejemplo completo de cómo ejecutar un marcador de rostro en una imagen, consulta el ejemplo de código para obtener más información.

Cómo controlar y mostrar los resultados

El marcador de rostros muestra un objeto FaceLandmarkerResult para cada ejecución de detección. El objeto de resultado contiene una malla de rostro para cada rostro detectado, con coordenadas para cada punto de referencia del rostro. De manera opcional, el objeto de resultado también puede contener formas de combinación, que denotan expresiones faciales, y una matriz de transformación facial para aplicar efectos faciales en los puntos de referencia detectados.

A continuación, se muestra un ejemplo de los datos de resultado de esta tarea:

FaceLandmarkerResult:
  face_landmarks:
    NormalizedLandmark #0:
      x: 0.5971359014511108
      y: 0.485361784696579
      z: -0.038440968841314316
    NormalizedLandmark #1:
      x: 0.3302789330482483
      y: 0.29289937019348145
      z: -0.09489090740680695
    ... (478 landmarks for each face)
  face_blendshapes:
    browDownLeft: 0.8296722769737244
    browDownRight: 0.8096957206726074
    browInnerUp: 0.00035583582939580083
    browOuterUpLeft: 0.00035752105759456754
    ... (52 blendshapes for each face)
  facial_transformation_matrixes:
    [9.99158978e-01, -1.23036895e-02, 3.91213447e-02, -3.70770246e-01]
    [1.66496094e-02,  9.93480563e-01, -1.12779640e-01, 2.27719707e+01]
    ...

En la siguiente imagen, se muestra una visualización del resultado de la tarea:

En el código de ejemplo de Face Landmarker, se muestra cómo mostrar los resultados que muestra la tarea. Consulta el ejemplo de código para obtener más información.