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

対象

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

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

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

要件

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

ラベル検出で動画にアノテーションを付ける

このチュートリアルでは、LABEL_DETECTION リクエストを使用する基本的な Video API アプリケーションについて段階的に説明します。LABEL_DETECTION リクエストは、画像の内容に基づいて選択されたラベル(タグ)で動画にアノテーションを付けます。たとえば、踏切を通過する列車の動画には、「train」、「transportation」、「railroad crossing」などのラベルが生成される可能性があります。

まずコード全体を示します(このコードのコメントのほとんどは削除されています。これは、コードそのものは単純であることを示すためです。コードについて説明していく中で、コメントを追加で示します)。

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)

この単純なアプリケーションでは、次の処理を行います。

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

これらのステップについて、下記で詳しく説明します。

ライブラリのインポート

import argparse

from google.cloud import videointelligence

いくつかの標準ライブラリをインポートします。argparse は、アプリケーションが入力ファイル名を引数として受け取れるようにします。sys は、API レスポンスを待っている間に出力のフォーマットを行います。また、簡単な待機ループを実行するために 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 のすべてのラベルに同じ処理を繰り返します。このチュートリアルでは、動画レベルのアノテーションのみを表示します。動画レベルのアノテーションを確認するため、結果から segment_label_annotations データを取得します。各セグメント ラベルのアノテーションには、説明(segment_label.description)、エンティティ カテゴリのリスト(category_entity.description)に加え、動画の先頭からの開始時間と終了時間オフセットで示されるセグメント内のエンティティの発生位置が含まれます。

{
   "name":"us-west1.12089999971048628582",
   "metadata":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
      "annotationProgress":[
         {
            "inputUri":"gs://your_bucket/your_oject",
            "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_oject",
            "segmentLabelAnnotations": [
              {
                "entity": {
                  "entityId": "/m/01yrx",
                  "languageCode": "en-US"
                },
                "segments": [
                  {
                    "segment": {
                      "startTimeOffset": "0s",
                      "endTimeOffset": "14.833664s"
                    },
                    "confidence": 0.98509187
                  }
                ]
              },
               ...
            ]
         }
      ]
   }
}

リクエストで送信された動画は 1 つのため、最初の結果の最初の description を取得してその description を出力します。

アプリケーションの実行

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

$ python labels.py gs://your_bucket/your_oject
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 を使用してアノテーション タスクを実行しました。