Como usar a API Vision com Python

1. Visão geral

5ab7829fc22b21c4.png

A API Vision permite que os desenvolvedores integrem facilmente recursos de detecção por visão nos aplicativos, incluindo rotulagem de imagens, detecção facial e de pontos de referência, reconhecimento óptico de caracteres (OCR) e marcação de conteúdo explícito.

Neste tutorial, o foco será o uso da API Vision com o Python.

O que você vai aprender

  • Como configurar o ambiente
  • Como realizar a detecção de rótulos
  • Como realizar a detecção de texto
  • Como realizar a detecção de pontos de referência
  • Como realizar a detecção facial
  • Como realizar a detecção de objetos

O que é necessário

  • um projeto do Google Cloud;
  • Use um navegador, como o Chrome ou o Firefox.
  • Familiaridade com Python

Pesquisa

Como você vai usar este tutorial?

Apenas leitura Ler e fazer os exercícios

Como você classificaria sua experiência com Python?

Iniciante Intermediário Proficiente

Como você classificaria sua experiência com os serviços do Google Cloud?

Iniciante Intermediário Proficiente

2. Configuração e requisitos

Configuração de ambiente autoguiada

  1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

  • O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
  • O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
  • Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.
  1. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud possa ser operado remotamente em um laptop, neste codelab você vai usar o Cloud Shell, um ambiente de linha de comando executado no Cloud.

Ativar o Cloud Shell

  1. No Console do Cloud, clique em Ativar o Cloud Shell853e55310c205094.png.

55efc1aaa7a4d3ad.png

Se você estiver iniciando o Cloud Shell pela primeira vez, verá uma tela intermediária com a descrição dele. Se aparecer uma tela intermediária, clique em Continuar.

9c92662c6a846a5c.png

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

9f0e51b578fecce5.png

Essa máquina virtual tem todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Grande parte do trabalho neste codelab, se não todo, pode ser feito em um navegador.

Depois de se conectar ao Cloud Shell, você verá sua autenticação e o projeto estará configurado com o ID do seu projeto.

  1. Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:
gcloud auth list

