Detectar rótulos

A API Vision detecta e extrai informações de diversas categorias sobre entidades dentro de uma imagem utilizando um amplo grupo de categorias.

Os rótulos podem identificar objetos gerais, locais, atividades, espécies de animais, produtos e muito mais. Se precisar de rótulos personalizados segmentados, o Cloud AutoML Vision permite que você treine um modelo de machine learning personalizado para classificar imagens.

Eles são retornados apenas em inglês. Com a API Cloud Translation, é possível traduzir esses rótulos para vários idiomas.

Imagem de rua do distrito de Setagaya
Crédito da imagem: Alex Knight em Unsplash.

Por exemplo, a imagem acima pode retornar a seguinte lista de rótulos:

Descrição Pontuação
Rua 0,872
Fotografia 0,852
Cidade 0,848
Noite 0,804
Beco 0,713

Solicitações de detecção de rótulos

Configurar autenticação e projeto do GCP

Detectar rótulos em uma imagem local

A API Vision pode realizar a detecção de recursos em um arquivo de imagem local enviando o conteúdo do arquivo de imagem como uma string codificada em base64 no corpo da sua solicitação.

REST e LINHA DE CMD

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • base64-encoded-image: a representação base64 (string ASCII) dos dados da imagem binária. Essa string precisa ser semelhante à seguinte:
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    Veja mais informações no tópico Codificação base64.

Método HTTP e URL:

POST https://vision.googleapis.com/v1/images:annotate

Corpo JSON da solicitação:

{
  "requests": [
    {
      "image": {
        "content": "base64-encoded-image"
      },
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        }
      ]
    }
  ]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://vision.googleapis.com/v1/images:annotate

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

Quando a solicitação é bem-sucedida, o servidor retorna um código de status HTTP 200 OK e a resposta no formato JSON.

Uma resposta LABEL_DETECTION inclui os rótulos detectados, sua pontuação, o tema e um ID de rótulo opaco, em que:

  • mid: se presente, contém um identificador gerado por máquina (MID, na sigla em inglês) correspondente à entrada do Mapa de informações do Google da entidade. Observe que os valores mid permanecem exclusivos em diferentes idiomas. Portanto, use esses valores para unir entidades de diferentes idiomas. Para inspecionar os valores do MID, consulte a documentação da API Google Knowledge Graph.
  • description: a descrição do rótulo.
  • score: o índice de confiança, que varia de 0 (sem confiança) a 1 (confiança muito alta).
  • topicality: a relevância do rótulo de anotação de conteúdo da imagem (ICA, na sigla em inglês) em relação à imagem. Ele avalia a importância de um rótulo para o contexto geral de uma página.


 {
 "responses": [
 {
 "labelAnnotations": [
 {
 "mid": "/m/01c8br",
 " description": "Street",
 "score": 0,87294734,
 "topicity": 0.87294734
 },
 {
 "mid": "/m/06pg22",
 "description": "Snapshot",
 "score": 0.8523099,
 topictopicity": 0,8523099
 },
 {
 "mid": "/m/0dx1j",{101
 } "description": "Town",
 "score": 0,4810410,
"topicityity: 0.8104104
 },
 {
 "mid": "/m/01d74z",{
 101} "description": "Night",
 "score": 0.80408716,
 "topicity": 0.80408716
 },
 {
 "mid": "/m/01lwf0",

 "description": "Alley",
 "score": 0.133133322,
 "topicity": 0.7133322
 }
 ]
 }
 ]
}

Go

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


// detectLabels gets labels from the Vision API for an image at the given file path.
func detectLabels(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	annotations, err := client.DetectLabels(ctx, image, nil, 10)
	if err != nil {
		return err
	}

	if len(annotations) == 0 {
		fmt.Fprintln(w, "No labels found.")
	} else {
		fmt.Fprintln(w, "Labels:")
		for _, annotation := range annotations {
			fmt.Fprintln(w, annotation.Description)
		}
	}

	return nil
}

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.


