RoRD-Layout-Recognation/docs/data_description.md

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"，值为数组，每个元素代表一个模板实例：

{
  "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 指明每个模板在大图中的左上角坐标和宽高。