Anotação off-line de imagens em lote

A API Vision pode executar serviços de detecção e anotação off-line (assíncronos) de um lote grande de arquivos de imagem usando qualquer tipo de recurso da Vision. Por exemplo, é possível especificar um ou vários recursos da API Vision, como TEXT_DETECTION, LABEL_DETECTION e LANDMARK_DETECTION para um único lote de imagens.

A saída de uma solicitação em lote off-line é gravada em um arquivo JSON criado no bucket especificado do Cloud Storage.

Observação: todos os tipos de recurso da API Vision também oferecem anotação de imagens em lote on-line síncrona. As solicitações on-line síncronas enviam uma resposta imediata a uma solicitação de anotação. Para mais informações, consulte as páginas de instruções.

• Solicitações on-line (síncronas): uma solicitação de anotação on-line (images:annotate ou files:annotate) retorna imediatamente anotações inline para o usuário. As solicitações de anotação on-line limitam a quantidade de arquivos que podem ser anotados em uma única solicitação. Com uma solicitação images:annotate, é possível especificar apenas um pequeno número de imagens (<=16) a serem anotadas. Com uma solicitação files:annotate, só é possível especificar um único arquivo e um pequeno número de páginas (<=5) nesse arquivo a ser anotado.
• Solicitações off-line (assíncronas): uma solicitação de anotação off-line (images:asyncBatchAnnotate ou files:asyncBatchAnnotate) inicia uma operação de longa execução (LRO, na sigla em inglês) e não retorna uma resposta imediatamente para o autor da chamada. Quando a LRO é concluída, as anotações são armazenadas como arquivos em um bucket especificado do Cloud Storage. Uma solicitação images:asyncBatchAnnotate permite especificar até 2.000 imagens por solicitação. Uma solicitação files:asyncBatchAnnotate permite especificar lotes maiores de arquivos e pode especificar mais páginas (<=2000) por arquivo para anotação em um único momento, o que não é possível com solicitações on-line.

Limitações

A API Vision aceita até 2.000 arquivos de imagem. Um lote maior de arquivos de imagem retornará um erro.

Observação: se houver arquivos em uma solicitação em lote que o Cloud Vision não processou, reenvie esses arquivos para evitar a cobrança por aqueles que foram processados.

Tipos de recursos compatíveis atualmente

Tipo de recurso
CROP_HINTS	Determinar os vértices sugeridos para uma região de corte em uma imagem.
DOCUMENT_TEXT_DETECTION	Execute o OCR em imagens de texto densas, como documentos (PDF/TIFF) e imagens com texto escrito à mão. TEXT_DETECTION pode ser usado para imagens de texto esparso. Tem precedência quando DOCUMENT_TEXT_DETECTION e TEXT_DETECTION estão presentes.
FACE_DETECTION	Detectar rostos na imagem.
IMAGE_PROPERTIES	Calcular um conjunto de propriedades de imagem, como as cores dominantes.
LABEL_DETECTION	Adicionar rótulos com base no conteúdo da imagem.
LANDMARK_DETECTION	Detectar pontos de referência na imagem.
LOGO_DETECTION	Detectar logotipos de empresas na imagem.
OBJECT_LOCALIZATION	Detectar e extrair vários objetos em uma imagem.
SAFE_SEARCH_DETECTION	Executar a SafeSearch segura para detectar conteúdo possivelmente inseguro ou indesejável.
TEXT_DETECTION	Realizar o reconhecimento óptico de caracteres (OCR) no texto dentro da imagem. A detecção de texto é otimizada para áreas de texto esparso em uma imagem maior. Se a imagem for um documento (PDF/TIFF), tiver texto denso ou contiver texto escrito à mão, use DOCUMENT_TEXT_DETECTION.
WEB_DETECTION	Detectar entidades de um assunto específico, como notícias, eventos ou celebridades na imagem, e encontrar imagens semelhantes na Web usando o poder da pesquisa do Imagens do Google.

Código de amostra

Use os exemplos de código a seguir para executar serviços de anotação off-line em um lote de arquivos de imagem no Cloud Storage.

Observação: nos exemplos de código a seguir, cada elemento das solicitações (requests_element/requestsElement) corresponde a uma única imagem. Para anotar mais imagens, crie um elemento de solicitação para cada imagem e adicione-o à matriz de solicitações (requests).

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido da API Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vision para Java.

Observação: para usuários do framework Spring do Java, o Spring Cloud do Google Cloud oferece uma maneira de configurar automaticamente as definições de autenticação e os objetos de cliente para usar a API Vision.

