Guia de detecção facial para Python

A tarefa Detector de rostos do MediaPipe permite detectar rostos em uma imagem ou um vídeo. Você pode usar essa tarefa para localizar rostos e características faciais em um frame. Essa tarefa usa um modelo de machine learning (ML) que funciona com imagens únicas ou um fluxo contínuo de imagens. A tarefa mostra localizações de rostos, com os seguintes pontos-chave faciais: olho esquerdo, olho direito, ponta do nariz, boca, tradição do olho esquerdo e trágico do olho direito.

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 Detector fornece uma implementação completa dessa tarefa em Python para sua referência. O código ajuda você a testar essa tarefa e começar a criar seu próprio detector facial. É possível visualizar, executar e editar o código de exemplo do Detector de rostos usando apenas seu navegador da Web.

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

Configuração

Nesta seção, descrevemos as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código para usar o Face Detector. Para informações gerais sobre a configuração do ambiente de desenvolvimento para o 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 Detector requer o pacote PyPI do mediaPipe. Você pode instalar e importar essas dependências com o seguinte comando:

$ python -m pip install mediapipe

Importações

Importe as seguintes classes para acessar as funções da tarefa do Detector de rostos:

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

Modelo

A tarefa do detector facial do MediaPipe requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Face Detector, 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_detector.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 detector facial do MediaPipe usa a função create_from_options para configurar a tarefa. A função create_from_options aceita valores para as opções de configuração processar. 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
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the image mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the video mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
FaceDetectorResult = mp.tasks.vision.FaceDetectorResult
VisionRunningMode = mp.tasks.vision.RunningMode

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

options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

Para conferir um exemplo completo de como criar um detector facial para usar 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, use uma biblioteca externa, como a OpenCV (link em inglês), 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 Detector usa as funções detect, detect_for_video e detect_async para acionar inferências. A detecção facial 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 detection on the provided single image.
# The face detector must be created with the image mode.
face_detector_result = detector.detect(mp_image)
    

# Perform face detection on the provided single image.
# The face detector must be created with the video mode.
face_detector_result = detector.detect_for_video(mp_image, frame_timestamp_ms)
    

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

Observe o seguinte:

• Quando executado no modo de vídeo ou de transmissão ao vivo, forneça também à tarefa do Face Detector o carimbo de data/hora do frame de entrada.
• Quando executada no modelo de imagem ou vídeo, a tarefa do Face Detector 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 do Face Detector 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 detector facial estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.

Para conferir um exemplo completo da execução de um Face Detector em uma imagem, consulte o exemplo de código.

Gerenciar e mostrar resultados

O Face Detector retorna um objeto FaceDetectorResult para cada execução de detecção. O objeto de resultado contém caixas delimitadoras para os rostos detectados e uma pontuação de confiança para cada um deles.

Veja a seguir um exemplo dos dados de saída dessa tarefa:

FaceDetectionResult:
  Detections:
    Detection #0:
      BoundingBox:
        origin_x: 126
        origin_y: 100
        width: 463
        height: 463
      Categories:
        Category #0:
          index: 0
          score: 0.9729152917861938
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.18298381567001343
          y: 0.2961040139198303
        NormalizedKeypoint #1:
          x: 0.3302789330482483
          y: 0.29289937019348145
        ... (6 keypoints for each face)
    Detection #1:
      BoundingBox:
        origin_x: 616
        origin_y: 193
        width: 430
        height: 430
      Categories:
        Category #0:
          index: 0
          score: 0.9251380562782288
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.6151331663131714
          y: 0.3713381886482239
        NormalizedKeypoint #1:
          x: 0.7460576295852661
          y: 0.38825345039367676
        ... (6 keypoints for each face)

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

Para a imagem sem caixas delimitadoras, consulte a imagem original.

O código de exemplo do Detector de rostos demonstra como exibir os resultados retornados da tarefa. Consulte o exemplo de código para mais detalhes.