SDK da Pesquisa Visual Computacional dos Serviços Cognitivos do Azure para Python

  • Artigo

O serviço de Pesquisa Visual Computacional fornece aos desenvolvedores o acesso a algoritmos avançados para processar imagens e retornar informações. Os algoritmos da Pesquisa Visual Computacional analisam o conteúdo de uma imagem de diferentes maneiras, dependendo das características visuais que interessam a você.

Use a Pesquisa Visual Computacional em seu aplicativo para:

  • Analisar imagens quanto a insights
  • Extrair texto de imagens
  • Gerar miniaturas

Procurando mais documentação?

Pré-requisitos

Caso precise de uma conta da API da Pesquisa Visual Computacional, crie uma com este comando da CLI do Azure:

RES_REGION=westeurope
RES_GROUP=<resourcegroup-name>
ACCT_NAME=<computervision-account-name>

az cognitiveservices account create \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --location $RES_REGION \
    --kind ComputerVision \
    --sku S1 \
    --yes

Instalação

Instale o SDK da Pesquisa Visual Computacional dos Serviços Cognitivos do Azure com o pip, opcionalmente em um ambiente virtual.

Configurar um ambiente virtual (opcional)

Embora não seja necessário, você poderá manter o sistema base e os ambientes do SDK do Azure isolados uns dos outros se você usar um ambiente virtual. Execute os seguintes comandos para configurar um ambiente virtual e, em seguida, entre nele com o venv, como cogsrv-vision-env:

python3 -m venv cogsrv-vision-env
source cogsrv-vision-env/bin/activate

Instalar o SDK

Instale o pacote do SDK da Pesquisa Visual Computacional dos Serviços Cognitivos do Azure para Python com o pip:

pip install azure-cognitiveservices-vision-computervision

Autenticação

Depois de criar o recurso da Pesquisa Visual Computacional, você precisará da região e de uma das chaves de conta para criar uma instância do objeto de cliente.

Use esses valores ao criar a instância do objeto de cliente ComputerVisionClient.

Obter credenciais

Use o snippet da CLI do Azure abaixo para popular duas variáveis de ambiente com a região e uma das chaves da conta da Pesquisa Visual Computacional (encontre também esses valores no portal do Azure). O snippet é formatado para o shell do Bash.

RES_GROUP=<resourcegroup-name>
ACCT_NAME=<computervision-account-name>

export ACCOUNT_REGION=$(az cognitiveservices account show \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --query location \
    --output tsv)

export ACCOUNT_KEY=$(az cognitiveservices account keys list \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --query key1 \
    --output tsv)

Criar cliente

Depois de preencher as ACCOUNT_REGION variáveis de ambiente e ACCOUNT_KEY , você pode criar o objeto cliente ComputerVisionClient .

from azure.cognitiveservices.vision.computervision import ComputerVisionClient
from azure.cognitiveservices.vision.computervision.models import VisualFeatureTypes
from msrest.authentication import CognitiveServicesCredentials

import os
region = os.environ['ACCOUNT_REGION']
key = os.environ['ACCOUNT_KEY']

credentials = CognitiveServicesCredentials(key)
client = ComputerVisionClient(
    endpoint="https://" + region + ".api.cognitive.microsoft.com/",
    credentials=credentials
)

Uso

Depois de inicializar um objeto cliente ComputerVisionClient , você poderá:

  • Analisar uma imagem: você pode analisar uma imagem para determinados recursos, como rostos, cores, marcas.
  • Gerar miniaturas: crie uma imagem JPEG personalizada para usar como uma miniatura da imagem original.
  • Obter a descrição de uma imagem: obtenha uma descrição da imagem com base em seu domínio de assunto.

Para obter mais informações sobre esse serviço, confira O que é a Pesquisa Visual Computacional?.

Exemplos

As seguintes seções fornecem vários snippets de código que abrangem algumas das tarefas mais comuns da Pesquisa Visual Computacional, incluindo:

Analisar uma imagem

Analise uma imagem para detectar determinadas características com analyze_image. Use a propriedade visual_features para definir os tipos de análises a serem realizados na imagem. Os valores comuns são VisualFeatureTypes.tags e VisualFeatureTypes.description.

url = "https://upload.wikimedia.org/wikipedia/commons/thumb/1/12/Broadway_and_Times_Square_by_night.jpg/450px-Broadway_and_Times_Square_by_night.jpg"

image_analysis = client.analyze_image(url,visual_features=[VisualFeatureTypes.tags])

for tag in image_analysis.tags:
    print(tag)

Obter a lista de domínios de assunto

Examine os domínios de assunto usados para analisar a imagem com list_models. Esses nomes de domínio são usados durante a análise de uma imagem por domínio. Um exemplo de um domínio é landmarks.

