SDK de Computer Vision de Azure Cognitive Services para Python

  • Artículo

El servicio Computer Vision proporciona a los desarrolladores acceso a algoritmos avanzados para procesar imágenes y devolver información. Los algoritmos de Computer Vision analizan el contenido de una imagen de diferentes formas, en función de las características visuales que le interesen.

Puede usar Computer Vision en su aplicación para lo siguiente:

  • Análisis de imágenes para obtener información
  • Extracción de texto de las imágenes
  • Generación de miniaturas

¿Busca más documentación?

Requisitos previos

Si necesita una cuenta de Computer Vision API, puede crear una con este comando de la CLI de 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

Instalación

Instale el SDK de Computer Vision de Azure Cognitive Services con pip y, opcionalmente, en un entorno virtual.

Configuración de un entorno virtual (opcional)

Aunque no es necesario, puede aislar el sistema base de los entornos de SDK de Azure si usa un entorno virtual. Ejecute los comandos siguientes para configurar un entorno virtual y acceder a él con venv, como cogsrv-vision-env:

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

Instalación del SDK

Instale el paquete del SDK de Computer Vision de Azure Cognitive Services para Python con pip:

pip install azure-cognitiveservices-vision-computervision

Authentication

Una vez creado el recurso de Computer Vision, necesita su regióny una de sus claves de cuenta para crear una instancia del objeto de cliente.

Estos valores se usan al crear la instancia del objeto de cliente ComputerVisionClient.

Obtener credenciales

Use el fragmento siguiente de la CLI de Azure para rellenar dos variables de entorno con la región de la cuenta de Computer Vision y una de sus claves (también puede encontrar estos valores en Azure Portal). El fragmento de código tiene el formato para el shell de 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)

Crear el cliente

Una vez que haya rellenado las ACCOUNT_REGION variables de entorno y ACCOUNT_KEY , puede crear el 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
)

Uso

Una vez que haya inicializado un objeto de cliente ComputerVisionClient , puede hacer lo siguiente:

  • Analizar una imagen: puede analizar una imagen para determinadas características, como caras, colores, etiquetas.
  • Generar miniaturas: cree una imagen JPEG personalizada para usarla como miniatura de la imagen original.
  • Obtener la descripción de una imagen: obtenga una descripción de la imagen en función de su dominio de sujeto.

Para más información acerca de este servicio, consulte ¿Qué es Computer Vision?.

Ejemplos

Las secciones siguientes proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Computer Vision, entre las que se incluyen las siguientes:

Análisis de una imagen

Puede analizar una imagen para detectar determinadas características con analyze_image. Use la propiedad visual_features para establecer los tipos de análisis que se pueden realizar en la imagen. Los valores habituales son VisualFeatureTypes.tags y 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)

Obtener una lista de dominios de sujeto

Revise los dominios de sujeto utilizados para analizar la imagen con list_models. Estos nombres de dominio se usan al analizar una imagen por dominio. Un ejemplo de un dominio es landmarks.

models = client.list_models()

for x in models.models_property:
    print(x)

Analizar una imagen por dominio

Puede analizar una imagen por dominio de sujeto con analyze_image_by_domain. Obtenga la lista de dominios de sujeto admitidos para usar el nombre de dominio correcto.

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

Obtener la descripción textual de una imagen

Puede obtener una descripción de texto basada en un idioma de una imagen con describe_image. Solicite varias descripciones con la propiedad max_description para realizar un análisis de texto para determinar palabras clave asociadas con la imagen. a train crossing a bridge over a body of water, a large bridge over a body of water y a train crossing a bridge over a large body of water son ejemplos de una descripción de texto de la siguiente imagen.

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)

Obtener el texto de la imagen

Puede obtener cualquier texto manuscrito o impreso de una imagen. Esto requiere dos llamadas al SDK: read y get_read_result. La llamada a read es asincrónica. En los resultados de la llamada get_read_result, debe comprobar si la primera llamada se completó con OperationStatusCodes antes de extraer los datos de texto. Los resultados incluyen el texto, así como las coordenadas del cuadro de límite para el 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)

Generar miniatura

Puede generar una miniatura (JPG) de una imagen con generate_thumbnail. La miniatura no necesita tener las mismas proporciones que la imagen original.

En este ejemplo se usa el paquete Pillow para guardar localmente la nueva imagen en miniatura.

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

Solución de problemas

General

Al interactuar con el objeto de cliente ComputerVisionClient mediante el SDK de Python, la clase ComputerVisionErrorException se usa para devolver errores. Los errores devueltos por el servicio se corresponden con los mismos códigos de estado HTTP devueltos para las solicitudes de API de REST.

Por ejemplo, si intenta analizar una imagen con una clave no válida, se devuelve un error 401. En el fragmento de código siguiente, el error se controla correctamente detectando la excepción y mostrando información adicional sobre el error.


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

Control de errores transitorios con reintentos

Mientras trabaja con el cliente ComputerVisionClient, puede encontrar errores transitorios debidos a los límites de frecuencia aplicados por el servicio u otros problemas transitorios, como interrupciones de red. Para información sobre cómo controlar estos tipos de errores, consulte la sección sobre el patrón Retry en la guía de patrones de diseño en la nube y el patrón Circuit Breaker relacionado.

Pasos siguientes

Más código de ejemplo

Hay varios ejemplos de SDK de Computer Vision para Python disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo de escenarios adicionales que suelen aparecer al trabajar con Computer Vision:

Documentación adicional

Para obtener documentación ampliada sobre el servicio Computer Vision, consulte la documentación de Azure Computer Vision en docs.microsoft.com.