07-数据集格式与导出

# 07 · 数据集格式与导出

本页只描述 GEIMG 输出的数据契约。数据集可以被任意下游程序读取；本 Wiki 不规定 Lua、游戏引擎或控件装配方式。

## 7.1 导出命令

```bash
GE_IMG_Tool.exe export dataset --out "output/demo"
```

当前实现还可能支持以下可选项，使用前以 `GE_IMG_Tool.exe export dataset --help` 为准：

```text
--container <name>
--prefab-id <id>
--asset-id <id>
--budget <n>
--alpha-max <n>
--strategy instantiate|pool
--no-images
```

其中与特定运行时资源绑定的字段属于可选上下文，不是 `shapes.json` 的核心拟合数据。

## 7.2 主要产物

常见数据集包含：

| 文件 | 用途 |
|---|---|
| `shapes.json` | 图元的原始结构化数据，唯一核心真相来源 |
| `manifest.json` | 源图尺寸、拟合参数、版本和输出上下文 |
| `metrics.json` | 误差导航信息、网格统计和最差区域 |
| `shapes.csv` | 便于表格或批处理读取的平面格式 |
| `preview.png` | 重建预览 |
| `preview_overlay.png` | 源图与重建叠加预览（若版本生成） |
| `diff.png` | 差异导航图（若版本生成） |

不要只交付预览图而丢掉 `shapes.json` 和 `manifest.json`；预览不能替代可重建数据。

## 7.3 `shapes.json`

示例：

```json
{
  "format": "geimg-shapes",
  "format_version": 1,
  "space": "source_image_pixels",
  "count": 2,
  "shapes": [
    {"t":"circle", "x":110.193, "y":77.58, "r":26.353, "rgba":[212,211,188,252]},
    {"t":"ellipse", "x":132.98, "y":148.663, "rx":21.347, "ry":21.347, "a":2.351687, "rgba":[210,217,197,252]}
  ]
}
```

| 字段 | 含义 |
|---|---|
| `t` | `circle`、`ellipse` 或 `line` |
| `x`,`y` | 图元中心，使用源图像素 |
| `r` | 圆半径 |
| `rx`,`ry` | 椭圆或线形图元的半轴 |
| `a` | 旋转角，使用弧度 |
| `rgba` | 0~255 的红、绿、蓝和 alpha |

数组顺序就是绘制顺序。解析器不能把半径当直径，也不能把弧度当角度；这三点属于数据不变量。

## 7.4 坐标空间

GEIMG 的拟合坐标使用 `source_image_pixels`：原点通常在源图左上，Y 轴向下。拟合分辨率可以与源图不同，但导出时仍应遵守 manifest 中声明的坐标语义。

下游程序如果要映射到自己的画布，应单独完成坐标转换，并保留原始源图尺寸。不要在 `shapes.json` 中途混入下游坐标。

## 7.5 版本和可复现性

交付数据集时一并保留：

- GEIMG 版本。
- 输入图片尺寸和必要的素材哈希。
- 拟合模式、开关和主要参数。
- 目标图元数和最终图元数。
- 视觉验收备注。

`metrics.json` 中的数值用于导航和复查，不等于跨版本可比较的质量分数。