models = client.list_models()

for x in models.models_property:
    print(x)

Analisar uma imagem por domínio

Analise uma imagem por domínio de assunto com analyze_image_by_domain. Obtenha a lista de domínios de assunto com suporte para usar o nome de domínio correto.

domain = "landmarks"
url = "https://images.pexels.com/photos/338515/pexels-photo-338515.jpeg"
language = "en"

analysis = client.analyze_image_by_domain(domain, url, language)

for landmark in analysis.result["landmarks"]:
    print(landmark["name"])
    print(landmark["confidence"])

Obter uma descrição de texto de uma imagem

Obtenha uma descrição de texto baseada na linguagem de uma imagem com describe_image. Solicite várias descrições com a propriedade max_description se estiver fazendo uma análise de texto para detectar palavras-chave associadas à imagem. Entre os exemplos de uma descrição de texto para a imagem a seguir estão a train crossing a bridge over a body of water, a large bridge over a body of water e a train crossing a bridge over a large body of water.

domain = "landmarks"
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"
language = "en"
max_descriptions = 3

analysis = client.describe_image(url, max_descriptions, language)

for caption in analysis.captions:
    print(caption.text)
    print(caption.confidence)

Obter o texto de uma imagem

Obtenha qualquer texto manuscrito ou impresso de uma imagem. Isso exige duas chamadas ao SDK: read e get_read_result. A chamada para leitura é assíncrona. Nos resultados da chamada get_read_result, você precisa verificar se a primeira chamada foi concluída OperationStatusCodes antes de extrair os dados de texto. Os resultados incluem o texto, bem como as coordenadas da caixa delimitadora para o texto.

# import models
from azure.cognitiveservices.vision.computervision.models import OperationStatusCodes

url = "https://github.com/Azure-Samples/cognitive-services-python-sdk-samples/raw/master/samples/vision/images/make_things_happen.jpg"
raw = True
numberOfCharsInOperationId = 36

# SDK call
rawHttpResponse = client.read(url, language="en", raw=True)

# Get ID from returned headers
operationLocation = rawHttpResponse.headers["Operation-Location"]
idLocation = len(operationLocation) - numberOfCharsInOperationId
operationId = operationLocation[idLocation:]

# SDK call
result = client.get_read_result(operationId)

# Get data
if result.status == OperationStatusCodes.succeeded:

    for line in result.analyze_result.read_results[0].lines:
        print(line.text)
        print(line.bounding_box)

Gerar uma miniatura

Gere uma miniatura (JPG) de uma imagem com generate_thumbnail. A miniatura não precisa estar nas mesmas proporções da imagem original.

Este exemplo usa o pacote do Pillow para salvar a nova imagem em miniatura localmente.

from PIL import Image
import io

width = 50
height = 50
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"

thumbnail = client.generate_thumbnail(width, height, url)

for x in thumbnail:
    image = Image.open(io.BytesIO(x))

image.save('thumbnail.jpg')

Solução de problemas

Geral

Quando você interage com o objeto de cliente do ComputerVisionClient usando o SDK do Python, a classe ComputerVisionErrorException é usada para retornar erros. Os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para as solicitações da API REST.

Por exemplo, se você tentar analisar uma imagem com uma chave inválida, um erro 401 será retornado. No snippet a seguir, o erro é tratado normalmente capturando a exceção e exibindo informações adicionais sobre o erro.


domain = "landmarks"
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"
language = "en"
max_descriptions = 3

try:
    analysis = client.describe_image(url, max_descriptions, language)

    for caption in analysis.captions:
        print(caption.text)
        print(caption.confidence)
except HTTPFailure as e:
    if e.status_code == 401:
        print("Error unauthorized. Make sure your key and region are correct.")
    else:
        raise

Tratar erros transitórios com novas tentativas

Ao trabalhar com o cliente ComputerVisionClient, é possível encontrar falhas transitórias causadas por limites de taxa impostos pelo serviço ou outros problemas transitórios, como interrupções de rede. Para obter informações sobre como lidar com esses tipos de falhas, confira Padrão de repetição no guia Padrões de Design de Nuvem e o padrão de Disjuntor relacionado.

Próximas etapas

Mais códigos de exemplo

Várias amostras do SDK da Pesquisa Visual Computacional para Python estão disponíveis para você no repositório GitHub do SDK. Essas amostras fornecem códigos de exemplo para cenários adicionais comumente encontrados ao trabalhar com a Pesquisa Visual Computacional:

Documentação adicional

Para obter uma documentação mais abrangente sobre o serviço de Pesquisa Visual Computacional, confira a documentação da Pesquisa Visual Computacional do Azure em docs.microsoft.com.