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 a ML, como comparar similaridade de duas imagens. Estas instruções mostram como usar o Incorporador de imagens com Python.

Para mais informações sobre recursos, modelos e opções de configuração, desta tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo para o incorporador de imagens 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 incorporador de imagem. É possível exibir, executar e editar Exemplo de incorporador de imagem código usando apenas o navegador da Web com o Google Colab. Você pode conferir o código-fonte neste exemplo 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 incorporador de imagens. 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 o Guia de configuração do Python.

Pacotes

A tarefa do incorporador de imagens ao pacote pip mediapipe. É possível instalar a dependência pelo seguinte:

$ python -m pip install mediapipe

Importações

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

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

Modelo

A tarefa MediaPipe Image Embedder exige um modelo treinado que seja compatível com esse tarefa. Para mais informações sobre os modelos treinados disponíveis para o incorporador de imagens, 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. Você pode usar o padrão MobileNetV3 um modelo de machine learning.

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

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

A tarefa "Incorporador de imagens" é compatível com três tipos de dados de entrada: imagens estáticas e arquivos de vídeo e transmissões de vídeo ao vivo. Escolha a guia correspondente ao tipo dos dados de entrada para você vai aprender a criar a tarefa e executar a inferência.

Imagem

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

Vídeo

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

Transmissão ao vivo

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:

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
l2_normalize Define se o vetor de atributo retornado deve ser normalizado com a norma L2. Use essa opção somente se o modelo ainda não tiver um L2_NORMALIZATION Op. do TFLite. Na maioria dos casos, esse já é o caso e Assim, a normalização L2 é alcançada por meio da inferência do TFLite sem a necessidade para essa opção. Boolean False
quantize Se o embedding retornado deve ser quantizado em bytes por meio de com a quantização escalar. Os embeddings são implicitamente definidos como unidade-norma e portanto, qualquer dimensão terá um valor em [-1.0, 1.0]. Usar a opção l2_normalize, se este não for o caso. Boolean False
result_callback Define o listener de resultados para receber os resultados de embedding. de forma assíncrona quando o incorporador de imagens está na transmissão ao vivo modo Só pode ser usado quando o modo de corrida está definido como LIVE_STREAM N/A Não definido

Preparar dados

Prepare sua entrada como um arquivo de imagem ou uma matriz numpy e, em seguida, converta-a em um mediapipe.Image. Se sua entrada for um arquivo de vídeo ou uma transmissão ao vivo de um webcam, você pode usar uma biblioteca externa, como OpenCV para carregar os frames de entrada como numpy matrizes de dados.

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 a função de incorporação correspondente ao modo de corrida para acionar ou inferências. A API Image Embedder retornará os vetores de embedding para o imagem ou frame de entrada.

Imagem

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

Vídeo

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

Transmissão ao vivo

# 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 nos modos de vídeo ou de transmissão ao vivo, você também precisa forneça à tarefa "Incorporador de imagens" o carimbo de data/hora do frame de entrada.
  • Ao executar na imagem ou no modelo de vídeo, a tarefa Incorporador de imagens 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 "Incorporador de imagens" não bloqueia thread atual, mas retorna imediatamente. Ele vai invocar seu resultado com o resultado da incorporação sempre que ele terminar de processar um frame de entrada. Se a função embedAsync for chamada quando o incorporador de imagens estiver ocupada processando outro frame, a tarefa ignora o novo frame de entrada.

Gerenciar e exibir resultados

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

Confira abaixo 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 pela incorporação da seguinte imagem:

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

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