Nvidia DeepStream5.0Gst-nvtracker插件功能说明

Posted 2022-12-01 行路南

Gst-nvtracker

Gst-nvtracker插件允许DeepStream 管道使用一个底层跟踪器来跟踪具有唯一ID的检测目标。它支持任何实现NvDsTracker API的底层库，包括三个参考实现：NvDCF、 KLT 和 IOU 跟踪器。作为这个 API 的一部分，插件查询底层库中关于输入格式和内存类型的功能和要求。然后，基于这些查询结果，插件将输入帧缓冲区转换为底层库请求的格式。例如，KLT 跟踪器使用 Luma 专用格式; NvDCF 使用 NV12或 RGBA格式; IOU 不需要缓冲区。

底层功能还包括支持跨多个输入流的批处理。批处理通常比独立处理每个流更有效。如果底层库支持批处理，那么这将是首选的操作模式。但是，如果低级库同时支持批处理和单流模式，则可以使用 enable-batch-process 配置选项来设置此首选项。低层功能还包括支持传递历史的帧数据，其中包括在过去帧中生成但尚未报告为输出的对象跟踪数据。这种情况可能发生在这样的情况: 低层跟踪器内部存储历史帧中生成的对象跟踪数据，因为置信度不足没有报告，但后来由于置信度的提升决定报告，这些历史帧数据可以作为用户元数据报告。这可以通过 enable-past-frame 配置选项启用。

该插件接受来自上游组件的 NV12-或 rgba 格式的帧数据，并将输入缓冲区转换为低层库所需格式的缓冲区，同时将宽度和高度转换为跟踪器要求的宽度和高度。(跟踪器的宽度和高度必须在配置文件的**[track]**中指定)。通过跟踪器配置节中的 ll-lib-file 配置选项选择使用哪一个跟踪器库。选定的跟踪器库还需要自己的配置文件，可以通过 ll-config-file 选项指定这个配置文件。三个的跟踪器库支持不同的跟踪算法:

• KLT 跟踪器使用基于 cpu 的 Kanade-Lucas-Tomasi (KLT)跟踪器算法的实现。此库不需要配置文件。
• IOU 跟踪器在两个连续帧之间的检测器边界框中使用 IOU 值来执行它们之间的关联或分配一个新的 ID。这个库接受一个可选的配置文件。
• NvDCF跟踪器采用基于相关滤波器的在线鉴别学习算法作为视觉目标跟踪器，同时采用数据关联算法进行多目标跟踪。此库接受一个可选的配置文件。

输入和输出

本节总结了 Gst-nvtracker 插件的输入、输出和通信设施。

• 输入

  • Gst Buffer (batched)
  • NvDsBatchMeta

  输入视频帧支持的颜色格式为 NV12和 RGBA。

• 控制参数

  • tracker-width
  • tracker-height
  • gpu-id (for dGPU only)
  • ll-lib-file
  • ll-config-file
  • enable-batch-process
  • enable-past-frame
  • tracking-surface-type
  • display-tracking-id

• 输出

  • Gst Buffer (provided as an input)
  • NvDsBatchMeta (with addition of tracked object coordinates, tracker confidence and object IDs in NvDsObjectMeta)

注意：

如果跟踪器算法不生成置信值，那么跟踪器的置信值将被设置为-0.1。对于 KLT 和 IOU 跟踪器 ， 置信度设置为 -0.1，因为这些算法不生成跟踪对象的置信度值。Nvdcf 跟踪器对被跟踪的目标产生置信度，其值在 NvDsObjectMeta 数据结构的tracker_confidence中设置

下表总结了该插件的特性

Feature	Description	Release
Configurable tracker width/height	帧在内部缩放到指定的分辨率以进行跟踪	DS 2.0
Multi-stream CPU/GPU tracker	支持跟踪来自不同源的帧组成的批处理缓冲区	DS 2.0
NV12 Input	—	DS 2.0
RGBA Input	—	DS 3.0
Allows low FPS tracking	IOU tracker	DS 3.0
Configurable GPU device	用户可以选择 GPU 进行内部缩放/颜色格式转换和跟踪	DS 2.0
Dynamic addition/deletion of sources at runtime	支持跟踪器在运行时添加的新源，并在删除源时清除资源	DS 3.0
Support for user’s choice of low-level library	动态加载用户选择的低层库	DS 4.0
Support for batch processing	如果底层库有能力处理这个问题的话，支持将帧从多个输入流批量发送到底层库	DS 4.0
Support for multiple buffer formats as input to low-level library	将输入缓冲区转换为底层库请求的格式，每帧最多可转换4种格式	DS 4.0
Support for reporting past-frame data	如果底层库支持过去帧数据报告功能，则支持报告过去帧数据	DS 5.0
Support for enabling tracking-id display	支持启用或禁用跟踪id的显示	DS 5.0