import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AsyncBatchAnnotateImagesRequest;
import com.google.cloud.vision.v1.AsyncBatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.GcsDestination;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.cloud.vision.v1.ImageSource;
import com.google.cloud.vision.v1.OutputConfig;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class AsyncBatchAnnotateImages {

  public static void asyncBatchAnnotateImages()
      throws InterruptedException, ExecutionException, IOException {
    String inputImageUri = "gs://cloud-samples-data/vision/label/wakeupcat.jpg";
    String outputUri = "gs://YOUR_BUCKET_ID/path/to/save/results/";
    asyncBatchAnnotateImages(inputImageUri, outputUri);
  }

  public static void asyncBatchAnnotateImages(String inputImageUri, String outputUri)
      throws IOException, ExecutionException, InterruptedException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ImageAnnotatorClient imageAnnotatorClient = ImageAnnotatorClient.create()) {

      // You can send multiple images to be annotated, this sample demonstrates how to do this with
      // one image. If you want to use multiple images, you have to create a `AnnotateImageRequest`
      // object for each image that you want annotated.
      // First specify where the vision api can find the image
      ImageSource source = ImageSource.newBuilder().setImageUri(inputImageUri).build();
      Image image = Image.newBuilder().setSource(source).build();

      // Set the type of annotation you want to perform on the image
      // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type
      Feature feature = Feature.newBuilder().setType(Feature.Type.LABEL_DETECTION).build();

      // Build the request object for that one image. Note: for additional images you have to create
      // additional `AnnotateImageRequest` objects and store them in a list to be used below.
      AnnotateImageRequest imageRequest =
          AnnotateImageRequest.newBuilder().setImage(image).addFeatures(feature).build();

      // Set where to store the results for the images that will be annotated.
      GcsDestination gcsDestination = GcsDestination.newBuilder().setUri(outputUri).build();
      OutputConfig outputConfig =
          OutputConfig.newBuilder()
              .setGcsDestination(gcsDestination)
              .setBatchSize(2) // The max number of responses to output in each JSON file
              .build();

      // Add each `AnnotateImageRequest` object to the batch request and add the output config.
      AsyncBatchAnnotateImagesRequest request =
          AsyncBatchAnnotateImagesRequest.newBuilder()
              .addRequests(imageRequest)
              .setOutputConfig(outputConfig)
              .build();

      // Make the asynchronous batch request.
      AsyncBatchAnnotateImagesResponse response =
          imageAnnotatorClient.asyncBatchAnnotateImagesAsync(request).get();

      // The output is written to GCS with the provided output_uri as prefix
      String gcsOutputUri = response.getOutputConfig().getGcsDestination().getUri();
      System.out.format("Output written to GCS with prefix: %s%n", gcsOutputUri);
    }
  }
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionNode.js.

Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const inputImageUri = 'gs://cloud-samples-data/vision/label/wakeupcat.jpg';
// const outputUri = 'gs://YOUR_BUCKET_ID/path/to/save/results/';

// Imports the Google Cloud client libraries
const {ImageAnnotatorClient} = require('@google-cloud/vision').v1;

// Instantiates a client
const client = new ImageAnnotatorClient();

// You can send multiple images to be annotated, this sample demonstrates how to do this with
// one image. If you want to use multiple images, you have to create a request object for each image that you want annotated.
async function asyncBatchAnnotateImages() {
  // Set the type of annotation you want to perform on the image
  // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type
  const features = [{type: 'LABEL_DETECTION'}];

  // Build the image request object for that one image. Note: for additional images you have to create
  // additional image request objects and store them in a list to be used below.
  const imageRequest = {
    image: {
      source: {
        imageUri: inputImageUri,
      },
    },
    features: features,
  };

  // Set where to store the results for the images that will be annotated.
  const outputConfig = {
    gcsDestination: {
      uri: outputUri,
    },
    batchSize: 2, // The max number of responses to output in each JSON file
  };

  // Add each image request object to the batch request and add the output config.
  const request = {
    requests: [
      imageRequest, // add additional request objects here
    ],
    outputConfig,
  };

  // Make the asynchronous batch request.
  const [operation] = await client.asyncBatchAnnotateImages(request);

  // Wait for the operation to complete
  const [filesResponse] = await operation.promise();

  // The output is written to GCS with the provided output_uri as prefix
  const destinationUri = filesResponse.outputConfig.gcsDestination.uri;
  console.log(`Output written to GCS with prefix: ${destinationUri}`);
}

asyncBatchAnnotateImages();

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionPython.

Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

from google.cloud import vision_v1

