Como usar a API Vision com Python

1. Visão geral

Com a API Vision, os desenvolvedores integram facilmente os recursos de detecção de visão nos aplicativos. Isso inclui rotulação de imagens, detecção de rostos e pontos de referência, reconhecimento óptico de caracteres (OCR) e identificação de conteúdo explícito.

Neste tutorial, você vai usar a API Vision com Python.

O que você vai aprender

• Como configurar seu ambiente
• Como realizar a detecção de rótulos
• Como fazer 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 o 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.

• 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.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. 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 do seu laptop, neste codelab usaremos 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 Shell.

Se esta for a primeira vez que você inicia o Cloud Shell, uma tela intermediária vai aparecer com a descrição dele. Se isso acontecer, clique em Continuar.

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

Essa máquina virtual contém 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. Neste codelab, quase todo o trabalho pode ser feito com um navegador.

Depois de se conectar ao Cloud Shell, você vai ver que sua conta já está autenticada e que o projeto está configurado com o ID do seu projeto.

2. 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`

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

3. Execute o comando a seguir no Cloud Shell para confirmar se 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].

Observação:se você estiver concluindo este tutorial fora do Cloud Shell, siga as etapas em Configurar as credenciais padrão do aplicativo.

3. configuração do ambiente

Antes de começar a usar a API Vision, execute o seguinte comando no Cloud Shell para ativar a API:

gcloud services enable vision.googleapis.com

Você verá algo como:

Operation "operations/..." finished successfully.

Agora você pode usar a API Vision.

Navegue até o diretório principal:

cd ~

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

virtualenv venv-vision

Ative o ambiente virtual:

source venv-vision/bin/activate

Observação:para parar de usar o ambiente virtual e voltar à versão do Python do sistema, use o comando deactivate.

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.

Observação:se você estiver configurando seu próprio ambiente de desenvolvimento em Python fora do Cloud Shell, siga estas diretrizes.

Nas próximas etapas, você vai usar um interpretador 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]:

Observação:se necessário, você pode sair da sua sessão IPython com o comando exit.

Você está pronto para fazer sua primeira solicitação...

4. Realizar detecção de rótulos

Um dos principais recursos da API Vision é identificar objetos ou entidades em uma imagem, o que é conhecido como anotação de rótulos. 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 ela. Ele retorna os rótulos mais correspondentes 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 em Tóquio:

Copie o seguinte código na sua 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 em relação a um conjunto de recursos específicos.

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

Se você receber um erro PermissionDenied, digite exit para sair do IPython e volte à etapa Configuração e requisitos.

Veja como a demonstração on-line apresenta os resultados:

Resumo

Nesta etapa, você conseguiu realizar a detecção de rótulos em uma imagem e mostrar 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 executa o reconhecimento óptico de caracteres (OCR). Ele detecta e extrai texto de uma imagem com suporte para uma ampla variedade de idiomas. Também é possível fazer a identificação automática de idioma.

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

Copie o seguinte código na sua 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 a demonstração on-line apresenta os resultados:

Resumo

Nesta etapa, você conseguiu realizar a detecção de texto em uma imagem e mostrar o texto reconhecido dela. Leia 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:

Copie o seguinte código na sua 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 a demonstração on-line apresenta os resultados:

Resumo

Nesta etapa, você conseguiu realizar a detecção de 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 identifica vários rostos em uma imagem, além dos principais atributos faciais associados, como estado emocional ou uso de chapéu.

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

Copie o seguinte código na sua 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 a demonstração on-line apresenta os resultados:

Resumo

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

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:

Copie o seguinte código na sua 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 a demonstração on-line apresenta os resultados:

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 há muito mais, e é possível solicitar vários recursos em uma única solicitação.

Este é 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!

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

Observação: este codelab não deve gerar custos. Com o nível sem custo financeiro do Google Cloud,você pode analisar 1.000 imagens por recurso sem custo financeiro todos os meses. Saiba mais sobre os preços do Vision.

Limpar

Para limpar o ambiente de desenvolvimento, no Cloud Shell:

• Se você ainda estiver na sessão do IPython, volte ao 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, no Cloud Shell:

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

Saiba mais

• Teste a demonstração on-line no seu navegador: https://cloud.google.com/vision
• Documentação da API Vision: https://cloud.google.com/vision/docs
• Python no Google Cloud: https://cloud.google.com/python
• Bibliotecas de cliente do Cloud para Python: https://github.com/googleapis/google-cloud-python

Licença

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