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.
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. # ...
Video
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. Há três
modos: IMAGE: o modo para entradas de imagem única. VIDEO: o modo para frames decodificados de um vídeo. LIVE_STREAM: é o modo para uma transmissão ao vivo de dados de entrada, como de uma câmera. Nesse modo, o resultListener precisa ser chamado para configurar um listener para receber resultados de forma assíncrona. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
l2_normalize |
Define se o vetor de atributo retornado será normalizado com a norma L2. Use essa opção somente se o modelo ainda não tiver uma operação nativa do TFLite L2_NORMALIZATION. Na maioria dos casos, esse já é o caso, e a normalização L2 é, portanto, feita por meio da inferência TFLite sem precisar dessa opção. | Boolean |
False |
quantize |
Define se o embedding retornado precisa ser quantizado em bytes por meio da quantização escalar. Os embeddings são implicitamente considerados padrão de unidade e, portanto, qualquer dimensão tem um valor em [-1.0, 1.0]. Use a opção l2_normalize se esse não for o caso. | Boolean |
False |
result_callback |
Define o listener de resultados para receber os resultados de incorporação de forma assíncrona quando o incorporador de imagens está no modo de transmissão ao vivo. 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 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.
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)
Video
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 execução para acionar inferências. A API Image Embedder retorna os vetores de embedding para a imagem ou o frame de entrada.
Imagem
# Perform image embedding on the provided single image. embedding_result = embedder.embed(mp_image)
Video
# 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 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])