Tutorial de deteção da Web

Público-alvo

O objetivo deste tutorial é ajudar a desenvolver aplicações com a funcionalidade de deteção na Web da API Vision. Parte do princípio de que tem conhecimentos básicos de técnicas e construções de programação, mas mesmo que seja um programador iniciante, deve conseguir acompanhar e executar este tutorial sem dificuldade e, em seguida, usar a documentação de referência da API Vision para criar aplicações básicas.

Este tutorial explica passo a passo uma aplicação da API Vision, mostrando como fazer uma chamada à API Vision para usar a respetiva funcionalidade de deteção na Web.

Pré-requisitos

Python

Vista geral

Este tutorial explica passo a passo uma aplicação básica da API Vision que usa um Web detection pedido. Uma Web detection resposta anota a imagem enviada no pedido com:

  • etiquetas obtidas da Web
  • URLs de sites que têm imagens correspondentes
  • URLs de imagens da Web que correspondem parcial ou totalmente à imagem no pedido
  • URLs de imagens visualmente semelhantes

Lista de códigos

À medida que lê o código, recomendamos que o acompanhe consultando a referência da API Vision Python.

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))

Esta aplicação simples realiza as seguintes tarefas:

  • Importa as bibliotecas necessárias para executar a aplicação
  • Usa um caminho de imagem como argumento e transmite-o para a função main()
  • Usa o cliente da API Google Cloud para realizar a deteção na Web
  • Faz um ciclo sobre a resposta e imprime os resultados
  • Imprime uma lista de entidades Web com descrição e classificação
  • Imprime uma lista de páginas correspondentes
  • Imprime uma lista de imagens com correspondência parcial
  • Imprime uma lista de imagens totalmente correspondentes

Uma visão mais detalhada

Importar bibliotecas

import argparse

from google.cloud import vision

Importamos bibliotecas padrão:

  • argparse para permitir que a aplicação aceite nomes de ficheiros de entrada como argumentos
  • io para ler a partir de ficheiros

Outras importações:

  • A classe ImageAnnotatorClient na biblioteca google.cloud.vision para aceder à API Vision.
  • O módulo types na biblioteca google.cloud.vision para criar pedidos.

Executar a aplicação

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))

Aqui, analisamos simplesmente o argumento transmitido que especifica o URL da imagem da Web e transmitimo-lo à função main().

Autenticação na API

Antes de comunicar com o serviço da API Vision, tem de autenticar o seu serviço através de credenciais adquiridas anteriormente. Numa aplicação, a forma mais simples de obter credenciais é usar as Credenciais padrão da aplicação (ADC). A biblioteca de cliente obtém as credenciais automaticamente. Por predefinição, isto é feito através da obtenção de credenciais da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que deve ser definida para apontar para o ficheiro de chave JSON da sua conta de serviço (consulte o artigo Configure uma conta de serviço para mais informações).

Construir o pedido

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 nosso serviço Vision API está pronto, podemos criar um pedido para o serviço.

Este fragmento do código realiza as seguintes tarefas:

  1. Cria uma instância ImageAnnotatorClient como cliente.
  2. Constrói um objeto Image a partir de um ficheiro local ou de um URI.
  3. Transmite o objeto Image ao método web_detection do cliente.
  4. Devolve as anotações.

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}")

Quando a operação estiver concluída, analisamos a WebDetection e imprimimos as entidades e os URLs contidos na anotação (os dois principais resultados de cada tipo de anotação são apresentados na secção seguinte).

Executar a aplicação

Para executar a aplicação, transmitimos o URL da Web (http://www.photos-public-domain.com/wp-content/uploads/2011/01/old-vw-bug-and-van.jpg) da seguinte imagem de um carro.

Segue-se o comando Python com o URL da Web transmitido da imagem do carro, seguido do resultado da consola. Tenha em atenção que é adicionada uma pontuação de relevância após as entidades indicadas. Tenha em atenção que as classificações não são normalizadas nem comparáveis entre diferentes consultas de imagens.

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

Parabéns! Realizou a deteção na Web através da API Vision!