DeepSORT 多目标跟踪：给每一辆车发一个不变的身份编号

01目标：每辆车一个固定编号，交叉时也不会换人

02问题：检测给了框，可它不知道「这还是刚才那辆」

路口装一台相机，想统计「今天过了多少辆车、每辆往哪走」。你可能想：检测不是已经能框出车了吗，数一数框不就完了？

数不了。检测是「一帧一帧独立看」的：这一帧 3 个框，下一帧还是 3 个框，它说不出哪个框接着哪个框。车往前开 20 像素，对检测来说就是「一辆全新的车」。用框数当日流量，同辆车会被数几十次。

把问号拆成三个具体问题：

① 车在动，框也在动，凭什么把这两个框认成同一辆？

② 两辆车交叉、擦身而过，怎么保证 ID 不互换？

③ 画面里的 ID 会涨到 30 多，这编号是随机的吗？

03现象：同一辆车十几秒后还是 ID 12

🎬 现象速览 · 30 秒先看效果

你会看到：高速路上每辆车套一个黄框，左上角写 ID 12 car。终端刷 [track] 30帧平均帧率: 16.4 tracks=13。下面三张是在板上真实跑出来的画面（同一段 test.mp4，不同时刻）。

怎么跑出来（两条命令）：第一条进目录确认模型与视频，第二条跑视频模式，浏览器打开推流地址看实时结果。

cd ~/ros2_ws/src/xflz_eai_car1/vision/07_multi_object_tracking
ls models/ test.mp4

models/: yolov8n.rknn deepsort.rknn yolov8n.onnx deepsort.onnx test.mp4

python src/app.py --video test.mp4

[track] mode=deepsort [track] 30帧平均帧率: 16.4 tracks=13 ← 浏览器打开 http://<板IP>:8080/track.mjpg 看画面

启动时也会刷几行 W RKNN: … not match 与 dynamic range 提示，属静态 shape 模型的正常输出，不影响结果。

🔍 看什么：三件事，看完再看下一节。

• 同一辆车的编号不变 —— 红车从画面这头开到那头，标签一直是同一个数字，不会因为框移动就换号。
• 框会「跟丢后补上」 —— 车被前车挡一下，框闪一下再回来，回来还是原编号。这是卡尔曼预测在撑着。
• 编号只增不减 —— 第 ③ 张编号已经到 30 了，可画面只有 5 辆车。编号是「历史上第几个被确认的目标」，不是「现在第几个」。

这就是本实验最终要呈现的现象。先照做、看懂它；第 05 节会带你亲手复现这三张图，并补上单图与实时两路。

04原理：四步连线题：先猜位置、再看长相、整体配对、发号淘汰

四个步骤回答第 02 节的三问：① 凭什么认同一辆 → 步骤 2 与 3；② 交叉不换人 → 步骤 3；③ 编号为什么涨 → 步骤 4。

1这一帧到底有哪些框？

吃什么：一帧图。做什么：跑 yolov8n（9 输出，检测模型，没有掩码分支）。吐什么：若干个框 + 类别 + 分数，再用 min_confidence: 0.6 筛一遍。

这一步与 EXP-06 的步骤 1~3 同款，唯一区别：配置是 classes: [2]（COCO 里的 car），所以画面上只出现车，人和巴士都被挡在外面。这也解释了一个常见疑惑：拿一张只有巴士的图去跑，会得到 tracks=0。

动它会怎样：min_confidence 调低（0.3）→ 弱检测也进跟踪，框变小、编号到处乱飘；调高 → 远处的车干脆不参与。

2它跑到哪去了？—— 没检测到也能猜

每条轨迹自带一个卡尔曼滤波器，状态是 8 个数：框中心 cx, cy、宽高比 a、高度 h，再加上它们各自的变化速度。所以轨迹「记得住」这辆车正在往哪开、开多快。

每帧先做一次 predict()：不看这一帧有没有检测，先把框按速度往前推一格。这就是第 02 节第一问的一半答案 —— 车被挡住的那一两帧，画面上的框不是「停在上个位置」，而是「按速度推出来的位置」。

