finish Experiment Tracking and Evaluation

2025-09-25 21:24:41 +08:00
parent 05ec32bac1
commit 17d3f419f6
9 changed files with 565 additions and 37 deletions
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ IC 版图在匹配时可能出现多种方向（0°、90°、180°、270° 及
 * **训练脚本**：通过**几何感知损失函数**训练模型，学习**几何结构描述子**而非纹理特征，确保对二值化、稀疏性、重复结构的鲁棒性。
 * **评估脚本**：可在验证集上评估模型性能，**专门针对IC版图特征**计算几何一致性指标。
 * **匹配工具**：使用训练好的模型进行**几何结构匹配**，有效区分重复图形并支持多实例检测。
+* **灵活配置与日志**：引入 OmegaConf 驱动的 YAML 配置 (`configs/*.yaml`)，配合 `utils.config_loader` 与 TensorBoard 监控实现参数/路径集中管理。

 ## 🛠️ 安装

@@ -46,20 +47,38 @@ pip install -e .
 ### 📁 项目结构

 ```
-ic_layout_recognition/
+RoRD-Layout-Recognation/
+├── configs/
+│   └── base_config.yaml          # YAML 配置入口
 ├── data/
-│   └── ic_dataset.py
+│   └── ic_dataset.py             # 数据集与数据接口
+├── docs/
+│   ├── data_description.md
+│   ├── feature_work.md
+│   ├── loss_function.md
+│   └── NextStep.md
 ├── models/
-│   └── rord.py
+│   └── rord.py                   # RoRD 模型定义
 ├── utils/
+│   ├── config_loader.py          # YAML 配置加载与路径转换
+│   ├── data_utils.py
 │   └── transforms.py
-├── train.py
-├── evaluate.py
-├── match.py
-├── LICENSE.txt
+├── losses.py                     # 几何感知损失集合
+├── train.py                      # 训练脚本（YAML + TensorBoard）
+├── evaluate.py                   # 评估脚本
+├── match.py                      # 模板匹配脚本
+├── config.py                     # 兼容旧流程的 YAML 读取 shim
+├── pyproject.toml
 └── README.md
 ```

+### 🧩 配置与模块化更新
+
+- **YAML 配置中心**：所有路径与超参数集中存放在 `configs/*.yaml`，通过 `utils.config_loader.load_config` 统一解析；CLI 的 `--config` 参数可切换实验配置，`to_absolute_path` 则保证相对路径相对配置文件解析。
+- **旧配置兼容**：`config.py` 现在仅作为兼容层，将 YAML 配置转换成原有的 Python 常量，便于逐步迁移历史代码。
+- **损失与数据解耦**：`losses.py` 汇总几何感知损失，`data/ic_dataset.py` 与 `utils/data_utils.py` 分离数据准备逻辑，便于扩展新的采样策略或损失项。
+- **日志体系**：`logging` 配置节配合 TensorBoard 集成，`train.py`、`evaluate.py`、`match.py` 可统一写入 `log_dir/子任务/experiment_name`。
+
 ## 🚀 使用方法

 ### 📋 训练准备清单
@@ -77,13 +96,35 @@ ic_layout_recognition/
  ```

 #### 2. 配置文件修改
-编辑 `config.py` 文件，修改以下路径：
-```python
-# 必需修改的路径
-LAYOUT_DIR = '你的布局图像目录路径'        # 训练数据目录
-SAVE_DIR = '你的模型和日志保存路径'        # 输出目录
+项目默认从 `configs/base_config.yaml` 读取训练、评估与日志参数。建议复制该文件并按实验命名，例如：
+
+```bash
+cp configs/base_config.yaml configs/exp_ic_baseline.yaml
 ```

