Vertex AI Vision 動態濾鏡

1. 目標

總覽

本程式碼研究室的重點是建立端對端 Vertex AI Vision 應用程式，示範如何傳送含有動作篩選功能的影片。在本教學課程中，我們將介紹動作篩選器設定中的不同參數：

動作偵測靈敏度
事件錄影時間下限
回溯期
收操時間
動作偵測區

課程內容

如何擷取影片以供串流播放
動態濾鏡提供的不同功能和使用方式
如何查看動態濾鏡的統計資料
如何根據影片調整設定

2. 事前準備

在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。前往專案選取器
確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
啟用 Compute Engine 和 Vision AI API。啟用 API

建立服務帳戶：

前往 Google Cloud 控制台中的「Create service account」(建立服務帳戶) 頁面。前往「建立服務帳戶」
選取專案。
在「Service account name」(服務帳戶名稱) 欄位中輸入名稱。Google Cloud 控制台會根據這個名稱填入「Service account ID」(服務帳戶 ID) 欄位。在「Service account description」(服務帳戶說明) 欄位中輸入說明。例如：快速入門導覽課程的服務帳戶。
按一下 [建立並繼續]。
如要提供專案存取權，請將下列角色授予服務帳戶：Vision AI > Vision AI 編輯者、Compute Engine > Compute 執行個體管理員 (Beta 版)、Storage > Storage 物件檢視者 †。在「Select a role」(選取角色) 清單中，選取角色。如要新增其他角色，請按一下「新增其他角色」，然後新增其他角色。注意：「Role」(角色) 欄位會影響服務帳戶在專案中可存取的資源。日後可以撤銷這些角色或授予其他角色。在正式環境中，請勿授予「擁有者」、「編輯者」或「檢視者」角色。而是根據需求，授予預先定義角色或自訂角色。
按一下「繼續」。
按一下「Done」(完成)，即完成建立服務帳戶。請勿關閉瀏覽器視窗，後續步驟會用到。

建立服務帳戶金鑰：

在 Google Cloud 控制台中，點按您建立的服務帳戶電子郵件地址。
點按「Keys」(金鑰)。
依序點按「Add key」(新增金鑰) 和「Create new key」(建立新的金鑰)。
按一下「建立」，系統會將 JSON 金鑰檔案下載至您的電腦。
點選「關閉」。
安裝並初始化 Google Cloud CLI。

† 如果要從 Cloud Storage bucket 複製範例影片檔，才需要這個角色。

3. 動態濾鏡

動作篩選器會擷取含有動作事件的動作和產品影片片段。使用者可以調整動作感應度、最短事件長度、回溯時間範圍、冷卻時間和動作偵測區域，根據自身需求設定篩選器。

動態篩選器設定

動態濾鏡提供 5 種設定，可供自訂。

動作感應靈敏度：觸發動作感應的靈敏度。
事件錄影時間下限：系統擷取動態事件的最短時間。
回溯期：偵測到動作事件前，影片應開始錄影的時間長度。
冷卻期：動作事件結束後，系統會進入指定時間長度的冷卻期。在冷卻期間，系統不會觸發動作事件。
動作偵測區域：使用者設定的區域，用於指定應執行動作偵測的位置。(我們會在後續章節中詳細說明)

動作感應靈敏度

在 vaictl 指令中使用 motion_detection_sensitivity 旗標。
字串。預設中繼資料。可選擇低、中或高。

動作偵測靈敏度越高，就越容易受到噪音和微小動作影響。如果場景中有較小的移動物體 (例如遠處的人) 且光線穩定，建議使用這項設定。

另一方面，低感應度較不易受到光線干擾。如果光源干擾較多 (例如戶外環境)，或是影片畫質較差 (可能會有更多雜訊)，這項設定就非常適合。由於這是最嚴格的篩選設定，因此可能會忽略小型物體的移動。

事件錄影時間下限

在 vaictl 指令中使用 min_event_length_in_seconds 旗標。
整數。預設為 10 秒。範圍介於 0 秒到 3600 秒。

在影格中偵測到動作事件片段後，系統會剖析動作事件影片，這個設定就是指影片的最低時長。

回溯期

在 vaictl 指令中使用 look_back_window_in_seconds 旗標。
整數。預設為 3 秒。範圍介於 0 秒到 3600 秒。

回溯期是指偵測到動作事件前，系統會快取的時間長度。當我們想瞭解偵測到動作事件前幾秒的畫面發生了什麼事，這項功能就非常實用。

等待期

在 vaictl 指令中使用 cool_down_period_in_seconds 旗標。
整數。預設值為 300 秒。範圍介於 0 秒到 3600 秒。

冷卻時間是指系統在偵測到動作事件後，暫停動作偵測的時間長度。在等待期內，系統不會執行任何運算來偵測動作。

4. 基本動作篩選器範例

Vaictl SDK 手冊

