nvdsanalytics 視頻分析插件是 DeepStream 5.0 添加的功能，對 nvinfer（主檢測器）和 nvtracker 附加的元數據執行分析，目前主要針對涉及感興趣區域（ROI）的過濾、過度擁擠檢測、方向檢測和跨線統計等四大功能，如下表：

功能說明

ROI 過濾此功能檢測 ROI 中是否存在目標類別的對象，結果作為每個對象的元數據附加，以及每幀 ROI 中的對象總數。

擁擠檢測在“ROI 過濾”的前提下，檢測每幀對象總數是否處于過度擁擠的狀態，就是檢測 ROI 中的對象數量是否超過預先配置的閾值。

方向檢測使用對象位置歷史記錄和當前幀信息檢查對象是否遵循預配置的方向。結果作為每個對象的元數據附加。

跨線統計此功能檢查對象是否遵循虛擬線的預配置方向，以及是否已越過虛擬線。當測線交叉時，結果將附加到對象上，同時還會附加幀元，其中累積計數與測線交叉的每幀計數一起附加。

可以看出這是 NVIDIA 經過實際項目的要求所增加的功能插件，主要就是針對視頻內的我們所指定的“某個區塊（興趣區，ROI）”或“某條線（跨越線）”范圍中的標的物件，進行“物件動向”的分析與統計（如下圖）。大部分的使用場景是在道路流量分析的應用，但這也可以應用在營建工地、生產工廠、樓宇、校園、消防設施的危險區（danger zone）監控，實用性非常之高。

有經驗的開發人員就會很清楚，如果缺少 nvdsanalytics 這個插件的時候，則開發者需要自行從 nvtracker 里面抽取相關數據，然后與興趣區或跨越線進行持續比對，確認是否屬于要列入統計數據的物件，至于“動向分析”功能，更需要大量的“前后幀”位置比對去進行判斷，這些開發的工作量是相當艱辛、計算量是非常巨大的，如今在 DeepStream 里面只要輕松調用 nvdsanalytics 插件，就能輕松地完成很復雜的工作。

在 DeepStream 開發套件里的 deepstream-nvdsanalytics-test 是 C/C++版本的范例代碼，先前文章里帶著大家安裝過的 deepstream_python_apps 范例中，也提供 Python 版本的代碼，在范例路徑下面的 deepstream-nvdsanalytics 里面。

Gst-nvdsanalytics 工作原理

DeepStream 一直令人贊賞的一個特色，就是將插件的接口做得十分簡單，因此在開始執行范例代碼之前，我們需要先對這個插件有個初步了解，請參考下面鏈接的原廠說明：https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_gst-nvdsanalytics.html

下圖是 Gst-nvdsanalytics 的基本工作原理圖：

整個執行流程其實就是很簡單的四個步驟：

接受上游（左邊）的 nvinfer 與 nvtracker 元件發送的批處理緩沖區（GstBuffer + NvDsBatchMeta），并從中提取元數據；

將元數據傳遞到低階 nvds_analytics 接口（上圖下方）進行處理；

低階接口根據為每個流的所制定配置（前面所列的四項功能）的規則去執行分析；

然后返回添加了分析元數據的作為輸出，這是每個跟蹤對象以及整個幀的分析結果。

這個插件伴隨著 NvDsAnalyticsFrameMeta 與 NvDsAnalyticsObjInfo 兩組元數據，可以在 DeepStream 開發包的sources/includes/nvds_analytics_meta.h 找到完整的定義，也可以在https://docs.nvidia.com/metropolis/deepstream/sdk-api/Meta/analytics.html 找到使用說明。這里也簡單說明一下，對于后面說明代碼時會有幫助：

NvDsAnalyticsFrameMeta：定義“幀級（frame level）”的數據內容，配合所提供的四項功能，主要結構如下：

ocStatus（數據類型：bool）：在給定的ROI 區域內

objInROIcnt（數據類型：unit32_t）：在ROI 區域內檢測到的物件總數

objLCCurrCnt（數據類型：unit64_t）：保存當前幀中跨線物件的數量objLCCumCnt（數據類型：unit64_t）：保存已配置線條的累計跨線物件數量

unique_id（數據類型：guint）：保存 nvdsanalytics 實例的唯一標識符objCnt（數據類型：unit64_t）：保存每幀里面每個類 ID 的對象總數

NvDsAnalyticsObjInfo：定義“對象（object level）”的數據內容，配合所提供的四項功能，主要結構如下：

roiStatus（數據類型：字符串數組）：保存對象所在的 ROI 標簽數組

ocStatus（數據類型：字符串數組）：保存對象所在的 ROI 標簽數組保存對象所在的過度擁擠標簽數組

lcStatus（數據類型：字符串數組）：保存對象已跨越的線交叉標簽數組

dirStatus（數據類型：字符串）：保存跟蹤對象的方向字符串

unique_id（數據類型：guint）：保存 nvdsanalytics 實例的唯一標識符

前面工作流最右邊的輸出，是以幀級的 NvDsAnalyticsFrameMeta 結構進行封裝，想要調用時就定義一個用戶元，將 meta_type 設置為NVDS_USER_FRAME_META_NVDSANALYTICS。然后將用戶元添加到 NvDsFrameMeta 的 frame_user_meta_list 成員。

分析（每個檢測到的對象）的輸出結果封裝在 NvDsAnalyticsObjInfo 結構中，同樣再定義定義一個用戶元，將類型設置為 NVDS_USER_OBJ_META_NVDSANALYTICS，然后將這個用戶元添加到 NvDsObjectMeta 的 obj_user_meta_list 成員中。

上述步驟與數據結構，已經將大部分 nvdsanalytics 插件的工作都部署的差不多了，剩下就是啟動并監聽交互信息的部分。