Gst Properties 插件属性

下表描述了 Gst-nvtracker 插件的 Gst 属性。

Property	Meaning	Type and Range	Example Notes
tracker-width	跟踪器要操作的帧宽度(以像素为单位)。	Integer, 0 to 4,294,967,295	tracker-width=640
tracker-height	跟踪器要操作的帧高度(以像素为单位)。	Integer, 0 to 4,294,967,295	tracker-height=384
ll-lib-file	将由 Gst-nvtracker 加载的跟踪程序库的路径名。	String	ll-lib-file=­/opt/nvidia/­deepstream/­deepstream/­lib/libnvds_nvdcf.so
ll-config-file	库的配置文件	Path to configuration file	ll-config-file=­­tracker_config.yml
gpu-id	要在其上分配设备/统一内存的GPU的ID，以及要进行缓冲区复制/缩放的GPU的ID。（仅限dGPU）	Integer, 0 to 4,294,967,295	gpu-id=0
enable-batch-process	启用/禁用批处理模式。只有在底层库同时支持批处理和单流处理时才有效。(可选)	Boolean	enable-batch-process=1
enable-past-frame	启用/禁用报告过去帧数据模式。只有在底层库支持时才有效。	Boolean	enable-past-frame=1
tracking-surface-type	设置跟踪的流类型(默认值为0)	Integer, ≥0	tracking-surface-type=0
display-tracking-id	在 OSD 上启用跟踪 ID 显示。	Boolean	display-tracking-id=1
iou-threshold	考虑用于关联的两个边界框的交并比阈值(仅用于 IOU 跟踪器)	float, [0…1]	iou-threshold=0.6
compute-hw	用于缩放的计算引擎： 0 - 默认值；1 - GPU；2 - VIC (Jetson only)	Integer, 0-2	compute-hw=1

自定义底层库

要编写定制的底层跟踪器库，用户可以实现 sources/includes/nvdstracker.h 中定义的 API。API 的部分内容参考了 sources/includes/nvbufsurface.h。API 函数和数据结构的名称前缀是 NvMOT，它代表 NVIDIA 多对象跟踪器。从底层库的角度来看，这是 API 的一般流程:

1. 第一个必需的功能是：

NvMOTStatus NvMOT_Query (
   uint16_t customConfigFilePathSize,
   char* pCustomConfigFilePath,
   NvMOTQuery *pQuery
);

插件在它开始与库的任何处理会话（上下文）之前,使用这个函数来查询底层库的功能和需求。查询的属性包括输入帧的颜色格式(例如，RGBA 或 NV12)、内存类型(例如，NVIDIA CUDA 设备或 cpu 映射的 NVMM) ，以及对批处理的支持。

该插件在初始化阶段执行此查询一次，其结果应用于使用底层库建立的所有上下文。如果指定了底层库配置文件，则在查询中提供该文件供库查询。查询返回的数据结构NvMOTQuery包含以下字段:

• NvMOTCompute computeConfig: 报告库支持的计算目标。当前插件只在启动上下文时回显报告的值。

• uint8_t numTransforms: 底层库所需的颜色格式的数量。这个字段的有效范围是0到NVMOT_MAX_TRANSFORMS。如果库不需要任何可视化数据，则将此值设置为0。注意，0并不意味着未转换的数据将被传递给库。

• NvBufSurfaceColorFormat colorFormats[NVMOT_MAX_TRANSFORMS]: 所需的颜色格式列表。只有第一个 numTransforms 项有效。

• NvBufSurfaceMemType memType: 转换缓冲区的内存类型。该插件分配这种类型的缓冲区来存储颜色和比例转换的帧，并且缓冲区被传递到每个帧的底层库。请注意，目前的支持仅限于以下类型:

  dGPU:

  NVBUF_MEM_CUDA_PINNED
  NVBUF_MEM_CUDA_UNIFIED
  

  Jetson:

  NVBUF_MEM_SURFACE_ARRAY
  

• bool supportBatchProcessing: 如果库支持跨多个流的批处理，则为 True; 否则为 false。

• bool supportPastFrame: 如果库支持输出过去帧，则为 True; 否则为 false。

2. 在查询之后，在任何帧到达之前，插件必须通过调用以下命令初始化底层库的上下文:

NvMOTStatus NvMOT_Init(
     NvMOTConfig *pConfigIn,
     NvMOTContextHandle *pContextHandle,
     NvMOTConfigResponse *pConfigResponse
);

上下文句柄在底层库之外是不透明的。在批处理模式下，插件为所有输入流请求一个上下文；在单个流处理模式下，插件对每个输入流进行调用，以便每个流都有自己的上下文。此调用包括上下文的配置请求。低层库可以实现：

