Tutorial sobre detecção na Web

Público

O objetivo deste tutorial é ajudar você a desenvolver aplicativos usando o recurso de detecção da Web da API Vision. Presumimos que você esteja familiarizado com construções e técnicas básicas de programação, mas mesmo se você for um programador iniciante, poderá acompanhar e executar este tutorial sem dificuldades e usar a documentação de referência da API Vision para criar aplicativos básicos.

Neste tutorial, discutimos sobre um aplicativo da API Vision e mostramos como fazer uma chamada a ela para usar o recurso de detecção na Web.

Pré-requisitos

• Configure um projeto da API Vision no Console do Google Cloud

• Configure o ambiente para usar o Application Default Credentials.

Python

• Instale o Python.
• Instale o pip.
• Instale a biblioteca de cliente do Google Cloud.

Visão geral

Neste tutorial, apresentamos um aplicativo básico da API Vision que usa uma solicitação Web detection. Uma resposta Web detection anota a imagem enviada na solicitação com:

• rótulos recebidos da Web;
• URLs com imagens correspondentes;
• URLs para imagens da Web que correspondem em parte ou totalmente à imagem na solicitação;
• URLs para imagens visualmente similares.

Listagem de códigos

Ao ler o código, recomendamos que você acompanhe a referência da API Vision para Python (em inglês).

import argparse

from google.cloud import vision

def annotate(path: str) -> vision.WebDetection:
    """Returns web annotations given the path to an image.

    Args:
        path: path to the input image.

    Returns:
        An WebDetection object with relevant information of the
        image from the internet (i.e., the annotations).
    """
    client = vision.ImageAnnotatorClient()

    if path.startswith("http") or path.startswith("gs:"):
        image = vision.Image()
        image.source.image_uri = path

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

        image = vision.Image(content=content)

    web_detection = client.web_detection(image=image).web_detection

    return web_detection

def report(annotations: vision.WebDetection) -> None:
    """Prints detected features in the provided web annotations.

    Args:
        annotations: The web annotations (WebDetection object) from which
        the features should be parsed and printed.
    """
    if annotations.pages_with_matching_images:
        print(
            f"\n{len(annotations.pages_with_matching_images)} Pages with matching images retrieved"
        )

        for page in annotations.pages_with_matching_images:
            print(f"Url   : {page.url}")

    if annotations.full_matching_images:
        print(f"\n{len(annotations.full_matching_images)} Full Matches found: ")

        for image in annotations.full_matching_images:
            print(f"Url  : {image.url}")

    if annotations.partial_matching_images:
        print(f"\n{len(annotations.partial_matching_images)} Partial Matches found: ")

        for image in annotations.partial_matching_images:
            print(f"Url  : {image.url}")

    if annotations.web_entities:
        print(f"\n{len(annotations.web_entities)} Web entities found: ")

        for entity in annotations.web_entities:
            print(f"Score      : {entity.score}")
            print(f"Description: {entity.description}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    path_help = str(
        "The image to detect, can be web URI, "
        "Google Cloud Storage, or path to local file."
    )
    parser.add_argument("image_url", help=path_help)
    args = parser.parse_args()

    report(annotate(args.image_url))

Esse aplicativo simples:

• Importa as bibliotecas necessárias para executar o aplicativo
• Usa um caminho de imagem como argumento e o transmite para a função main()
• Usa o cliente da API Google Cloud para executar a detecção na Web.
• Retorna a resposta e imprime os resultados.
• Imprime uma lista de entidades da Web com descrição e pontuação.
• Imprime uma lista de páginas correspondentes.
• Imprime uma lista de imagens parcialmente correspondentes.
• Imprime uma lista de imagens totalmente correspondentes.

Mais detalhes

Como importar bibliotecas

import argparse

from google.cloud import vision

Importamos bibliotecas padrão:

• argparse para permitir que o aplicativo aceite nomes de arquivo de entrada como argumentos;
• io para leitura de arquivos.

Outras importações:

• A classe ImageAnnotatorClient na biblioteca google.cloud.vision para acessar a API Vision.
• O módulo types na biblioteca google.cloud.vision para criar solicitações.

Como executar o aplicativo

parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
)
path_help = str(
    "The image to detect, can be web URI, "
    "Google Cloud Storage, or path to local file."
)
parser.add_argument("image_url", help=path_help)
args = parser.parse_args()