+在 YAML 中修改路径与关键参数：
+
+```yaml
+paths:
+  layout_dir: "数据集/训练图像目录"
+  save_dir: "输出目录（模型与日志）"
+  val_img_dir: "验证集图像目录"
+  val_ann_dir: "验证集标注目录"
+  template_dir: "模板图像目录"
+
+training:
+  num_epochs: 50
+  batch_size: 8
+  learning_rate: 5.0e-5
+
+logging:
+  use_tensorboard: true
+  log_dir: "runs"
+  experiment_name: "baseline"
+```
+
+> 保留 `config.py` 仅用于兼容旧版脚本；新流程全部通过 YAML + `utils.config_loader` 载入配置。
+
 #### 3. 环境检查
 确保已正确安装所有依赖：
 ```bash
@@ -95,17 +136,20 @@ python -c "import cv2; print('OpenCV version:', cv2.__version__)"

 #### 基础训练
 ```bash
-python train.py --data_dir /path/to/your/layouts --save_dir /path/to/your/models
+uv run python train.py --config configs/exp_ic_baseline.yaml
 ```

+上述命令将读取 `configs/exp_ic_baseline.yaml` 中的路径和训练参数；若未指定 `--config`，脚本会回落到 `configs/base_config.yaml`。
+
 #### 自定义训练参数
 ```bash
-python train.py \
-    --data_dir /path/to/your/layouts \
-    --save_dir /path/to/your/models \
-    --epochs 50 \
-    --batch_size 8 \
-    --lr 5e-5
+uv run python train.py \
+  --config configs/exp_ic_baseline.yaml \
+  --data_dir /override/layouts \
+  --save_dir /override/models \
+  --epochs 60 \
+  --batch_size 16 \
+  --lr 1e-4
 ```

 #### 查看所有可用参数
@@ -119,22 +163,56 @@ python train.py --help
 - 最佳模型：`rord_model_best.pth`
 - 最终模型：`rord_model_final.pth`

-### 🚀 快速开始示例
+### <EFBFBD> TensorBoard 实验追踪
+
+`configs/base_config.yaml` 中新增的 `logging` 区块用于控制 TensorBoard：
+
+```yaml
+logging:
+  use_tensorboard: true          # 是否启用 TensorBoard 记录
+  log_dir: "runs"                # 日志根目录（相对/绝对路径均可）
+  experiment_name: "default"    # 实验名称，将作为子目录名
+```
+
+需要临时覆盖时，可在命令行传入参数（以下命令均可用 `uv run` 直接执行）：
+
+```bash
+uv run python train.py --log_dir logs --experiment_name exp001
+uv run python evaluate.py --log_dir logs --experiment_name exp001
+uv run python match.py --tb_log_matches --log_dir logs --experiment_name exp001
+uv run python train.py --disable_tensorboard            # 如需关闭记录
+```
+
+执行训练、评估或模板匹配后，通过下列命令启动 TensorBoard：
+
+```bash
+uv run tensorboard --logdir runs
+```
+
+TensorBoard 中将展示：
+
+- `train.py`：损失、学习率、梯度范数等随时间变化曲线；
+- `evaluate.py`：精确率 / 召回率 / F1 分数；
+- `match.py`（配合 `--tb_log_matches`）：每个匹配实例的内点数量、尺度和总检测数量。
+
+### <20>🚀 快速开始示例
 ```bash
 # 1. 安装依赖
 uv sync

-# 2. 修改配置文件
-# 编辑 config.py 中的 LAYOUT_DIR 和 SAVE_DIR
+# 2. 复制并编辑 YAML 配置
+cp configs/base_config.yaml configs/exp_ic_baseline.yaml
+# 根据数据路径与实验需求调整 paths/training/logging 字段

 # 3. 开始训练
-python train.py --data_dir ./data/layouts --save_dir ./output
+uv run python train.py --config configs/exp_ic_baseline.yaml

 # 4. 使用训练好的模型进行匹配
-python match.py --model_path ./output/rord_model_final.pth \
-                --layout ./test/layout.png \
-                --template ./test/template.png \
-                --output ./result.png
+uv run python match.py --config configs/exp_ic_baseline.yaml \
+                       --model_path ./output/rord_model_final.pth \
+                       --layout ./test/layout.png \
+                       --template ./test/template.png \
+                       --output ./result.png
 ```

 ### 4. 模板匹配