Detectar rostos e atributos faciais em imagens

A API Cloud Vision permite detectar vários rostos em uma imagem, além de atributos faciais importantes associados, como acessórios de cabeça ou pontos de referência faciais. Use o Cloud Vision para tarefas de visão computacional e análise de imagens que exigem a identificação desses aspectos faciais gerais.

A tecnologia de reconhecimento facial, que é diferente da detecção facial, identifica ou verifica um indivíduo específico de uma imagem em um banco de dados de pessoas conhecidas. A API Cloud Vision não é compatível com reconhecimento facial ou identificação individual.

Solicitações de detecção facial

Configurar o projeto do Google Cloud e a autenticação

Detectar rostos em uma imagem local

Use a API Vision para detectar atributos em um arquivo de imagem local.

Para solicitações REST, envie o conteúdo do arquivo de imagem como uma string codificada em base64 no corpo da solicitação.

Para solicitações da gcloud e da biblioteca de cliente, especifique o caminho para uma imagem local na solicitação.

REST

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. A string precisa ser semelhante à seguinte:
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    Saiba mais no tópico Codificação base64.
  • RESULTS_INT: (opcional) um valor inteiro de resultados a serem retornados. Se você omitir o campo "maxResults" e o valor dele, a API vai retornar o valor padrão de 10 resultados. Esse campo não se aplica aos seguintes tipos de recursos: TEXT_DETECTION, DOCUMENT_TEXT_DETECTION ou CROP_HINTS.
  • PROJECT_ID: o ID do projeto do Google Cloud .

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": RESULTS_INT,
          "type": "FACE_DETECTION"
        }
      ]
    }
  ]
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -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 com o nome request.json e execute o comando abaixo: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

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 FACE_DETECTION inclui caixas delimitadoras para todos os rostos detectados, pontos de referência detectados nos rostos (olhos, nariz, boca etc.) e classificações de confiança para propriedades de rosto e imagem (como subexposição, desfoque e acessórios de cabeça). Os campos de probabilidade de emoção (joyLikelihood, sorrowLikelihood, angerLikelihood e surpriseLikelihood) foram descontinuados e retornam UNKNOWN.

Go

Antes de testar este exemplo, siga as instruções de configuração do Go 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 Vision Go.

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


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

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

	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.DetectFaces(ctx, image, nil, 10)
	if err != nil {
		return err
	}
	if len(annotations) == 0 {
		fmt.Fprintln(w, "No faces found.")
	} else {
		fmt.Fprintln(w, "Faces:")
		for i, annotation := range annotations {
			fmt.Fprintln(w, "  Face", i)
			fmt.Fprintln(w, "    Anger:", annotation.AngerLikelihood)
			fmt.Fprintln(w, "    Joy:", annotation.JoyLikelihood)
			fmt.Fprintln(w, "    Surprise:", annotation.SurpriseLikelihood)
		}
	}
	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.FaceAnnotation;
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 DetectFaces {

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

  // Detects faces in the specified local image.
  public static void detectFaces(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.FACE_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 (FaceAnnotation annotation : res.getFaceAnnotationsList()) {
          System.out.format(
              "anger: %s%njoy: %s%nsurprise: %s%nposition: %s",
              annotation.getAngerLikelihood(),
              annotation.getJoyLikelihood(),
              annotation.getSurpriseLikelihood(),
              annotation.getBoundingPoly());
        }
      }
    }
  }
}

Node.js

Antes de testar este exemplo, 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 Vision Node.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. 

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

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

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

  const [result] = await client.faceDetection(fileName);
  const faces = result.faceAnnotations;
  console.log('Faces:');
  faces.forEach((face, i) => {
    console.log(`  Face #${i + 1}:`);
    console.log(`    Joy: ${face.joyLikelihood}`);
    console.log(`    Anger: ${face.angerLikelihood}`);
    console.log(`    Sorrow: ${face.sorrowLikelihood}`);
    console.log(`    Surprise: ${face.surpriseLikelihood}`);
  });
}
detectFaces();

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 Vision Python.

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

def detect_faces(path):
    """Detects faces in an image."""
    from google.cloud import vision

    client = vision.ImageAnnotatorClient()

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

    image = vision.Image(content=content)

    response = client.face_detection(image=image)
    faces = response.face_annotations

    # Names of likelihood from google.cloud.vision.enums
    likelihood_name = (
        "UNKNOWN",
        "VERY_UNLIKELY",
        "UNLIKELY",
        "POSSIBLE",
        "LIKELY",
        "VERY_LIKELY",
    )
    print("Faces:")

    for face in faces:
        print(f"anger: {likelihood_name[face.anger_likelihood]}")
        print(f"joy: {likelihood_name[face.joy_likelihood]}")
        print(f"surprise: {likelihood_name[face.surprise_likelihood]}")

        vertices = [
            f"({vertex.x},{vertex.y})" for vertex in face.bounding_poly.vertices
        ]

        print("face bounds: {}".format(",".join(vertices)))

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

Outras linguagens

C#: siga as instruções de configuração do C# na página das bibliotecas de cliente e acesse a documentação de referência do Vision para .NET.

PHP: siga as instruções de configuração do PHP na página das bibliotecas de cliente e acesse a documentação de referência do Vision para PHP.

Ruby: siga as instruções de configuração do Ruby na página das bibliotecas de cliente e visite adocumentação de referência do Vision para Ruby.

Detectar rostos em uma imagem remota

Use a API Vision para realizar a detecção de recursos em um arquivo de imagem localizado no Cloud Storage ou na web. Para enviar uma solicitação de arquivo remoto, especifique o URL da Web do arquivo ou o URI do Cloud Storage no corpo da solicitação.

