feat: add Cesium semantic inspection mode

2026-08-05 13:24:39 +08:00
parent 400525dd07
commit 607d8fc0b1
18 changed files with 542 additions and 56 deletions
--- a/.trellis/spec/pipeline/cli-and-stages.md
+++ b/.trellis/spec/pipeline/cli-and-stages.md
@@ -70,7 +70,8 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
  - `<fileStem>-compressed-webp768.glb`
  - `<fileStem>-compressed-webp768.json`
  - `<fileStem>-compressed-webp768-cesium-preview.html`
- 伴生 metadata 的 `asset` 和 `assets[0].url` 改为压缩 GLB 文件名。
+- 伴生 metadata 的 `asset` 与 `id="main"` 资产 URL 改为压缩 GLB 文件名；其余资产（包括
+  `category="semantic"` 的 Cesium 分类检查 GLB）必须原样保留。
 - preview HTML 只替换 `window.OSM_ASSET_PREVIEW_CONFIG` 的 `glbName` /
  `metadataName` 和 loading 文案，不改 preview runtime。
 - 成功时 stdout 打印 `GLB_COMPRESS_DONE <json>`，包含压缩前后大小、image /
@@ -100,6 +101,7 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
 ### 6. Tests Required

 - `node --check scripts/compress-glb.js`
+- `npm run test:compress-glb`：断言压缩 metadata 只替换主资产，不丢失语义资产。
 - `node --check scripts/build-area.js`
 - 对目标区域跑一次 `npm run compress:glb -- ... --metadata --preview`
 - 对目标区域跑一次 `npm run build:area -- --stages compress`
--- a/.trellis/spec/preview/index.md
+++ b/.trellis/spec/preview/index.md
@@ -201,6 +201,73 @@ GLB 停留在**局部 ENU 坐标系**（X 东、Y 北、Z 上），靠伴生 JSO

 `scenePlacement(metadata)`（`:131`）负责这一步。**改动导出侧的坐标约定必须同步改这里。**

+## 语义检查资产
+
+### 1. 范围与触发条件
+
+`cesium` 阶段除完整主 GLB 外，会按 Blender 顶层集合导出可选检查资产：道路、建筑、
+绿化与设施、水体。它们只服务于预览检查；主 GLB 仍是下游兼容基线，不能被替换。
+
+### 2. 调用形式
+
+不新增 CLI 参数。正常运行 Cesium 阶段即可：
+
+```bash
+npm run build:area -- --config config/areas/<area>.json --stages cesium
+```
+
+### 3. 契约
+
+- `blender/export_cesium.py:SEMANTIC_ASSETS` 是集合名、稳定资产 ID 与展示名的唯一映射：
+  `03_Roads → roads`、`04_Buildings → buildings`、`02_Green + 05_Props → vegetation`、
+  `01_Water → water`。
+- 每个有几何的类别额外写 `<stem>-<id>.glb`，且必须保留与主 GLB 相同的局部 ENU 坐标和
+  已处理的 Cesium 材质。
+- metadata 的主资产保持 `id="main"`、`enabled=true`；辅助项设
+  `category="semantic"`、`enabled=false`，并提供 `id`、`label`、`type="model"`、`url`。
+- `build-area.js:semanticAssetRecords()` 必须验证 metadata 声明的每个语义文件存在后才写
+  Cesium manifest。
+- 浏览器先加载非语义资产；只有点 `Inspect` 才加载辅助 GLB。检查模式必须隐藏主场景，
+  返回 `Scene` 必须隐藏辅助模型，禁止两套几何重叠渲染。
+- 没有 `category="semantic"` 的旧 metadata 仍按单资产预览打开，`Inspect` 按钮禁用。
+
+### 4. 校验与错误矩阵
+
+| 条件 | 结果 |
+|---|---|
+| 类别集合没有可导出 mesh | metadata 不声明该类别，预览不显示该开关 |
+| metadata 声明语义资产但文件不存在 | Cesium 阶段失败，不能写成功 manifest |
+| 辅助 GLB 浏览器加载失败 | 该开关禁用并写入诊断；主场景继续可用 |
+| 旧 metadata 没有语义项 | 完整场景照常显示，`Inspect` 不可点击 |
+
+### 5. 正常、基础与错误示例
+
+- 正常：进入 `Inspect` 后道路、建筑、绿化与设施、水体全部显示，再单独取消任一类别。
+- 基础：旧的只有 `main` 资产的 metadata 不展示分类控件，所有原有控制仍可用。
+- 错误：主 GLB 和语义 GLB 同时可见，导致道路、建筑等重复渲染和闪烁。
+
+### 6. 必需测试
+
+- `node scripts/test-preview-assets.js`：断言生成页包含模式切换与语义开关挂载点。
+- `node --check scripts/build-area.js`、`node --check scripts/lib/area-preview.js`、
+  `node --check scripts/lib/cesium-preview.js`。
+- 目标区域运行 `--stages cesium`，确认 metadata 的语义 `assets` 与同名辅助 GLB 一一对应。
+- 浏览器在桌面及窄屏分别切换 `Scene` / `Inspect`，确认不重叠且控制不溢出。
+
+### 7. 错误与正确写法
+
+错误：把辅助模型标为默认启用，页面加载时把它们与主 GLB 一起绘制。
+
+```json
+{ "id": "roads", "enabled": true, "category": "semantic" }
+```
+
+正确：默认关闭并在检查模式按需加载。
+
+```json
+{ "id": "roads", "enabled": false, "category": "semantic" }
+```
+
 ---

 ## 本地预览必须走 HTTP
