ラベル検出のチュートリアル

対象

このチュートリアルは、Video Intelligence API を使用するアプリケーションの調査と開発を開始できるように作られています。Python に関する基本的な知識がある方を対象としています。また、プログラミングに関する限定的な知識を理解できる必要もあります。このチュートリアルを終了すると、リファレンス ドキュメントを使用して独自の基本的なアプリケーションを作成できるようになります。

このチュートリアルでは、Python コードの Video Intelligence API アプリケーションを使用します。ここでの目的は、Python クライアント ライブラリについて説明することではなく、動画ラベル検出機能を使用して Video Intelligence API を呼び出す方法を説明することです。Java や Node.js のアプリケーションも基本的にはこれと同様です。

コードのみの例や他の言語のサンプルについては、関連する入門ガイドをご覧ください。

要件

このチュートリアルには、次の前提条件があります。

• Google Cloud Console で Video Intelligence API プロジェクトが設定されている。
• サービス アカウントとアプリケーションのデフォルト認証情報を使用して環境を設定している。
• Python プログラミングに関する基本知識がある。
• Python 開発環境の設定が完了している。
  最新バージョンの Python、pip と virtualenv をシステムにインストールすることをおすすめします。手順については、Google Cloud 用の Python 開発環境の設定ガイドをご覧ください。
• Google Cloud クライアント ライブラリをインストールしている。

ラベル検出を使用して動画にアノテーションを付ける

このチュートリアルでは、LABEL_DETECTION リクエストを使用する基本的な Video API アプリケーションについて順を追って説明します。LABEL_DETECTION リクエストにより、画像コンテンツに基づいて選択されたラベル（または「タグ」）で動画にアノテーションが付けられます。たとえば、踏切を通過する列車の動画では、「train」、「transportion」、「railroadcrosscrossing」などのラベルが生成されます。

このチュートリアルに必要なコード全体を次に示します。このコードのコメントのほとんどは削除されています。これは、コードそのものは単純であることを示すためです。代わりに、コードについて説明していく中で、コメントを追加で示します。

import argparse

from google.cloud import videointelligence

def analyze_labels(path):
    """Detects labels given a GCS path."""
    video_client = videointelligence.VideoIntelligenceServiceClient()
    features = [videointelligence.Feature.LABEL_DETECTION]
    operation = video_client.annotate_video(
        request={"features": features, "input_uri": path}
    )
    print("\nProcessing video for label annotations:")

    result = operation.result(timeout=90)
    print("\nFinished processing.")

    segment_labels = result.annotation_results[0].segment_label_annotations
    for i, segment_label in enumerate(segment_labels):
        print("Video label description: {}".format(segment_label.entity.description))
        for category_entity in segment_label.category_entities:
            print(
                "\tLabel category description: {}".format(category_entity.description)
            )

        for i, segment in enumerate(segment_label.segments):
            start_time = (
                segment.segment.start_time_offset.seconds
                + segment.segment.start_time_offset.microseconds / 1e6
            )
            end_time = (
                segment.segment.end_time_offset.seconds
                + segment.segment.end_time_offset.microseconds / 1e6
            )
            positions = "{}s to {}s".format(start_time, end_time)
            confidence = segment.confidence
            print("\tSegment {}: {}".format(i, positions))
            print("\tConfidence: {}".format(confidence))
        print("\n")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("path", help="GCS file path for label detection.")
    args = parser.parse_args()

    analyze_labels(args.path)

この簡単なアプリケーションでは次のタスクを実行します。

1. アプリケーションの実行に必要なライブラリをインポートする
2. Cloud Storage URI に保存されている動画ファイルを引数として受け取り、main() 関数に渡す
3. Video Intelligence API サービスの実行に必要な認証情報を取得する
4. 動画サービスに送信する動画アノテーション リクエストを作成する
5. リクエストを送信し、長時間実行オペレーションを返す
6. 動画が処理されて戻り値が返されるまで、長時間実行オペレーションをループする
7. サービスのレスポンスを解析してユーザーにレスポンスを表示する

ライブラリをインポートする

import argparse

from google.cloud import videointelligence

いくつかの標準ライブラリがインポートされています。アプリケーションが入力ファイル名を引数として受け取れるようにする argparse や API レスポンスを待っている間に出力をフォーマッティングするための sys です。単純な待機ループを実行するためにパッケージ time がインポートされます。

Video Intelligence API を使用する場合は、API 呼び出しのディレクトリを保持する google.cloud.videointelligence_v1 とその列挙型クラスをインポートする必要があります。

アプリケーションを実行する