• 检查配置，只有在请求被接受时才创建上下文。如果配置请求的任何部分被拒绝，则不会创建任何上下文，并且返回状态必须设置为 nvmottus_error。pConfigResponse 字段可以选择性地包含特定配置项的状态。
• 根据配置预分配资源。

3. 一旦上下文被初始化，插件每次从上游接收数据时，都会将帧数据和检测到的对象边界框一起发送到底层库。

它总是将数据显示为一批帧，尽管在每个流处理上下文中，该批处理只能包含一个帧。注意，根据跟踪器插件的帧到达时间，帧批处理的组合可以是完整的批处理(包含来自所有流的帧)或部分批处理(只包含来自流的子集的帧)。在这两种情况下，每个批处理都保证最多包含来自每个流的一个帧。

此处理的函数调用是：

NvMOTStatus NvMOT_Process(NvMOTContextHandle contextHandle,
     NvMOTProcessParams *pParams,
     NvMOTTrackedObjBatch *pTrackedObjectsBatch
);

• pParams 是指向要处理的帧的输入批处理的指针。该结构包含一个或多个帧的列表，每个流中最多有一个帧。因此，没有两个帧条目具有相同的 streamID。每个帧数据条目都包含一个或多个缓冲区列表，这些缓冲区是低级库所需的颜色格式，以及该帧的对象属性数据列表。大多数库最多只需要一种颜色格式。
• pTrackedObjectsBatch 是指向对象属性数据输出批的指针。它预先填充了 numFilled 的值，该值是输入参数中包含的帧数。
• 如果一个帧没有输出对象属性数据，它仍然以 numFilled 计数，并用一个空列表条目(NvMOTTrackedObjList)表示。空列表项具有正确的 streamide 设置，numFilled 设置为0。

4. 获取历史帧的跟踪信息

根据低层跟踪器的能力，可能会有一些在过去帧中生成的被跟踪的对象数据，但是这些数据在内部存储而不会被报告，比如说，由于对过去帧的信任度较低。如果它对后面的帧更有信心并准备报告它们，那么可以使用以下函数调用从跟踪器插件检索过去的帧数据。在 NvDsBatchMeta 中，过去的帧数据被输出为batch_user_meta_list 列表:

NvMOTStatus NvMOT_ProcessPast(NvMOTContextHandle contextHandle,
     NvMOTProcessParams *pParams,
     NvDsPastFrameObjBatch *pPastFrameObjBatch
);

• pParams 是指向要处理的输入批处理的指针。该结构用于检查批处理中的流 ID 列表。

• pPastFrameObjBatch 是指向过去帧中生成的对象属性数据的输出批处理的指针。数据结构 NvDsPastFrameObjBatch 在 include/nvds_tracker_meta.h 中定义。它可以包括输入中每个流的一组跟踪数据。对于每个对象，可能存在多个过去帧数据，以防跟踪数据被存储为对象的多个帧。

5. 动态删除源

如果一个视频流源被动态删除，插件调用下面的函数，这样底层的跟踪器库也可以删除它。请注意，这个 API 是可选的，只有在启用批处理模式时才有效，这意味着它只有在底层跟踪库具有实际实现时才会执行。如果调用，底层跟踪程序库可以释放它可能分配的任何每个流资源:

void NvMOT_RemoveStreams(NvMOTContextHandle contextHandle, NvMOTStreamId streamIdMask);

6. 当所有的处理完成后，插件调用这个函数来清理上下文:

void NvMOT_DeInit(NvMOTContextHandle contextHandle);

跟踪器库比较和权衡

deepstreamsdk提供了三个参考底层跟踪器库，它们在准确性、健壮性和效率方面具有不同的资源需求和性能特征，允许用户根据自己的用例和需求选择最佳跟踪器。对比见下表。

Tracker	GPU Computational Load	CPU Computational Load	Pros	Cons	Best Use Cases
IOU	X	非常低	轻量级	没有视觉特征进行匹配，所以容易出现频繁的跟踪 ID 开关和故障。不适合快速移动的场景。	对象位置稀疏，大小不同。检测器被期望运行每帧或非常频繁(例如。每隔一帧)。
KLT	X	高	对于简单的场景效果相当好	高 CPU 利用率。由于噪音和干扰，如阴影，非刚性变形，平面外旋转和部分遮挡，易改变视觉外观的。无法处理低纹理的对象。	对象具有强大的纹理和简单的背景。理想的高 CPU 资源可用性。
NvDCF	Medium	低	对部分遮挡、阴影和其他短暂的视觉变化有很强的抵抗力。	由于计算复杂度的增加，比 KLT 和 IOU 慢。减少了处理的流的总数。	具有部分遮挡的多目标复杂场景。

参考文章

https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_gst-nvtracker.html?highlight=tracker