Azure Cognitive Services 计算机视觉 SDK for Python

计算机视觉服务为开发者提供访问高级算法来处理图像并返回信息。计算机视觉算法根据您感兴趣的视觉特征以不同的方式分析图像内容。

您可以在应用程序中使用计算机视觉来

• 分析图像以获得洞察力
• 从图像中提取文本
• 生成缩略图

需要更多文档吗？

• SDK参考文档
• 认知服务计算机视觉文档

先决条件

• Azure订阅 - 创建免费账户
• Azure 计算机视觉资源
• Python 3.6+

如果您需要计算机视觉API账户，您可以使用以下Azure CLI命令创建一个。

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

安装

使用pip安装Azure认知服务计算机视觉SDK，可选地在一个虚拟环境中安装。

配置虚拟环境（可选）

尽管不是必需的，但如果您使用虚拟环境，则可以将您的系统基本环境和Azure SDK环境相互隔离。执行以下命令进行配置，然后使用venv进入虚拟环境，例如cogsrv-vision-env。

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

安装SDK

使用pip安装Python的Azure认知服务计算机视觉SDK包包。

pip install azure-cognitiveservices-vision-computervision

身份验证

创建您的计算机视觉资源后，您需要其区域和其一个账户密钥来实例化客户端对象。

创建ComputerVisionClient客户端对象时使用这些值。

获取凭证

使用以下Azure CLI片段来填充两个环境变量，其中包含计算机视觉账户的区域和其一个密钥（您也可以在Azure门户中找到这些值）。片段格式为Bash shell。

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)

创建客户端

一旦填充了ACCOUNT_REGION和ACCOUNT_KEY环境变量，您就可以创建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
)

用法

初始化ComputerVisionClient客户端对象后，您可以

• 分析图像：您可以分析图像以获取某些特征，例如面部、颜色、标签。
• 生成缩略图：创建一个自定义JPEG图像作为原始图像的缩略图。
• 获取图像描述：根据其主题领域获取图像描述。

有关此服务的更多信息，请参阅什么是计算机视觉？。

示例

以下部分提供了几个代码片段，涵盖了最常见的计算机视觉任务，包括

• 分析图像
• 获取主题领域列表
• 按领域分析图像
• 获取图像的文本描述
• 从图像中获取手写文本
• 生成缩略图

分析图像

您可以使用analyze_image分析图像的某些特征。使用visual_features属性来设置对图像要执行的分析的类型。常见值包括VisualFeatureTypes.tags和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)

获取主题领域列表

使用list_models查看用于分析您的图像的主题领域。这些域名用于按领域分析图像时。一个示例域名是landmarks。

models = client.list_models()

for x in models.models_property:
    print(x)

按领域分析图像

您可以通过使用analyze_image_by_domain方法通过主题域分析图像。获取支持的主题域列表，以便使用正确的域名。

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

您可以使用describe_image方法获取图像的基于语言的文本描述。如果您正在进行与图像相关的关键词文本分析，请使用max_description属性请求多个描述。以下图像的文本描述示例包括一列火车穿越一座跨越水体的桥梁，一座跨越水体的宽阔桥梁和一列火车穿越一座跨越宽阔水体的桥梁。

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)

从图像中获取文本

您可以从图像中获取任何手写或印刷的文本。这需要两次调用SDK：read和get_read_result。读取调用是异步的。在get_read_result调用结果中，您需要在提取文本数据之前检查第一次调用是否成功完成OperationStatusCodes。结果包括文本以及文本的边界框坐标。

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

生成缩略图

您可以使用generate_thumbnail方法生成图像的缩略图（JPG）。缩略图不需要与原始图像具有相同的比例。

此示例使用Pillow包将新缩略图图像保存在本地。

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

故障排除

通用

当您使用Python SDK与ComputerVisionClient客户端对象交互时，使用ComputerVisionErrorResponseException类返回错误。服务返回的错误对应于REST API请求返回的相同HTTP状态码。

例如，如果您尝试使用无效密钥分析图像，将返回一个401错误。在以下片段中，通过捕获异常并显示有关错误的附加信息，优雅地处理了错误。

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

使用重试处理暂时性错误

在使用ComputerVisionClient客户端时，您可能会遇到由服务强制执行的速率限制或其他暂时性问题，例如网络中断。有关处理这些类型故障的信息，请参阅Cloud Design Patterns指南中的重试模式和相关断路器模式。

下一步操作

更多示例代码

在SDK的GitHub仓库中提供了多个计算机视觉Python SDK示例。这些示例代码为使用计算机视觉时遇到的常见场景提供了示例。

• 查看示例仓库

其他文档

有关计算机视觉服务的更详细文档，请参阅docs.microsoft.com上的Azure计算机视觉文档。

发布历史

0.9.0 (2021-05-31)

重大更改

• 操作ComputerVisionClientOperationsMixin.read有一个新的签名
• 操作ComputerVisionClientOperationsMixin.read_in_stream有一个新的签名

0.8.0 (2021-03-22)

功能

• 模型Line有一个新的参数appearance
• 模型TagResult有一个新的参数model_version
• 模型DomainModelResults有一个新的参数model_version
• 模型AreaOfInterestResult有一个新的参数model_version
• 模型DetectResult有一个新的参数model_version
• 模型ImageAnalysis有一个新的参数model_version
• 模型ImageDescription有一个新的参数model_version
• 模型OcrResult有一个新的参数model_version
• 模型ComputerVisionError有一个新的参数innererror

重大更改