--- a/.trellis/tasks/08-05-cesium-preview-controls/check.jsonl
+++ b/.trellis/tasks/08-05-cesium-preview-controls/check.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-05-cesium-preview-controls/design.md
+++ b/.trellis/tasks/08-05-cesium-preview-controls/design.md
@@ -0,0 +1,28 @@
+# 设计：Cesium 语义资产检查
+
+## 边界
+
+Blender 场景已按集合组织要素。Cesium 导出器在不修改作者场景的前提下，复用现有导出材质处理，先生成完整主 GLB，再按集合筛选对象生成道路、建筑、植被和水体四份辅助 GLB。主 GLB 继续是默认资产和兼容基线。
+
+## 资产契约
+
+metadata 保持现有 `asset` 字段指向主 GLB，并将 `assets` 扩展为：
+
+- `main`：完整场景，默认启用；
+- `roads`、`buildings`、`vegetation`、`water`：语义检查资产，默认关闭。
+
+每个资产提供稳定的 `id`、中文 `label`、`type: model`、相对 `url` 与 `enabled`。旧 metadata 缺少这些额外资产时，预览按现有单资产回退路径加载。
+
+## 预览交互
+
+主场景模式只显示主 GLB，并保留现有 `Scene` 总开关。切入分类检查模式时隐藏主 GLB、显示四个类别复选项；选择类别时加载并显隐对应资产。离开分类模式后恢复主场景，避免完整模型和类别模型重叠渲染。
+
+控制面板继续是贴边的紧凑工具面，不添加嵌套卡片。模式切换使用分段控件，类别开关按一行标签排列；窄屏时自然换行。颜色只用于状态和可访问性反馈，不做大面积装饰。
+
+## 兼容与回滚
+
+主 GLB、主 metadata 和既有预览文件名均不变。任意辅助 GLB 缺失时，预览记录该资产失败但完整场景仍可加载。回滚只需恢复旧 exporter/runtime，主产物仍可使用。
+
+## 风险
+
+多次导出会增加 Cesium 阶段耗时与磁盘占用，但只影响验证辅助产物，不改变主 GLB。导出时需确保每份辅助资产保留与主 GLB 相同的局部 ENU 坐标和材质处理。
--- a/.trellis/tasks/08-05-cesium-preview-controls/implement.jsonl
+++ b/.trellis/tasks/08-05-cesium-preview-controls/implement.jsonl
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
--- a/.trellis/tasks/08-05-cesium-preview-controls/implement.md
+++ b/.trellis/tasks/08-05-cesium-preview-controls/implement.md
@@ -0,0 +1,21 @@
+# 实施计划：Cesium 语义资产检查
+
+1. 读取 Blender 场景集合，定义四个稳定的语义导出组；完整 GLB 仍走当前路径。
+2. 扩展 `export_cesium.py`：导出四份辅助 GLB，并把资产描述写进 metadata。
+3. 扩展 `build-area.js` 的 Cesium 输出检查和 manifest，使辅助资产成为该阶段的受管产物。
+4. 更新 `area-preview.js`、`cesium-preview.js` 与 CSS：增加完整/分类模式及分类显隐控件，保持旧 metadata 回退。
+5. 为 HTML 注入、metadata 回退和模式状态编写 Node 侧测试；运行既有预览与纯 Python 测试。
+6. 在本机重建一个区域，确认辅助 GLB 坐标、材质、模式切换及窄屏布局；此环境若 Blender 沙箱失败，不将其计为代码失败。
+
+## 验证
+
+```bash
+node scripts/test-preview-assets.js
+python3 -m unittest discover blender/tests
+git diff --check
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages cesium
+```
+
+## 回滚点
+
+主 GLB 与原 preview 文件保持不变。若辅助导出或分类预览异常，可删除语义资产声明并恢复为单资产加载，不影响既有场景。
--- a/.trellis/tasks/08-05-cesium-preview-controls/prd.md
+++ b/.trellis/tasks/08-05-cesium-preview-controls/prd.md
@@ -0,0 +1,47 @@
+# Cesium 预览控制
+
+## 目标
+
+让 Cesium 预览更便于检查已生成的园区场景，不涉及 QGIS 数据编辑或压缩产物策略。
+
+## 已确认事实
+
+- 预览已有 `Overview`、`Oblique`、`Detail`、`Route` 相机预设，以及车辆跟随；重复开发这些控件没有价值。
+- 预览已有主场景、路线、车辆的显隐开关；多 GLB 时也会自动提供资产级开关。
+- 当前导出物只有一个主 GLB，metadata 只记录场景统计和一个 `main` 资产，不含可用于点选的要素属性。
+- 预览是验证层，改动不应改变 Blender 主资产的几何或 QGIS 工作流。
+
+## 候选范围
+
+- 按场景类别显隐，例如道路、建筑、植被、水体。
+- 点击可识别对象后显示基础信息。
+- 保持既有相机预设、车辆控制和单场景加载的兼容性。
+
+## 已确认决策
+
+- 场景按道路、建筑、植被、水体等语义类别额外导出 GLB，Cesium 预览分别加载。
+- 保留现有主 GLB，作为完整场景基线和兼容入口。
+- 首版不提供点选要素属性；这需要逐要素 OSM 元数据映射，另行规划。
+- 控件遵循现有低干扰预览风格：紧凑分组、清晰状态、克制色彩和无装饰性卡片堆叠。
+
+## 需求
+
+1. Cesium 导出额外生成道路、建筑、植被、水体四类语义 GLB，并写入 metadata 资产清单。
+2. 预览默认加载主 GLB；用户可切换到语义资产检查模式，在该模式独立显示或隐藏每个类别。
+3. 预览保留现有相机预设、车辆巡航、主场景开关及单 GLB metadata 的兼容行为。
+4. 控件在桌面和窄屏下保持可读、可操作且不遮挡关键画面。
+
+## 不在范围内
+
+- QGIS 图层、人工数据修补和 reimport 流程。
+- 将压缩 GLB 设为默认产物。
+- 地图、地形或在线底图功能。
+- 点击要素属性、OSM ID 或名称映射。
+
+## 验收标准
+
+- [ ] 一次 Cesium 导出会保留主 GLB，并产出四个可独立加载的类别 GLB。
+- [ ] metadata 的 `assets` 同时声明主场景和各类别资产，旧 metadata 仍可作为单资产场景打开。
+- [ ] 预览可在完整场景与分类检查模式之间切换；分类模式可独立控制道路、建筑、植被、水体。
+- [ ] 现有 Overview、Oblique、Detail、Route、车辆和诊断控件仍可使用。
+- [ ] 控件在常规桌面与窄屏宽度下无重叠、无溢出，视觉层级与现有预览一致。
--- a/.trellis/tasks/08-05-cesium-preview-controls/task.json
+++ b/.trellis/tasks/08-05-cesium-preview-controls/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "cesium-preview-controls",
+  "name": "cesium-preview-controls",
+  "title": "Cesium preview controls",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-05",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
				`@@ -0,0 +1 @@`
				{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}