为什么用高度 h 做尺度：远处的车小、近处的大，用高度当基准，噪声参数能随框大小自动缩放，近处宽容、远处严格。

动它会怎样：这一步没有可调参数。但预测只对未来几帧有效 —— 推太久（比如丢失 30 帧还按老速度飞）会飞出去，所以必须有步骤 4 的淘汰。

3两个框，凭什么说是同一辆车？

这是第 02 节第一、二问的核心。做法分三层，顺序是关键：

• 先看长相：把每个框裁出来，缩到 64×128、按 ImageNet 归一化，过 ReID 模型得到 512 维向量。两枚向量夹角越小越像，用余弦距离衡量。同时用马氏距离卡一道门：位置离预测太远的配对直接作废（阈值取 CHI2INV95[2]，统计上的 95% 置信界）。
• 再按「丢了多久」分级：刚丢 1 帧的先配、丢 2 帧的再配……一直到丢 70 帧，这叫级联匹配。为什么顺序重要？刚丢的轨迹位置预测最准，让它们优先挑，才不会被「丢了很久、已经飘了」的旧轨迹抢走检测。
• 最后兜底：还没配上的、以及还没被确认的新轨迹，用纯 IoU 配一次（max_iou_distance: 0.8）。

为什么不是「重叠最多的就是同一辆」：两车并行或交叉时，IoU 最高的那一对经常是错的 —— 能区分它们的是长相。所以外观优先、IoU 兜底。

动它会怎样：max_dist（默认 0.2）是长相门限，调小 → 遮挡后回来被当成新车；调大 → 两辆同款同色的车可能被认成一辆。max_iou_distance 调小 → 移动中的车容易丢轨迹（配置注释写明 0.7 会丢，所以取 0.8）。

4编号为什么能涨到 30 多？

这是第 02 节第三问的答案，也是画面上最容易让人误解的一个数。

• 连上了：轨迹继承旧编号，只更新位置与外观特征库（nn_budget: 100 条，超了丢最旧的）。
• 没连上：这个检测新建一条轨迹，编号 = _next_id，然后计数器 +1。计数器从 1 开始、永不回退。
• 新轨迹要先「试用」：连续命中 n_init: 3 帧才被确认、才会画出来。闪过一帧的误检不占编号。
• 淘汰：连续 max_age: 70 帧没配上就删除轨迹。注意删除不回收编号。

动它会怎样：max_age 调小（10）→ 遮挡几帧就换号，编号涨得飞快；调大（200）→ 抗遮挡更强，但开走的车轨迹会在画面外飘很久，容易被别的检测接上变成错号。n_init 调大 → 编号更干净，但新目标要慢几帧才显示。

先认识 5 个词

这张表只看第 2、5 两列就够用：第 2 列是数据形态，第 5 列是你能拧的旋钮。函数名在第四列，追代码时再看。

05实操：单图 / 视频 / 实时三条命令

先看「敲的命令」和「原理第几步」怎么对上号 —— 每一行都是第 04 节某一格的落地。

1. 先用单图确认「只追车」约 3 分钟

   单图模式只跑一帧、只起 1 个 worker。因为 classes: [2] 只保留 car，拿一张只有巴士和行人的图去跑，会得到 tracks=0 —— 不是坏了，是过滤生效了。

   cd ~/ros2_ws/src/xflz_eai_car1/vision/07_multi_object_tracking
   python src/app.py --image ../06_semantic_segmentation/images/bus.jpg --save out.jpg

   [track] mode=deepsort [track] tracks=0 saved -> out.jpg

   把 classes 改成 [5]（bus）再跑一次，tracks 就变成 1。这一步确认：过滤发生在检测之后、跟踪之前。