• 操作ComputerVisionClientOperationsMixin.analyze_image有一个新的签名
• 操作ComputerVisionClientOperationsMixin.analyze_image_by_domain有一个新的签名
• 操作ComputerVisionClientOperationsMixin.analyze_image_by_domain_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.analyze_image_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.describe_image有一个新的签名
• 操作ComputerVisionClientOperationsMixin.describe_image_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.detect_objects有一个新的签名
• 操作ComputerVisionClientOperationsMixin.detect_objects_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.generate_thumbnail有一个新的签名
• 操作ComputerVisionClientOperationsMixin.generate_thumbnail_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.get_area_of_interest有一个新的签名
• 操作ComputerVisionClientOperationsMixin.get_area_of_interest_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.read_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.recognize_printed_text有一个新的签名
• 操作ComputerVisionClientOperationsMixin.recognize_printed_text_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.tag_image有一个新的签名
• 操作ComputerVisionClientOperationsMixin.tag_image_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.read有一个新的签名
• 模型AnalyzeResults有一个新的必需参数model_version
• 模型ComputerVisionError不再有参数request_id

0.7.0 (2020-10-08)

功能

• 支持3.1服务版本

0.6.0 (2020-05-18)

功能

• 模型Line有一个新的参数language
• 添加了操作ComputerVisionClientOperationsMixin.read
• 添加了操作ComputerVisionClientOperationsMixin.get_read_result
• 添加了操作ComputerVisionClientOperationsMixin.read_in_stream

重大更改

• 模型Line的参数words现在为必需
• 模型Line的参数bounding_box现在为必需
• 模型Line的参数text现在为必需
• 模型Word的参数confidence现在为必需
• 移除了操作ComputerVisionClientOperationsMixin.get_text_operation_result
• 移除了操作ComputerVisionClientOperationsMixin.get_read_operation_result
• 移除了操作ComputerVisionClientOperationsMixin.recognize_text_in_stream
• 移除了操作ComputerVisionClientOperationsMixin.recognize_text
• 移除了操作ComputerVisionClientOperationsMixin.batch_read_file
• 移除了操作ComputerVisionClientOperationsMixin.batch_read_file_in_stream
• 模型ReadOperationResult有一个新的签名

0.5.0 (2019-10-01)

功能

• 模型AdultInfo有一个新的参数is_gory_content
• 模型AdultInfo有一个新的参数gore_score

重大更改

• 操作ComputerVisionClientOperationsMixin.analyze_image有一个新的签名
• 操作ComputerVisionClientOperationsMixin.analyze_image_in_stream有一个新的签名
• 操作ComputerVisionClientOperationsMixin.describe_image有一个新的签名
• 操作ComputerVisionClientOperationsMixin.describe_image_in_stream有一个新的签名

0.4.0 (2019-06-27)

重大更改

• "batch_read_file"和"batch_read_file_in_stream"不再有"mode"参数

错误修复

• "bounding_box"现在支持浮点数
• 状态报告中的“Not Started”错误拼写

0.3.0 (2019-03-11)

功能

• 模型ImageAnalysis有一个新的参数brands
• 模型ImageAnalysis有一个新的参数objects
• 模型Word有一个新的参数confidence

重大更改

• 客户端ComputerVisionAPI已重命名为ComputerVisionClient
• 模型Word的参数text现在为必需
• 模型Word的参数bounding_box现在为必需

0.2.0 (2018-06-22)

功能

• analyze_image 现在支持 'en', 'es', 'ja', 'pt', 'zh'（包括这些操作的 "in_stream" 版本）
• describe_image/tag_image/analyze_image_by_domain 现在支持语言参数（包括这些操作的 "in_stream" 版本）
• Client 类可以用作上下文管理器，以保持底层 HTTP 会话打开以提高性能

错误修复

• 修复了几个无效的 JSON 描述，这会导致出现意外的异常（包括来自 bug #2614 的 OCRResult）

重大更改

• recognize_text 中的 "detect_handwriting" 布尔值现在是一个 "mode" 字符串，在 'Handwritten' 和 'Printed' 之间

一般重大更改

本版本使用下一代代码生成器，可能会引入重大更改。

• 模型签名现在只使用关键字参数语法。所有位置参数必须重写为关键字参数。为了在大多数情况下保持自动补全，现在为 Python 2 和 Python 3 生成模型。Python 3 使用 "*" 语法进行关键字参数。
• 枚举类型现在使用 "str" 混合（类 AzureEnum(str, Enum)）来改进遇到未识别枚举值时的行为。虽然这不是一个重大更改，但区别很重要，这里进行了说明：https://docs.pythonlang.cn/3/library/enum.html#others 简要说明
  • 不应使用 "is"。
  • "format" 将返回字符串值，其中 "%s" 字符串格式化将返回 NameOfEnum.stringvalue。应首选格式化语法。
• 新的长时间运行操作
  • 返回类型从 msrestazure.azure_operation.AzureOperationPoller 更改为 msrest.polling.LROPoller。外部 API 保持不变。
  • 返回类型现在始终为 msrest.polling.LROPoller，无论使用哪些可选参数。
  • 使用 raw=True 时的行为已改变。现在不再返回初始调用结果作为 ClientRawResponse（不进行轮询），而是返回一个 LROPoller。轮询后，最终资源将作为 ClientRawResponse 返回。
  • 新的 polling 参数。默认行为是 Polling=True，将使用 ARM 算法进行轮询。当 Polling=False 时，将返回初始调用的响应而不进行轮询。
  • polling 参数接受 msrest.polling.PollingMethod 子类的实例。
  • add_done_callback 在轮询完成后调用将不再引发异常，而是立即执行回调。

0.1.0 (2018-01-23)

• 初始发布