add some functions.

docs/NextStep.md

@@ -1,257 +1,173 @@
-# 本地 TensorBoard 实验追踪方案
+# 下一步工作计划 (NextStep)
 
-日期：2025-09-25
+**最后更新**: 2025-10-20  
+**范围**: 仅聚焦于 `feature_work.md` 的第二部分「模型架构 (Model Architecture)」的落地执行计划  
+**上下文**: 核心功能已完成，本文档将模型架构优化转化为可执行的工程计划，便于直接实施与验收。
 
-## 目标
-- 在本地工作站搭建一套轻量、低成本的实验追踪与可视化管道，覆盖训练、评估和模板匹配流程。
-- 结合现有 YAML 配置体系，为后续扩展（自动化调参、远程同步）保留接口。
-
-## 环境与前置准备
-1. **系统与软件**
-   - 操作系统：Ubuntu 22.04 / Windows 11 / macOS 14（任选其一）。
-   - Python 环境：使用项目默认的 `uv` 虚拟环境（见 `uv.lock` / `pyproject.toml`）。
-2. **依赖安装**
-   ```bash
-   uv add tensorboard tensorboardX
-   ```
-3. **目录规划**
-   - 在项目根目录创建 `runs/`，建议按 `runs/<experiment_name>/` 组织日志。
-   - 训练与评估可分别输出到 `runs/train/`、`runs/eval/` 子目录。
-
-## 集成步骤
-### 1. 配置项扩展
-- 在 `configs/base_config.yaml` 中添加：
-  ```yaml
-  logging:
-    use_tensorboard: true
-    log_dir: "runs"
-    experiment_name: "baseline"
-  ```
-- 命令行新增 `--log-dir`、`--experiment-name` 参数，默认读取配置，可在执行时覆盖。
-
-### 2. 训练脚本 `train.py`
-1. **初始化 SummaryWriter**
-   ```python
-   from torch.utils.tensorboard import SummaryWriter
-
-   log_dir = Path(args.log_dir or cfg.logging.log_dir)
-   experiment = args.experiment_name or cfg.logging.experiment_name
-   writer = SummaryWriter(log_dir=log_dir / "train" / experiment)
-   ```
-2. **记录训练指标**（每个 iteration）
-   ```python
-   global_step = epoch * len(train_dataloader) + i
-   writer.add_scalar("loss/total", loss.item(), global_step)
-   writer.add_scalar("loss/det", det_loss.item(), global_step)
-   writer.add_scalar("loss/desc", desc_loss.item(), global_step)
-   writer.add_scalar("optimizer/lr", scheduler.optimizer.param_groups[0]['lr'], global_step)
-   ```
-3. **验证阶段记录**
-   - Epoch 结束后写入平均损失、F1 等指标。
-   - 可视化关键点热力图、匹配示意图：`writer.add_image()`。
-4. **资源清理**
-   - 训练结束调用 `writer.close()`。
-
-### 3. 评估脚本 `evaluate.py`
-1. 初始化 `SummaryWriter(log_dir / "eval" / experiment)`。
-2. 收集所有验证样本的预测框 (boxes)、置信度 (scores) 与真实标注 (ground truth boxes)。
-3. 使用 `sklearn.metrics.average_precision_score` 或 `pycocotools` 计算每个样本的 Average Precision，并汇总为 mAP：
-   ```python
-   from sklearn.metrics import average_precision_score
-   ap = average_precision_score(y_true, y_scores)
-   writer.add_scalar("eval/AP", ap, global_step)
-   ```
-4. 在成功匹配（IoU ≥ 阈值）后，从 `match_template_multiscale` 返回值中获取单应矩阵 `H`。
-5. 使用 `cv2.decomposeHomographyMat` 或手动分解方法，将 `H` 提取为旋转角度、平移向量和缩放因子：
-   ```python
-   _, Rs, Ts, Ns = cv2.decomposeHomographyMat(H, np.eye(3))
-   rot_angle = compute_angle(Rs[0])
-   trans_vec = Ts[0]
-   scale = np.linalg.norm(Ns[0])
-   ```
-6. 从标注文件中读取真实几何变换参数 (rotation_gt, trans_gt, scale_gt)，计算误差：
-   ```python
-   err_rot = abs(rot_angle - rotation_gt)
-   err_trans = np.linalg.norm(trans_vec - trans_gt)
-   err_scale = abs(scale - scale_gt)
-   writer.add_scalar("eval/err_rot", err_rot, img_id)
-   writer.add_scalar("eval/err_trans", err_trans, img_id)
-   writer.add_scalar("eval/err_scale", err_scale, img_id)
-   ```
-7. 使用 `writer.add_histogram` 记录误差分布，并通过 `writer.add_image` 可选地上传误差直方图：
-   ```python
-   writer.add_histogram("eval/err_rot_hist", err_rot_list, epoch)
-   ```
-8. 在 TensorBoard 的 Scalars、Histograms 和 Images 面板中分别查看指标曲线、误差分布及可视化结果。
-
-### 4. 模板匹配调试 `match.py`
-- 新增参数 `--tb-log-matches`（布尔值）。
-- 启用后，将关键点分布、Homography 误差统计写入 `runs/match/<experiment>/`。
-
-## 可视化与使用
-1. **启动 TensorBoard**
-   ```bash
-   tensorboard --logdir runs --port 6006
-   ```
-   - 浏览器访问 `http://localhost:6006`。
-   - 若需局域网共享可加 `--bind_all`。
-2. **推荐面板布局**
-   - Scalars：损失曲线、学习率、评估指标。
-   - Images：关键点热力图、模板匹配结果。
-   - Histograms：描述子分布、梯度范数（可选）。
-   - Text：记录配置摘要、Git 提交信息。
-
-## 版本控制与组织
-- 实验命名建议采用 `YYYYMMDD_project_variant`，方便检索。
-- 使用 `writer.add_text()` 保存关键配置和 CLI 参数，形成自描述日志。
-- 可开发 `tools/export_tb_summary.py` 导出曲线数据供文档或汇报使用。
-
-## 进阶扩展
-1. **自动化脚本**：在 `Makefile` / `tasks.json` 中增加命令，一键启动训练 + TensorBoard。
-2. **远程访问**：通过 `ssh -L` 或 `ngrok` 转发端口，注意访问权限控制。
-3. **对比实验**：利用 TensorBoard `Compare Runs` 功能或统一父目录对比多次实验。
-4. **CI 集成**：在持续集成流程中生成日志，作为构建工件保存。
-
-## 验证与维护
-- **功能自测**：运行 1–2 个 epoch，确认日志生成并正确展示。
-- **存储监控**：定期清理或压缩旧实验，避免磁盘占满。
-- **备份策略**：重要实验可打包日志或同步至远程仓库。
-- **团队培训**：在 README 中补充使用说明，组织示例演示。
-
-## 下一步
-- [ ] 修改配置和脚本，接入 SummaryWriter。
-- [ ] 准备示例 Notebook/文档，展示 TensorBoard 面板截图。
-- [ ] 后续评估是否需要接入 W&B、MLflow 等更高级平台。
+> 参考来源：`docs/feature_work.md` 第二部分；更宏观的阶段规划见 `docs/todos/`
 
 ---
 
