DeepStream Single-View 3D Tracking

在视频分析应用中，传统多目标跟踪通常工作在 2D 图像平面上：检测器输出 bounding box，tracker 负责在连续帧之间维持稳定的 object ID。这种方式在简单场景中效果很好，但在零售、仓库、交通等真实环境中，经常会遇到遮挡、人体只露出上半身、检测框突然变小或偏移的问题。检测框一旦不稳定，tracker 就容易发生 ID switch 或 track 丢失。

DeepStream 的 Single-View 3D Tracking，简称 SV3DT，正是为了解决这类问题。它不只在 2D 图像坐标中跟踪目标，而是利用单个静态摄像头的相机投影矩阵和目标 3D 模型，把目标状态估计到物理世界坐标系中，从而更稳定地理解目标的位置和运动。

Sample 做了什么

deepstream-tracker-3d 这个 sample 展示了如何在 DeepStream 中运行单视角 3D 跟踪。它使用一个固定摄像头视频 Retail02_short.mp4，通过 PeopleNet 做行人检测，再通过 nvtracker 加载 NvMultiObjectTracker 低层 tracker 库，实现 3D tracking。

整体 pipeline 可以理解为：

Video Source

→ Streammux

→ PeopleNet Detection

→ Gst-nvtracker + NvDCF 3D Tracking

→ OSD Visualization

→ MP4 Output / Tracking Metadata Output

其中关键点在 tracker 配置，而不是普通检测配置。DeepStream app config 中的 [tracker] 使用：

ll-lib-file 指向 libnvds_nvmultiobjecttracker.so
ll-config-file 指向 config_tracker_NvDCF_accuracy_3D.yml
tracker-width / tracker-height 与输入视频分辨率保持一致

也就是说，DeepStream 的 Gst-nvtracker 负责 GStreamer pipeline 集成，真正的跟踪算法由低层 tracker library 提供。

为什么需要 3D Tracking

普通 2D tracking 主要依赖图像中的 bounding box。例如一个人被货架、柱子或其他人挡住时，检测器可能只能看到头部或上半身，于是 bounding box 会突然变短、变窄或位置偏移。对于 tracker 来说，这个目标看起来像是"形状变了、位置跳了"，就容易导致跟踪失败。

SV3DT 引入了一个重要假设：人或物体在真实世界中有稳定的 3D 几何结构。例如 sample 中把人建模为一个圆柱体，配置里有 height 和 radius。当检测框只覆盖可见部分时，SV3DT 可以结合相机投影矩阵，把 3D 人体模型投影回 2D 图像，估计更完整的目标框、脚点位置和可见度。

这样 tracker 跟踪的不只是 2D bounding box，而是更接近真实物理世界中的目标位置。

Sample 中的关键配置

这个 sample 最关键的配置文件有三个。

第一个是 DeepStream app 配置 deepstream_app_source1_3d_tracking.txt。它定义输入视频、streammux、PeopleNet detector、tracker、OSD 和输出视频。这里的 tracker 配置明确使用 3D tracking 的低层配置文件。

第二个是 tracker 配置 config_tracker_NvDCF_accuracy_3D.yml。这里启用了几个核心模块：

StateEstimator 中使用 stateEstimatorType: 3，表示使用 3D/location-based state estimator。
ObjectModelProjection 指定 camera model file，并启用 visibility 和 foot location 输出。
VisualTracker 使用 NvDCF/VPI backend，用视觉特征增强跟踪鲁棒性。
ReID 用于目标 re-association，帮助目标短暂丢失后重新关联。
PoseEstimator 使用 BodyPose3DNet，帮助估计人体关键点和高度。

第三个是相机配置 camInfo.yml。它提供：

projectionMatrix_3x4：3x4 相机投影矩阵
modelInfo.height：人体模型高度
modelInfo.radius：人体圆柱模型半径

这说明 SV3DT 并不是只靠检测器输出就能工作。它需要场景相机的几何信息。对于新的摄像头或新视频，必须重新准备相机投影矩阵。

Pose Estimator 的作用

README 中说明，当前 sample 默认使用 2D pose estimator。Pose estimator 会估计人体关键点，例如头部、腰部等。SV3DT 可以利用这些关键点作为 anchor，估计每个人的 3D 高度和脚点位置。

如果在 tracker config 中把 poseEstimatorType 设置为 0，pose estimator 会被关闭。此时算法会退化为使用 2D 检测框和固定人体模型来估计 3D 位置，例如根据检测框顶部近似对齐人体头部位置。

简单理解：

开启 pose estimator：3D 高度估计更个体化，结果更准，但计算更多。
关闭 pose estimator：配置更简单，计算更少，但依赖固定人体模型，精度可能下降。

输出结果

这个 sample 不只是显示 2D tracking box，还会输出 3D tracking 相关结果。

直接可视化方面，DeepStream OSD 会显示重建后的 3D bounding box，即使人在视频中存在部分遮挡，也可以看到较完整的目标框。结果视频会保存为 out.mp4。

元数据方面，sample 会输出 tracking dump，例如：

frame number
object unique id
bbox 位置
confidence
class id
tracker state
visibility
foot image position
foot world position
projected convex hull 信息

其中 foot world position 很重要，它表示目标在 3D 世界地平面上的位置，而不是图像上的像素位置。这对行为分析、轨迹分析、区域统计和跨时间稳定跟踪都更有价值。

如下图，是程序运行的结果。

如何迁移到自己的视频

如果要把这个 sample 用到自己的摄像头或视频，主要需要改三类内容。

第一，替换视频源，并确保 streammux 和 tracker-width / tracker-height 与视频分辨率匹配。

第二，生成新摄像头的 3x4 投影矩阵，并更新 camInfo.yml。这是 SV3DT 的核心输入。如果相机矩阵不准确，3D 位置、脚点和投影模型都会受影响。

第三，根据目标类别调整 detector 和 3D model。如果不是行人，而是 forklift、robot 或其他物体，需要有合适的检测模型，也需要为目标定义合理的 3D 几何尺寸。

适合的应用场景

Single-View 3D Tracking 特别适合固定摄像头场景，例如：

零售门店中的行人轨迹分析
仓库中的人员或设备跟踪
工厂区域的人车混行监控
室内空间中的人流统计
容易发生遮挡的监控场景

它的优势不是替代检测器，而是在检测器输出不稳定时，用相机几何和 3D 模型增强 tracking 的连续性。

总结

DeepStream 的 Single-View 3D Tracking 可以理解为把传统 2D MOT 提升到"相机几何感知"的 tracking。它仍然使用常规 DeepStream pipeline：source、streammux、PGIE、nvtracker、OSD，但 tracker 配置中额外引入了相机投影矩阵、3D 目标模型、3D state estimator、pose estimator 和 3D metadata 输出。

这个 sample 的价值在于，它展示了一个完整路径：从 PeopleNet 检测，到 NvDCF-based 3D tracking，再到 3D bbox、foot location、visibility 和轨迹结果输出。对于遮挡较多、需要真实世界位置分析的场景，SV3DT 比普通 2D tracking 更稳定，也更适合做后续空间行为分析。