如要查看 vaictl 手冊，瞭解如何使用動作篩選器輸入串流，請使用下列指令。

vaictl send video-file applying motion-filter -h

準備範例影片

您可以使用下列 gsutil cp 指令複製範例影片。請替換下列變數：

來源：要使用的影片檔案位置。你可以使用自己的影片檔案來源 (例如 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。詳情請參閱「Cloud 據點」一文。
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>

準備動作篩選器指令

使用輸入串流的動態濾鏡有兩種方式。第一個選項是將動作事件傳送至雲端控制台中的串流。第二種做法是將動作事件傳送至本機儲存空間。

將結果傳送至 Cloud 控制台

您可以使用 vaictl 將輸出影片資料串流至 Cloud 控制台。首先，請在 Cloud 控制台中啟用 Vision AI API。

註冊新的串流

按一下 Vertex AI Vision 左側面板中的「串流」分頁標籤。
按一下「註冊」
在「Stream name」(串流名稱) 中輸入 motion-detection-stream
在區域中輸入 us-central1
按一下「註冊」

將結果傳送至串流

這項指令會將影片檔案串流至串流。如果使用 –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) 負向區域，動作偵測會忽略註解區域中的任何動作。

區域註解

在 vaictl 指令中使用 zone_annotation 旗標，輸入區域多邊形的座標。
字串。區域註解的預設值為空白。

區域註解是使用者輸入的字串，表示使用者想隱藏或聚焦的影格區域。如要註解區域，使用者必須為區域中的每個節點指定 x 軸和 y 軸的圖片座標。可用區必須有三個以上的節點，才能形成多邊形。一個影格可以有多個區域。如果區域重疊，兩個區域涵蓋的範圍仍會受到保護。

區域註解有特定的輸入語法，請務必遵守。

如要標示單一節點，請使用 : 連接圖片座標的 x 軸和 y 軸。舉例來說，左上角的 (0,0) 節點會標示為 0:0。
如要表示單一區域中的所有節點，請使用 ; 連接節點。舉例來說，如果某個區域的節點為 (0,0)、(100,0)、(100,100) 和 (0, 100)，該區域就會標示為 0:0;100:0;100:100;0:100。請務必輸入相鄰的節點做為連接節點，順時針或逆時針皆可。

動作偵測區 - 正方形 *具有四個節點的方形區域。

動作偵測區 - 三角形 *具有三個節點的三角形區域。

如要在單一影格中標示多個區域，請使用 - 連接不同區域。舉例來說，如果我們想輸入 (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。

動作偵測區域 - 包含兩個區域的影格 *畫面中的兩個區域。

如要從圖片取得座標，網路上有一些工具可協助您取得座標。例如，請參閱「Wolfram - Get Coordinates from Image」。

排除註解區域

在 vaictl 指令中使用 exclude_annotated_zone 標記，設定偵測區域內或區域外的動作。
布林值。預設值為 false。

排除註解區域是使用者輸入的布林值，表示使用者是否要排除動作偵測中的註解區域。

如果設為 true，註解區域會做為負區域。系統不會偵測註解區域中的動作。

動作偵測區 - 排除選項 *只在輸入區域外執行動作偵測。

如果設為 false，該區域會做為正向區域，動態偵測功能會著重於此。

動作偵測區 - 包含選項 *只在輸入區域執行動作偵測。

6. 動作偵測區域的動作篩選器範例

在本範例中，我們將使用前景中樹木不斷移動的影片做為範例。在一般動作篩選器設定中，影片只會產生一個動作事件，且長度與原始影片相同，因為動作篩選器會將移動的樹木註冊為「在整部影片中持續移動」。不過，有了動作偵測區域，我們就能適當遮蓋樹木的動作，並專注於車輛和行人的動作。

準備影片

範例影片 (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 change detection benchmark dataset》，載於 Proc. IEEE Workshop on Change Detection (CDW-2012) at CVPR-2012，Providence, RI，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

動作偵測區域 - 從範例影片中標註的區域執行動作偵測 *只在輸入區域外執行動作偵測。

傳送含有動作濾鏡的影片串流

將動作事件傳送至雲端控制台

您可以使用 vaictl 將輸出影片資料串流至 Cloud 控制台。首先，請在 Cloud 控制台中啟用 Vision AI API。

註冊新的串流

按一下 Vertex AI Vision 左側面板中的「串流」分頁標籤。
按一下「註冊」
在「Stream name」(串流名稱) 中輸入 motion-detection-stream
在區域中輸入 us-central1
按一下「註冊」

將結果傳送至串流

在開頭加上 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 資訊主頁的「串流」分頁中查看影片動態消息。

前往「串流」分頁

將結果傳送至本機儲存空間

在開頭加上 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

意見回饋

按一下這裡提供意見

問卷調查

您會如何使用本教學課程？

僅閱讀

閱讀並完成練習

您覺得這個程式碼研究室是否實用？

非常實用

還算實用