Python 用の Azure Cognitive Services Computer Vision SDK

  • [アーティクル]

Computer Vision サービスを使用すると、開発者は、イメージを処理して情報を返すための高度なアルゴリズムにアクセスできます。 Computer Vision のアルゴリズムでは、ユーザーが関心を寄せた視覚的特徴に応じて、さまざまな方法で画像のコンテンツを分析します。

自分のアプリケーションで Computer Vision を使用すると、以下のことができます。

  • 画像を分析して分析情報を得る
  • 画像からテキストを抽出する
  • サムネイルを生成する

その他のドキュメントをお探しですか?

前提条件

Computer Vision 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 Cognitive Services Computer Vision SDK を (必要に応じて仮想環境内に) インストールします。

仮想環境を構成する (オプション)

必須ではありませんが、仮想環境を使用すると、お使いのベース システムと Azure SDK 環境を相互に分離させておくことができます。 venv を使用した次のコマンドを実行して、仮想環境 (例: cogsrv-vision-env) を構成した後にその仮想環境に入ります。

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

SDK のインストール

pip を使用して、Python 用の Azure Cognitive Services Computer Vision SDK パッケージをインストールします。

pip install azure-cognitiveservices-vision-computervision

認証

Computer Vision リソースを作成した後は、クライアント オブジェクトをインスタンス化するために、そのリージョンとそのアカウント キーの 1 つが必要になります。

ComputerVisionClient クライアント オブジェクトのインスタンスを作成するときに、これらの値を使用します。

資格情報の取得

次の Azure CLI スニペットを使用して、2 つの環境変数に Computer Vision アカウントのリージョンとそのアカウント キーの 1 つを設定します (これらの値は、Azure portal 内で見つけることもできます)。 このスニペットは 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)

クライアントの作成

環境変数と ACCOUNT_KEY 環境変数をACCOUNT_REGION設定したら、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 イメージを作成します。
  • 画像の説明を取得する: そのサブジェクト ドメインに基づいて画像の説明を取得します。

このサービスの詳細については、「Computer Vision とは」を参照してください。

例

次のセクションでは、以下に示す Computer Vision の最も一般的なタスクのいくつかに対応したコード スニペットをいくつか紹介します。

イメージを分析する

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 プロパティを使用して、いくつかの説明を要求します。 次の画像のテキスト説明の例には、a train crossing a bridge over a body of water、a large bridge over a body of water、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)

画像からテキストを取得する

画像から手書きのテキストや印刷されたテキストを取得できます。 これには、SDK に対する 2 つの呼び出し (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 クライアント オブジェクトを操作する場合、ComputerVisionErrorException クラスを使用してエラーを返します。 このサービスによって返されるエラーは、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 クライアントの操作中に、このサービスによって適用されたレート制限によって一時的な障害が発生したり、ネットワークの停止など、他の一時的な問題が発生したりする可能性があります。 これらの種類の障害の処理については、クラウド設計パターン ガイドの「再試行パターン」および「サーキット ブレーカー パターン」を参照してください。

次のステップ

その他のサンプル コード

Computer Vision Python SDK のサンプルは、この SDK の GitHub リポジトリでいくつか公開されています。 これらのサンプルでは、Computer Vision の操作中によく発生する追加のシナリオのコード例を示しています。

その他のドキュメント

Computer Vision サービスに関するさらに詳細なドキュメントについては、docs.microsoft.com にある Azure Computer Vision のドキュメントを参照してください。