Guia de incorporação de imagens para Web

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 a similaridade de duas imagens. Estas instruções mostram como usar o incorporador de imagens para apps Node e da Web.

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 Image Embedder oferece uma implementação completa dessa tarefa em JavaScript para sua referência. Esse código ajuda você a testar essa tarefa e começar a criar seu próprio app de incorporação de imagens. É possível visualizar, executar e editar o exemplo do Image Embedder usando apenas seu navegador da Web.

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 seu ambiente de desenvolvimento para usar as tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para a Web.

Pacotes JavaScript

O código do Image Embedder está disponível no pacote @mediapipe/tasks-vision NPM do MediaPipe. Você pode encontrar e baixar essas bibliotecas nos links fornecidos no guia de configuração da plataforma.

É possível instalar os pacotes necessários com o seguinte código para teste local usando este comando:

npm install @mediapipe/tasks-vision

Se você quiser importar o código da tarefa usando um serviço de rede de fornecimento de conteúdo (CDN), adicione o seguinte código à tag <head> no arquivo HTML:

<!-- You can replace jsDelivr with your preferred CDN -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.mjs"
    crossorigin="anonymous"></script>
</head>

Modelo

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

Selecione e faça o download de um modelo e armazene-o no diretório do projeto:

<dev-project-root>/app/shared/models/

Criar a tarefa

Especificar um caminho de modelo

É possível criar uma tarefa com as opções padrão usando o método createFromModelPath():

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
  const imageEmbedder = await ImageEmbedder.createFromOptions(vision, {
    baseOptions: {
      modelAssetPath: `https://storage.googleapis.com/mediapipe-models/image_embedder/mobilenet_v3_small/float32/1/mobilenet_v3_small.tflite`
    },
  });

Especificar o buffer do modelo

Se o modelo já estiver carregado na memória, use o método createFromModelBuffer():

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const imageEmbedder = ImageEmbedder.createFromModelBuffer(
    vision, 
    new Uint8Array(...)
);

Especificar opções personalizadas

A tarefa do MediaPipe Image Embedder usa a função createFromOptions para configurar a tarefa. A função createFromOptions aceita valores para opções de configuração. Para mais informações sobre opções de configuração, consulte Opções de configuração.

O código a seguir demonstra como criar e configurar a tarefa com opções personalizadas:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const imageEmbedder = await ImageEmbedder.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "model.tflite"
      },
      quantize: true
    });

Opções de configuração

Essa tarefa tem as seguintes opções de configuração para aplicativos da Web:

Nome da opção Descrição Intervalo de valor Valor padrão
running_mode Define o modo de execução da tarefa. Há dois modos:

IMAGE: o modo para entradas de imagem única.

VIDEO: o modo para frames decodificados de um vídeo ou em uma transmissão ao vivo de dados de entrada, como de uma câmera.		 {IMAGE, VIDEO} IMAGE
l2Normalize Se o vetor de recursos retornado será normalizado com a norma L2. Use essa opção somente se o modelo ainda não tiver uma operação nativa L2_NORMALIZATION do TFLite. Na maioria dos casos, isso já acontece e a normalização L2 é alcançada por inferência do TFLite sem necessidade dessa opção. Boolean False
quantize Indica se o embedding retornado precisa ser quantizado em bytes usando quantização escalar. Os embeddings são implicitamente considerados de norma unitária. Portanto, qualquer dimensão tem um valor em [-1,0, 1,0]. Use a opção "l2Normalize" se não for esse o caso. Boolean False

Preparar dados

O Image Embedder pode incorporar imagens em qualquer formato compatível com o navegador host. A tarefa também processa o pré-processamento de entrada de dados, incluindo redimensionamento, rotação e normalização de valores.

As chamadas para os métodos Image Embedder embed() e embedForVideo() são executadas de forma síncrona e bloqueiam a linha de execução da interface do usuário. Se você quiser extrair vetores de recursos de frames de vídeo, cada incorporação vai bloquear a linha de execução principal. Para evitar isso, implemente web workers para executar os métodos embed() e embedForVideo() em outra linha de execução.

Executar a tarefa

O incorporador de imagens usa os métodos embed() (com modo de execução image) e embedForVideo() (com modo de execução video) para acionar inferências. A API Image Embedder vai retornar os vetores de embedding para a imagem de entrada.

O código a seguir demonstra como executar o processamento com o modelo de tarefa:

Imagem

const image = document.getElementById("image") as HTMLImageElement;
const imageEmbedderResult = imageEmbedder.embed(image);

Vídeo

  const video = document.getElementById("webcam");

  const startTimeMs = performance.now();
  const embedderResult = await imageEmbedder.embedForVideo(video, startTimeMs);

Processar e mostrar resultados

Ao executar a inferência, a tarefa Image Embedder retorna um objeto ImageEmbedderResult que contém os vetores de embedding da imagem ou do frame de entrada.

Confira abaixo 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

Esse resultado foi obtido incorporando a seguinte imagem:

Plano médio de um gato exótico

É possível comparar a similaridade semântica de dois embeddings usando a função ImageEmbedder.cosineSimilarity. Confira o exemplo de código a seguir.

// Compute cosine similarity.
const similarity = ImageEmbedder.cosineSimilarity(
  imageEmbedderResult.embeddings[0],
  otherEmbedderResult.embeddings[0]);

O exemplo de código do Image Embedder mostra como exibir os resultados do embedder retornados da tarefa. Consulte o exemplo para mais detalhes.