Guia de detecção de pontos de referência facial para Python

A tarefa MediaPipe Face Landmarker permite detectar pontos de referência do rosto e expressões faciais em imagens e vídeos. Você pode usar essa tarefa para identificar expressões faciais humanas e aplicar filtros e efeitos faciais para criar um avatar virtual. Esta tarefa usa modelos de aprendizado de máquina (ML) que podem funcionar com imagens únicas ou um fluxo contínuo de imagens. A tarefa gera pontos de referência faciais tridimensionais, pontuações de blendshape (coeficientes que representam a expressão facial) para inferir superfícies faciais detalhadas em tempo real e matrizes de transformação para realizar as transformações necessárias para a renderização de efeitos.

O exemplo de código descrito nestas instruções está disponível no GitHub. Para mais informações sobre os recursos, modelos e opções de configuração desta tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo para o Face Landmarker oferece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda a testar essa tarefa e a criar seu próprio marcador de rosto. Você pode conferir, executar e editar o código de exemplo do Face Landmarker usando apenas seu navegador da Web.

Se você estiver implementando o Face Landmarker para Raspberry Pi, consulte o app de exemplo Raspberry Pi.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Face Landmarker. Para informações gerais sobre como configurar o ambiente de desenvolvimento para usar as tarefas do MediaPipe, incluindo os requisitos da versão da plataforma, consulte o Guia de configuração para Python.

Pacotes

A tarefa do MediaPipe Face Landmarker requer o pacote PyPI do MediaPipe. É possível instalar e importar essas dependências com o seguinte:

$ python -m pip install mediapipe

Importações

Importe as classes a seguir para acessar as funções de tarefa do Face Landmarker:

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

Modelo

A tarefa do MediaPipe Face Landmarker requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Face Landmarker, consulte a seção "Modelos" da visão geral da tarefa.

Selecione e faça o download do modelo e armazene-o em um diretório local:

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

Use o parâmetro model_asset_path do objeto BaseOptions para especificar o caminho do modelo a ser usado. Para conferir um exemplo de código, consulte a próxima seção.

Criar a tarefa

A tarefa do MediaPipe Face Landmarker usa a função create_from_options para configurar a tarefa. A função create_from_options aceita valores para opções de configuração. Para mais informações sobre as opções de configuração, consulte Opções de configuração.

O código a seguir demonstra como criar e configurar essa tarefa.

Esses exemplos também mostram as variações da construção de tarefas para imagens, arquivos de vídeo e transmissão ao 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 conferir um exemplo completo de como criar um marcador de rosto para uso com uma imagem, consulte o exemplo de código.

Opções de configuração

Esta tarefa tem as seguintes opções de configuração para aplicativos Python:

Preparar dados

Prepare a entrada como um arquivo de imagem ou uma matriz NumPy e converta-a em um objeto mediapipe.Image. Se a entrada for um arquivo de vídeo ou uma transmissão ao vivo de uma webcam, use uma biblioteca externa, como o OpenCV, para carregar os frames de entrada como matrizes 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)
    

Executar a tarefa

O Face Landmarker usa as funções detect, detect_for_video e detect_async para acionar inferências. Para a detecção de características faciais, isso envolve pré-processar os dados de entrada e detectar rostos na imagem.

O código abaixo demonstra como executar o processamento com o modelo de tarefas.

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

Observe o seguinte:

• Ao executar no modo de vídeo ou de transmissão ao vivo, forneça também o carimbo de data/hora do frame de entrada para a tarefa do Face Landmarker.
• Ao ser executada no modelo de imagem ou vídeo, a tarefa de detecção de pontos faciais bloqueia a linha de execução atual até que ela termine de processar a imagem ou o frame de entrada.
• Quando executada no modo de transmissão ao vivo, a tarefa de detecção de pontos faciais é retornada imediatamente e não bloqueia a linha de execução atual. Ele invoca o listener de resultado com o resultado da detecção sempre que termina de processar um frame de entrada. Se a função de detecção for chamada quando a tarefa do Face Landmarker estiver ocupada processando outro frame, a tarefa vai ignorar o novo frame de entrada.

Para conferir um exemplo completo de execução de um Face Landmarker em uma imagem, consulte o exemplo de código para saber mais.

Processar e mostrar resultados

O Face Landmarker retorna um objeto FaceLandmarkerResult para cada execução de detecção. O objeto de resultado contém uma malha de rosto para cada rosto detectado, com coordenadas para cada ponto de referência do rosto. Opcionalmente, o objeto de resultado também pode conter blendshapes, que denotam expressões faciais, e uma matriz de transformação facial para aplicar efeitos faciais nos pontos de referência detectados.

Confira a seguir um exemplo dos dados de saída desta tarefa:

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

A imagem a seguir mostra uma visualização da saída da tarefa:

O código de exemplo do Face Landmarker demonstra como exibir os resultados retornados pela tarefa. Consulte o exemplo de código para mais detalhes.