first commit

utils/target_tracker/README.md

@@ -0,0 +1,29 @@
+# target_tracker（Python 版）
+
+多目标追踪过滤器：8 维恒速卡尔曼滤波 + 贪婪关联 + 主目标锁定选举。
+移植自 `reference-c++/target_tracker/`（规格：docs/视觉追踪技术路线.md）。
+
+## 接口清单
+
+| 名称 | 说明 |
+| --- | --- |
+| `Detection(x1, y1, x2, y2, conf, cls_id=0)` | 单帧检测框输入 |
+| `FrameShape(height, width)` | 画面尺寸（仅 Coast 兜底选举取画面中心用） |
+| `TrackResult` | 每帧输出九字段：tracked / primary_id / center / box / confidence / is_predicted / lost_frames / n_active / raw |
+| `TrackerConfig(max_lost_frames=8, max_association_dist=200.0, min_hits=3, dist_weight=0.5, iou_weight=0.5)` | 追踪器配置 |
+| `TargetTracker(config=None)` | 追踪器主类 |
+| `.update(detections, frame_shape=None) -> TrackResult` | 单帧主流程（§7 六步） |
+| `.last_result() -> TrackResult` | 跨线程读取最近一帧结果（加锁拷贝） |
+| `.reset()` / `.active_count()` / `.active_tracks()` / `.get_config()` | 生命周期与查询 |
+| `KalmanBoxFilter` / `BoxCXCYWH` | 单目标滤波器（可独立使用：initiate / predict / update） |
+| `Tracklet` / `BoxXYXY` / `to_center_size` / `to_xyxy` / `compute_iou` | 轨道与几何工具 |
+
+## 与 C++ 版的差异
+
+- **依赖**：矩阵运算用 numpy（C++ 手写定长运算避免 Eigen）；关联/选举路径用纯标量，与 C++ 逐位同序。
+- **Optional 语义**：C++ `std::optional<T>` → Python `None`；`State()` → `state` 属性（返回拷贝）。
+- **线程模型**：与 C++ 一致——仅 `last_result()` 加 `threading.Lock`，`update()` 单线程调用。
+- **字段命名**：成员函数蛇形命名（`IsDead` → `is_dead` 属性，`MarkMiss` → `mark_miss`）。
+- 行为语义（死亡判定 `lost_count > max_lost` 严格大于、best_cost=1.0 严格小于、
+  ID 严格递增不复用、Q 用状态原值 / R 用 abs×2 的刻意不对称、S 求逆前 1e-9 正则化）
+  与 C++ 完全一致，由 27 条移植测试锁定。