2. 视频模式：看编号稳住约 5 分钟

   视频模式起 3 个 worker 的检测池，并把结果推到 MJPEG。

   python src/app.py --video test.mp4

   [track] mode=deepsort [track] 30帧平均帧率: 14.7 tracks=15 [track] 30帧平均帧率: 16.4 tracks=13 ← 浏览器打开 http://<板IP>:8080/track.mjpg

   盯近处那辆车的标签：它从画面底部开到顶部，编号一直不变。tracks 会上下浮动，那是同时存在的车辆数在变。

3. 实时相机：deepsort 与 sort 对照约 8 分钟

   板上标准走法是 ROS 话题。先起驱动再跑程序，两个终端 ROS_DOMAIN_ID 必须一致（N 取 0~101 任一整数，每台设备各选各的）。

   终端一 · 起相机驱动

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   ros2 launch ascamera hp60c.launch.py

   日志持续滚动，无 ERROR

   终端二 · 跑跟踪

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   cd ~/ros2_ws/src/xflz_eai_car1/vision/07_multi_object_tracking
   python src/app.py --ros

   [track] mode=deepsort [track] 30帧平均帧率: xx.x tracks=N ← http://<板IP>:8080/track.mjpg

   对照实验：把 tracker.mode 改 sort 重跑（不动模型），再让人从别人身后穿过 —— sort 会在交叉处换号，deepsort 不会。这就是「长相」那一层的价值。

你该看到的画面

踩坑速查

请阅读这个多目标跟踪项目的七个模块：src/app.py、src/detect.py、src/preprocess.py、src/tracker.py、src/track.py、src/reid.py、src/rknnpool.py。
它们共同完成「读一帧 → 检测 → 匹配 → 画编号」。
请输出一张表，每行一个模块，四列：模块名 / 一句话职责 / 被谁调用 / 从哪个配置项取值。
要求指出关键函数的所在行号；说不清谁调谁的地方请标出来，不要猜。

请按「主线程处理一帧」的视角，为 src/app.py 的主循环画一张流程图。
必须包含：检测池 put/get 的进出；tracker.predict 与 tracker.update 的先后；没有检测结果时如何处理；ReID 缺失时如何退回 sort 模式。
每个框写函数名，判断框写条件，不要用「处理」「分析」这类空词。

请为视频模式画一张时序图，参与者用真实名字：主线程、RKNNPool 的 worker 线程、ReIDPool 的 worker 线程、MjpegServer。
按顺序标出：读帧、检测入队、worker 推理、结果出队、裁剪目标送 ReID、Tracker.update、绘制、推流。
并标注哪些环节是并行流水线，哪些是同步等待。

06互动：拖 max_age 和 max_dist，看遮挡后还是不是原 ID

📌 这一节是「掌握检查」：亲手改一个参数，看现象是否朝你预期的方向变，还要能说出为什么 —— 说得出，才算掌握。

第 04 节讲了四步，真正的判据只有两条线：「愿意等多久」= max_age，「像不像」= max_dist。命令跑一次只能看一种组合，这里做成能拖的时间轴。

怎么读出规律：先把 max_dist 拉到最大、只动 max_age —— 看到「等多久」这条线；再把 max_age 拉到最大、只动 max_dist —— 看到「像不像」这条线。任何一条断了，编号都会断。

07验证：三道小测

08章节总结：检测管「在哪」，跟踪管「还是谁」

这页讲了什么，它们怎么串起来

前置依赖 · 缺一样就跑不起来

这套代码用在哪儿

• 路口卡口计数：虚拟线 + 轨迹跨越判定，按 ID 去重统计车流量与方向，替代地感线圈。
• 门店 / 电梯客流：同一个人被反复计数的问题，靠跟踪 ID 天然解决；配 classes: [0] 只追 person。
• 机器人跟人：锁住「要跟的那个人」的 ID，输出它的框中心作为跟随目标 —— 这是 EXP-11 的上游能力。
• 不该用它的场合：只需要「这一帧有没有人」时不必上跟踪，多花的算力没有收益；相机在动、镜头切换的场景也不适用。

下一个实验换一个方向：跟踪告诉我们「它一直在」，但说不出它离我多远。EXP-10 会用深度图把这个距离补上。