report(annotate(args.image_url))

Neste caso, simplesmente analisamos o argumento transmitido que especifica o URL da imagem da Web e o transmitimos para a função main().

Como autenticar com a API

Antes de se comunicar com a API do Vision, você precisa autenticar seu serviço usando as credenciais já adquiridas. A maneira mais simples de receber credenciais em um aplicativo é usar o Application Default Credentials (ADC). A biblioteca de cliente recebe as credenciais automaticamente. Por padrão, isso é feito quando são recebidas as credenciais da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Elas precisam ser configuradas para indicar o arquivo de chave JSON da sua conta de serviço. Para mais informações, consulte Configurar uma conta de serviço.

Como criar a solicitação

client = vision.ImageAnnotatorClient()

if path.startswith("http") or path.startswith("gs:"):
    image = vision.Image()
    image.source.image_uri = path

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

    image = vision.Image(content=content)

web_detection = client.web_detection(image=image).web_detection

Agora que o serviço da Vision API está pronto, podemos criar uma solicitação para ele.

Esse snippet de código executa as seguintes tarefas:

1. Cria uma instância ImageAnnotatorClient como o cliente.
2. Cria um objeto Image a partir de um arquivo local ou um URI.
3. Transmite o objeto Image para o método web_detection do cliente.
4. Retorna as anotações.

Como imprimir a resposta

if annotations.pages_with_matching_images:
    print(
        f"\n{len(annotations.pages_with_matching_images)} Pages with matching images retrieved"
    )

    for page in annotations.pages_with_matching_images:
        print(f"Url   : {page.url}")

if annotations.full_matching_images:
    print(f"\n{len(annotations.full_matching_images)} Full Matches found: ")

    for image in annotations.full_matching_images:
        print(f"Url  : {image.url}")

if annotations.partial_matching_images:
    print(f"\n{len(annotations.partial_matching_images)} Partial Matches found: ")

    for image in annotations.partial_matching_images:
        print(f"Url  : {image.url}")

if annotations.web_entities:
    print(f"\n{len(annotations.web_entities)} Web entities found: ")

    for entity in annotations.web_entities:
        print(f"Score      : {entity.score}")
        print(f"Description: {entity.description}")

Após a conclusão da operação, abordamos o WebDetection e imprimimos as entidades e URLs contidos na anotação. Os dois principais resultados de cada tipo de anotação são mostrados na próxima seção.

Como executar o aplicativo

Para executar o aplicativo, transmitimos o URL http://www.photos-public-domain.com/wp-content/uploads/2011/01/old-vw-bug-and-van.jpg da imagem de carro a seguir.

Este é o comando Python com o URL da imagem de carro transmitido, seguido pela saída do console. A pontuação de relevância está localizada após a lista de entidades. As pontuações não são normalizadas ou comparáveis em diferentes consultas de imagem.

python web_detect.py "http://www.photos-public-domain.com/wp-content/uploads/2011/01/old-vw-bug-and-van.jpg"

5 Pages with matching images retrieved
Url   : http://www.photos-public-domain.com/2011/01/07/old-volkswagen-bug-and-van/
Url   : http://pix-hd.com/old+volkswagen+van+for+sale
...

2 Full Matches found:
Url  : http://www.photos-public-domain.com/wp-content/uploads/2011/01/old-vw-bug-and-van.jpg
Url  : http://www.wbwagen.com/media/old-volkswagen-bug-and-van-picture-free-photograph-photos-public_s_66f487042adad5a6.jpg

4 Partial Matches found:
Url  : http://www.photos-public-domain.com/wp-content/uploads/2011/01/old-vw-bug-and-van.jpg
Url  : http://www.wbwagen.com/media/old-vw-bug-and-vanjpg_s_ac343d7f041b5f8d.jpg
...

5 Web entities found:
Score      : 5.35028934479
Description: Volkswagen Beetle
Score      : 1.43998003006
Description: Volkswagen
Score      : 0.828279972076
Description: Volkswagen Type 2
Score      : 0.75271999836
Description: Van
Score      : 0.690039992332
Description: Car

Como esperado, a detecção na Web do Cloud Vision encontrou e retornou em fullMatchingImages o URL da imagem da Web que transmitimos como entrada para o aplicativo. Ele é o último URL listado acima.

Parabéns! Você realizou a detecção da Web usando a API Vision.