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

A tarefa do MediaPipe Face Pointser permite detectar pontos de referência do rosto e expressões faciais em imagens e vídeos. É possível usar essa tarefa para identificar expressões faciais humanas e aplicar filtros e efeitos faciais para criar um avatar virtual. Essa tarefa usa modelos de machine learning (ML) que funcionam com imagens únicas ou um fluxo contínuo de imagens. A tarefa gera pontos de referência tridimensionais de rostos, pontuações de mesclagem (coeficientes que representam expressão facial) para inferir superfícies faciais detalhadas em tempo real e gera 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 dessa tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo do Face extras fornece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda você a testar essa tarefa e começar a criar seu próprio ponto de referência de rosto. É possível visualizar, executar e editar o código de exemplo do Face extras (link em inglês) usando apenas seu navegador da Web.

Se você estiver implementando o Rospberry Pi, consulte o app de exemplo do Raspberry Pi (link em inglês).

Configuração

Nesta seção, descrevemos as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código para usar o recurso de reconhecimento facial. Para informações gerais sobre a configuração do ambiente de desenvolvimento para uso de tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para Python.

Pacotes

A tarefa MediaPipe Face Framework 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 seguintes classes para acessar as funções da tarefa do Ponto de referência do rosto:

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

Modelo

A tarefa do MediaPipe Face Framework requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o ponto de referência facial, consulte a seção Modelos de 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. Confira um exemplo de código na próxima seção.

Criar a tarefa

A tarefa do MediaPipe Face extras usa a função create_from_options para configurar a tarefa. A função create_from_options aceita valores a serem processados pelas 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 de construção da tarefa 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 ponto de referência facial 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 sua entrada como um arquivo de imagem ou uma matriz numpy e a converta em um objeto mediapipe.Image. Se a entrada for um arquivo de vídeo ou uma transmissão ao vivo de uma webcam, você poderá usar uma biblioteca externa, como 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 Ponto de referência facial usa as funções detect, detect_for_video e detect_async para acionar inferências. Para o ponto de referência de rostos, isso envolve o pré-processamento de dados de entrada e a detecção de rostos na imagem.

O código a seguir demonstra como executar o processamento com o modelo de tarefa.

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

• Quando a execução é feita no modo de vídeo ou de transmissão ao vivo, forneça também à tarefa do Face Summary (link em inglês) o carimbo de data/hora do frame de entrada.
• Quando executada no modelo de imagem ou vídeo, a tarefa "Marco de rostos" bloqueia a linha de execução atual até terminar de processar a imagem ou o frame de entrada.
• Quando executada no modo de transmissão ao vivo, a tarefa "Marco do rosto" retorna imediatamente e não bloqueia a linha de execução atual. Ele vai invocar o listener de resultados com o resultado da detecção sempre que terminar de processar um frame de entrada. Se a função de detecção for chamada quando a tarefa do Face Markdown estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.

Para conferir um exemplo completo da execução de um ponto de referência facial em uma imagem, consulte o exemplo de código (link em inglês) para mais detalhes.

Gerenciar e mostrar resultados

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

Veja a seguir um exemplo dos dados de saída dessa 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 abaixo mostra uma visualização da saída da tarefa:

O código de exemplo do Marcador de rosto demonstra como mostrar os resultados retornados da tarefa. Consulte o exemplo de código para mais detalhes.