Resposta ao comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`
  1. Execute o seguinte comando no Cloud Shell para confirmar que o comando gcloud sabe sobre seu projeto:
gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se o projeto não estiver configurado, configure-o usando este comando:

gcloud config set project <PROJECT_ID>

Resposta ao comando

Updated property [core/project].

3. Configuração do ambiente

Antes de começar a usar a API Vision, execute o seguinte comando no Cloud Shell para ativá-la:

gcloud services enable vision.googleapis.com

Você verá algo como:

Operation "operations/..." finished successfully.

Agora você pode usar a API Vision.

Navegue até seu diretório principal:

cd ~

Crie um ambiente virtual de Python para isolar as dependências:

virtualenv venv-vision

Ative o ambiente virtual:

source venv-vision/bin/activate

Instale o IPython e a biblioteca de cliente da API Vision:

pip install ipython google-cloud-vision

Você verá algo como:

...
Installing collected packages: ..., ipython, google-cloud-vision
Successfully installed ... google-cloud-vision-3.4.0 ...

Agora você já pode usar a biblioteca de cliente da API Vision.

Nas próximas etapas, você vai usar um interpretador de Python interativo chamado IPython, que foi instalado na etapa anterior. Inicie uma sessão executando ipython no Cloud Shell:

ipython

Você verá algo como:

Python 3.9.2 (default, Feb 28 2021, 17:03:44)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.12.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

Você já pode fazer sua primeira solicitação...

4. Realizar a detecção de rótulos

Um dos principais recursos da API Vision é identificar objetos ou entidades em uma imagem, conhecida como anotação de rótulo. A detecção de rótulos identifica objetos gerais, locais, atividades, espécies de animais, produtos e muito mais. A API Vision usa uma imagem de entrada e retorna os rótulos mais prováveis que se aplicam a essa imagem. Ela retorna os principais rótulos correspondentes junto com uma pontuação de confiança de uma correspondência com a imagem.

Neste exemplo, você vai realizar a detecção de rótulos em uma imagem (cortesia de Alex Knight) de Setagaya, um distrito popular de Tóquio:

756f97f0b1e46c38.jpeg

Copie o código a seguir na sessão do IPython:

from typing import Sequence

from google.cloud import vision


def analyze_image_from_uri(
    image_uri: str,
    feature_types: Sequence,
) -> vision.AnnotateImageResponse:
    client = vision.ImageAnnotatorClient()

    image = vision.Image()
    image.source.image_uri = image_uri
    features = [vision.Feature(type_=feature_type) for feature_type in feature_types]
    request = vision.AnnotateImageRequest(image=image, features=features)

    response = client.annotate_image(request=request)

    return response


def print_labels(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for label in response.label_annotations:
        print(
            f"{label.score:4.0%}",
            f"{label.description:5}",
            sep=" | ",
        )

Estude o código e veja como ele usa o método da biblioteca de cliente annotate_image para analisar uma imagem e identificar um conjunto de recursos.

Envie uma solicitação com o recurso LABEL_DETECTION:

image_uri = "gs://cloud-samples-data/vision/label/setagaya.jpeg"
features = [vision.Feature.Type.LABEL_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_labels(response)

A seguinte saída será exibida:

================================================================================
 97% | Bicycle
 96% | Tire
 94% | Wheel
 91% | Automotive lighting
 89% | Infrastructure
 87% | Bicycle wheel
 86% | Mode of transport
 85% | Building
 83% | Electricity
 82% | Neighbourhood

Veja como os resultados são apresentados pela demonstração on-line:

2191b0425c9c148f.png

Resumo

Nesta etapa, você realizou a detecção de rótulos em uma imagem e exibiu os rótulos mais prováveis associados a ela. Leia mais sobre a detecção de rótulos.

5. Realizar detecção de texto

A detecção de texto realiza o reconhecimento óptico de caracteres (OCR). Ele detecta e extrai o texto de uma imagem com suporte para vários idiomas. Também é possível fazer a identificação automática de idioma.

Neste exemplo, você vai realizar a detecção de texto na imagem de uma placa de trânsito:

4dedd3fcfd9ad99b.jpeg

Copie o código a seguir na sessão do IPython:

def print_text(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for annotation in response.text_annotations:
        vertices = [f"({v.x},{v.y})" for v in annotation.bounding_poly.vertices]
        print(
            f"{repr(annotation.description):42}",
            ",".join(vertices),
            sep=" | ",
        )

Envie uma solicitação com o recurso TEXT_DETECTION:

image_uri = "gs://cloud-samples-data/vision/ocr/sign.jpg"
features = [vision.Feature.Type.TEXT_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_text(response)

A seguinte saída será exibida:

================================================================================
'WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE' | (310,821),(2225,821),(2225,1965),(310,1965)
'WAITING'                                  | (344,821),(2025,879),(2016,1127),(335,1069)
'?'                                        | (2057,881),(2225,887),(2216,1134),(2048,1128)
'PLEASE'                                   | (1208,1230),(1895,1253),(1891,1374),(1204,1351)
'TURN'                                     | (1217,1414),(1718,1434),(1713,1558),(1212,1538)
'OFF'                                      | (1787,1437),(2133,1451),(2128,1575),(1782,1561)
'YOUR'                                     | (1211,1609),(1741,1626),(1737,1747),(1207,1731)
'ENGINE'                                   | (1213,1805),(1923,1819),(1920,1949),(1210,1935)

Veja como os resultados são apresentados pela demonstração on-line:

9c70fbce871c5fe5.png

Resumo

Nesta etapa, você conseguiu realizar a detecção de texto em uma imagem e exibir o texto reconhecido a partir da imagem. Saiba mais sobre a detecção de texto.

6. Realizar detecção de pontos de referência

A detecção de pontos de referência encontra estruturas famosas, naturais e construídas pelo homem em uma imagem.

Neste exemplo, você vai realizar a detecção de pontos de referência em uma imagem (cortesia de John Towner) da Torre Eiffel:

fb7801e36884b875.jpeg

Copie o código a seguir na sessão do IPython:

def print_landmarks(response: vision.AnnotateImageResponse, min_score: float = 0.5):
    print("=" * 80)
    for landmark in response.landmark_annotations:
        if landmark.score < min_score:
            continue
        vertices = [f"({v.x},{v.y})" for v in landmark.bounding_poly.vertices]
        lat_lng = landmark.locations[0].lat_lng
        print(
            f"{landmark.description:18}",
            ",".join(vertices),
            f"{lat_lng.latitude:.5f}",
            f"{lat_lng.longitude:.5f}",
            sep=" | ",
        )

Envie uma solicitação com o recurso LANDMARK_DETECTION:

image_uri = "gs://cloud-samples-data/vision/landmark/eiffel_tower.jpg"
features = [vision.Feature.Type.LANDMARK_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_landmarks(response)

A seguinte saída será exibida:

================================================================================
Trocadéro Gardens  | (303,36),(520,36),(520,371),(303,371) | 48.86160 | 2.28928
Eiffel Tower       | (458,76),(512,76),(512,263),(458,263) | 48.85846 | 2.29435

Veja como os resultados são apresentados pela demonstração on-line:

2788697365670985.png

Resumo

Nesta etapa, você conseguiu detectar pontos de referência em uma imagem da Torre Eiffel. Leia mais sobre a detecção de pontos de referência.

7. Realizar detecção facial

A detecção de características faciais detecta vários rostos em uma imagem, além dos principais atributos faciais associados, como estado emocional ou uso de chapéus.

Neste exemplo, você vai detectar rostos na imagem a seguir (cortesia de Himanshu Singh Gurjar):

58c578ece524cf32.jpeg

Copie o código a seguir na sessão do IPython:

def print_faces(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for face_number, face in enumerate(response.face_annotations, 1):
        vertices = ",".join(f"({v.x},{v.y})" for v in face.bounding_poly.vertices)
        print(f"# Face {face_number} @ {vertices}")
        print(f"Joy:     {face.joy_likelihood.name}")
        print(f"Exposed: {face.under_exposed_likelihood.name}")
        print(f"Blurred: {face.blurred_likelihood.name}")
        print("-" * 80)

Envie uma solicitação com o recurso FACE_DETECTION:

image_uri = "gs://cloud-samples-data/vision/face/faces.jpeg"
features = [vision.Feature.Type.FACE_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_faces(response)

A seguinte saída será exibida:

================================================================================
# Face 1 @ (1077,157),(2146,157),(2146,1399),(1077,1399)
Joy:     VERY_LIKELY
Exposed: VERY_UNLIKELY
Blurred: VERY_UNLIKELY
--------------------------------------------------------------------------------
# Face 2 @ (144,1273),(793,1273),(793,1844),(144,1844)
Joy:     VERY_UNLIKELY
Exposed: VERY_UNLIKELY
Blurred: UNLIKELY
--------------------------------------------------------------------------------
# Face 3 @ (785,167),(1100,167),(1100,534),(785,534)
Joy:     VERY_UNLIKELY
Exposed: LIKELY
Blurred: VERY_LIKELY
--------------------------------------------------------------------------------

Veja como os resultados são apresentados pela demonstração on-line:

cbb7f59299651b83.png

Resumo

Nesta etapa, você conseguiu realizar a detecção facial. Leia mais sobre a detecção facial.

8. Realizar a detecção de objetos

Neste exemplo, você vai realizar a detecção de objetos na mesma imagem anterior (cortesia de Alex Knight) de Setagaya:

756f97f0b1e46c38.jpeg

Copie o código a seguir na sessão do IPython:

def print_objects(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for obj in response.localized_object_annotations:
        nvertices = obj.bounding_poly.normalized_vertices
        print(
            f"{obj.score:4.0%}",
            f"{obj.name:15}",
            f"{obj.mid:10}",
            ",".join(f"({v.x:.1f},{v.y:.1f})" for v in nvertices),
            sep=" | ",
        )

Envie uma solicitação com o recurso OBJECT_LOCALIZATION:

image_uri = "gs://cloud-samples-data/vision/label/setagaya.jpeg"
features = [vision.Feature.Type.OBJECT_LOCALIZATION]

response = analyze_image_from_uri(image_uri, features)
print_objects(response)

A seguinte saída será exibida:

================================================================================
 93% | Bicycle         | /m/0199g   | (0.6,0.6),(0.8,0.6),(0.8,0.9),(0.6,0.9)
 92% | Bicycle wheel   | /m/01bqk0  | (0.6,0.7),(0.7,0.7),(0.7,0.9),(0.6,0.9)
 91% | Tire            | /m/0h9mv   | (0.7,0.7),(0.8,0.7),(0.8,1.0),(0.7,1.0)
 75% | Bicycle         | /m/0199g   | (0.3,0.6),(0.4,0.6),(0.4,0.7),(0.3,0.7)
 51% | Tire            | /m/0h9mv   | (0.3,0.6),(0.4,0.6),(0.4,0.7),(0.3,0.7)

Veja como os resultados são apresentados pela demonstração on-line:

e1c2ca803d874a6b.png

Resumo

Nesta etapa, você conseguiu realizar a detecção de objetos. Leia mais sobre a detecção de objetos.

9. Vários recursos

Você já viu como usar alguns recursos da API Vision, mas existem muitos outros e é possível solicitar vários recursos com uma única solicitação.

Aqui está o tipo de solicitação que você pode fazer para receber todos os insights de uma só vez:

image_uri = "gs://..."
features = [
    vision.Feature.Type.OBJECT_LOCALIZATION,
    vision.Feature.Type.FACE_DETECTION,
    vision.Feature.Type.LANDMARK_DETECTION,
    vision.Feature.Type.LOGO_DETECTION,
    vision.Feature.Type.LABEL_DETECTION,
    vision.Feature.Type.TEXT_DETECTION,
    vision.Feature.Type.DOCUMENT_TEXT_DETECTION,
    vision.Feature.Type.SAFE_SEARCH_DETECTION,
    vision.Feature.Type.IMAGE_PROPERTIES,
    vision.Feature.Type.CROP_HINTS,
    vision.Feature.Type.WEB_DETECTION,
    vision.Feature.Type.PRODUCT_SEARCH,
    vision.Feature.Type.OBJECT_LOCALIZATION,
]

# response = analyze_image_from_uri(image_uri, features)

E há mais possibilidades, como realizar detecções em um lote de imagens de forma síncrona ou assíncrona. Confira todos os guias de instruções.

10. Parabéns!

5ab7829fc22b21c4.png

Você aprendeu a usar a API Vision com Python e testou alguns recursos de detecção de imagem.

Limpar

Para limpar seu ambiente de desenvolvimento, faça o seguinte no Cloud Shell:

  • Se você ainda estiver na sessão do IPython, volte para o shell: exit
  • Pare de usar o ambiente virtual do Python: deactivate
  • Exclua a pasta do ambiente virtual: cd ~ ; rm -rf ./venv-vision

Para excluir seu projeto do Google Cloud usando o Cloud Shell:

  • Recupere seu ID do projeto atual: PROJECT_ID=$(gcloud config get-value core/project)
  • Verifique se este é o projeto que você quer excluir: echo $PROJECT_ID
  • Exclua o projeto: gcloud projects delete $PROJECT_ID

Saiba mais

Licença

Este conteúdo está sob a licença Atribuição 2.0 Genérica da Creative Commons.