From dc4214f8585116f55a02436930647b90ea1bbf5f Mon Sep 17 00:00:00 2001 From: wuweh Date: Fri, 15 May 2026 13:33:57 +0000 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=E7=94=9F=E6=88=90=E9=A1=B9?= =?UTF-8?q?=E7=9B=AECode=20Wiki=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- CODE_WIKI.md | 581 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 581 insertions(+) create mode 100644 CODE_WIKI.md diff --git a/CODE_WIKI.md b/CODE_WIKI.md new file mode 100644 index 0000000..db748da --- /dev/null +++ b/CODE_WIKI.md @@ -0,0 +1,581 @@ +# RadarMOTR Code Wiki + +## 项目概述 + +**RadarMOTR** 是一个基于 Transformer 神经网络的多目标跟踪系统，专门用于处理 Range-Doppler Maps（距离-多普勒图）。该项目基于 [MOTRv2](https://github.com/megvii-research/MOTRv2) 和 [Deformable DETR](https://github.com/fundamentalvision/Deformable-DETR) 构建。 + +### 核心特性 + +- **基于 Transformer 的跟踪**: 使用神经网络替代传统 Kalman Filter 进行目标关联 +- **支持多种跟踪器**: 集成 RadarMOTR、SORT、Kalman Filter 三种跟踪算法 +- **多后端支持**: 支持 ResNet18 和 ResNet50 骨干网络 +- **分布式训练**: 支持多 GPU 数据并行训练 + +### 项目来源 + +- 发表论文: 2024 International Radar Conference (RADAR) +- 预印本: [Accepted Preprint](https://bwsyncandshare.kit.edu/s/zCgc5o89L44oN5a) +- 数据集: [RADTrack](https://github.com/madeit07/RADTrack) + +--- + +## 项目架构 + +``` +RadarMOTR/ +├── configs/ # 配置文件目录 +│ ├── base/ # 基础配置 +│ │ ├── dataset.yaml # 数据集配置 +│ │ ├── model.yaml # 模型配置 +│ │ └── misc.yaml # 杂项配置 +│ ├── trackers/ # 跟踪器配置 +│ │ ├── kf.yaml # Kalman Filter 配置 +│ │ ├── radarmotr.yaml # RadarMOTR 配置 +│ │ └── sort.yaml # SORT 配置 +│ ├── train.yaml # 训练配置 +│ ├── eval.yaml # 评估配置 +│ ├── resnet18.yaml # ResNet18 骨干网络配置 +│ └── resnet50.yaml # ResNet50 骨干网络配置 +├── datasets/ # 数据处理模块 +│ ├── radartrack.py # 雷达数据集加载器 +│ ├── transforms.py # 数据增强变换 +│ ├── radar_transforms.py # 雷达专用数据增强 +│ ├── data_prefetcher.py # 数据预取器 +│ └── samplers.py # 分布式采样器 +├── models/ # 核心模型模块 +│ ├── radarmotr.py # RadarMOTR 主模型 +│ ├── deformable_transformer_plus.py # 可变形Transformer +│ ├── backbones/ # 骨干网络 +│ │ ├── backbone.py # 骨干网络基类 +│ │ └── circular_resnet.py # 循环ResNet +│ ├── structures/ # 数据结构 +│ │ ├── instances.py # Instance 数据结构 +│ │ └── boxes.py # Bounding Box 工具 +│ ├── ops/ # 自定义算子 +│ │ └── ms_deform_attn.py # 多尺度可变形注意力 +│ ├── clip_matcher.py # Clip 匹配器 +│ ├── matcher.py # Hungarian 匹配器 +│ ├── position_encoding.py # 位置编码 +│ ├── optimizer.py # 优化器构建 +│ └── tracker.py # 跟踪器基类 +├── trackers/ # 跟踪器实现 +│ ├── tracker_base.py # 跟踪器基类 +│ ├── radarmotr.py # RadarMOTR 跟踪器 +│ ├── sort.py # SORT 跟踪器 +│ ├── kf.py # Kalman Filter 跟踪器 +│ └── util/ # 跟踪器工具 +│ ├── sort.py +│ └── kf.py +├── util/ # 工具函数 +│ ├── misc.py # 分布式训练辅助函数 +│ ├── box_ops.py # 边界框操作 +│ ├── checkpoint.py # 检查点管理 +│ └── tool.py # 模型加载工具 +├── tools/ # 辅助工具 +│ ├── visualize.py # 可视化工具 +│ └── eval_to_markdown.py # 评估结果转换 +├── main.py # 训练入口 +├── eval.py # 评估入口 +└── engine.py # 训练/评估引擎 +``` + +--- + +## 核心模块详解 + +### 1. 模型模块 (`models/`) + +#### 1.1 RadarMOTR 主模型 (`models/radarmotr.py`) + +**RadarMOTR** 是项目的核心模型，集成了 Transformer 架构进行多目标跟踪。 + +**主要类**: `RadarMOTR(nn.Module)` + +**初始化参数**: +- `backbone`: 骨干网络 +- `transformer`: Transformer 编码器-解码器 +- `num_classes`: 目标类别数 +- `num_queries`: 查询槽数量 +- `num_feature_levels`: 特征层级数 +- `criterion`: 损失函数计算器 +- `qim`: Query 交互模块 +- `post_process`: 后处理模块 +- `track_base`: 运行时跟踪基类 +- `aux_loss`: 是否使用辅助损失 +- `with_box_refine`: 是否使用边界框迭代细化 +- `two_stage`: 是否使用两阶段检测 +- `query_denoise`: 查询去噪参数 + +**核心方法**: + +| 方法 | 说明 | +|------|------| +| `forward(data)` | 训练时的前向传播，处理连续帧 | +| `predict(img, ori_img_size, track_instances, proposals)` | 推理时的预测方法 | +| `_generate_empty_tracks()` | 生成空的跟踪实例 | +| `_forward_backbone(samples)` | 骨干网络前向传播 | +| `_forward_single_image(samples, track_instances, gtboxes)` | 单帧前向传播 | +| `_post_process_single_image(pred, track_instances, is_last, gt_instances)` | 单帧后处理 | + +**模型构建函数**: `build(args)` - 根据配置构建完整的 RadarMOTR 模型 + +#### 1.2 可变形 Transformer (`models/deformable_transformer_plus.py`) + +**核心类**: `DeformableTransformer` + +**架构组成**: +- **Encoder**: `DeformableTransformerEncoder` - 多层可变形注意力编码器 +- **Decoder**: `DeformableTransformerDecoder` - 多层可变形注意力解码器 +- **Layer**: `DeformableTransformerEncoderLayer` / `DeformableTransformerDecoderLayer` + +**关键特性**: +- 支持多尺度特征融合 +- 可配置编码器/解码器层数 +- 支持 memory bank 用于时序建模 +- 支持 self-cross attention 机制 + +#### 1.3 骨干网络 (`models/backbones/`) + +**支持的后端网络**: +- `circular_resnet18`: 循环填充的 ResNet18 +- `resnet18`: 标准 ResNet18 +- `resnet50`: 标准 ResNet50 + +**特征输出**: +- 多层级特征: layer2, layer3, layer4 +- 输出通道: [128, 256, 512] (ResNet18) / [512, 1024, 2048] (ResNet50) +- 步长: [8, 16, 32] + +#### 1.4 Query 交互模块 (`models/qim.py`) + +**核心类**: `QueryInteractionModuleV2` + +**功能**: 在帧间传递和更新跟踪查询嵌入 + +**关键方法**: +- `_select_active_tracks()`: 选择活跃的跟踪 +- `_update_track_embedding()`: 更新跟踪嵌入 + +#### 1.5 匹配器 (`models/matcher.py`, `models/clip_matcher.py`) + +**HungarianMatcher**: 使用 Hungarian 算法进行二分图匹配 + +**ClipMatcher**: 扩展匹配器，支持 clip 级别的损失计算 + +**匹配成本**: +- 分类成本 (Focal Loss) +- 边界框 L1 成本 +- GIoU 成本 + +### 2. 数据处理模块 (`datasets/`) + +#### 2.1 雷达数据集 (`datasets/radartrack.py`) + +**核心类**: + +| 类名 | 说明 | +|------|------| +| `RadarTrack` | 主数据集类 | +| `RadarSequence` | 单个雷达序列 | +| `RadarTrackSequences` | 验证集数据集 | + +**数据格式**: +- 支持格式: RDTrack, RATrack +- 标注格式: MOT 格式 +- 检测格式: 外部检测器输出 + +**数据增强**: +- `MotTranslateBoxes`: 边界框平移 +- `MotRandomReverseAndHFlip`: 随机翻转 +- `MotRandomNoise`: 随机噪声 +- `MotNormalize`: 标准化 + +### 3. 跟踪器模块 (`trackers/`) + +#### 3.1 跟踪器基类 (`trackers/tracker_base.py`) + +**核心类**: `Tracker` (抽象基类) + +**接口方法**: +- `track_frame(frame, data)`: 单帧跟踪 +- `track(loader, seq_id, output_dir)`: 批量跟踪 +- `reset()`: 重置跟踪状态 + +#### 3.2 跟踪器实现 + +| 跟踪器 | 文件 | 说明 | +|--------|------|------| +| RadarMOTR | `radarmotr.py` | 基于神经网络的跟踪 | +| SORT | `sort.py` | 基于 IOU 的跟踪 | +| Kalman Filter | `kf.py` | 基于卡尔曼滤波的跟踪 | + +### 4. 工具模块 (`util/`) + +#### 4.1 分布式训练工具 (`util/misc.py`) + +**关键类和函数**: + +| 函数/类 | 说明 | +|---------|------| +| `MetricLogger` | 训练指标记录器 | +| `SmoothedValue` | 平滑值追踪 | +| `NestedTensor` | 嵌套张量容器 | +| `init_distributed_mode()` | 初始化分布式训练 | +| `nested_tensor_from_tensors()` | 张量转嵌套张量 | +| `reduce_dict()` / `reduce_dict_async()` | 分布式规约 | + +#### 4.2 边界框操作 (`util/box_ops.py`) + +- `box_giou()`: 计算 GIoU +- `box_cxcywh_to_xyxy()`: 格式转换 +- `box_xyxy_to_cxcywh()`: 格式转换 + +--- + +## 关键数据结构 + +### Instances (`models/structures/instances.py`) + +管理图像中的实例集合，支持动态字段。 + +**主要属性**: +- `boxes`: 边界框 [N, 4] +- `labels`: 类别标签 [N] +- `scores`: 置信度分数 [N] +- `obj_ids`: 目标 ID [N] +- `matched_gt_idxes`: 匹配的 GT 索引 [N] +- `pred_logits`: 预测类别 logits [N, num_classes] +- `pred_boxes`: 预测边界框 [N, 4] +- `output_embedding`: 输出嵌入 [N, hidden_dim] +- `mem_bank`: 记忆库 [N, max_his_length, hidden_dim] + +**支持操作**: +- `cat()`: 合并多个 Instances +- `to()`: 设备转换 +- `__getitem__()`: 索引和切片 + +### Boxes (`models/structures/boxes.py`) + +边界框数据结构，支持多种格式。 + +**支持格式**: +- `xyxy`: [x1, y1, x2, y2] +- `xywh`: [x, y, w, h] +- `cxcywh`: [cx, cy, w, h] + +--- + +## 配置文件说明 + +### 训练配置 (`configs/train.yaml`) + +```yaml +start_epoch: 0 +epochs: 80 +lr_drop: 40 +output_dir: 'data/RadarMOTR' +``` + +### 模型配置 (`configs/base/model.yaml`) + +```yaml +# 学习率 +lr: 0.0002 +lr_backbone: 0.00002 + +# Transformer 配置 +hidden_dim: 256 +nheads: 8 +enc_layers: 6 +dec_layers: 6 +dim_feedforward: 1024 + +# 骨干网络 +backbone: 'resnet50' +num_feature_levels: 4 + +# 跟踪配置 +num_queries: 10 +score_threshold: 0.6 +filter_score_threshold: 0.5 +miss_tolerance: 10 +``` + +### 评估配置 (`configs/trackers/radarmotr.yaml`) + +```yaml +tracker: 'RadarMOTR' +model_path: 'data/models/radarmotr_r18.pth' +score_threshold: 0.5 +filter_score_threshold: 0.5 +miss_tolerance: 5 +area_threshold: 0 +``` + +--- + +## 依赖关系 + +### 核心依赖 + +``` +torch>=2.1.0 +torchvision>=0.16.0 +``` + +### 项目依赖 + +``` +scipy==1.11.4 # 优化算法 +sacred==0.8.5 # 实验管理 +PyYAML==6.0.1 # 配置解析 +Pillow==10.1.0 # 图像处理 +tqdm==4.66.1 # 进度条 +pandas==2.1.4 # 数据处理 +opencv-python-headless # 图像处理 +``` + +### 评估依赖 + +``` +numpy==1.23.5 +scipy==1.11.4 +pycocotools==2.0.6 +matplotlib==3.8.2 +tabulate==0.9.0 +filterpy==1.4.5 # Kalman Filter +scikit-image==0.22.0 +``` + +### CUDA 依赖 + +``` +MultiScaleDeformableAttention (自定义算子) +- 需要 GNU G++ Compiler <11 +- 需要 CUDA Toolkit 11.8 +``` + +--- + +## 运行方式 + +### 环境安装 + +```bash +# 1. 克隆仓库 +git clone --recurse-submodules https://github.com/madeit07/RadarMOTR.git +cd RadarMOTR + +# 2. 创建 conda 环境 +conda create -n radarmotr python=3.11 +conda activate radarmotr + +# 3. 安装 PyTorch +conda install pytorch=2.1 torchvision=0.16 pytorch-cuda=11.8 -c pytorch -c nvidia + +# 4. 安装 CUDA Toolkit +conda install cuda-libraries-dev cuda-nvcc cuda-nvtx cuda-cupti -c nvidia/label/cuda-11.8.0 + +# 5. 安装其他依赖 +pip install -r requirements.txt + +# 6. 编译 MultiScaleDeformableAttention +cd ./models/ops +./make.sh +``` + +### 训练 + +```bash +# 单 GPU 训练 +python main.py with resnet18 + +# 多 GPU 训练 +torchrun --standalone --nnodes 1 --nproc_per_node 4 --max_restarts 2 main.py with resnet18 + +# 使用预训练权重 +python main.py with resnet18 pretrained=/motrv2_base_r18_v2.pth +``` + +### 评估 + +```bash +# RadarMOTR 跟踪器评估 +python eval.py with radarmotr resnet18 split=val model_path=/radarmotr_r18.pth + +# Kalman Filter 评估 +python eval.py with kf split=val tracker_dirname=kf + +# SORT 评估 +python eval.py with sort split=val tracker_dirname=sort +``` + +### 自定义配置 + +```bash +# 修改学习率 +python main.py with resnet18 lr=0.0001 + +# 修改批量大小 +python main.py with resnet18 batch_size=4 + +# 启用调试模式 +python main.py with resnet18 debug +``` + +--- + +## 数据集准备 + +### RDTrack 数据集 + +1. 从 [Google Drive](https://drive.google.com/drive/folders/1h0Tv5X86o7G_yNxn9_nTYm_3EKvdRcIO) 下载 +2. 解压并保存到 `data/dataset/RDTrack` + +### 数据格式 + +``` +RDTrack/ +├── rdtrack-train/ +│ └── seq_001/ +│ ├── seqinfo.ini +│ ├── img1/ +│ │ └── 000001.png +│ ├── det/ +│ │ └── det.txt +│ └── gt/ +│ └── gt.txt +├── rdtrack-val/ +└── seqmaps/ + └── rdtrack-train.txt +``` + +### 预训练权重 + +| 权重 | 骨干网络 | 路径 | +|------|----------|------| +| motrv2_base_r18_v2.pth | ResNet18 | data/models/ | +| motrv2_base_v2.pth | ResNet50 | data/models/ | +| radarmotr_r18.pth | ResNet18 | data/models/ | + +--- + +## 训练流程 + +### 主训练循环 (`main.py`) + +``` +1. 初始化分布式环境 + ↓ +2. 构建模型和损失函数 + ↓ +3. 构建数据集和数据加载器 + ↓ +4. 构建优化器和学习率调度器 + ↓ +5. 加载预训练权重（如有） + ↓ +6. 训练循环: + ├── 前向传播 + ├── 计算损失 + ├── 反向传播 + ├── 梯度裁剪 + ├── 参数更新 + └── 学习率调整 + ↓ +7. 验证循环（如配置启用） + ↓ +8. 保存检查点 +``` + +### 模型前向传播 (`RadarMOTR.forward`) + +``` +输入: 连续帧数据 + ↓ +对每帧进行: + ├── 骨干网络特征提取 + ├── Transformer 编码器处理 + ├── Transformer 解码器处理 + ├── 分类和边界框预测 + ├── 跟踪匹配 + └── Query 交互更新 + ↓ +输出: 预测结果 + 损失 +``` + +--- + +## 评估指标 + +### 支持的评估指标 + +| 指标类别 | 具体指标 | +|----------|----------| +| HOTA | HOTA, DetA, AssA | +| CLEAR | MOTA, MOTP, IDF1 | +| Identity | IDs, FG, GT | +| 计数 | FP, FN, Frag | + +### 评估输出 + +评估结果保存到 `data/trackers/-//` + +--- + +## 扩展指南 + +### 添加新的跟踪器 + +1. 继承 `Tracker` 基类 +2. 实现 `track_frame()` 方法 +3. 在 `eval.py` 的 `build_tracker()` 函数中注册 + +### 添加新的骨干网络 + +1. 在 `models/backbones/` 中实现 +2. 在 `BACKBONES` 字典中注册 +3. 更新配置文件的 `backbone` 参数 + +### 修改损失函数 + +1. 修改 `models/clip_matcher.py` 中的损失计算 +2. 或创建新的 Criterion 类 +3. 在 `models/radarmotr.py` 的 `build()` 函数中集成 + +--- + +## 常见问题 + +### Q: 训练时显存不足怎么办？ + +A: 尝试以下方法： +- 减小 `batch_size` +- 启用梯度检查点: `use_grad_checkpointing=true` +- 减少 `num_queries` +- 使用 ResNet18 骨干网络 + +### Q: 如何加速推理？ + +A: 建议： +- 使用较短的 `miss_tolerance` +- 调整 `score_threshold` 和 `filter_score_threshold` +- 使用批量推理 + +### Q: 模型无法收敛怎么办？ + +A: 检查： +- 学习率设置 +- 数据增强配置 +- 预训练权重是否正确加载 +- `query_denoise` 参数 + +--- + +## 参考资料 + +- [MOTRv2](https://github.com/megvii-research/MOTRv2) +- [MOTR](https://github.com/megvii-research/MOTR) +- [Deformable DETR](https://github.com/fundamentalvision/Deformable-DETR) +- [DETR](https://github.com/facebookresearch/detr) +- [RADTrack Dataset](https://github.com/madeit07/RADTrack) From 0f14d7da8135e3ee60bc2240c1adc6e15fa5475a Mon Sep 17 00:00:00 2001 From: wuweh Date: Fri, 15 May 2026 13:54:38 +0000 Subject: [PATCH 2/2] =?UTF-8?q?feat:=20=E7=94=9F=E6=88=90=E9=A1=B9?= =?UTF-8?q?=E7=9B=AECode=20Wiki=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- .../radarmotr-beginner-guide/checklist.md | 22 +++ .trae/specs/radarmotr-beginner-guide/spec.md | 75 +++++++++++ .trae/specs/radarmotr-beginner-guide/tasks.md | 125 ++++++++++++++++++ ...41\345\210\222\346\200\273\350\247\210.md" | 96 ++++++++++++++ ...57\344\270\216\344\273\213\347\273\215.md" | 72 ++++++++++ ...03\344\270\216\344\276\235\350\265\226.md" | 73 ++++++++++ ...07\344\273\266\350\257\246\350\247\243.md" | 68 ++++++++++ ...04\347\220\206\346\265\201\347\250\213.md" | 53 ++++++++ ...60\346\215\256\347\273\223\346\236\204.md" | 56 ++++++++ ...45\345\217\243\346\265\201\347\250\213.md" | 54 ++++++++ ...70\345\277\203\346\250\241\345\236\213.md" | 53 ++++++++ ...37\350\270\252\351\200\273\350\276\221.md" | 49 +++++++ ...15\344\270\216\346\215\237\345\244\261.md" | 41 ++++++ ...60\344\270\216\346\200\273\347\273\223.md" | 53 ++++++++ 14 files changed, 890 insertions(+) create mode 100644 .trae/specs/radarmotr-beginner-guide/checklist.md create mode 100644 .trae/specs/radarmotr-beginner-guide/spec.md create mode 100644 .trae/specs/radarmotr-beginner-guide/tasks.md create mode 100644 "tutorials/00_\345\255\246\344\271\240\350\256\241\345\210\222\346\200\273\350\247\210.md" create mode 100644 "tutorials/01_\351\241\271\347\233\256\350\203\214\346\231\257\344\270\216\344\273\213\347\273\215.md" create mode 100644 "tutorials/02_\347\216\257\345\242\203\344\270\216\344\276\235\350\265\226.md" create mode 100644 "tutorials/03_\351\205\215\347\275\256\346\226\207\344\273\266\350\257\246\350\247\243.md" create mode 100644 "tutorials/04_\346\225\260\346\215\256\345\244\204\347\220\206\346\265\201\347\250\213.md" create mode 100644 "tutorials/05_\346\240\270\345\277\203\346\225\260\346\215\256\347\273\223\346\236\204.md" create mode 100644 "tutorials/06_\351\241\271\347\233\256\345\205\245\345\217\243\346\265\201\347\250\213.md" create mode 100644 "tutorials/07_\346\240\270\345\277\203\346\250\241\345\236\213.md" create mode 100644 "tutorials/08_\350\267\237\350\270\252\351\200\273\350\276\221.md" create mode 100644 "tutorials/09_\345\214\271\351\205\215\344\270\216\346\215\237\345\244\261.md" create mode 100644 "tutorials/10_\345\267\245\345\205\267\345\207\275\346\225\260\344\270\216\346\200\273\347\273\223.md" diff --git a/.trae/specs/radarmotr-beginner-guide/checklist.md b/.trae/specs/radarmotr-beginner-guide/checklist.md new file mode 100644 index 0000000..7716ffe --- /dev/null +++ b/.trae/specs/radarmotr-beginner-guide/checklist.md @@ -0,0 +1,22 @@ +# RadarMOTR 小白学习指南 - Verification Checklist + +## 文档完整性 +- [x] 学习计划总览文档已创建 (`tutorials/00_学习计划总览.md`) +- [x] 阶段 1-10 文档全部创建 +- [x] 所有文档在 `tutorials/` 目录下 + +## 内容质量 +- [x] 每个阶段文档有明确的学习目标 +- [x] 文档使用通俗易懂的中文 +- [x] 文档结构清晰，易于导航 +- [x] 对关键代码有详细的解释 + +## 代码链接 +- [x] 每个文档包含相关文件的可点击链接 +- [x] 所有链接指向正确的位置 +- [x] 重要函数有行号锚点 + +## 学习体验 +- [x] 学习路径由易到难排列 +- [x] 各阶段学习时间分配合理 +- [x] 有代码示例和解释 diff --git a/.trae/specs/radarmotr-beginner-guide/spec.md b/.trae/specs/radarmotr-beginner-guide/spec.md new file mode 100644 index 0000000..59309f8 --- /dev/null +++ b/.trae/specs/radarmotr-beginner-guide/spec.md @@ -0,0 +1,75 @@ +# RadarMOTR 小白学习指南 - Product Requirement Document + +## Overview +- **Summary**: 创建一套完整的、循序渐进的小白学习指南，帮助初学者从零基础理解 RadarMOTR 多目标跟踪项目。 +- **Purpose**: 解决小白面对复杂项目不知道从何入手的问题，提供清晰的学习路径和详细讲解。 +- **Target Users**: 计算机视觉/深度学习初学者、雷达数据处理爱好者、多目标跟踪入门者。 + +## Goals +- 提供清晰的学习路径，按照由浅入深的顺序排列 +- 对每个学习阶段提供详细的文档和代码注释 +- 帮助小白理解项目的架构、核心逻辑和运行流程 +- 最终让小白能够独立运行、调试和扩展项目 + +## Non-Goals (Out of Scope) +- 不修改任何项目源代码（纯讲解性质） +- 不创建新的算法或模型 +- 不进行性能优化或新功能开发 +- 不替代官方文档或论文 + +## Background & Context +RadarMOTR 是一个基于 Transformer 的雷达多目标跟踪项目，代码结构复杂，包含多个子系统。对于小白来说，直接看代码很容易迷失方向。需要一套系统性的学习方案。 + +## Functional Requirements +- **FR-1**: 创建学习计划总览文档 +- **FR-2**: 为每个学习阶段创建详细的讲解文档 +- **FR-3**: 标注关键代码位置和功能说明 +- **FR-4**: 提供流程图和架构图辅助理解 + +## Non-Functional Requirements +- **NFR-1**: 文档使用中文编写，通俗易懂 +- **NFR-2**: 提供可点击的代码链接，方便跳转 +- **NFR-3**: 文档结构清晰，易于导航 +- **NFR-4**: 各阶段学习时间估计合理 + +## Constraints +- **Technical**: 基于现有项目结构，不改变代码 +- **Business**: 不影响现有项目功能 +- **Dependencies**: 需要利用已有的 CODE_WIKI.md 和代码 + +## Assumptions +- 小白有基础的 Python 知识 +- 小白了解基本的深度学习概念 +- 小白已经完成环境搭建 + +## Acceptance Criteria + +### AC-1: 学习计划总览文档创建成功 +- **Given**: 项目结构已分析完成 +- **When**: 创建学习计划文档 +- **Then**: 文档包含完整的学习阶段划分和时间估计 +- **Verification**: `human-judgment` +- **Notes**: 文档应逻辑清晰，学习路径合理 + +### AC-2: 各阶段详细讲解文档创建成功 +- **Given**: 学习计划总览已完成 +- **When**: 为每个学习阶段编写详细讲解 +- **Then**: 每个阶段都有独立文档，包含核心代码注释 +- **Verification**: `human-judgment` + +### AC-3: 关键代码位置标注完成 +- **Given**: 各阶段文档已创建 +- **When**: 在文档中添加代码链接 +- **Then**: 文档中包含可点击的文件和函数链接 +- **Verification**: `programmatic` (检查链接有效性) + +### AC-4: 学习流程图创建完成 +- **Given**: 整体流程分析完成 +- **When**: 绘制学习流程和数据流程图表 +- **Then**: 图表清晰展示项目的数据流和控制流 +- **Verification**: `human-judgment` + +## Open Questions +- [ ] 小白是否需要更基础的 PyTorch 入门讲解？ +- [ ] 是否需要包含实际运行步骤的详细截图？ +- [ ] 是否需要创建简化的示例代码用于教学？ diff --git a/.trae/specs/radarmotr-beginner-guide/tasks.md b/.trae/specs/radarmotr-beginner-guide/tasks.md new file mode 100644 index 0000000..f60d929 --- /dev/null +++ b/.trae/specs/radarmotr-beginner-guide/tasks.md @@ -0,0 +1,125 @@ +# RadarMOTR 小白学习指南 - The Implementation Plan (Decomposed and Prioritized Task List) + +## [ ] Task 1: 创建学习计划总览文档 +- **Priority**: P0 +- **Depends On**: None +- **Description**: + - 创建 `tutorials/00_学习计划总览.md + - 列出完整的学习路径 + - 为每个阶段标注学习时间和重点内容 +- **Acceptance Criteria Addressed**: [AC-1] +- **Test Requirements**: + - `human-judgement` TR-1.1: 文档包含 10 个学习阶段，每个阶段有明确的时间估计 + - `human-judgement` TR-1.2: 学习路径逻辑清晰，从易到难排列合理 +- **Notes**: 参考之前为用户提供的建议路径 + +## [ ] Task 2: 阶段 1: 项目背景介绍文档 +- **Priority**: P0 +- **Depends On**: [Task 1] +- **Description**: + - 创建 `tutorials/01_项目背景与介绍.md` + - 介绍项目是什么、要解决什么问题 + - 项目的主要特点和应用场景 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-2.1: 清晰讲解项目用途 + - `programmatic` TR-2.2: 文档中包含指向相关文件链接 + +## [ ] Task 3: 阶段 2: 依赖与环境配置 +- **Priority**: P0 +- **Depends On**: [Task 2] +- **Description**: + - 创建 `tutorials/02_环境与依赖.md` + - 讲解项目的环境要求和依赖项 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-3.1: 详细讲解每个依赖的作用 + - `programmatic` TR-3.2: 包含依赖文件的链接 + +## [ ] Task 4: 阶段 3: 配置文件详解 +- **Priority**: P0 +- **Depends On**: [Task 3] +- **Description**: + - 创建 `tutorials/03_配置文件详解.md` + - 讲解核心配置文件和参数含义 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-4.1: 对关键参数的详细解释 + - `programmatic` TR-4.2: 所有配置文件有链接 + +## [ ] Task 5: 阶段 4: 数据处理流程 +- **Priority**: P0 +- **Depends On**: [Task 4] +- **Description**: + - 创建 `tutorials/04_数据处理流程.md` + - 讲解数据加载、预处理和增强 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-5.1: 数据流程清晰 + - `programmatic` TR-5.2: 数据相关代码文件有链接 + +## [ ] Task 6: 阶段 5: 核心数据结构 +- **Priority**: P0 +- **Depends On**: [Task 5] +- **Description**: + - 创建 `tutorials/05_核心数据结构.md` + - 讲解 Instances 和 Boxes +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-6.1: 数据结构的字段和方法清晰 + - `programmatic` TR-6.2: 相关类和函数有链接 + +## [ ] Task 7: 阶段 6: 入口流程 +- **Priority**: P0 +- **Depends On**: [Task 6] +- **Description**: + - 创建 `tutorials/06_项目入口流程.md` + - 讲解训练和评估的主流程 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-7.1: 流程图或文字说明清晰 + - `programmatic` TR-7.2: main.py 和 eval.py 有链接 + +## [ ] Task 8: 阶段 7: 核心模型 +- **Priority**: P0 +- **Depends On**: [Task 7] +- **Description**: + - 创建 `tutorials/07_核心模型.md` + - 讲解 RadarMOTR 和 Transformer +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-8.1: 模型结构和前向传播清晰 + - `programmatic` TR-8.2: 模型文件有链接 + +## [ ] Task 9: 阶段 8: 跟踪逻辑 +- **Priority**: P0 +- **Depends On**: [Task 8] +- **Description**: + - 创建 `tutorials/08_跟踪逻辑.md` + - 讲解跟踪器和 Query 交互 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-9.1: 跟踪过程清晰 + - `programmatic` TR-9.2: 跟踪器文件有链接 + +## [ ] Task 10: 阶段 9: 匹配与损失 +- **Priority**: P0 +- **Depends On**: [Task 9] +- **Description**: + - 创建 `tutorials/09_匹配与损失.md` + - 讲解 Hungarian 匹配和损失函数 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-10.1: 损失计算流程 + - `programmatic` TR-10.2: 匹配器和损失函数有链接 + +## [ ] Task 11: 阶段 10: 工具函数 +- **Priority**: P0 +- **Depends On**: [Task 10] +- **Description**: + - 创建 `tutorials/10_工具函数与总结.md` + - 讲解工具函数和项目总结 +- **Acceptance Criteria Addressed**: [AC-2, AC-3] +- **Test Requirements**: + - `human-judgement` TR-11.1: 工具函数清晰 + - `programmatic` TR-11.2: 工具文件有链接 diff --git "a/tutorials/00_\345\255\246\344\271\240\350\256\241\345\210\222\346\200\273\350\247\210.md" "b/tutorials/00_\345\255\246\344\271\240\350\256\241\345\210\222\346\200\273\350\247\210.md" new file mode 100644 index 0000000..b76ba00 --- /dev/null +++ "b/tutorials/00_\345\255\246\344\271\240\350\256\241\345\210\222\346\200\273\350\247\210.md" @@ -0,0 +1,96 @@ +# RadarMOTR 小白学习指南 - 学习计划总览 + +欢迎！这是一套完整的 RadarMOTR 项目学习指南，专门为小白准备。 + +## 📚 学习建议 + +1. **循序渐进**：不要跳阶段，按顺序学习 +2. **边看边画**：在学习的过程中画流程图、画结构图 +3. **动手实践**：在理解的基础上尝试运行代码 +4. **多查资料**：遇到不懂的概念，先查基础资料 + +## 📋 学习路线图 + +| 阶段 | 主题 | 建议学习时间 | 难度 | +|------|------|--------------|------| +| 1️⃣ | [项目背景与介绍](./01_项目背景与介绍.md) | 10分钟 | ⭐ | +| 2️⃣ | [环境与依赖](./02_环境与依赖.md) | 30分钟 | ⭐⭐ | +| 3️⃣ | [配置文件详解](./03_配置文件详解.md) | 1小时 | ⭐⭐ | +| 4️⃣ | [数据处理流程](./04_数据处理流程.md) | 1-2小时 | ⭐⭐⭐ | +| 5️⃣ | [核心数据结构](./05_核心数据结构.md) | 30分钟 | ⭐⭐ | +| 6️⃣ | [项目入口流程](./06_项目入口流程.md) | 2-3小时 | ⭐⭐⭐ | +| 7️⃣ | [核心模型](./07_核心模型.md) | 2-3小时 | ⭐⭐⭐⭐ | +| 8️⃣ | [跟踪逻辑](./08_跟踪逻辑.md) | 1-2小时 | ⭐⭐⭐ | +| 9️⃣ | [匹配与损失](./09_匹配与损失.md) | 1小时 | ⭐⭐⭐ | +| 🔟 | [工具函数与总结](./10_工具函数与总结.md) | 30分钟 | ⭐⭐ | + +## 🎯 各阶段学习目标 + +### 阶段 1：项目背景与介绍 +**目标**：了解 RadarMOTR 是什么、要解决什么问题 +- 阅读项目 README +- 理解项目的应用场景 +- 查看整体架构图 + +### 阶段 2：环境与依赖 +**目标**：搞懂项目需要什么环境和依赖 +- 理解各依赖库的作用 +- 了解环境安装步骤 +- 学习如何配置环境变量 + +### 阶段 3：配置文件详解 +**目标**：理解每个配置参数的含义 +- 学习配置文件的结构 +- 掌握核心参数的作用 +- 了解如何调整超参数 + +### 阶段 4：数据处理流程 +**目标**：理解数据是怎么加载和处理的 +- 学习数据集加载逻辑 +- 理解数据增强方法 +- 掌握数据格式转换 + +### 阶段 5：核心数据结构 +**目标**：深入理解 Instances 和 Boxes +- 学习 Instances 类的作用和字段 +- 理解 Boxes 类的格式转换 +- 掌握数据结构的使用方法 + +### 阶段 6：项目入口流程 +**目标**：搞懂训练和评估的主流程 +- 学习 main.py 的训练流程 +- 理解 eval.py 的评估流程 +- 掌握 engine.py 的核心逻辑 + +### 阶段 7：核心模型 +**目标**：理解 RadarMOTR 模型的核心机制 +- 学习 RadarMOTR 类的结构 +- 理解 Transformer 编码器-解码器 +- 掌握前向传播和推理流程 + +### 阶段 8：跟踪逻辑 +**目标**：理解跟踪是怎么实现的 +- 学习跟踪器基类 +- 理解 Query 交互模块 +- 掌握帧间跟踪更新机制 + +### 阶段 9：匹配与损失 +**目标**：理解匹配和损失计算 +- 学习 Hungarian 匹配 +- 理解损失函数 +- 掌握损失计算流程 + +### 阶段 10：工具函数与总结 +**目标**：收尾并总结整个项目 +- 学习工具函数 +- 项目整体总结 +- 下一步学习建议 + +## 📖 参考资料 + +- [CODE_WIKI.md](../CODE_WIKI.md) - 完整的项目技术文档 +- [README.md](../README.md) - 项目官方介绍 +- [论文](https://bwsyncandshare.kit.edu/s/zCgc5o89L44oN5a) - RadarMOTR 技术论文 +- [RADTrack 数据集](https://github.com/madeit07/RADTrack) - 配套数据集 + +现在开始吧！从 [阶段 1](./01_项目背景与介绍.md) 开始。 diff --git "a/tutorials/01_\351\241\271\347\233\256\350\203\214\346\231\257\344\270\216\344\273\213\347\273\215.md" "b/tutorials/01_\351\241\271\347\233\256\350\203\214\346\231\257\344\270\216\344\273\213\347\273\215.md" new file mode 100644 index 0000000..72bf18c --- /dev/null +++ "b/tutorials/01_\351\241\271\347\233\256\350\203\214\346\231\257\344\270\216\344\273\213\347\273\215.md" @@ -0,0 +1,72 @@ +# 阶段 1：项目背景与介绍 + +## 🎯 学习目标 +- 了解 RadarMOTR 是什么项目 +- 理解它解决了什么问题 +- 掌握项目的核心特点 + +## 📖 1.1 项目是什么？ + +**RadarMOTR** 是一个基于 Transformer 的雷达多目标跟踪系统。 + +简单理解： +- 它可以在雷达的距离-多普勒图上找到多个物体 +- 并且可以持续跟踪这些物体在不同帧之间的运动 +- 使用神经网络替代传统的手工方法 + +## 📖 1.2 为什么需要这个项目？ + +传统的雷达跟踪方法主要使用： +- **卡尔曼滤波**：预测物体的运动 +- **匈牙利匹配**：关联不同帧的检测 + +但这些方法有缺点： +- 参数需要大量手工调试 +- 难以适应复杂场景 +- 对噪声敏感 + +RadarMOTR 的优势： +- 使用神经网络端到端学习 +- Transformer 可以捕捉长距离的上下文关系 +- 更适应复杂的雷达数据特点 + +## 📖 1.3 项目架构 + +让我们看一下这个图：[docs/images/RadarMOTR_Architecture_2.png](../docs/images/RadarMOTR_Architecture_2.png) + +整体流程大概是这样： +1. 外部检测器先检测出物体 +2. RadarMOTR 接收检测结果 +3. 使用 Transformer 进行跟踪关联 +4. 输出跟踪结果 + +## 📖 1.4 技术背景 + +这个项目建立在多个优秀的工作基础之上： + +| 项目 | 作用 | +|------|------| +| [MOTRv2](https://github.com/megvii-research/MOTRv2) | 视频多目标跟踪，基于 Query | +| [MOTR](https://github.com/megvii-research/MOTR) | 原版 MOTR | +| [Deformable DETR](https://github.com/fundamentalvision/Deformable-DETR) | 可变形 Transformer 检测器 | +| [DETR](https://github.com/facebookresearch/detr) | 原始的 DETR 检测器 | + +## 📖 1.5 核心代码文件 + +虽然还没学代码，但我们先看看主要文件： + +- [README.md](../README.md) - 这是项目的官方介绍 +- [main.py](../main.py) - 训练程序入口 +- [eval.py](../eval.py) - 评估程序入口 +- [models/radarmotr.py](../models/radarmotr.py) - 核心模型代码 + +## 📝 本阶段总结 + +你现在应该了解： +1. RadarMOTR 是做雷达多目标跟踪的 +2. 它用 Transformer 替代传统方法 +3. 它有多个优秀的开源项目作为基础 + +## 🎯 下一步 + +现在前往 [阶段 2：环境与依赖](./02_环境与依赖.md)，了解项目需要什么环境和依赖。 diff --git "a/tutorials/02_\347\216\257\345\242\203\344\270\216\344\276\235\350\265\226.md" "b/tutorials/02_\347\216\257\345\242\203\344\270\216\344\276\235\350\265\226.md" new file mode 100644 index 0000000..c480190 --- /dev/null +++ "b/tutorials/02_\347\216\257\345\242\203\344\270\216\344\276\235\350\265\226.md" @@ -0,0 +1,73 @@ +# 阶段 2：环境与依赖 + +## 🎯 学习目标 +- 了解项目需要什么环境和依赖 +- 理解每个依赖的作用 +- 掌握安装顺序 + +## 📦 2.1 依赖文件 + +项目有三个依赖文件： + +| 文件 | 用途 | +|------|------| +| [requirements.txt](../requirements.txt) | 完整依赖 | +| [requirements_min.txt](../requirements_min.txt) | 最小依赖 | +| [requirements_eval.txt](../requirements_eval.txt) | 评估专用依赖 | + +## 📦 2.2 核心依赖讲解 + +### PyTorch & TorchVision +- **作用**：深度学习框架 +- **版本要求**：torch == 2.1 +- **用途**：定义、训练、推理神经网络 +- **学习建议**：这是最重要的依赖，先确保安装 + +### 其他重要库 +| 库 | 用途 | +|----|------| +| NumPy | 科学计算基础库 | +| SciPy | 更高级的科学计算 | +| OpenCV | 图像处理 | +| Pillow | 图像处理基础库 | +| Pandas | 数据处理和分析 | +| PyYAML | 解析配置文件 | + +## 🏗️ 2.3 环境要求 + +### 硬件要求 +- **GPU**：至少一张支持 CUDA 的显卡 +- **系统**：Linux（推荐 Ubuntu 20.04） +- **内存**：越大越好 + +### 编译器 +- **GCC**：需要编译自定义 CUDA 算子 + +## 🚀 2.4 安装步骤 + +1. 创建 Conda 环境 +2. 安装 PyTorch +3. 安装 CUDA 工具包 +4. 安装其他依赖 +5. 编译自定义算子 + +## 🔧 2.5 自定义算子 + +在 [models/ops](../models/ops/) 目录下有自定义 CUDA 算子： + +``` +MultiScaleDeformableAttention +``` + +这是可变形注意力的高效实现，需要编译。 + +## 📝 本阶段总结 + +你现在应该了解： +1. 项目的主要依赖库和它们的用途 +2. 硬件和系统要求 +3. 安装的大概步骤 + +## 🎯 下一步 + +前往 [阶段 3：配置文件详解](./03_配置文件详解.md)。 diff --git "a/tutorials/03_\351\205\215\347\275\256\346\226\207\344\273\266\350\257\246\350\247\243.md" "b/tutorials/03_\351\205\215\347\275\256\346\226\207\344\273\266\350\257\246\350\247\243.md" new file mode 100644 index 0000000..2079cbc --- /dev/null +++ "b/tutorials/03_\351\205\215\347\275\256\346\226\207\344\273\266\350\257\246\350\247\243.md" @@ -0,0 +1,68 @@ +# 阶段 3：配置文件详解 + +## 🎯 学习目标 +- 理解配置文件的组织 +- 掌握核心参数的含义 +- 学会如何调整参数 + +## 📂 3.1 配置文件目录 + +配置文件都在 [configs/](../configs/) 目录下： + +| 目录/文件 | 用途 | +|-----------|------| +| [configs/base/](../configs/base/) | 基础配置 | +| [configs/trackers/](../configs/trackers/) | 跟踪器配置 | +| [configs/train.yaml](../configs/train.yaml) | 训练配置 | +| [configs/eval.yaml](../configs/eval.yaml) | 评估配置 | +| [configs/resnet18.yaml](../configs/resnet18.yaml) | ResNet18 配置 | +| [configs/resnet50.yaml](../configs/resnet50.yaml) | ResNet50 配置 | + +## ⚙️ 3.2 基础配置文件 + +### base/misc.yaml +- 日志、输出目录等杂项配置 + +### base/dataset.yaml +- 数据集路径、数据加载器参数 + +### base/model.yaml ⭐ +**这是最重要的配置！ +- 学习率 +- Transformer 参数 +- 骨干网络选择 +- 跟踪器超参数 + +## 🎛️ 3.3 核心参数详解 + +### 学习率相关 +```yaml +lr: 0.0002 # 主学习率 +lr_backbone: 0.00002 # 骨干网络学习率（比主学习率小 10 倍 +``` + +### Transformer 参数 +```yaml +hidden_dim: 256 # 隐藏层维度 +enc_layers: 6 # 编码器层数 +dec_layers: 6 # 解码器层数 +nheads: 8 # 注意力头数 +``` + +### 跟踪器参数 +```yaml +num_queries: 10 # 额外的检测 Query 数量 +score_threshold: 0.6 # 保持跟踪的分数阈值 +miss_tolerance: 10 # 允许目标消失多少帧后删除跟踪 +``` + +## 📝 本阶段总结 + +你现在应该了解： +1. 配置文件的组织结构 +2. 核心参数的作用 +3. 如何调整参数 + +## 🎯 下一步 + +前往 [阶段 4：数据处理流程](./04_数据处理流程.md)。 diff --git "a/tutorials/04_\346\225\260\346\215\256\345\244\204\347\220\206\346\265\201\347\250\213.md" "b/tutorials/04_\346\225\260\346\215\256\345\244\204\347\220\206\346\265\201\347\250\213.md" new file mode 100644 index 0000000..834ac24 --- /dev/null +++ "b/tutorials/04_\346\225\260\346\215\256\345\244\204\347\220\206\346\265\201\347\250\213.md" @@ -0,0 +1,53 @@ +# 阶段 4：数据处理流程 + +## 🎯 学习目标 +- 理解数据是如何加载的 +- 掌握预处理和增强 +- 了解数据格式 + +## 📚 4.1 核心数据文件 + +主要文件都在 [datasets/](../datasets/) 目录： + +| 文件 | 作用 | +|------|------| +| [datasets/radartrack.py](../datasets/radartrack.py) | 数据集类，最重要！ | +| [datasets/transforms.py](../datasets/transforms.py) | 通用数据变换 | +| [datasets/radar_transforms.py](../datasets/radar_transforms.py) | 雷达专用变换 | +| [datasets/data_prefetcher.py](../datasets/data_prefetcher.py) | 数据预取 | + +## 🏗️ 4.2 核心类结构 + +### RadarSequence 类 +代表单个雷达序列，管理该序列的所有帧和标注。 + +### RadarTrack 类 +主数据集类，管理所有序列，提供采样功能。 + +## 🔄 4.3 数据加载流程 + +``` +1. 解析 seqinfo.ini → 序列信息 +2. 读取图像文件 +3. 读取标注 gt.txt → GT +4. 读取检测 det.txt → 检测结果 +5. 数据增强（如果是训练 +6. 返回图像 + 标注 +``` + +## 🎨 4.4 数据增强 + +训练时使用的增强： +- 随机翻转和水平翻转 +- 随机噪声 + +## 📝 本阶段总结 + +你现在应该了解： +1. 数据集是怎么加载的 +2. 数据增强方法 +3. 数据格式 + +## 🎯 下一步 + +前往 [阶段 5：核心数据结构](./05_核心数据结构.md)。 diff --git "a/tutorials/05_\346\240\270\345\277\203\346\225\260\346\215\256\347\273\223\346\236\204.md" "b/tutorials/05_\346\240\270\345\277\203\346\225\260\346\215\256\347\273\223\346\236\204.md" new file mode 100644 index 0000000..02ea219 --- /dev/null +++ "b/tutorials/05_\346\240\270\345\277\203\346\225\260\346\215\256\347\273\223\346\236\204.md" @@ -0,0 +1,56 @@ +# 阶段 5：核心数据结构 + +## 🎯 学习目标 +- 理解 Instances 类 +- 理解 Boxes 类 +- 掌握它们的字段和方法 + +## 🏗️ 5.1 数据结构文件 + +在 [models/structures/](../models/structures/) 目录： + +| 文件 | 作用 | +|------|------| +| [models/structures/instances.py](../models/structures/instances.py) | Instances 类 | +| [models/structures/boxes.py](../models/structures/boxes.py) | Boxes 类 | + +## 📦 5.2 Instances 类 + +Instances 是最重要的数据结构！ + +### 主要字段 +| 字段 | 作用 | +|------|------| +| pred_logits | 预测分类 logits | +| pred_boxes | 预测边界框 | +| output_embedding | 输出嵌入 | +| ref_pts | 参考点 | +| obj_idxes | 目标 ID | +| scores | 置信度分数 | +| matched_gt_idxes | 匹配的 GT 索引 | +| disappear_time | 消失帧数 | + +### 支持的方法 +- `to(device) - 移动到设备 +- `cat(instance_lists) - 合并 +- 索引操作 + +## 📦 5.3 Boxes 类 + +边界框的表示和操作类。 + +### 支持格式 +- xyxy: 左上角右下角 +- xywh: 左上角宽高 +- cxcywh: 中心坐标宽高 + +## 📝 本阶段总结 + +你现在应该了解： +1. Instances 和 Boxes 的作用 +2. 主要字段的含义 +3. 基本操作方法 + +## 🎯 下一步 + +前往 [阶段 6：项目入口流程](./06_项目入口流程.md)。 diff --git "a/tutorials/06_\351\241\271\347\233\256\345\205\245\345\217\243\346\265\201\347\250\213.md" "b/tutorials/06_\351\241\271\347\233\256\345\205\245\345\217\243\346\265\201\347\250\213.md" new file mode 100644 index 0000000..c9473a7 --- /dev/null +++ "b/tutorials/06_\351\241\271\347\233\256\345\205\245\345\217\243\346\265\201\347\250\213.md" @@ -0,0 +1,54 @@ +# 阶段 6：项目入口流程 + +## 🎯 学习目标 +- 理解训练主流程 +- 理解评估主流程 +- 掌握入口文件 + +## 📂 6.1 入口文件 + +| 文件 | 作用 | +|------|------| +| [main.py](../main.py) | 训练入口（Sacred实验 | +| [eval.py](../eval.py) | 评估入口 | +| [engine.py](../engine.py) | 训练和评估的引擎 | + +## 🏋️ 6.2 训练流程 (main.py) + +``` +1. 初始化分布式环境 +2. 构建模型 +3. 构建数据集和加载器 +4. 构建优化器 +5. 训练循环 + - 前向传播 + - 计算损失 + - 反向传播 + - 更新参数 +6. 保存检查点 +``` + +### 关键函数 +- `train(args, _run, _log) - 主训练函数 +- `train_one_epoch() - 单轮训练 + +## 🏃 6.3 评估流程 (eval.py) + +``` +1. 加载模型权重 +2. 遍历每个序列 + - 每帧跟踪 +3. 保存结果 +4. 运行评估指标 +``` + +## 📝 本阶段总结 + +你现在应该了解： +1. 训练和评估的主流程 +2. 入口文件的结构 +3. 关键函数的作用 + +## 🎯 下一步 + +前往 [阶段 7：核心模型](./07_核心模型.md)。 diff --git "a/tutorials/07_\346\240\270\345\277\203\346\250\241\345\236\213.md" "b/tutorials/07_\346\240\270\345\277\203\346\250\241\345\236\213.md" new file mode 100644 index 0000000..b5d46d2 --- /dev/null +++ "b/tutorials/07_\346\240\270\345\277\203\346\250\241\345\236\213.md" @@ -0,0 +1,53 @@ +# 阶段 7：核心模型 + +## 🎯 学习目标 +- 理解 RadarMOTR 模型 +- 理解 Transformer +- 掌握前向和推理 + +## 📚 7.1 核心模型文件 + +| 文件 | 作用 | +|------|------| +| [models/radarmotr.py](../models/radarmotr.py) | RadarMOTR 类（最重要！ | +| [models/deformable_transformer_plus.py](../models/deformable_transformer_plus.py) | Transformer | + +## 🏗️ 7.2 RadarMOTR 模型结构 + +### 主要组件 +- 骨干网络：提取特征 +- 可变形 Transformer +- Query 交互 +- 跟踪基类 + +### 核心方法 +| 方法 | 作用 | +|------|------| +| `forward(data)` | 训练前向传播 +| `predict(img, ...)` | 推理 +| `_forward_backbone()` | 骨干网络 +| `_generate_empty_tracks()` | 初始空跟踪 + +## 🔄 7.3 前向传播 + +训练时 + +``` +1. 对每帧 + - 骨干网络提取特征 + - Transformer 处理 + - 输出预测 + - 匹配损失 + - Query 交互 +``` + +## 📝 本阶段总结 + +你现在应该了解： +1. 模型的主要组件 +2. 前向传播流程 +3. 训练和推理的区别 + +## 🎯 下一步 + +前往 [阶段 8：跟踪逻辑](./08_跟踪逻辑.md)。 diff --git "a/tutorials/08_\350\267\237\350\270\252\351\200\273\350\276\221.md" "b/tutorials/08_\350\267\237\350\270\252\351\200\273\350\276\221.md" new file mode 100644 index 0000000..d6dc105 --- /dev/null +++ "b/tutorials/08_\350\267\237\350\270\252\351\200\273\350\276\221.md" @@ -0,0 +1,49 @@ +# 阶段 8：跟踪逻辑 + +## 🎯 学习目标 +- 理解跟踪器 +- 理解 Query 交互 +- 掌握帧间更新 + +## 📚 8.1 跟踪器文件 + +| 文件 | 作用 | +|------|------| +| [trackers/tracker_base.py](../trackers/tracker_base.py) | 基类 | +| [trackers/radarmotr.py](../trackers/radarmotr.py) | RadarMOTR 实现 | +| [models/qim.py](../models/qim.py) | Query 交互模块 | +| [models/tracker.py](../models/tracker.py) | 跟踪基类 | + +## 🔄 8.2 Query 交互模块 (QIM) + +### 作用 +在帧间传递和更新跟踪 Query + +### 主要步骤 +``` +1. 选择活跃的跟踪 +2. 更新嵌入 +3. 为下一帧准备 +``` + +## 🏃 8.3 跟踪器工作流程 + +``` +每帧： +1. 获取检测框 +2. 模型预测 +3. 过滤低分 +4. 分配 ID +5. 更新历史 +``` + +## 📝 本阶段总结 + +你现在应该了解： +1. 跟踪器的基类和实现 +2. Query 交互的作用 +3. 帧间更新的流程 + +## 🎯 下一步 + +前往 [阶段 9：匹配与损失](./09_匹配与损失.md)。 diff --git "a/tutorials/09_\345\214\271\351\205\215\344\270\216\346\215\237\345\244\261.md" "b/tutorials/09_\345\214\271\351\205\215\344\270\216\346\215\237\345\244\261.md" new file mode 100644 index 0000000..0a0bcc5 --- /dev/null +++ "b/tutorials/09_\345\214\271\351\205\215\344\270\216\346\215\237\345\244\261.md" @@ -0,0 +1,41 @@ +# 阶段 9：匹配与损失 + +## 🎯 学习目标 +- 理解 Hungarian 匹配 +- 理解损失函数 +- 掌握计算 + +## 📚 9.1 匹配文件 + +| 文件 | 作用 | +|------|------| +| [models/matcher.py](../models/matcher.py) | Hungarian 匹配器 | +| [models/clip_matcher.py](../models/clip_matcher.py) | Clip 匹配 | + +## 🔗 9.2 Hungarian 匹配 + +### 作用 +在预测和 GT 之间做二分图匹配。 + +### 匹配成本 +- 分类成本 +- 边界框 L1 成本 +- GIoU 成本 + +## 📉 9.3 损失函数 + +### 损失组成： +1. 分类损失（Focal Loss） +2. 边界框损失（L1 + GIoU） +3. 辅助损失 + +## 📝 本阶段总结 + +你现在应该了解： +1. 匹配机制 +2. 损失组成 +3. 计算流程 + +## 🎯 下一步 + +前往 [阶段 10：工具函数与总结](./10_工具函数与总结.md)。 diff --git "a/tutorials/10_\345\267\245\345\205\267\345\207\275\346\225\260\344\270\216\346\200\273\347\273\223.md" "b/tutorials/10_\345\267\245\345\205\267\345\207\275\346\225\260\344\270\216\346\200\273\347\273\223.md" new file mode 100644 index 0000000..b425770 --- /dev/null +++ "b/tutorials/10_\345\267\245\345\205\267\345\207\275\346\225\260\344\270\216\346\200\273\347\273\223.md" @@ -0,0 +1,53 @@ +# 阶段 10：工具函数与总结 + +## 🎯 学习目标 +- 理解工具函数 +- 项目整体总结 +- 下一步学习 + +## 📚 10.1 工具文件 + +在 [util/](../util/)： + +| 文件 | 作用 | +|------|------| +| [util/misc.py](../util/misc.py) | 杂项（分布式 | +| [util/box_ops.py](../util/box_ops.py) | 边界框操作 | +| [util/checkpoint.py](../util/checkpoint.py) | 检查点 | +| [util/tool.py](../util/tool.py) | 工具 | + +## 📝 10.2 核心工具函数 + +### util/misc.py +- MetricLogger - 指标记录 +- NestedTensor - 嵌套张量 +- 分布式工具函数 + +## 📊 10.3 项目总结 + +### 整体架构回顾 +``` +数据 → 骨干网络 → Transformer → 匹配 → 损失 + ↓ + Query 交互 +``` + +## 📖 10.4 下一步学习建议 + +1. 阅读论文，理解算法细节 +2. 尝试修改超参数，观察效果 +3. 尝试在自己的数据上测试 +4. 深入理解 Transformer +5. 尝试改进或改进 + +## 🎉 恭喜！ + +你已经完成了整个学习路径！ + +现在你应该可以： +- 理解项目架构 +- 读懂核心代码 +- 运行训练和评估 +- 进行简单的修改 + +回头看看 [CODE_WIKI.md](../CODE_WIKI.md) 作为参考手册！