-# 推理与匹配改造计划（FPN + NMS）
+## 🔴 模型架构优化（Feature Work 第二部分）
 
-日期：2025-09-25
+目标：在保证现有精度的前提下，提升特征提取效率与推理速度；为后续注意力机制与多尺度策略提供更强的特征基础。
 
-## 目标
-- 将当前的“图像金字塔 + 多次推理”的匹配流程，升级为“单次推理 + 特征金字塔 (FPN)”以显著提速。
-- 在滑动窗口提取关键点后增加去重（NMS/半径抑制），降低冗余点与后续 RANSAC 的计算量。
-- 保持与现有 YAML 配置、TensorBoard 记录和命令行接口的一致性；以 uv 为包管理器管理依赖和运行。
+### 总体验收标准（全局）
+- [ ] 训练/验证流程在新骨干和注意力方案下均可跑通，无崩溃/NaN。
+- [ ] 在代表性验证集上，最终指标（IoU/mAP）不低于当前 VGG-16 基线；若下降需给出改进措施或回滚建议。
+- [ ] 推理时延或显存占用至少一种维度优于基线，或达到“相当 + 结构可扩展”的工程收益。
+- [ ] 关键改动均通过配置开关控制，可随时回退。
 
-## 设计概览
-- FPN：在 `models/rord.py` 中，从骨干网络多层提取特征（例如 VGG 的 relu2_2/relu3_3/relu4_3），通过横向 1x1 卷积与自顶向下上采样构建 P2/P3/P4 金字塔特征；为每个尺度共享或独立地接上检测头与描述子头，导出同维度描述子。
-- 匹配路径：`match.py` 新增 FPN 路径，单次前向获得多尺度特征，逐层与模板进行匹配与几何验证；保留旧路径（图像金字塔）作为回退，通过配置开关切换。
-- 去重策略：在滑窗聚合关键点后，基于“分数优先 + 半径抑制 (radius NMS)”进行去重；半径和分数阈值配置化。
+---
 
