odin_ros_driver1/README_track.md

yolo + stable track 说明

这套逻辑的目标不是直接相信 ByteTrack 的 raw id，而是维护一个更稳定的 stable id。

1. 基本概念

• raw id ByteTrack 当前帧给出的轨迹号，只表示短时 2D 跟踪结果，可能抖动、复用、换人。
• stable id 本节点自己维护的长期身份号，用于：
  • /target_observation
  • /track_observations
  • RViz marker
  • ReID gallery
• primary target 当前跟随目标。它只是某一个 stable id，不是单独一套编号。

2. 当前关联逻辑

每一帧大致按下面顺序运行：

1. YOLO pose
2. ByteTrack
3. raw-id fast path
   • 如果某个 row 的 raw id 能续上上一帧同一个 stable id，先临时绑定
   • 注意：这一步现在只是“初始猜测”，不是最终判决
4. ReID
   • 对还没绑定的 row，和所有已有 stable id 的 gallery 做相似度比较
   • 若满足 match_threshold 且领先第二名至少 gap_threshold，直接回绑旧 stable id
5. single-person 3D fallback
   • 只在单人场景下启用
   • 只服务当前 primary target
   • 用于 ReID crop 不可用时的兜底恢复
6. new stable id allocate
   • 如果和所有旧 stable id 都无法匹配
   • 且同一个 ByteTrack raw id 连续出现满 target_reid_confirm_hits_before_allocate
   • 才会申请一个新的 stable id

3. stable id 的原则

• stable id 是长期身份，不是当前画面里的顺位号
• 某个目标暂时丢失时，它原来的 stable id 会继续保留，直到 timeout age out
• 不能因为画面里少了一个人，就把别人的 stable id 顶上去

这也是为什么：

• raw id 可以变
• 但 stable id 应该尽量不变

4. gallery 更新原则

gallery 现在不会随意更新。

4.1 什么时候能进 gallery

只有在下列情况之一时，当前 feature 才允许写进对应 stable id：

• 该 row 通过 ReID 成功回绑到旧 stable id
• 该 row 已经拿到正式 stable id，并且到了定期 refresh 时机
• 该 row 是经过连续确认后刚申请到的新 stable id

4.2 什么时候不允许更新

如果一个 row 是通过 raw-id fast path 临时续上的，但 ReID 明显反对这个绑定，则：

• 该帧不会更新这个 stable id 的 gallery
• 必要时会直接撤销 fast-path 绑定，让后续 ReID 重新决定该 row 属于哪个旧 stable id

这样做是为了避免：

• ByteTrack 一次短时漂移
• 把错人的 feature 写进旧 stable id
• 进而污染整个 gallery

4.3 fallback dist 会不会更新 gallery

不会。

fallback dist 只负责在单人场景下帮 primary target 暂时保住 stable id，不负责更新外观库。

5. 默认关键参数

这些参数都在：

• control_command.yaml

当前常用参数：

• target_reid_gallery_size: 8 每个 stable id 最多缓存 8 个 ReID feature
• target_reid_feature_update_interval: 5 最多每 5 帧尝试刷新一次 gallery
• target_reid_match_threshold: 0.65
• target_reid_gap_threshold: 0.10
• target_reid_lost_timeout_frames: 150
• target_reid_confirm_hits_before_allocate: 5 新人申请新 stable id 前，要求同一个 ByteTrack raw id 连续确认 5 帧
• target_reid_3d_fallback_enabled: 1 单人场景启用 3D fallback

6. debug topic

假设 sync_topic_prefix=/odin/sync，则当前会有这些调试输出：

• /odin/sync/detection_img_debug/compressed 调试图。未分配 stable id 的 detection 画白色；已分配 stable id 的 detection 画对应彩色。
• /odin/sync/gallery_debug 原始 sensor_msgs/Image，不是 compressed。 用于看 ReID gallery 当前缓存了哪些人像 crop。 当前布局是：
  • 最多 8 行，对应 8 个 stable id
  • 10 列，对应 gallery 槽位

此外还有：

• /odin/sync/target_observation 当前 primary target
• /odin/sync/track_observations 当前帧所有 fresh 3D 的 stable tracks
• /odin/sync/detection_pos_cam
• /odin/sync/detection_pos_world

7. debug_reid

开启：

• debug_reid: 1

后，会打印每一帧的 ReID 相似度矩阵，格式类似：

[ReIDMatrix] prev_sid=1 bytetrack_id=[2,1] stable_id=[1,0] sims=[1->[sid0:0.905,sid1:0.508],2->[sid1:0.938,sid0:0.489]]

解释：

• prev_sid 上一时刻的 primary stable id
• bytetrack_id=[...] 当前帧 ByteTrack row 的 raw ids
• stable_id=[...] 当前系统最终给每个 row 绑定到的 stable ids
• sims=[...] 每个 ByteTrack row 和所有已有 stable id gallery 的相似度

这个日志主要用来排查：

• 为什么某个 row 没能回绑到旧 stable id
• 是 ByteTrack 漂了，还是 gallery 被污染了
• 当前绑定结果和 ReID 结果是否一致

8. 当前已知设计取向

这版实现明确偏向下面的目标：

• stable id 尽量稳定
• 允许 ByteTrack 暂时失败
• 不允许一次错误 fast-path 直接污染 gallery
• 在多人场景下，优先相信 ReID，不用 3D fallback 去硬改多人 stable id

如果后面还要继续调，最值得重点观察的是：

• debug_reid 的矩阵输出
• /odin/sync/gallery_debug
• 某个 stable id 的 gallery 是否被混入了别人的 crop