Guia de detecção de objetos para Python

A tarefa MediaPipe Object Detector permite detectar a presença e a localização de vários classes de objetos. Estas instruções mostram como usar o Detector de objetos em Python. O exemplo de código descrito nestas instruções está disponível em GitHub.

Para saber como essa tarefa funciona, confira a demonstração na Web. Para mais informações sobre os recursos, modelos e de configuração dessa tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo do Detector de objetos fornece uma implementação completa em Python para sua referência. Esse código ajuda a testar a tarefa começou a criar seu próprio app de classificação de texto. Você pode exibir, executar e editar o exemplo de código do detector de objetos; usando apenas seu navegador da Web.

Se você estiver implementando o Object Detector para Raspberry Pi, consulte a Exemplo do Raspberry Pi app.

Configuração

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

Pacotes

A tarefa Object Detector requer o pacote pip mediapipe. É possível instalar os pacotes necessários com os seguintes comandos:

$ python -m pip install mediapipe

Importações

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

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

Modelo

A tarefa MediaPipe Object Detector requer um modelo treinado que seja compatível com esse tarefa. Para mais informações sobre modelos treinados disponíveis para o detector de objetos, consulte na seção de visão geral da tarefa Modelos.

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

model_path = '/absolute/path/to/lite-model_efficientdet_lite0_detection_metadata_1.tflite'

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

Use a função create_from_options para criar a tarefa. A A função create_from_options aceita opções de configuração, incluindo modo, nome de exibição, localidade, número máximo de resultados, limite de confiança, lista de permissões e de bloqueio. Se você não definir uma opção de configuração, a tarefa usará o valor padrão. Para mais informações sobre as opções de configuração, consulte a seção Opções de configuração.

A tarefa Detector de objetos é compatível com vários tipos de dados de entrada: imagens estáticas, vídeos arquivos e streams de vídeo ao vivo. Escolha a guia correspondente aos dados de entrada para ver como criar a tarefa e executar a inferência.

Imagem

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    max_results=5,
    running_mode=VisionRunningMode.IMAGE)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

Vídeo

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    max_results=5,
    running_mode=VisionRunningMode.VIDEO)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

Transmissão ao vivo

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
DetectionResult = mp.tasks.components.containers.detections.DetectionResult
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

def print_result(result: DetectionResult, output_image: mp.Image, timestamp_ms: int):
    print('detection result: {}'.format(result))

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    max_results=5,
    result_callback=print_result)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...
    

Para um exemplo completo de como criar um detector de objetos 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:

Nome da opção Descrição Intervalo de valor Valor padrão
running_mode Define o modo de execução da tarefa. Existem três modos:

IMAGEM: o modo para entradas de imagem única.

VÍDEO: o modo para frames decodificados de um vídeo.

LIVE_STREAM: o modo de transmissão ao vivo da entrada dados de uma câmera, por exemplo. Neste modo, resultListener deve ser chamado para configurar um listener e receber resultados de forma assíncrona.
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
display_names Define o idioma dos rótulos a serem usados para nomes de exibição fornecidos no metadados do modelo da tarefa, se disponíveis. O padrão é en para inglês. É possível adicionar rótulos localizados aos metadados de um modelo personalizado usando a API Metadata Writer do TensorFlow Lite; Código da localidade en
max_results Define o número máximo opcional de resultados de detecção com maior pontuação como voltar. Qualquer número positivo -1 (todos os resultados são retornados)
score_threshold Define o limite de pontuação da previsão que substitui o fornecido no os metadados do modelo (se houver). Resultados abaixo desse valor são rejeitados. Qualquer flutuação Não definido
category_allowlist Define a lista opcional de nomes de categorias permitidos. Se não estiver vazio, resultados de detecção cujo nome de categoria não esteja neste conjunto serão que foram filtradas. Nomes de categorias duplicados ou desconhecidos são ignorados. Essa opção é mutuamente exclusiva com category_denylist e usando os dois resultarão em erro. Qualquer string Não definido
category_denylist Define a lista opcional de nomes de categorias que não são permitidos. Se não vazio, os resultados de detecção cujo nome de categoria estiver neste conjunto serão filtrados para fora. Nomes de categorias duplicados ou desconhecidos são ignorados. Essa opção é mutuamente exclusivo com category_allowlist e usar ambos resulta em um erro. Qualquer string Não definido

Preparar dados

Prepare sua entrada como um arquivo de imagem ou uma matriz numpy, e depois converter em um objeto mediapipe.Image. Se a entrada for um arquivo de vídeo ou transmissão ao vivo por webcam, é possível usar uma biblioteca externa, como OpenCV para carregar os frames de entrada como numpy matrizes de dados.

Os exemplos a seguir explicam e mostram como preparar os dados para o processamento para cada um dos tipos de dados disponíveis:

Imagem

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)
    

Vídeo

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)
    

Transmissão ao vivo

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

É possível chamar uma das funções de detecção para acionar inferências. O objeto A tarefa do detector retornará os objetos detectados na imagem de entrada ou no frame.

Imagem

# Perform object detection on the provided single image.
detection_result = detector.detect(mp_image)
    

Vídeo

# Calculate the timestamp of the current frame
frame_timestamp_ms = 1000 * frame_index / video_file_fps

# Perform object detection on the video frame.
detection_result = detector.detect_for_video(mp_image, frame_timestamp_ms)
    

Transmissão ao vivo

# Send the latest frame to perform object detection.
# Results are sent to the `result_callback` provided in the `ObjectDetectorOptions`.
detector.detect_async(mp_image, frame_timestamp_ms)
    

Para um exemplo completo de como executar um detector de objetos em uma imagem, consulte o exemplo de código para mais detalhes.

Observe o seguinte:

  • Ao executar nos modos de vídeo ou de transmissão ao vivo, você também precisa forneça à tarefa do Object Detector o carimbo de data/hora do frame de entrada.
  • Ao ser executada na imagem ou no modelo de vídeo, a tarefa do detector de objetos bloquear a linha de execução atual até que ela termine de processar a imagem de entrada ou frame.
  • Quando executada no modo de transmissão ao vivo, a tarefa "Detector de objetos" não bloqueia thread atual, mas retorna imediatamente. Ele vai invocar seu resultado com o resultado da detecção sempre que ele terminar de processar um erro. frame de entrada. Se a função de detecção for chamada quando a tarefa do Detector de objetos estiver ocupado processando outro frame, o novo frame de entrada será ignorado.

Gerenciar e exibir resultados

Ao executar a inferência, a tarefa Detector de objetos retorna um Objeto ObjectDetectionResult que descreve os objetos encontrados em a imagem de entrada.

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

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

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

O código de exemplo do Object Detector demonstra como exibir a detecção resultados retornados da tarefa, consulte a exemplo de código para mais detalhes.