Guia de incorporação de imagens para Python

A tarefa do 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 Image Embedder com Python.

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 exemplo de código para o Embedder de imagem fornece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda a testar essa tarefa e começar a criar seu próprio incorporador de imagens. Você pode conferir, executar e editar o código de exemplo do injetor de imagens usando apenas seu navegador da Web com o Google Colab. Confira o código-fonte desse 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 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 Image Embedder usa o pacote mediapipe pip. É possível instalar a dependência com o seguinte:

$ python -m pip install mediapipe

Importações

Importe as classes a seguir para acessar as funções de tarefa do Image Embedder:

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

Modelo

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

Selecione e faça o download de um modelo e o armazene em um diretório local. Você pode usar o modelo MobileNetV3 recomendado.

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

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

base_options = BaseOptions(model_asset_path=model_path)

Criar a tarefa

Você pode usar 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 de incorporação. Para mais informações sobre as opções de configuração, consulte Visão geral da configuração.

A tarefa Image Embedder oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e transmissões de vídeo ao vivo. Escolha a guia correspondente ao tipo de dados de entrada para saber 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 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

É 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 do incorporador de imagem o carimbo de data/hora do frame de entrada.
• Quando executada no modelo de imagem ou vídeo, a tarefa do incorporador de imagens bloqueia a linha de execução atual até que ela termine de processar a imagem de entrada ou o frame.
• Quando executada no modo de transmissão ao vivo, a tarefa do incorporador de imagens não bloqueia a linha de execução atual, mas retorna imediatamente. Ele vai invocar o listener de resultado com o resultado de incorporação sempre que terminar 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 vai ignorar o novo frame de entrada.

Processar e mostrar resultados

Ao executar a inferência, a tarefa Image Embedder retorna um objeto ImageEmbedderResult que contém a lista de categorias possíveis para os objetos na imagem ou frame de entrada.

Confira a seguir um exemplo dos dados de saída desta 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

Esse resultado foi obtido ao incorporar a seguinte imagem:

É possível comparar a semelhança de duas embeddings usando a função ImageEmbedder.cosine_similarity. Confira o exemplo de código a seguir:

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