🧪 Omega Test 文档

核心目标：通过 CityEngine 导出的 OBJ 生成黄金标准 JSON，精确对比 CGA.js 引擎与 CityEngine 的函数解析精度。本文档是 Omega 测试体系的唯一权威来源，配置维度调整将在此同步更新。

1. 概述

Omega Test 是 CGA.js 引擎的黄金标准对比测试框架。它的工作原理是：

1. 在 CityEngine 中应用一个 CGA 规则（如 extrude(10)）到标准 footprint
2. 导出最终 3D 模型为 Wavefront OBJ 格式
3. 通过 Omega 工具上传 OBJ，填写完整的元数据
4. 自动生成包含几何数据、Scope、对比策略的黄金标准 JSON
5. 将 JSON 放入测试套件，对比 CGA.js 引擎的输出

1.1 测试基础设施

1.2 架构级修补（8 项核心基础设施）

2. 黄金标准 JSON 结构

Omega 工具生成的 JSON 包含 5 个顶级字段：

{
  "_meta":       { ... },   // 测试元数据（函数、参数、版本、运行环境、对比策略）
  "cga":        "Lot --> extrude(10)",  // CGA 规则源码
  "input":      { ... },   // 初始 Shape（vertices + faces + scope + pivot）
  "expected":   { ... },   // CityEngine 输出的几何数据
  "notes":      { ... }    // 关键检查项、CE 行为说明、边界标签
}

2.1 _meta — 测试元数据

2.2 input — 初始 Shape

"input": {
  "vertices": [
    {"x": 0, "y": 0, "z": 0},
    {"x": 10, "y": 0, "z": 0},
    {"x": 10, "y": 0, "z": 10},
    {"x": 0, "y": 0, "z": 10}
  ],
  "faces": [
    {"indices": [0,1,2,3], "normal": {"x":0,"y":1,"z":0}}
  ],
  "scope": {"sx":10, "sy":0, "sz":10,
            "tx":0, "ty":0, "tz":0,
            "rx":0, "ry":0, "rz":0},
  "pivot": {"x":0, "y":0, "z":0}
}

2.3 expected — CityEngine 输出

"expected": {
  "vertex_count": 24,
  "face_count": 10,
  "vertices": [[0,0,0], [10,0,0,] ...],
  "faces": [[0,1,2], [0,2,3], ...],
  "bbox": {
    "min": {"x": 0, "y": 0, "z": 0},
    "max": {"x": 10, "y": 10, "z": 10}
  },
  "scope": {"sx":10, "sy":10, "sz":10},
  "metadata": {
    "polygonCount": 1,
    "vertexCount": 24,
    "faceCount": 10,
    "area": 100,
    "volume": 1000,
    "height": 10,
    "boundaryLength": 40
  }
}

2.4 notes — 测试备注

"notes": {
  "critical_checks": [
    "顶点数应为8（4底+4顶）",
    "面数应为6（4侧+顶+底）",
    "顶面法向必须向上(0,1,0)"
  ],
  "obj_precision_warning": "顶点坐标精度受限于OBJ格式（6位小数），对比时使用 epsilon=1e-4",
  "cityengine_behavior": {
    "overhang": 0.5,
    "miter_limit": 0.3,
    "known_cityengine_behavior": "CityEngine在L形凹角处会生成内部脊线",
    "cgajs_approximation": "当前为简化实现，未处理凹角缝合",
    "boundary_tags": ["extreme_ratio"]
  }
}

3. 配置维度总览

Omega 工具从几何、运行环境、对比策略、CityEngine 特殊行为四个维度采集 20+ 个配置项。精确填写这些字段是测试可信度的关键。

3.1 基础元数据

3.2 初始 Scope 配置（⚙️ 高级）

为什么重要？ 很多引擎实现只测试了轴对齐、无旋转、原点的 trivial 情况。实际 CityEngine 中 footprint 可能是旋转过的，如果引擎内部错误地使用了世界坐标而非局部 Scope 坐标，结果会完全不同。

3.3 运行环境（🔧 高级）

3.4 对比策略（📏 高级）

这是避免"假阳性"失败的关键。 如果强制所有函数都用 vertex_exact + epsilon=1e-4，roof 系列几乎不可能通过（CityEngine 的三角化策略和我们不同）。分层对比策略是"精准测试"的核心。

3.5 CityEngine 特殊行为（🏗️ 高级）

3.6 边界条件标签

setback 在退台距离大于 footprint 尺寸时，CityEngine 会退化为一条线而不是崩溃。记录这些边界行为，才能确保我们的引擎也优雅降级而不是抛异常。

4. CityEngine OBJ 导出设置详细指南

OBJ 是 Omega 测试的唯一输入格式。正确的导出设置直接决定黄金标准 JSON 的质量和对比可信度。

核心原则：一个 OBJ = 一个函数 + 一个输入 Shape 的最终结果。不要在一个 OBJ 中包含多个模型或多个生成阶段的几何。