import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.EntityAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.protobuf.ByteString;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DetectLabels {

  public static void detectLabels() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String filePath = "path/to/your/image/file.jpg";
    detectLabels(filePath);
  }

  // Detects labels in the specified local image.
  public static void detectLabels(String filePath) throws IOException {
    List<AnnotateImageRequest> requests = new ArrayList<>();

    ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));

    Image img = Image.newBuilder().setContent(imgBytes).build();
    Feature feat = Feature.newBuilder().setType(Feature.Type.LABEL_DETECTION).build();
    AnnotateImageRequest request =
        AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
    requests.add(request);

    // 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 client = ImageAnnotatorClient.create()) {
      BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
      List<AnnotateImageResponse> responses = response.getResponsesList();

      for (AnnotateImageResponse res : responses) {
        if (res.hasError()) {
          System.out.format("Error: %s%n", res.getError().getMessage());
          return;
        }

        // For full list of available annotations, see http://g.co/cloud/vision/docs
        for (EntityAnnotation annotation : res.getLabelAnnotationsList()) {
          annotation
              .getAllFields()
              .forEach((k, v) -> System.out.format("%s : %s%n", k, v.toString()));
        }
      }
    }
  }
}

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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vision para Node.js.

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const fileName = 'Local image file, e.g. /path/to/image.png';

// Performs label detection on the local file
const [result] = await client.labelDetection(fileName);
const labels = result.labelAnnotations;
console.log('Labels:');
labels.forEach(label => console.log(label.description));

Python

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

def detect_labels(path):
    """Detects labels in the file."""
    from google.cloud import vision
    import io
    client = vision.ImageAnnotatorClient()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = vision.Image(content=content)

    response = client.label_detection(image=image)
    labels = response.label_annotations
    print('Labels:')

    for label in labels:
        print(label.description)

    if response.error.message:
        raise Exception(
            '{}\nFor more info on error messages, check: '
            'https://cloud.google.com/apis/design/errors'.format(
                response.error.message))

Outros idiomas

C# : Siga as instruções: Instruções de configuração do C# na página de bibliotecas de cliente e acesse aDocumentação de referência da Vision para .NET.

PHP : Siga as instruções: Instruções de configuração do PHP na página de bibliotecas de cliente e acesse aDocumentação de referência da Vision para PHP.

Raquel : Siga as instruções: Instruções de configuração do Ruby na página de bibliotecas de cliente e acesse aDocumentação de referência do Vision para Ruby.

Detectar rótulos em uma imagem remota

Para sua comodidade, a API Vision realiza a detecção de recursos diretamente em um arquivo de imagem localizado no Google Cloud Storage ou na Web sem a necessidade de enviar o conteúdo do arquivo de imagem no corpo da solicitação.

REST e LINHA DE CMD

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • cloud-storage-image-uri: o caminho para um arquivo de imagem válido em um bucket do Cloud Storage. Você precisa ter, pelo menos, privilégios de leitura para o arquivo. Exemplo:
    • gs://cloud-samples-data/vision/label/setagaya.jpeg

Método HTTP e URL:

POST https://vision.googleapis.com/v1/images:annotate

Corpo JSON da solicitação:

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "cloud-storage-image-uri"
        }
      },
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        },
      ]
    }
  ]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://vision.googleapis.com/v1/images:annotate

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

Quando a solicitação é bem-sucedida, o servidor retorna um código de status HTTP 200 OK e a resposta no formato JSON.

Uma resposta LABEL_DETECTION inclui os rótulos detectados, sua pontuação, o tema e um ID de rótulo opaco, em que:

  • mid: se presente, contém um identificador gerado por máquina (MID, na sigla em inglês) correspondente à entrada do Mapa de informações do Google da entidade. Observe que os valores mid permanecem exclusivos em diferentes idiomas. Portanto, use esses valores para unir entidades de diferentes idiomas. Para inspecionar os valores do MID, consulte a documentação da API Google Knowledge Graph.
  • description: a descrição do rótulo.
  • score: o índice de confiança, que varia de 0 (sem confiança) a 1 (confiança muito alta).
  • topicality: a relevância do rótulo ICA (Image Content Annotation) para a imagem. Ele avalia a importância de um rótulo para o contexto geral de uma página.


 {
 "responses": [
 {
 "labelAnnotations": [
 {
 "mid": "/m/01c8br",
 " description": "Street",
 "score": 0,87294734,
 "topicity": 0.87294734
 },
 {
 "mid": "/m/06pg22",
 "description": "Snapshot",
 "score": 0.8523099,
 topictopicity": 0,8523099
 },
 {
 "mid": "/m/0dx1j",{101
 } "description": "Town",
 "score": 0,4810410,
"topicityity: 0.8104104
 },
 {
 "mid": "/m/01d74z",{
 101} "description": "Night",
 "score": 0.80408716,
 "topicity": 0.80408716
 },
 {
 "mid": "/m/01lwf0",

 "description": "Alley",
 "score": 0.133133322,
 "topicity": 0.7133322
 }
 ]
 }
 ]
}