-## 配置变更（YAML）
-在 `configs/base_config.yaml` 中新增/扩展：
+## 2.1 实验更现代的骨干网络（Backbone）
+
+优先级：🟠 中  |  预计工期：~1 周  |  产出：可切换的 backbone 实现 + 对照报告
+
+### 设计要点（小合约）
+- 输入：与现有 `RoRD` 一致的图像张量 B×C×H×W。
+- 输出：供检测头/描述子头使用的中高层特征张量；通道数因骨干不同而异（VGG:512、ResNet34:512、Eff-B0:1280）。
+- 约束：不改变下游头部的接口形状（头部输入通道需根据骨干进行对齐适配）。
+- 失败模式：通道不匹配/梯度不通/预训练权重未正确加载/收敛缓慢。
+
+### 配置扩展（YAML）
+在 `configs/base_config.yaml` 增加（或确认存在）：
 
 ```yaml
 model:
-   fpn:
-      enabled: true            # 开启 FPN 推理
-      out_channels: 256        # 金字塔特征通道数
-      levels: [2, 3, 4]        # 输出层级，对应 P2/P3/P4
-      norm: "bn"              # 归一化类型：bn/gn/none
-
-matching:
-   use_fpn: true              # 使用 FPN 路径；false 则沿用图像金字塔
-   nms:
-      enabled: true
-      radius: 4                # 半径抑制像素半径
-      score_threshold: 0.5     # 关键点保留的最低分数
-   # 其余已有参数保留，如 ransac_reproj_threshold/min_inliers/inference_window_size...
+	backbone:
+		name: "vgg16"   # 可选：vgg16 | resnet34 | efficientnet_b0
+		pretrained: true
+		# 用于选择抽取的特征层（按不同骨干约定名称）
+		feature_layers:
+			vgg16: ["relu3_3", "relu4_3"]
+			resnet34: ["layer3", "layer4"]
+			efficientnet_b0: ["features_5", "features_7"]
 ```
 
-注意：所有相对路径依旧使用 `utils.config_loader.to_absolute_path` 以配置文件所在目录为基准解析。
+### 代码改动建议
+- 文件：`models/rord.py`
+	1) 在 `__init__` 中根据 `cfg.model.backbone.name` 动态构建骨干：
+		 - vgg16（现状保持）
+		 - resnet34：从 `torchvision.models.resnet34(weights=IMAGENET1K_V1)` 构建；保存 `layer3/layer4` 输出。
+		 - efficientnet_b0：从 `torchvision.models.efficientnet_b0(weights=IMAGENET1K_V1)` 构建；保存末两段 `features` 输出。
+	2) 为不同骨干提供统一的“中间层特征导出”接口（注册 forward hook 或显式调用子模块）。
+	3) 依据所选骨干的输出通道，调整检测头与描述子头的输入通道（如使用 1×1 conv 过渡层以解耦通道差异）。
+	4) 保持现有前向签名与返回数据结构不变（训练/推理兼容）。
 
