Vertex AI Vision モーション フィルタ

1. 目標

概要

この Codelab では、エンドツーエンドの Vertex AI Vision アプリケーションを作成し、モーション フィルタリング機能を使用して動画を送信する方法を説明します。このチュートリアルでは、モーション フィルタ設定の各種パラメータについて説明します。

  • モーション検知の感度
  • アクティビティの最小時間
  • ルックバック ウィンドウ
  • クールダウン時間
  • モーション検知ゾーン

学習内容

  • ストリーミング用の動画を取り込む方法
  • モーション フィルタで利用できる各種機能と使用方法
  • モーション フィルタの統計情報を確認する方法
  • 動画に応じて設定を調整する方法

2. 始める前に

  1. Google Cloud コンソールの [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。プロジェクト セレクタに移動
  2. Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
  3. Compute Engine API と Vision AI API を有効にします。API を有効にする

サービス アカウントを作成します。

  1. Google Cloud コンソールで [サービス アカウントの作成] ページに移動します。[サービス アカウントの作成] に移動
  2. プロジェクトを選択します。
  3. [サービス アカウント名] フィールドに名前を入力します。Google Cloud コンソールは、この名前に基づいて [サービス アカウント ID] フィールドに入力します。[サービス アカウントの説明] フィールドに説明を入力します。たとえば、クイックスタート用のサービス アカウントなどです。
  4. [作成して続行] をクリックします。
  5. プロジェクトへのアクセス権を付与するには、サービス アカウントに次のロールを付与します。[Vision AI] > [Vision AI 編集者]、[Compute Engine] > [Compute インスタンス管理者（ベータ版）]、[ストレージ] > [ストレージ オブジェクト閲覧者] †。[ロールを選択] リストでロールを選択します。ロールを追加するには、[別のロールを追加] をクリックして各ロールを追加します。注: [ロール] フィールドは、サービス アカウントがプロジェクト内のどのリソースにアクセスできるかに影響します。これらのロールは後で取り消すことも、追加のロールを付与することもできます。本番環境では、オーナー、編集者、閲覧者のロールを付与しないでください。代わりに、ニーズに合わせて事前定義ロールまたはカスタムロールを付与します。
  6. [続行] をクリックします。
  7. [完了] をクリックして、サービス アカウントの作成を完了します。ブラウザ ウィンドウは閉じないでください。次のステップでこれを使用します。

サービス アカウント キーを作成します。

  1. Google Cloud コンソールで、作成したサービス アカウントのメールアドレスをクリックします。
  2. [キー] をクリックします。
  3. [鍵を追加]、[新しい鍵を作成] の順にクリックします。
  4. [作成] をクリックします。JSON キーファイルがパソコンにダウンロードされます。
  5. [閉じる] をクリックします。
  6. Google Cloud CLI をインストールして初期化します。

† このロールは、Cloud Storage バケットからサンプル動画ファイルをコピーする場合にのみ必要です。

3. モーション フィルタ

モーション フィルタは、モーション イベントを含むモーション セグメントと商品動画セグメントをキャプチャします。ユーザーは、モーションの感度、イベントの最小長、ルックバック ウィンドウ、クールダウン期間、モーション検出ゾーンを調整することで、自分のニーズに合わせてフィルタを設定できます。

モーション フィルタの設定

モーション フィルタには、カスタマイズ可能な 5 つの設定があります。

  1. 動きに対する感度: 動きを検出する感度。
  2. 最小アクティビティ時間: モーション イベントをキャプチャする最小時間。
  3. ルックバック ウィンドウ: モーション イベントが検出される前に動画の録画を開始するまでの時間。
  4. クールダウン期間: モーション イベントが終了すると、指定した期間のクールダウンが行われます。クールダウン期間中は、モーション イベントはトリガーされません。
  5. モーション検出ゾーン: モーション検出を実行する場所を指定する、ユーザーが構成したゾーン。（後のセクションで詳しく説明します）

動きに対する感度

vaictl コマンドでフラグ motion_detection_sensitivity を使用します。
文字列。デフォルトのメディア。低、中、高から選択できます。

モーション検知の感度を高くすると、ノイズや小さな動きに敏感になります。この設定は、動くものが小さい環境（遠くの人物など）や、光が安定している設定におすすめします。

一方、感度が低いと、照明による干渉の影響を受けにくくなります。この設定は、屋外環境など照明による干渉が多い場合や、ノイズが多い低画質の動画に最適です。この設定は最も積極的なフィルタリングであるため、小さな被写体の動きが無視される可能性があります。

アクティビティの最小時間

vaictl コマンドでフラグ min_event_length_in_seconds を使用します。
整数。デフォルトは 10 秒です。範囲は 0 ～ 3,600 秒です。

フレーム内でモーション イベント セグメントが検出されると解析されるモーション イベント動画の最小時間。

ルックバック ウィンドウ

vaictl コマンドでフラグ look_back_window_in_seconds を使用します。
整数。デフォルトは 3 秒です。値の範囲は 0 ～ 3,600 秒です。

ルックバック ウィンドウは、モーション イベントが検出される前にキャッシュに保存された期間です。モーション イベントが検出される数秒前にフレーム内で何が起こっているかを確認する場合に便利です。

クールダウン期間

vaictl コマンドでフラグ cool_down_period_in_seconds を使用します。
整数。デフォルトは 300 秒です。範囲は 0 ～ 3,600 秒です。

クールダウン期間は、モーション イベントがキャプチャされた後にモーション検知を一時停止する時間です。クールダウン期間中、動きを検出するための演算は行われません。

4. 基本的なモーション フィルタの例

Vaictl SDK マニュアル

モーション フィルタのある入力ストリームの vaictl マニュアルを確認するには、次のコマンドを使用します。

vaictl send video-file applying motion-filter -h

サンプル動画を準備する

  1. サンプル動画をコピーするには、次の gsutil cp コマンドを使用します。次の変数を置き換えます。
  • SOURCE: 使用する動画ファイルの場所。独自の動画ファイルソース（gs://BUCKET_NAME/FILENAME.mp4 など）を使用するか、サンプル動画（gs://cloud-samples-data/vertex-ai-vision/street_vehicles_people.mp4）（人物と車両が写っている動画、ソース）を使用できます。
export SOURCE=gs://cloud-samples-data/vertex-ai-vision/street_vehicles_people.mp4
gsutil cp $SOURCE .

環境変数を準備する

提供されているコマンド テンプレートを使用するには、以下の環境変数を設定します。

vaictl 変数

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • LOCATION_ID: 地域 ID。（us-central1 など）。詳細については、クラウドのロケーションをご覧ください。
  • LOCAL_FILE: ローカル動画ファイルのファイル名。たとえば、street_vehicles_people.mp4 などです。
  • -loop フラグ: 省略可。ファイルデータをループしてストリーミングをシミュレートします。
export PROJECT_ID=<Your Google Cloud project ID>
export LOCATION_ID=us-central1

モーション フィルタ変数

  • MOTION_SENSITIVITY: モーション検出の感度。
  • MIN_EVENT_LENGTH: モーション イベントの最小時間。
  • LOOK_BACK_WINDOW: モーション イベントの最初のモーションの前にキャプチャする時間。
  • COOL_DOWN_PERIOD: モーション イベントがキャプチャされた後にモーション検出が一時停止する期間。
export MOTION_SENSITIVITY=<low or medium or high>
export MIN_EVENT_LENGTH=<0-3600>
export LOOK_BACK_WINDOW=<0-3600>
export COOL_DOWN_PERIOD=<0-3600>

モーション フィルタ コマンドを準備する

入力ストリームでモーション フィルタを使用する方法は 2 つあります。最初の方法は、Cloud コンソールでモーション イベントをストリームに送信することです。2 つ目のオプションは、モーション イベントをローカル ストレージに送信する方法です。

結果を Cloud コンソールに送信する

vaictl を使用して、出力動画データを Cloud コンソールにストリーミングできます。まず、Cloud コンソールで Vision AI API を有効にします。

新しいストリームを登録する

  1. Vertex AI Vision の左側のパネルで [ストリーム] タブをクリックします。
  2. [登録] をクリックします。
  3. [ストリーム名] に「motion-detection-stream」と入力します。
  4. 地域に us-central1 と入力します。
  5. [登録] をクリックします。

結果をストリームに送信する

このコマンドは、動画ファイルをストリームにストリーミングします。-loop フラグを使用すると、コマンドを停止するまで動画がストリーミングにループされます。このコマンドはバックグラウンド ジョブとして実行し、ストリーミングを継続します。

先頭に nohup、最後に & を追加してバックグラウンド ジョブにします。

INPUT_VIDEO=street_vehicles_people.mp4

vaictl -p $PROJECT \
       -l $LOCATION_ID \
       -c application-cluster-0 \
       --service-endpoint visionai.googleapis.com \
  send video-file  --file-path $INPUT_VIDEO \
  applying motion-filter
         --motion-sensitivity=$MOTION_SENSITIVITY \
         --min-event-length=$MIN_EVENT_LENGTH \
         --lookback-length=$LOOK_BACK_WINDOW \
         --cooldown-length=$COOL_DOWN_PERIOD \
  to streams motion-detection-stream --loop

vaictl 取り込みオペレーションの開始から動画がダッシュボードに表示されるまで、100 秒ほどかかることがあります。

ストリームの取り込みが可能になったら、Vertex AI Vision ダッシュボードの [ストリーム] タブでトラフィック ストリーム ストリームを選択して、動画フィードを表示できます。

[ストリーム] タブに移動

ローカル ストレージに結果を送信する

このコマンドは、動画ファイルをストリームにストリーミングします。

先頭に nohup、末尾に & を追加して、バックグラウンド ジョブにします。

INPUT_VIDEO=street_vehicles_people.mp4
OUTPUT_PATH=<path_to_store_motion_events_on_local_disk>

nohup vaictl -p $PROJECT \
             -l $LOCATION_ID \
             -c application-cluster-0 \
             --service-endpoint visionai.googleapis.com \
  send video-file  --file-path $INPUT_VIDEO \
  applying motion-filter
         --motion-sensitivity=$MOTION_SENSITIVITY \
         --min-event-length=$MIN_EVENT_LENGTH \
         --lookback-length=$LOOK_BACK_WINDOW \
         --cooldown-length=$COOL_DOWN_PERIOD \
  to mp4file --mp4-file-path=$OUTPUT_PATH --loop

5. モーション検知ゾーン

このセクションでは、モーション検知ゾーンの使用方法と設定方法について説明します。ゾーンは、興味のないエリアからの動きをマスクしてモーション検知を改善することを目的としています。

モーション検出ゾーンには、（1）アノテーションが付いた領域でのみモーション検出が実行されるポジティブ ゾーンと、（2）アノテーションが付いた領域の動きをモーション検出が無視するネガティブ ゾーンの 2 種類があります。

ゾーン アノテーション

vaictl コマンドでフラグ zone_annotation を使用して、ゾーンのポリゴンの座標を入力します。
文字列。デフォルトはゾーン アノテーションで空です。

ゾーン アノテーションはユーザーが入力する文字列であり、ユーザーが非表示にする、またはフォーカスするフレーム内のゾーンを示します。ゾーンにアノテーションを付けるには、ゾーン内の各ノードの X 軸と Y 軸の画像座標を指定する必要があります。ゾーンは、ポリゴンを形成するために 3 つ以上のノードが必要です。フレームには複数のゾーンが存在することがあります。ゾーンが重複している場合、両方のゾーンがカバーするエリアは引き続きカバーされます。

ゾーン アノテーションには、従う必要がある特定の入力構文があります。

  • 単一のノードを表すには、: を使用して画像座標の x 軸と y 軸を接続します。たとえば、左上の (0,0) ノードは 0:0 と表されます。
  • 1 つのゾーン内のすべてのノードを指定するには、; を使用してノードを接続します。たとえば、(0,0)、(100,0)、(100,100)、(0, 100) のノードがあるゾーンの場合、ゾーンは 0:0;100:0;100:100;0:100 と表されます。ノードを入力するときは、必ず隣接する接続ノードとして入力します。順序は時計回りまたは反時計回りのどちらでもかまいません。

モーション検出ゾーン - 正方形*4 つのノードがある正方形のゾーン。

モーション検出ゾーン - 三角形*3 つのノードがある三角形のゾーン。

  • 1 つのフレーム内に複数のゾーンを示すには、- を使用して異なるゾーンを接続します。たとえば、(0,0)、(100,0)、(100,100)、(0,100) と、(120,120)、(110,150)、(200,160) の両方を入力する場合、入力ゾーンのアノテーションは 0:0;100:0;100:100;0:100-120:120;110:150;200:160 になります。

モーション検出ゾーン - 2 つのゾーンがあるフレーム*フレーム内の 2 つのゾーン。

画像から座標を取得するには、オンラインで利用できる座標取得ツールがあります。たとえば、Wolfram - 画像から座標を取得するをご覧ください。

アノテーション付きのゾーンを除外する

vaictl コマンドでフラグ exclude_annotated_zone を使用して、ゾーン内またはゾーン外でのモーションの検出を構成します。
ブール値。デフォルト: false。

アノテーション付きのゾーンを除外するは、ユーザーからのブール値入力で、モーション検出でアノテーション付きのゾーンを除外するかどうかを示します。

  • true に設定すると、アノテーション付きゾーンはネガティブゾーンとして機能します。アノテーションを付けたゾーン内の動きは検出されません。

モーション検知ゾーン - 除外オプション *入力ゾーンの外でのみモーション検知を実行します。

  • false に設定すると、そのゾーンは正のゾーンとして機能し、動きの検出がフォーカスされます。

モーション検出ゾーン - オプションを追加 *モーション検知は、入力ゾーンでのみ実行します。

6. モーション検出ゾーンを使用したモーション フィルタの例

この例では、前景で木が絶えず動いている動画を例として使用します。通常のモーション フィルタ設定では、モーション フィルタが動いている木を「動画全体で常に動いている」ものとして登録するため、動画から生成されるモーション イベントは、元の動画の長さの 1 つだけになります。ただし、モーション検知ゾーンを使用すると、木の動きを適切にマスクして、車や歩行者の動きにフォーカスできます。

動画の準備

サンプル動画（gs://cloud-samples-data/vertex-ai-vision/dynamic-background-fall.mp4）には、www.changedetection.net の木、車、歩行者が含まれています。

動画のクレジット: N. Goyette, P.-M. Jodoin、F. Porikli, J. Konrad、P. Ishwar、changedetection.net: A new changedetection. net: A new change detected benchmark dataset、Proc. IEEE Workshop on Change Detection（CDW-2012）、CVPR-2012、Providence、RIO、6 月 16 ～ 21 日、2012

環境変数の準備

Google Cloud プロジェクト変数。

export PROJECT_ID=<Your Google Cloud project ID>
export LOCATION_ID=us-central1
export LOCAL_FILE=street_vehicles_people.mp4

基本的なモーション フィルタの構成。

export MOTION_SENSITIVITY=<low or medium or high>
export MIN_EVENT_LENGTH=<0-3600>
export LOOK_BACK_WINDOW=<0-3600>
export COOL_DOWN_PERIOD=<0-3600>

モーション検出ゾーンの設定。

以下から選択して、モーション検知ゾーンのさまざまな用途を確認してください。

モーション検出のツリーを除外する。

export ZONE_ANNOTATION="0:0;680:0;660:70;380:320;100:150"
export EXCLUDE_ANNOTATED_ZONE=true

モーション検出ゾーン - サンプル動画のアノテーション付きのゾーンからモーション検出を除外 *入力ゾーンの外でのみモーション検知を実行します。

道路でのモーション検知に重点を置く。

export ZONE_ANNOTATION="0:300;780:300;780:480;0:480"
export EXCLUDE_ANNOTATED_ZONE=false

モーション検出ゾーン - サンプル動画のアノテーション付きゾーンからモーション検出を実行する *入力ゾーンの外でのみモーション検知を実行します。

モーション フィルタを使用して動画ストリームを送信する

モーション イベントを Cloud コンソールに送信する

vaictl を使用して、出力動画データを Cloud コンソールにストリーミングできます。まず、Cloud コンソールで Vision AI API を有効にします。

新しいストリームを登録する

  1. Vertex AI Vision の左側のパネルで [ストリーム] タブをクリックします。
  2. [登録] をクリックします。
  3. [ストリーム名] に「motion-detection-stream」と入力します。
  4. 地域に us-central1 と入力します。
  5. [登録] をクリックします。

結果をストリームに送信する

このコマンドは、動画ファイルをストリームにストリーミングします。-loop フラグを使用すると、コマンドを停止するまで動画がストリーミングにループされます。このコマンドはバックグラウンド ジョブとして実行し、ストリーミングを継続します。

先頭に nohup、最後に & を追加してバックグラウンド ジョブにします。

vaictl -p $PROJECT \
       -l $LOCATION_ID \
       -c application-cluster-0 \
       --service-endpoint visionai.googleapis.com \
  send video-file  --file-path $INPUT_VIDEO \
  applying motion-filter
         --motion-sensitivity=$MOTION_SENSITIVITY \
         --min-event-length=$MIN_EVENT_LENGTH \
         --lookback-length=$LOOK_BACK_WINDOW \
         --cooldown-length=$COOL_DOWN_PERIOD \
         --zone_annotation=ZONE_ANNOTATION \
         --exclude_annotated_zone=$EXCLUDE_ANNOTATED_ZONE \
  to streams motion-detection-stream --loop

vaictl 取り込みオペレーションの開始から動画がダッシュボードに表示されるまで、100 秒ほどかかることがあります。

ストリームの取り込みが利用可能になったら、Vertex AI Vision ダッシュボードの [ストリーム] タブで、トラフィック ストリームを選択して動画フィードを表示できます。

[ストリーム] タブに移動

結果をローカル ストレージに送信する

このコマンドは、動画ファイルをストリームにストリーミングします。–loop フラグを使用すると、コマンドを停止するまで、動画がストリームにループ再生されます。このコマンドはバックグラウンド ジョブとして実行し、ストリーミングを継続します。

先頭に nohup、末尾に & を追加して、バックグラウンド ジョブにします。

OUTPUT_PATH=<path_to_store_motion_events>

vaictl -p $PROJECT \
       -l $LOCATION_ID \
       -c application-cluster-0 \
       --service-endpoint visionai.googleapis.com \
  send video-file  --file-path $INPUT_VIDEO \
  applying motion-filter
         --motion-sensitivity=$MOTION_SENSITIVITY \
         --min-event-length=$MIN_EVENT_LENGTH \
         --lookback-length=$LOOK_BACK_WINDOW \
         --cooldown-length=$COOL_DOWN_PERIOD \
         --zone_annotation=$ZONE_ANNOTATION \
         --exclude_annotated_zone=$EXCLUDE_ANNOTATED_ZONE \
  to mp4file --mp4-file-path=$OUTPUT_PATH --loop

7. 完了

お疲れさまでした。ラボはこれで完了です。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、ctrl + z を使用してコマンドラインから vaictl SDK オペレーションを終了します。

リソース

https://cloud.google.com/vision-ai/docs/overview

https://cloud.google.com/vision-ai/docs/motion-filtering-model

https://cloud.google.com/vision-ai/docs/create-manage-streams

フィードバック

フィードバックを送信する

アンケート

このチュートリアルをどのように使用されますか？

通読するのみ 通読し、演習を行う

この Codelab はどの程度役に立ちましたか？

とても役に立つ 役に立った