項目配置文件說明

這個范例的代碼與前面幾個范例的工作流程是一致的，只是這里接受多個輸入源，包括 H264/H265 視頻文件與 RTSP 視頻流，因此需要建立多個隊列（queue）作為緩沖來處理，至于 nvanalytics_src_pad_buffer_probe 部分與 test1 的 osd_sink_pad_buffer_probe 代碼結構的邏輯也是相近的，因此請自行根據先前代碼內容進行類比，這里就不花力氣再重復那些冗余的內容。

不過這個項目里面的配置文件與前面的項目有比較大的不同之處，因此這里就花點時間探索這部分的細節。范例的配置文件為 config_nvdsanalytics.txt，一共有 5 個配置組。

這個插件一共有以下的 5 個配置組：

［property］：配置插件的一般行為，這是唯一的強制（必須有的）組

［roi-filtering-stream-《n》］：為第《n》個流配置 roi 篩選規則參數，無數量限制

［overcrowding-stream《n》］：為第《n》個流配置過度擁擠參數的閾值

［direction-detection-stream-《n》］：為第《n》個流配置方向檢測參數

［line-crossing-stream-《n》］：為第《n》個流配置跨線參數

在［property］組里面的參數是大家比較熟悉的，其他組里面有幾個用法比較特殊的參數，在這里挑出來說明：

roi-《label》：用在［roi-filtering-stream-《n》］與［overcrowding-stream-《n》］這兩個組，可自行配置《label》名稱，例如“RF”、“OC”、“DangerZone”等，后面設定一組“多（3 以上）邊形”坐標，使用“;”作為間隔，坐標順序為“x1;y1;x2;y2;x3; y3;。..”，例如“roi-DangerZone=295;643;579;634;642;913;56;828”、“roi-OC=295;643;579; 634;642;913;56;828”等，可以為每個視頻源指定多個的興趣區。

direction-《label》：用在［direction-detection-stream-《n》］組，可自行配置《label》內容，例如“South”、“East”、“Forward”等等，后面給定一組（x1;y1;x2;y2）坐標來表示方向，當對象沿這個方向移動時，前面設定的標簽將作為用戶元數據附加到對象里，可以為每個視頻源指定多個方向。

line-crossing-《label》：用在［line-crossing-stream-《n》］組里面，同樣可自行設定《label》內容，例如“Entry”、“Exit”、“Start”等，后面的設定值定義兩組線的四個坐標，依序為（x1d;y1d;x2d;y2d;x1c;y1c;x2c;y2c），其中第一組（x1d;y1d;x2d;y2d）代表移動的方向，如下圖“向下方的黃色箭頭”所表示；第二組（x1c;y1c;x2c;y2c）標示“跨越線”的坐標，如下圖與黃色箭頭所交叉的“橫向線”。

只有當物件“以符合要求的方向通過跨越線”，才算符合這里的統計要求，才會納入這個視頻分析的計數之中，這個功能定義的十分完善。

同樣的，我們可以為每個視頻流提供多組這種跨越線的配置。

extended：用在［line-crossing-stream-《n》］組，這個開關設定值是為了將上一個參數做個擴展，當設置為“0（關閉）”的時候，則計算物件通過的參考依據就僅止于“兩條線的交叉點”，如果設置為“1（開啟）”時，就會以（x1c;y1c;x2c;y2c）整條線作為參考依據。

mode：用在［line-crossing-stream-《n》］與［direction-detection-stream-《n》］這兩個組，設定“檢測方向”與“配置方向”一致性的嚴格程度，有“loose（寬松）”、“strict（嚴格）”、“balance（平衡）”三種選項，例如“loose”只檢查物體是否已越過線，并且該物體保持同一方向行進即可，公差可能會很高。

以上是比較復雜的參數與用法的簡單說明，如果需要所有參數的完整說明，請直接參考https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_gst-nvdsanalytics.html下方的“Configuration File Parameters”內容。

接下來就開始執行這個很有用處的范例，透過修改參數值來感受用途。

范例執行

由于 deepstream_nvdsanalytics.py 這個代碼可以接受多個視頻輸入，因此需要使用“file:///”格式給定輸入文件完整路徑，為了簡化指令長度，我們在工作目錄下使用軟鏈接來提供視頻文件路徑：

ln -s 。./。./。./。./samples/streams/sample_720p.h264 ~/test.h264python3 deepstream_nvdsanalytics.py file:///home/nvidia/test.h264

下面是這個范例的執行畫面：

接下去看看所顯現的數據代表什么意思，下面是我們截取第 649 幀圖像的檢測結果：

##################################################Object 503 moving in direction： NorthObject 499 moving in direction： NorthObject 526 roi status： ［‘RF’］Objs in ROI： {‘RF’： 1}Linecrossing Cumulative： {‘Exit’： 20}Linecrossing Current Frame： {‘Exit’： 0}Frame Number= 649 stream id= 0 Number of Objects= 7 Vehicle_count= 5 Person_count= 2

最上面兩行表示物件編號 503 與 499 行進方向為“North”

第 3 行在 RF 興趣區檢測到編號 526 物件（圖左方站立的人）

第 4 行顯示興趣區 RF 目前檢測到“1”個物件

第 5 行統計出“累積通過”右方黃色線的物件數量為“20”

第 6 行顯示“正在通過”右方黃色線的物件數量為“0”

第 7 行顯示這是“第 649 幀”，檢測到“7”個物件，其中有“5”輛車與“2”個人

如何？這個插件的功能很棒吧，可以讓你自由地設定要監控的區域，并且非常有效率地按照你所設定的要求，反饋對應的統計數據。

責任編輯：haq