-## 实施步骤
+### 进展更新（2025-10-20）
+- 已完成：在 `models/rord.py` 集成多骨干选择（`vgg16`/`resnet34`/`efficientnet_b0`），并实现统一的中间层抽取函数 `_extract_c234`（可后续重构为 `build_backbone`/`extract_features` 明确接口）。
+- 已完成：FPN 通用化，基于 C2/C3/C4 构建 P2/P3/P4，按骨干返回正确的 stride。
+- 已完成：单图前向 Smoke Test（三种骨干，单尺度与 FPN）均通过。
+- 已完成：CPU 环境 A/B 基准（单尺度 vs FPN）见 `docs/description/Performance_Benchmark.md`。
+- 待完成：GPU 环境基准（速度/显存）、基于真实数据的精度评估与收敛曲线对比。
 
-1) 基线分支与依赖
-- 新开分支保存改造：
-   ```bash
-   git checkout -b feature/fpn-matching
-   uv sync
-   ```
-- 目前不引入新三方库，继续使用现有 `torch/opencv/numpy`。
+### 落地步骤（Checklist）
+- [x] 在 `models/rord.py` 增加/落地骨干构建与中间层抽取逻辑（当前通过 `_extract_c234` 实现）。
+- [x] 接入 ResNet-34：返回等价中高层特征（layer2/3/4，通道≈128/256/512）。
+- [x] 接入 EfficientNet-B0：返回 `features[2]/[3]/[6]`（约 24/40/192），FPN 以 1×1 横向连接对齐到 `fpn_out_channels`。
+- [x] 头部适配：单尺度头使用骨干高层通道数；FPN 头统一使用 `fpn_out_channels`。
+- [ ] 预训练权重：支持 `pretrained=true` 加载；补充权重加载摘要打印（哪些层未命中）。
+- [x] 单图 smoke test：前向通过、无 NaN（三种骨干，单尺度与 FPN）。
 
-2) 模型侧改造（`models/rord.py`）
-- 提取多层特征：在骨干网络中暴露中间层输出（如 C2/C3/C4）。
-- 构建 FPN：
-   - 使用 1x1 conv 降维对齐通道；
-   - 自顶向下上采样并逐级相加；
-   - 3x3 conv 平滑，得到 P2/P3/P4；
-   - 可选归一化（BN/GN）。
-- 头部适配：复用或复制现有检测头/描述子头到每个 P 层，输出：
-   - det_scores[L]：B×1×H_L×W_L
-   - descriptors[L]：B×D×H_L×W_L（D 与现有描述子维度一致）
-- 前向接口：
-   - 训练模式：维持现有输出以兼容训练；
-   - 匹配/评估模式：支持 `return_pyramid=True` 返回 {P2,P3,P4} 的 det/desc。
+### 评测与选择（A/B 实验）
+- [ ] 在固定数据与超参下，比较 vgg16/resnet34/efficientnet_b0：
+	- 收敛速度（loss 曲线 0-5 epoch）
+	- 推理速度（ms / 2048×2048）与显存（GB）[CPU 初步结果已产出，GPU 待复测；见 `docs/description/Performance_Benchmark.md`]
+	- 验证集 IoU/mAP（真实数据集待跑）
+- [ ] 形成表格与可视化图，给出选择结论与原因（CPU 版初稿已在报告中给出观察）。
+- [ ] 若新骨干在任一关键指标明显受损，则暂缓替换，仅保留为可切换实验选项。
 
-3) 匹配侧改造（`match.py`）
-- 配置读取：根据 `matching.use_fpn` 决定走 FPN 或旧图像金字塔路径。
-- FPN 路径：
-   - 对 layout 与 template 各做一次前向，获得 {det, desc}×L；
-   - 对每个层级 L：
-      - 从 det_scores[L] 以 `score_threshold` 抽取关键点坐标与分数；
-      - 半径 NMS 去重（见步骤 4）；
-      - 使用 desc[L] 在对应层做特征最近邻匹配（可选比值测试）并估计单应性 H_L（RANSAC）；
-   - 融合多个层级的候选：选取内点数最多或综合打分最佳的实例；
-   - 将层级坐标映射回原图坐标；输出 bbox 与 H。
-- 旧路径保留：若 `use_fpn=false`，继续使用当前图像金字塔多次推理策略，便于回退与对照实验。
+### 验收标准（2.1）
+- [ ] 三种骨干方案均可训练与推理（当前仅验证推理，训练与收敛待验证）；
+- [ ] 最终入选骨干在 IoU/mAP 不低于 VGG 的前提下，带来显著的速度/显存优势之一；
+- [x] 切换完全配置化（无需改代码）。
 
