From 370cf07b7c5500c30c43f877e269d235fef87dfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=84=A6=E4=B8=83=E4=B8=83?=
 <137185356+Jiao-77@users.noreply.github.com>
Date: Mon, 21 Jul 2025 17:01:18 +0800
Subject: [PATCH] Create data_description.md

---
 docs/data_description.md | 100 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 docs/data_description.md

diff --git a/docs/data_description.md b/docs/data_description.md
new file mode 100644
index 0000000..1cd4311
--- /dev/null
+++ b/docs/data_description.md
@@ -0,0 +1,100 @@
+RoRD 模型 ‑ 完整数据说明  
+版本：v1.0（仅针对仓库实际代码，不含 README 抽象描述）
+
+────────────────────────────────────  
+一、数据类型总览  
+
+| 阶段 | 需要数据 | 目录示例 | 是否必须 | 说明 |
+|---|---|---|---|---|
+| 训练 | 布局图像（PNG） | `train/layouts/*.png` | ✅ | 仅图像，无标注 |
+| 验证 / 测试 | 验证图像（PNG） | `val/images/*.png` | ✅ | 大图 |
+|  | 模板图像（PNG） | `val/templates/*.png` | ✅ | 小图 |
+|  | 标注 JSON | `val/annotations/*.json` | ✅ | 每张验证图一份 |
+
+────────────────────────────────────  
+二、文件格式与内容  
+
+1. 布局 / 验证 / 模板图像  
+   • 后缀：`.png`  
+   • 通道：单通道或三通道皆可（代码内部转为灰度）  
+   • 颜色：二值化黑白最优；灰度亦可  
+   • 分辨率：任意，推荐 1024×1024 以上保证细节  
+   • 命名：无限制，保持唯一即可  
+
+2. 标注 JSON（与每张验证图像同名）  
+   文件路径：`val/annotations/{image_basename}.json`  
+   根对象仅含一个键 `"boxes"`，值为数组，每个元素代表一个模板实例：
+
+```json
+{
+  "boxes": [
+    {
+      "template": "nmos_stdcell.png",
+      "x": 128,
+      "y": 256,
+      "width": 64,
+      "height": 32
+    },
+    {
+      "template": "pmos_stdcell.png",
+      "x": 300,
+      "y": 120,
+      "width": 64,
+      "height": 32
+    }
+  ]
+}
+```
+
+字段含义  
+| 字段 | 类型 | 取值范围 | 描述 |
+|---|---|---|---|
+| template | string | 必须与 `val/templates` 中某文件名完全一致 | 对应模板图像 |
+| x | int | ≥ 0 | 模板左上角在大图中的列坐标（像素），原点在左上角 |
+| y | int | ≥ 0 | 模板左上角在大图中的行坐标（像素） |
+| width | int | > 0 | 模板在大图中的宽度（像素），一般等于模板图像实际宽度 |
+| height | int | > 0 | 模板在大图中的高度（像素） |
+
+────────────────────────────────────  
+三、目录结构示范  
+
+project_root/  
+├── train/  
+│   └── layouts/  
+│       ├── chipA.png  
+│       ├── chipB.png  
+│       └── …  
+├── val/  
+│   ├── images/  
+│   │   ├── chip1.png  
+│   │   └── chip2.png  
+│   ├── templates/  
+│   │   ├── nmos_stdcell.png  
+│   │   └── pmos_stdcell.png  
+│   └── annotations/  
+│       ├── chip1.json  
+│       └── chip2.json  
+
+────────────────────────────────────  
+四、常见问题速查  
+
+1. 训练时是否需要 JSON？  
+   → 不需要。训练阶段仅读取 `train/layouts/*.png`，内部自动生成旋转/镜像自监督对。  
+
+2. JSON 中可以多写字段吗？  
+   → 可以，但评估脚本只解析 `"boxes"` 及 5 个必要子字段，其余忽略。  
+
+3. 坐标超出图像边界会怎样？  
+   → 代码未做强制裁剪，需自行保证 `x+width ≤ image_width` 且 `y+height ≤ image_height`，否则评估阶段 IoU 计算会出错。  
+
+4. 模板尺寸必须固定吗？  
+   → 不必。不同模板宽高可不同，只要在 JSON 中写对实际值即可。  
+
+5. 一个模板可在同一张图中出现多次吗？  
+   → 可以，在 `"boxes"` 数组中添加多条记录即可。  
+
+────────────────────────────────────  
+五、一句话总结  
+
+训练：给模型一堆版图 PNG；  
+验证 / 测试：给模型大图 + 小模板 + JSON 指明每个模板在大图中的左上角坐标和宽高。