Go

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


// detectLabels gets labels from the Vision API for an image at the given file path.
func detectLabelsURI(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	image := vision.NewImageFromURI(file)
	annotations, err := client.DetectLabels(ctx, image, nil, 10)
	if err != nil {
		return err
	}

	if len(annotations) == 0 {
		fmt.Fprintln(w, "No labels found.")
	} else {
		fmt.Fprintln(w, "Labels:")
		for _, annotation := range annotations {
			fmt.Fprintln(w, annotation.Description)
		}
	}

	return nil
}

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.


import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.EntityAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.cloud.vision.v1.ImageSource;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DetectLabelsGcs {

  public static void detectLabelsGcs() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String filePath = "gs://your-gcs-bucket/path/to/image/file.jpg";
    detectLabelsGcs(filePath);
  }

  // Detects labels in the specified remote image on Google Cloud Storage.
  public static void detectLabelsGcs(String gcsPath) throws IOException {
    List<AnnotateImageRequest> requests = new ArrayList<>();

    ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
    Image img = Image.newBuilder().setSource(imgSource).build();
    Feature feat = Feature.newBuilder().setType(Feature.Type.LABEL_DETECTION).build();
    AnnotateImageRequest request =
        AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
    requests.add(request);

    // 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 client = ImageAnnotatorClient.create()) {
      BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
      List<AnnotateImageResponse> responses = response.getResponsesList();

      for (AnnotateImageResponse res : responses) {
        if (res.hasError()) {
          System.out.format("Error: %s%n", res.getError().getMessage());
          return;
        }

        // For full list of available annotations, see http://g.co/cloud/vision/docs
        for (EntityAnnotation annotation : res.getLabelAnnotationsList()) {
          annotation
              .getAllFields()
              .forEach((k, v) -> System.out.format("%s : %s%n", k, v.toString()));
        }
      }
    }
  }
}

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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vision para Node.js.

// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Bucket where the file resides, e.g. my-bucket';
// const fileName = 'Path to file within bucket, e.g. path/to/image.png';

// Performs label detection on the gcs file
const [result] = await client.labelDetection(
  `gs://${bucketName}/${fileName}`
);
const labels = result.labelAnnotations;
console.log('Labels:');
labels.forEach(label => console.log(label.description));

Python

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

def detect_labels_uri(uri):
    """Detects labels in the file located in Google Cloud Storage or on the
    Web."""
    from google.cloud import vision
    client = vision.ImageAnnotatorClient()
    image = vision.Image()
    image.source.image_uri = uri

    response = client.label_detection(image=image)
    labels = response.label_annotations
    print('Labels:')

    for label in labels:
        print(label.description)

    if response.error.message:
        raise Exception(
            '{}\nFor more info on error messages, check: '
            'https://cloud.google.com/apis/design/errors'.format(
                response.error.message))

gcloud

Para detectar rótulos em uma imagem, use o comando gcloud ml vision detect-labels, como mostrado no exemplo a seguir:

gcloud ml vision detect-labels gs://cloud-samples-data/vision/label/setagaya.jpeg

Outros idiomas

C# : Siga as instruções: Instruções de configuração do C# na página de bibliotecas de cliente e acesse aDocumentação de referência da Vision para .NET.

PHP : Siga as instruções: Instruções de configuração do PHP na página de bibliotecas de cliente e acesse aDocumentação de referência da Vision para PHP.

Raquel : Siga as instruções: Instruções de configuração do Ruby na página de bibliotecas de cliente e acesse aDocumentação de referência do Vision para Ruby.

Testar

Teste a detecção de rótulos abaixo. É possível usar a imagem já especificada (gs://cloud-samples-data/vision/label/setagaya.jpeg) ou determinar sua própria imagem. Envie a solicitação selecionando Executar.

Imagem de rua do distrito de Setagaya
Crédito da imagem: Alex Knight em Unsplash.

Corpo da solicitação:

{
  "requests": [
    {
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        }
      ],
      "image": {
        "source": {
          "imageUri": "gs://cloud-samples-data/vision/label/setagaya.jpeg"
        }
      }
    }
  ]
}