-4) 关键点去重（NMS/半径抑制）
-- 输入：关键点集合 K = {(x, y, score)}。
-- 算法：按 score 降序遍历，若与已保留点的欧氏距离 < radius 则丢弃，否则保留。
-- 复杂度：O(N log N) 排序 + O(N·k) 检查（k 为邻域个数，可通过网格划分加速）。
-- 参数：`matching.nms.radius`、`matching.nms.score_threshold`。
+### 风险与回滚（2.1）
+- 通道不匹配导致维度错误 → 在进入头部前统一使用 1×1 conv 适配；
+- 预训练权重与自定义层名不一致 → 显式映射并记录未加载层；
+- 收敛变慢 → 暂时提高训练轮数、调学习率/BN 冻结策略；不达标即回滚 `backbone.name=vgg16`。
 
-5) TensorBoard 记录（扩展）
-- Scalars：
-   - `match_fpn/level_L/keypoints_before_nms`、`keypoints_after_nms`
-   - `match_fpn/level_L/inliers`、`best_instance_inliers`
-   - `match_fpn/instances_found`、`runtime_ms`
-- Text/Image：
-   - 关键点可视化（可选），最佳实例覆盖图；
-   - 记录使用的层级与最终选中尺度信息。
+---
 
-6) 兼容性与回退
-- 通过 YAML `matching.use_fpn` 开关控制路径；
-- 保持 CLI 不变，新增可选 `--fpn-off`（等同 use_fpn=false）仅作为临时调试；
-- 若新路径异常可快速回退旧路径，保证生产可用性。
+## 2.2 集成注意力机制（CBAM / SE-Net）
 
-## 开发里程碑与工时预估
-- M1（0.5 天）：配置与分支、占位接口、日志钩子。
-- M2（1.5 天）：FPN 实现与前向接口；单图 smoke 测试。
-- M3（1 天）：`match.py` FPN 路径、尺度回映射与候选融合。
-- M4（0.5 天）：NMS 实现与参数打通；
-- M5（0.5 天）：TensorBoard 指标与可视化；
-- M6（0.5 天）：对照基线的性能与速度评估，整理报告。
+优先级：🟠 中  |  预计工期：~7–10 天  |  产出：注意力增强的 RoRD 变体 + 对照报告
 
-## 质量门禁与验收标准
-- 构建：`uv sync` 无错误；`python -m compileall` 通过；
-- 功能：在 2–3 张样例上，FPN 路径输出的实例数量与旧路径相当或更优；
-- 速度：相同输入，FPN 路径总耗时较旧路径下降 ≥ 30%；
-- 稳定性：无异常崩溃；在找不到匹配时能优雅返回空结果；
-- 指标：TensorBoard 中关键点数量、NMS 前后对比、内点数、总实例数与运行时均可见。
+### 模块选择与嵌入位置
+- 方案 A：CBAM（通道注意 + 空间注意），插入至骨干高层与两类头部之前；
+- 方案 B：SE-Net（通道注意），轻量但仅通道维，插入多个阶段以增强稳定性；
+- 建议：先实现 CBAM，保留 SE 作为备选开关。
 