parser = argparse.ArgumentParser(
    description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
parser.add_argument("path", help="GCS file path for label detection.")
args = parser.parse_args()

analyze_labels(args.path)

ここでは、Cloud Storage URI の動画ファイル名を取得するために渡された引数が解析され、main() 関数に渡されます。

API に対する認証

Video Intelligence API サービスと通信する前に、事前に取得した認証情報を使用してサービスを認証する必要があります。アプリケーション内で認証情報を取得する最も簡単な方法は、アプリケーションのデフォルト認証情報（ADC）を使用することです。デフォルトでは、ADC は GOOGLE_APPLICATION_CREDENTIALS 環境ファイルから認証情報を取得しようとします。このファイルは、サービス アカウントの JSON キーファイルを指すように設定されているはずです（クイックスタートで、ADC を使用するためのサービス アカウントと環境を設定しました。）

リクエストを作成する

video_client = videointelligence.VideoIntelligenceServiceClient()
features = [videointelligence.Feature.LABEL_DETECTION]
operation = video_client.annotate_video(
    request={"features": features, "input_uri": path}
)

Video Intelligence API サービスの準備ができたので、そのサービスに対するリクエストを作成できます。Video Intelligence API へのリクエストは JSON オブジェクトとして作成されます。このようなリクエストの具体的な構造については、Video Intelligence API リファレンスをご覧ください。

このコード スニペットにより、次の処理が行われます。

1. annotate_video() メソッドに対する POST リクエストの JSON を作成する。
2. 渡された動画ファイル名の Cloud Storage の場所をリクエストに挿入する。
3. annotate メソッドが LABEL_DETECTION を実行することを示します。

オペレーションを確認する

result = operation.result(timeout=90)
print("\nFinished processing.")

既存のオペレーションに対する既存のオペレーション リクエストを使用して、while ループを作成し、そのオペレーションの状態を定期的に確認します。オペレーションが done 状態になったことが示されたら、レスポンスが解析されます。

レスポンスをパースする

segment_labels = result.annotation_results[0].segment_label_annotations
for i, segment_label in enumerate(segment_labels):
    print("Video label description: {}".format(segment_label.entity.description))
    for category_entity in segment_label.category_entities:
        print(
            "\tLabel category description: {}".format(category_entity.description)
        )

    for i, segment in enumerate(segment_label.segments):
        start_time = (
            segment.segment.start_time_offset.seconds
            + segment.segment.start_time_offset.microseconds / 1e6
        )
        end_time = (
            segment.segment.end_time_offset.seconds
            + segment.segment.end_time_offset.microseconds / 1e6
        )
        positions = "{}s to {}s".format(start_time, end_time)
        confidence = segment.confidence
        print("\tSegment {}: {}".format(i, positions))
        print("\tConfidence: {}".format(confidence))
    print("\n")

オペレーションが完了すると、レスポンスには AnnotateVideoResponse 内に結果が含まれます。これは、リクエストに送信された各動画に対応する annotationResults のリストで構成されています。リクエストで送信された動画は 1 つのみであるため、結果の最初の segmentLabelAnnotations が取得され、segmentLabelAnnotations 内のすべてのラベルがループされます。このチュートリアルでは、segmentLabelAnnotations のみを使用して動画レベルのアノテーションのみを表示します。各 segment_label には、説明（segment_label.description）、エンティティ カテゴリのリスト（segment_label.category_entities）、動画に出現するラベルの開始時刻と終了時刻を識別するセグメントのリストが含まれます。（segment_label_annotations の場合は、動画全体または動画セグメントにまたがる 1 つのセグメントである必要があります）。

{
   "name":"us-west1.12089999971048628582",
   "metadata":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
      "annotationProgress":[
         {
            "inputUri":"gs://YOUR_BUCKET/YOUR_OBJECT",
            "updateTime":"2020-01-31T01:49:52.498015Z",
            "startTime":"2020-01-31T01:49:43.056481Z"
         }
      ]
   },
   "done": true,
   "response":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse",
      "annotationResults":[
         {
            "inputUri":"gs://YOUR_BUCKET/YOUR_OBJECT",
            "segmentLabelAnnotations": [
              {
                "entity": {
                  "entityId": "/m/01yrx",
                  "languageCode": "en-US"
                },
                "segments": [
                  {
                    "segment": {
                      "startTimeOffset": "0s",
                      "endTimeOffset": "14.833664s"
                    },
                    "confidence": 0.98509187
                  }
                ]
              },
               ...
            ]
         }
      ]
   }
}

リクエストで送信された動画は 1 つのみであるため、最初の結果の最初の description が出力されます。

アプリケーションを実行する

アプリケーションは、動画の Cloud Storage URI を単にアプリケーションに渡すだけで実行できます。

$ python labels.py gs://YOUR_BUCKET/YOUR_OBJECT
Operation us-west1.4757250774497581229 started: 2020-01-30T01:46:30.158989Z
Operation processing ...
The video has been successfully processed.

Video label description: urban area
        Label category description: city
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.946980476379

Video label description: traffic
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.94105899334

Video label description: vehicle
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.919958174229
...
 

出力

出力の例を以下に示します。

Processing video for label annotations:


Finished processing.
Video label description: crowd
        Label category description: people
        Segment 0: 0.0s to 60.24s
        Confidence: 0.527720749378

Video label description: official
        Label category description: person
        Segment 0: 0.0s to 60.24s
        Confidence: 0.372822880745

Video label description: audience
        Label category description: people
        Segment 0: 0.0s to 60.24s
        Confidence: 0.501719772816

Video label description: news
        Segment 0: 0.0s to 60.24s
        Confidence: 0.867252230644

Video label description: people
        Label category description: person
        Segment 0: 0.0s to 60.24s
        Confidence: 0.46747264266

Video label description: politics
        Segment 0: 0.0s to 60.24s
        Confidence: 0.319397002459

これで完了です。Video Intelligence API を使用してアノテーション タスクを実行しました。