Share via

SDK de Imagem Digitalizada dos Serviços Cognitivos do Azure para Python

  • Artigo

O serviço Imagem Digitalizada fornece aos programadores acesso a algoritmos avançados para processamento de imagens e devolução de informações. Imagem Digitalizada algoritmos analisam o conteúdo de uma imagem de formas diferentes, consoante as funcionalidades visuais que lhe interessam.

Pode utilizar Imagem Digitalizada na sua aplicação para:

  • Analisar imagens para obter informações
  • Extrair texto de imagens
  • Gerar miniaturas

Está à procura de mais documentação?

Pré-requisitos

Se precisar de uma conta de API Imagem Digitalizada, pode criar 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 os Serviços Cognitivos do Azure Imagem Digitalizada SDK com pip, opcionalmente num ambiente virtual.

Configurar um ambiente virtual (opcional)

Embora não seja necessário, pode manter o sistema base e os ambientes do SDK do Azure isolados uns dos outros se utilizar um ambiente virtual. Execute os seguintes comandos para configurar e, em seguida, introduza um ambiente virtual com 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 de Imagem Digitalizada dos Serviços Cognitivos do Azure para Python com pip:

pip install azure-cognitiveservices-vision-computervision

Autenticação

Depois de criar o recurso Imagem Digitalizada, precisa da respetiva região e de uma das respetivas chaves de conta para instanciar o objeto de cliente.

Utilize estes valores quando criar a instância do objeto de cliente ComputerVisionClient .

Obter credenciais

Utilize o fragmento da CLI do Azure abaixo para preencher duas variáveis de ambiente com a região da conta Imagem Digitalizada e uma das respetivas chaves (também pode encontrar estes valores no portal do Azure). O fragmento está formatado para a 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 , pode criar o objeto de 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
)

Utilização

Depois de inicializar um objeto de cliente ComputerVisionClient , pode:

  • Analisar uma imagem: pode analisar uma imagem para determinadas funcionalidades, como rostos, cores, etiquetas.
  • Gerar miniaturas: crie uma imagem JPEG personalizada para utilizar como miniatura da imagem original.
  • Obter descrição de uma imagem: obtenha uma descrição da imagem com base no respetivo domínio de assunto.

Para obter mais informações sobre este serviço, consulte O que é Imagem Digitalizada?.

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas de Imagem Digitalizada mais comuns, incluindo:

Analisar uma imagem

Pode analisar uma imagem para determinadas funcionalidades com analyze_image. Utilize a visual_features propriedade para definir os tipos de análise a executar 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 lista de domínios de assunto

Reveja os domínios do assunto utilizados para analisar a sua imagem com list_models. Estes nomes de domínio são utilizados ao analisar 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

Pode analisar uma imagem por domínio de assunto com analyze_image_by_domain. Obtenha a lista de domínios de assunto suportados para utilizar 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 a descrição de texto de uma imagem

Pode obter uma descrição de texto baseada em idioma de uma imagem com describe_image. Peça várias descrições com a max_description propriedade se estiver a fazer uma análise de texto para palavras-chave associadas à imagem. Exemplos de uma descrição de texto para a imagem seguinte incluem a train crossing a bridge over a body of water, a large bridge over a body of watere 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 texto da imagem

Pode obter qualquer texto manuscrito ou impresso a partir de uma imagem. Isto requer duas chamadas para o SDK: read e get_read_result. A chamada para ler é assíncrona. Nos resultados da chamada de get_read_result, tem de verificar se a primeira chamada foi concluída com OperationStatusCodes antes de extrair os dados de texto. Os resultados incluem o texto, bem como as coordenadas da caixa delimitadora do 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 miniatura

Pode gerar uma miniatura (JPG) de uma imagem com generate_thumbnail. A miniatura não precisa de estar nas mesmas proporções que a imagem original.

Este exemplo utiliza o pacote Pillow para guardar 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')

Resolução de problemas

Geral

Quando interage com o objeto de cliente ComputerVisionClient com o SDK Python, a ComputerVisionErrorResponseException classe é utilizada para devolver erros. Os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST.

Por exemplo, se tentar analisar uma imagem com uma chave inválida, é devolvido um 401 erro. No fragmento seguinte, o erro é processado corretamente através da deteção da exceção e da apresentação de 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

Lidar com erros transitórios com repetições

Ao trabalhar com o cliente ComputerVisionClient , poderá deparar-se com falhas transitórias causadas por limites de taxa impostos pelo serviço ou outros problemas transitórios, como falhas de rede. Para obter informações sobre como lidar com estes tipos de falhas, veja Padrão de repetição no guia Padrões de Conceção da Cloud e o padrão de Disjuntor Automático relacionado.

Passos seguintes

Mais código de exemplo

Estão disponíveis vários Imagem Digitalizada exemplos do SDK Python no repositório do GitHub do SDK. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com Imagem Digitalizada:

Documentação adicional

Para obter documentação mais extensa sobre o serviço Imagem Digitalizada, veja a documentação do Azure Imagem Digitalizada sobre docs.microsoft.com.