-## 快速试用（命令）
-```bash
-# 同步环境
-uv sync
-
-# 基于 YAML 启用 FPN 匹配（推荐）
-uv run python match.py \
-   --config configs/base_config.yaml \
-   --layout /path/to/layout.png \
-   --template /path/to/template.png \
-   --tb_log_matches
-
-# 临时关闭 FPN（对照实验）
-# 可通过把 configs 中 matching.use_fpn 设为 false，或后续提供 --fpn-off 开关
-
-# 打开 TensorBoard 查看匹配指标
-uv run tensorboard --logdir runs
+### 配置扩展（YAML）
+```yaml
+model:
+	attention:
+		enabled: true
+		type: "cbam"   # 可选：cbam | se | none
+		places: ["backbone_high", "det_head", "desc_head"]
+		# 可选超参：reduction、kernel_size 等
+		reduction: 16
+		spatial_kernel: 7
 ```
 
-## 风险与回滚
-- FPN 输出与原检测/描述子头的维度/分布不一致，需在实现时对齐通道与归一化；
-- 多层融合策略（如何选取最佳实例）可能影响稳定性，可先以“内点数最大”作为启发式；
-- 如出现精度下降或不稳定，立即回退 `matching.use_fpn=false`，保留旧流程并开启数据记录比对差异。
+### 代码改动建议
+- 文件：`models/rord.py`
+	1) 实现 `CBAM` 与 `SEBlock` 模块（或从可靠实现迁移），提供简洁 forward。
+	2) 在 `__init__` 中依据 `cfg.model.attention` 决定在何处插入：
+		 - backbone 高层输出后（增强高层语义的判别性）；
+		 - 检测头、描述子头输入前（分别强化不同任务所需特征）。
+	3) 注意保持张量尺寸不变；若引入残差结构，保证与原路径等价时可退化为恒等映射。
+
+### 落地步骤（Checklist）
+- [ ] 实现 `CBAM`：通道注意（MLP/Avg+Max Pool）+ 空间注意（7×7 conv）。
+- [ ] 实现 `SEBlock`：Squeeze（全局池化）+ Excitation（MLP, reduction）。
+- [ ] 在 `RoRD` 中用配置化开关插拔注意力，默认关闭。
+- [ ] 在进入检测/描述子头前分别测试开启/关闭注意力的影响。
+- [ ] 记录注意力图（可选）：导出中间注意图用于可视化对比。
+
+### 训练与评估
+- [ ] 以入选骨干为基线，分别开启 `cbam` 与 `se` 进行对照；
+- [ ] 记录：训练损失、验证 IoU/mAP、推理时延/显存；
+- [ ] 观察注意力图是否集中在关键几何（边角/交点/突变）；
+- [ ] 若带来过拟合迹象（验证下降），尝试减弱注意力强度或减少插入位置。
+
+### 验收标准（2.2）
+- [ ] 模型在开启注意力后稳定训练，无数值异常；
+- [ ] 指标不低于无注意力基线；若提升则量化收益；
+- [ ] 配置可一键关闭以回退。
+
+### 风险与回滚（2.2）
+- 注意力导致过拟合或梯度不稳 → 降低 reduction、减少插入点、启用正则；
+- 推理时延上升明显 → 对注意力路径进行轻量化（如仅通道注意或更小 kernel）。
+
+---
+
+## 工程与度量配套
+
+### 实验记录（建议）
+- 在 TensorBoard 中新增：
+	- `arch/backbone_name`、`arch/attention_type`（Text/Scalar）；
+	- `train/loss_total`、`eval/iou_metric`、`eval/map`；
+	- 推理指标：`infer/ms_per_image`、`infer/vram_gb`。
+
+### 对照报告模板（最小集）
+- 数据集与配置摘要（随机种子、批大小、学习率、图像尺寸）。
+- 三个骨干 + 注意力开关的结果表（速度/显存/IoU/mAP）。
+- 结论与落地选择（保留/关闭/待进一步实验）。
+
+---
+
+## 排期与里程碑（建议）
+- M1（1 天）：骨干切换基础设施与通道适配层；单图 smoke 测试。
+- M2（2–3 天）：ResNet34 与 EfficientNet-B0 接入与跑通；
+- M3（1–2 天）：A/B 评测与结论；
+- M4（3–4 天）：注意力模块接入、训练对照、报告输出。
+
+---
+
+## 相关参考
+- 源文档：`docs/feature_work.md` 第二部分（模型架构）
+- 阶段规划：`docs/todos/`
+- 配置系统：`configs/base_config.yaml`
+