4.1 导出前准备

1. 在 CityEngine 中写好最小 CGA 规则，确保只调用一个目标函数（如 extrude(10)）
2. 选中场景中的初始 Shape（footprint），应用规则（Generate）
3. 在 Scene 窗口中，只选中最终生成的 3D 模型（不要选中初始 footprint）
4. 菜单栏 → File → Export Models...

4.2 基础设置（General）

4.3 几何设置（Geometry）

4.4 法线与 UV（Normals & Texture Coordinates）

4.5 材质（Materials）

4.6 三角化策略（最关键）

这是最容易导致面数不一致的问题。CityEngine 对某些面保持四边形，对其他面自动三角化。我们的解析器支持多边形（face indices > 3），但对比时的 faceCount 必须严格一致。

验证方法：导出后打开 OBJ 文件，检查 f 行。如果每行有 3 个索引（如 f 1 2 3），说明是三角化；如果有 4 个（如 f 1 2 3 4），是四边形。我们的解析器两者都支持。

4.7 导出后验证清单

导出完成后，在文本编辑器中打开 OBJ 文件，确认以下结构存在：

# 顶点坐标（至少3列，X Y Z）
v 0.000000 0.000000 0.000000
v 10.000000 0.000000 0.000000
v 10.000000 0.000000 10.000000
v 0.000000 0.000000 10.000000

# 法线（如果勾选了导出法线）
vn 0.000000 1.000000 0.000000

# 面索引（1-based，我们的解析器会自动转为 0-based）
# 四边形格式
f 1 2 3 4
# 或三角化格式
f 1 2 3
f 1 3 4

常见问题排查

4.8 与 Omega.html 的字段映射

5. 函数推荐配置速查表

当您为具体函数创建黄金标准时，可直接套用下表的推荐配置：

6. 完整测试流程

1. 编写最小 CGA 规则
   只包含一个目标函数，例如：
   Lot --> extrude(10) 或 Lot --> roofHip(30, 0.5)
2. 选择或创建标准 footprint
   在 CityEngine 中选中初始 Shape → Generate。
   如果 footprint 不在 6 种预设内，可在 Omega 工具中手动填写 vertices + faces。
3. 选中最终模型并导出
   Scene 窗口中只选中最终 3D 模型（高亮状态）。
   File → Export Models → Wavefront OBJ，按 §4 设置参数。
4. 命名文件
   {函数}_{参数}_{形状}.obj，例：roofHip_30_Lshape.obj
5. 快速验证 OBJ 内容
   文本编辑器打开，确认有 v、f 行，且 f 的索引数量符合三角化策略。
6. 上传 Omega 工具并填写元数据
   访问 /omega.html，拖拽上传 OBJ。
   按 §3 精确填写所有配置维度。
7. 生成并下载 JSON
   点击"开始转换"，验证 JSON 内容完整后下载。
   文件名自动为：{函数名}_{OBJ文件名}.json
8. 放入测试套件
   将 JSON 放入 /omega-test/cases/tier_s/ 目录，编写对应的 .test.ts 用例。
9. 运行对比测试
   cd /omega-test && npm test。观察是否通过，根据 errors/warnings 修复引擎。
10. 记录已知差异
    如果 CityEngine 行为与引擎输出有预期内的差异（如三角化策略不同），在 notes.cityengine_behavior 中记录，并调整 comparison.ignore 或 comparison.mode。

6.1 批量上传与服务器自动保存

从 v3.2 开始，Omega 工具支持一次上传多个 OBJ，并按以下流程自动处理：

1. 自动生成批次 ID
   页面加载时会生成唯一的 batch_id（如 omega-1718371200000-a1b2c3），同一批上传的所有文件共享该 ID。
2. 文件名自动解析
   系统按 function_param1_param2_inputshape.obj 解析函数名、参数与输入形状，并自动套用对应的标准 footprint。
3. 服务器保存成功 case
   每个成功的转换结果都会保存到服务器：
   /www/wwwroot/cgajs-engine/tests/golden/omega-uploads/<batch_id>/<case_id>/golden.json
4. 生成失败报告
   同一目录下的 report.json 记录该批次所有文件的状态与错误信息。
5. 一键复制失败列表
   转换完成后，结果区会显示“复制批次 ID”和“复制失败列表”按钮，直接贴给 AI 即可开始修复。

AI 修复流程：上传完成后我不会自动修复引擎。请在结果区复制“失败列表”或“批次 ID”发给我；我可以直接读取服务器上的 report.json 与 golden.json，按你的指令定位并修复。

6.2 相关 API

7. 常见问题

8. 变更记录

本文档是 Omega 测试体系的唯一权威来源。所有配置维度的调整将在此同步更新。

如何追踪变更：本文档托管于 /omega-docs.html，源码版本与 omega.html 的 .footer 中的版本号保持一致（当前 v3.2）。如有配置维度变更，将在此表格追加记录并提升版本号。