Guia de incorporação de imagens para Python

A tarefa MediaPipe Image Embedder permite converter dados de imagem em uma representação numérica para realizar tarefas de processamento de imagens relacionadas ao ML, como comparar a semelhança de duas imagens. Estas instruções mostram como usar o incorporador de imagens com o Python.

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 incorporador de imagens oferece 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 incorporador de imagem. É possível ver, executar e editar o exemplo de código do Image Embedder usando apenas seu navegador da Web com o Google Colab. Confira o código-fonte deste exemplo no GitHub.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Image Embedder. 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 do incorporador de imagens é o pacote pipe pipe. Você pode instalar a dependência com o seguinte:

$ python -m pip install mediapipe

Importações

Importe as seguintes classes para acessar as funções da tarefa Incorporador de imagens:

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

Modelo

A tarefa MediaPipe Image Embedder requer um modelo treinado compatível com ela. Para mais informações sobre os modelos treinados disponíveis para o incorporador de imagens, consulte a seção Modelos de visão geral da tarefa.

Selecione e faça o download de um modelo e armazene-o em um diretório local. É possível usar o modelo MobileNetV3 recomendado.

model_path = '/absolute/path/to/mobilenet_v3_small_075_224_embedder.tflite'

Especifique o caminho do modelo dentro do parâmetro model_asset_path, conforme mostrado abaixo:

base_options = BaseOptions(model_asset_path=model_path)

Criar a tarefa

Use a função create_from_options para criar a tarefa. A função create_from_options aceita opções de configuração para definir as opções do incorporador. Para mais informações sobre as opções de configuração, consulte Visão geral da configuração.

A tarefa Incorporador de imagens oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e streams de vídeo ao vivo. Escolha a guia correspondente ao tipo de dados de entrada para conferir como criar a tarefa e executar a inferência.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ImageEmbedder = mp.tasks.vision.ImageEmbedder
ImageEmbedderOptions = mp.tasks.vision.ImageEmbedderOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ImageEmbedderOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    quantize=True,
    running_mode=VisionRunningMode.IMAGE)

with ImageEmbedder.create_from_options(options) as embedder:
  # The embedder is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ImageEmbedder = mp.tasks.vision.ImageEmbedder
ImageEmbedderOptions = mp.tasks.vision.ImageEmbedderOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ImageEmbedderOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    quantize=True,
    running_mode=VisionRunningMode.VIDEO)

with ImageEmbedder.create_from_options(options) as embedder:
  # The embedder is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ImageEmbedderResult = mp.tasks.vision.ImageEmbedder.ImageEmbedderResult
ImageEmbedder = mp.tasks.vision.ImageEmbedder
ImageEmbedderOptions = mp.tasks.vision.ImageEmbedderOptions
VisionRunningMode = mp.tasks.vision.RunningMode

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

options = ImageEmbedderOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    quantize=True,
    result_callback=print_result)

with ImageEmbedder.create_from_options(options) as embedder:
  # The embedder is initialized. Use it here.
  # ...
    

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

É possível chamar a função de incorporação correspondente ao modo de execução para acionar inferências. A API Image Embedder retorna os vetores de embedding para a imagem ou o frame de entrada.

# Perform image embedding on the provided single image.
embedding_result = embedder.embed(mp_image)
    

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

# Perform image embedding on the video frame.
embedding_result = embedder.embed_for_video(mp_image, frame_timestamp_ms)
    

# Send the latest frame to perform image embedding.
# Results are sent to the `result_callback` provided in the `ImageEmbedderOptions`.
embedder.embed_async(mp_image, frame_timestamp_ms)
    

Observe o seguinte:

• Ao executar no modo de vídeo ou de transmissão ao vivo, também é necessário fornecer à tarefa de incorporação de imagens o carimbo de data/hora do frame de entrada.
• Quando executada no modelo de imagem ou de vídeo, a tarefa de incorporação de imagens 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 incorporação de imagens não bloqueia a linha de execução atual, mas retorna imediatamente. Ele invoca o listener de resultados com o resultado de incorporação sempre que termina de processar um frame de entrada. Se a função embedAsync for chamada quando a tarefa do incorporador de imagens estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.

Gerenciar e mostrar resultados

Ao executar a inferência, a tarefa de incorporação de imagens retorna um objeto ImageEmbedderResult que contém a lista de categorias possíveis para os objetos na imagem de entrada ou no frame.

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

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

Este resultado foi obtido com a incorporação da seguinte imagem:

Compare a semelhança de dois embeddings usando a função ImageEmbedder.cosine_similarity. Confira um exemplo no código a seguir.

# Compute cosine similarity.
similarity = ImageEmbedder.cosine_similarity(
  embedding_result.embeddings[0],
  other_embedding_result.embeddings[0])