def sample_async_batch_annotate_images(
    input_image_uri="gs://cloud-samples-data/vision/label/wakeupcat.jpg",
    output_uri="gs://your-bucket/prefix/",
):
    """Perform async batch image annotation."""
    client = vision_v1.ImageAnnotatorClient()

    source = {"image_uri": input_image_uri}
    image = {"source": source}
    features = [
        {"type_": vision_v1.Feature.Type.LABEL_DETECTION},
        {"type_": vision_v1.Feature.Type.IMAGE_PROPERTIES},
    ]

    # Each requests element corresponds to a single image.  To annotate more
    # images, create a request element for each image and add it to
    # the array of requests
    requests = [{"image": image, "features": features}]
    gcs_destination = {"uri": output_uri}

    # The max number of responses to output in each JSON file
    batch_size = 2
    output_config = {"gcs_destination": gcs_destination, "batch_size": batch_size}

    operation = client.async_batch_annotate_images(
        requests=requests, output_config=output_config
    )

    print("Waiting for operation to complete...")
    response = operation.result(90)

    # The output is written to GCS with the provided output_uri as prefix
    gcs_output_uri = response.output_config.gcs_destination.uri
    print(f"Output written to GCS with prefix: {gcs_output_uri}")

Resposta

Uma solicitação bem-sucedida retorna arquivos JSON de resposta no bucket do Cloud Storage indicado no exemplo de código. O número de respostas por arquivo JSON é determinado por batch_size no exemplo de código.

A resposta retornada será semelhante às respostas do recurso regular da API Vision, dependendo dos recursos solicitados para uma imagem.

Nas respostas a seguir, são exibidas as anotações LABEL_DETECTION e TEXT_DETECTION para image1.png, IMAGE_PROPERTIES para image2.jpg e OBJECT_LOCALIZATION para image3.jpg.

A resposta também inclui um campo context que mostra o URI do arquivo.

offline_batch_output/output-1-to-2.json

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/07s6nbt",
          "description": "Text",
          "score": 0.93413997,
          "topicality": 0.93413997
        },
        {
          "mid": "/m/0dwx7",
          "description": "Logo",
          "score": 0.8733531,
          "topicality": 0.8733531
        },
        ...
        {
          "mid": "/m/03bxgrp",
          "description": "Company",
          "score": 0.5682425,
          "topicality": 0.5682425
        }
      ],
      "textAnnotations": [
        {
          "locale": "en",
          "description": "Google\n",
          "boundingPoly": {
            "vertices": [
              {
                "x": 72,
                "y": 40
              },
              {
                "x": 613,
                "y": 40
              },
              {
                "x": 613,
                "y": 233
              },
              {
                "x": 72,
                "y": 233
              }
            ]
          }
        },
        ...
                ],
                "blockType": "TEXT"
              }
            ]
          }
        ],
        "text": "Google\n"
      },
      "context": {
        "uri": "gs://cloud-samples-data/vision/document_understanding/image1.png"
      }
    },
    {
      "imagePropertiesAnnotation": {
        "dominantColors": {
          "colors": [
            {
              "color": {
                "red": 229,
                "green": 230,
                "blue": 238
              },
              "score": 0.2744754,
              "pixelFraction": 0.075339235
            },
            ...
            {
              "color": {
                "red": 86,
                "green": 87,
                "blue": 95
              },
              "score": 0.025770646,
              "pixelFraction": 0.13109145
            }
          ]
        }
      },
      "cropHintsAnnotation": {
        "cropHints": [
          {
            "boundingPoly": {
              "vertices": [
                {},
                {
                  "x": 1599
                },
                {
                  "x": 1599,
                  "y": 1199
                },
                {
                  "y": 1199
                }
              ]
            },
            "confidence": 0.79999995,
            "importanceFraction": 1
          }
        ]
      },
      "context": {
        "uri": "gs://cloud-samples-data/vision/document_understanding/image2.jpg"
      }
    }
  ]
}

offline_batch_output/output-3-to-3.json

{
  "responses": [
    {
      "context": {
        "uri": "gs://cloud-samples-data/vision/document_understanding/image3.jpg"
      },
      "localizedObjectAnnotations": [
        {
          "mid": "/m/0bt9lr",
          "name": "Dog",
          "score": 0.9669734,
          "boundingPoly": {
            "normalizedVertices": [
              {
                "x": 0.6035543,
                "y": 0.1357359
              },
              {
                "x": 0.98546547,
                "y": 0.1357359
              },
              {
                "x": 0.98546547,
                "y": 0.98426414
              },
              {
                "x": 0.6035543,
                "y": 0.98426414
              }
            ]
          }
        },
        ...
        {
          "mid": "/m/0jbk",
          "name": "Animal",
          "score": 0.58003056,
          "boundingPoly": {
            "normalizedVertices": [
              {
                "x": 0.014534635,
                "y": 0.1357359
              },
              {
                "x": 0.37197515,
                "y": 0.1357359
              },
              {
                "x": 0.37197515,
                "y": 0.98426414
              },
              {
                "x": 0.014534635,
                "y": 0.98426414
              }
            ]
          }
        }
      ]
    }
  ]
}