Guida al rilevamento dei punti di riferimento dei volti per Python

L'attività MediaPipe Face Landmarker consente di rilevare punti di riferimento del viso ed espressioni facciali in immagini e video. Puoi utilizzare questa attività per identificare le espressioni facciali umane e applicare filtri ed effetti per il viso per creare un avatar virtuale. Questa attività utilizza modelli di machine learning (ML) che possono funzionare con singole immagini o con uno stream continuo di immagini. L'attività genera punti di riferimento del viso tridimensionali, punteggi di blendshape (coefficienti che rappresentano l'espressione facciale) per dedurre superfici del viso dettagliate in tempo reale e matrici di trasformazione per eseguire le trasformazioni necessarie per il rendering degli effetti.

L'esempio di codice descritto in queste istruzioni è disponibile su GitHub. Per ulteriori informazioni sulle funzionalità, sui modelli e sulle opzioni di configurazione di questa attività, consulta la Panoramica.

Esempio di codice

Il codice di esempio per il rilevamento dei punti di riferimento del volto fornisce un'implementazione completa di questa attività in Python come riferimento. Questo codice ti aiuta a testare questa attività e a iniziare a creare il tuo indicatore di punti di riferimento del viso. Puoi visualizzare, eseguire e modificare il codice di esempio di Face Landmarker utilizzando solo il browser web.

Se stai implementando il rilevamento dei punti di riferimento del volto per Raspberry Pi, consulta l'app di esempio per Raspberry Pi.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo e i progetti di codice specificamente per utilizzare Face Landmarker. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività MediaPipe, inclusi i requisiti della versione della piattaforma, consulta la guida alla configurazione per Python.

Pacchetti

L'attività MediaPipe Face Landmarker richiede il pacchetto PyPI mediapipe. Puoi installare e importare queste dipendenze con quanto segue:

$ python -m pip install mediapipe

Importazioni

Importa le seguenti classi per accedere alle funzioni di attività di rilevamento dei punti di riferimento del viso:

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

Modello

L'attività di rilevamento dei punti di riferimento del viso di MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per Face Landmarker, consulta la sezione Modelli della panoramica dell'attività.

Seleziona e scarica il modello, quindi memorizzalo in una directory locale:

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

Utilizza il parametro BaseOptions dell'oggetto model_asset_path per specificare il percorso del modello da utilizzare. Per un esempio di codice, consulta la sezione successiva.

Crea l'attività

Il compito MediaPipe Face Landmarker utilizza la funzione create_from_options per configurare il compito. La funzione create_from_options accetta valori per le opzioni di configurazione da gestire. Per ulteriori informazioni sulle opzioni di configurazione, consulta Opzioni di configurazione.

Il codice seguente mostra come creare e configurare questa attività.

Questi esempi mostrano anche le varianti della costruzione dell'attività per immagini, file video e live streaming.

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

Per un esempio completo di creazione di un rilevamento di punti di riferimento del viso da utilizzare con un'immagine, consulta l'esempio di codice.

Opzioni di configurazione

Questa attività ha le seguenti opzioni di configurazione per le applicazioni Python:

Preparazione dei dati

Prepara l'input come file immagine o array numpy, quindi convertilo in un oggetto mediapipe.Image. Se l'input è un file video o un live streaming da una webcam, puoi utilizzare una libreria esterna come OpenCV per caricare i frame di input come array 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)
    

Esegui l'attività

Il rilevamento dei punti di riferimento del viso utilizza le funzioni detect, detect_for_video e detect_async per attivare le deduzioni. Per il rilevamento dei punti di riferimento del volto, è necessario pre-elaborare i dati di input e rilevare i volti nell'immagine.

Il seguente codice mostra come eseguire l'elaborazione con il modello di attività.

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

Tieni presente quanto segue:

• Quando esegui l'operazione in modalità video o live streaming, fornisci anche all'attività di rilevamento dei punti di riferimento del viso il timestamp del frame di input.
• Quando viene eseguito nel modello di immagine o video, il compito di rilevamento dei punti di riferimento del volto blocca il thread corrente fino al termine dell'elaborazione dell'immagine o dell'inquadratura di input.
• Quando viene eseguita in modalità live streaming, l'attività di rilevamento dei punti di riferimento del volto restituisce immediatamente il risultato e non blocca il thread corrente. Evocherà l'ascoltatore dei risultati con il risultato del rilevamento ogni volta che termina l'elaborazione di un frame di input. Se la funzione di rilevamento viene chiamata quando l'attività Face Landmarker è impegnata a elaborare un altro frame, l'attività ignorerà il nuovo frame di input.

Per un esempio completo di esecuzione di un rilevamento di punti di riferimento del volto su un'immagine, consulta l'esempio di codice per maggiori dettagli.

Gestire e visualizzare i risultati

L'elemento Face Landmarker restituisce un oggetto FaceLandmarkerResult per ogni esecuzione del rilevamento. L'oggetto risultato contiene un mesh del volto per ogni volto rilevato, con le coordinate di ogni punto di riferimento del volto. Se vuoi, l'oggetto risultato può anche contenere blendshape, che indicano le espressioni facciali, e una matrice di trasformazione facciale per applicare effetti sul viso ai punti di riferimento rilevati.

Di seguito è riportato un esempio dei dati di output di questa attività:

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

L'immagine seguente mostra una visualizzazione dell'output dell'attività:

Il codice di esempio di Face Landmarker mostra come visualizzare i risultati restituiti dall'attività. Per maggiori dettagli, consulta l'esempio di codice.