REST

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/face/faces.jpeg
  • RESULTS_INT: (opcional) um valor inteiro de resultados a serem retornados. Se você omitir o campo "maxResults" e o valor dele, a API vai retornar o valor padrão de 10 resultados. Esse campo não se aplica aos seguintes tipos de recursos: TEXT_DETECTION, DOCUMENT_TEXT_DETECTION ou CROP_HINTS.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "requests": [
    {
      "image": {
        "source": {
          "imageUri": "CLOUD_STORAGE_IMAGE_URI"
        }
       },
       "features": [
         {
           "maxResults": RESULTS_INT,
           "type": "FACE_DETECTION"
         }
       ]
    }
  ]
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -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 com o nome request.json e execute o comando abaixo: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

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 FACE_DETECTION inclui caixas delimitadoras para todos os rostos detectados, pontos de referência detectados nos rostos (olhos, nariz, boca etc.) e classificações de confiança para propriedades de rosto e imagem (como subexposição, desfoque e acessórios de cabeça). Os campos de probabilidade de emoção (joyLikelihood, sorrowLikelihood, angerLikelihood e surpriseLikelihood) foram descontinuados e retornam UNKNOWN.

Go

Antes de testar este exemplo, siga as instruções de configuração do Go 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 Vision Go.

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


// detectFaces gets faces from the Vision API for an image at the given file path.
func detectFacesURI(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.DetectFaces(ctx, image, nil, 10)
	if err != nil {
		return err
	}
	if len(annotations) == 0 {
		fmt.Fprintln(w, "No faces found.")
	} else {
		fmt.Fprintln(w, "Faces:")
		for i, annotation := range annotations {
			fmt.Fprintln(w, "  Face", i)
			fmt.Fprintln(w, "    Anger:", annotation.AngerLikelihood)
			fmt.Fprintln(w, "    Joy:", annotation.JoyLikelihood)
			fmt.Fprintln(w, "    Surprise:", annotation.SurpriseLikelihood)
		}
	}
	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.FaceAnnotation;
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 DetectFacesGcs {

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

  // Detects faces in the specified remote image on Google Cloud Storage.
  public static void detectFacesGcs(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.FACE_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 (FaceAnnotation annotation : res.getFaceAnnotationsList()) {
          System.out.format(
              "anger: %s%njoy: %s%nsurprise: %s%nposition: %s",
              annotation.getAngerLikelihood(),
              annotation.getJoyLikelihood(),
              annotation.getSurpriseLikelihood(),
              annotation.getBoundingPoly());
        }
      }
    }
  }
}

Node.js

Antes de testar este exemplo, 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 Vision Node.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. 

// 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 face detection on the gcs file
const [result] = await client.faceDetection(`gs://${bucketName}/${fileName}`);
const faces = result.faceAnnotations;
console.log('Faces:');
faces.forEach((face, i) => {
  console.log(`  Face #${i + 1}:`);
  console.log(`    Joy: ${face.joyLikelihood}`);
  console.log(`    Anger: ${face.angerLikelihood}`);
  console.log(`    Sorrow: ${face.sorrowLikelihood}`);
  console.log(`    Surprise: ${face.surpriseLikelihood}`);
});

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 Vision Python.

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

def detect_faces_uri(uri):
    """Detects faces in the file located in Google Cloud Storage or the web."""
    from google.cloud import vision

    client = vision.ImageAnnotatorClient()
    image = vision.Image()
    image.source.image_uri = uri

    response = client.face_detection(image=image)
    faces = response.face_annotations

    # Names of likelihood from google.cloud.vision.enums
    likelihood_name = (
        "UNKNOWN",
        "VERY_UNLIKELY",
        "UNLIKELY",
        "POSSIBLE",
        "LIKELY",
        "VERY_LIKELY",
    )
    print("Faces:")

    for face in faces:
        print(f"anger: {likelihood_name[face.anger_likelihood]}")
        print(f"joy: {likelihood_name[face.joy_likelihood]}")
        print(f"surprise: {likelihood_name[face.surprise_likelihood]}")

        vertices = [
            f"({vertex.x},{vertex.y})" for vertex in face.bounding_poly.vertices
        ]

        print("face bounds: {}".format(",".join(vertices)))

    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 fazer a detecção facial, use o comando gcloud ml vision detect-faces:

gcloud ml vision detect-faces gs://cloud-samples-data/vision/face/faces.jpeg

Linguagens adicionais

C#: siga as instruções de configuração do C# na página das bibliotecas de cliente e acesse a documentação de referência do Vision para .NET.

PHP: siga as instruções de configuração do PHP na página das bibliotecas de cliente e acesse a documentação de referência do Vision para PHP.

Ruby: siga as instruções de configuração do Ruby na página das bibliotecas de cliente e visite adocumentação de referência do Vision para Ruby.

Teste a detecção facial

Teste a detecção facial usando o aplicativo da Web a seguir. É possível usar a imagem fornecida (gs://cloud-samples-data/vision/face/faces.jpeg) ou especificar sua própria imagem do Cloud Storage. Envie a solicitação clicando em Executar.

Corpo da solicitação:

{
  "requests": [
    {
      "features": [
        {
          "maxResults": 10,
          "type": "FACE_DETECTION"
        }
      ],
      "image": {
        "source": {
          "imageUri": "gs://cloud-samples-data/vision/face/faces.jpeg"
        }
      }
    }
  ]
}

Abra o APIs Explorer do Google e envie a solicitação.

  1. Para abrir o APIs Explorer do Google, clique em Teste.

  2. Opcional. Modifique o corpo da solicitação atual.

  3. Para enviar a solicitação, clique em Executar.