feat(preview): add low poly vehicle library

2026-08-05 16:00:04 +08:00
parent 436eb482fd
commit 3108336bf4
53 changed files with 15829 additions and 13 deletions
--- a/.trellis/spec/blender/asset-generation.md
+++ b/.trellis/spec/blender/asset-generation.md
@@ -259,6 +259,17 @@ tilt_y       = TILT_JITTER * math.cos(index * 0.927295)
 | 靠调 `FOLIAGE_EMISSION` 提亮植被 | 用错了旋钮，该调 albedo gain |
 | 在 `MATERIALS` 中间插入条目 | GLB 材质索引整体平移 |

+## 第三方资产导入的源文件边界
+
+第三方 Blend 只属于一次性入库工具的输入，不能成为 `build:area` 或 Cesium 预览的运行时依赖。
+完成拆分后，仓库必须包含可直接消费的 glTF/bin、共享贴图、manifest 和人工预览；原始下载文件可
+以删除。导入工具应将源文件路径作为显式 `--source` 参数，manifest 最多保留源文件名作溯源，
+不能写死用户 Downloads 目录。
+
+删除原始文件前必须确认入库资产已通过结构验证和人工预览；删除后若需重新导入，必须重新取得
+同一 Blend 与其外部贴图。`blender/tools/split_lowpoly_cars.py` 是这一约定的实例，不参与区域
+构建阶段。
+
 ---

 ## 相关
--- a/.trellis/tasks/08-05-lowpoly-cars-assets/check.jsonl
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/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-lowpoly-cars-assets/design.md
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/design.md
@@ -0,0 +1,54 @@
+# 设计：LowPoly Cars 资产库
+
+## 边界与目录
+
+本任务独立于区域构建和 Cesium 预览。新增目录
+`assets/models/custom/lowpoly_cars/`，其内部结构与 Shapespark 植物包一致：
+
+```text
+lowpoly_cars/
+  manifest.json
+  index.html
+  textures/
+  <vehicle-id>/model.gltf
+  <vehicle-id>/model.bin
+  <vehicle-id>/preview.png
+```
+
+源 `.blend` 保留在用户 Downloads，不复制入仓库；`manifest.json` 保存源文件名与根对象名，
+以便可追溯而不引入二进制源文件。
+
+## 拆分与规范化
+
+新 Blender 工具以 Empty 根节点和其全部后代 mesh 作为一辆车。根节点名是稳定初始 ID：
+`car_a01_002`、`truck_a01_001` 等。名称重复的车辆保留全部条目，不依据几何统计猜测合并。
+
+导出前把每辆车的根节点变换 bake 到其后代网格，再把局部原点置于车辆的水平中心和最低接地点。
+规范化的预览坐标为 X 前进、Y 向上、Z 横向；若源根节点的朝向不符合它，工具按对象族显式
+变换并由渲染缩略图复核。不能依赖源文件中用于陈列的全局坐标、`0.001` 缩放或 90°/180°旋转。
+
+保留同一辆车的 mesh 分件与材质槽，避免为图库的便利合并导致窗、轮胎等材质丢失。图像依赖
+集中复制到 `textures/`，glTF 以相对路径引用，重复车款不能复制同一张贴图。
+
+## 产物与预览
+
+工具为每辆车导出 glTF/bin，使用隔离的三点布光、地面阴影与固定透视相机输出
+`preview.png`。`index.html` 只消费 manifest，响应式显示缩略图、ID、类别、三角面数、尺寸和
+材质；它不依赖 Cesium、Node 打包或区域输出，通过 HTTP 直接查看。
+
+`manifest.json` 的每项至少包含 `id`、`name`、`category`、`sourceRoot`、`model`、`bin`、
+`preview`，以及 `metrics.vertices`、`metrics.triangles`、`metrics.dimensions`、
+`metrics.materials`。`category` 取 `car`、`truck` 或 `tractor`。
+
+## 风险与回退
+
+Blender 的沙箱内加载会崩溃，因此导出、渲染和检查仅通过受批准的沙箱外 Blender 调用。若
+某一根节点导出失败，工具记录错误并继续其余资产；manifest 只收录有效产物，失败根节点写入
+报告。删除 `lowpoly_cars/` 不影响任何当前构建阶段或 Cesium 巡航。
+
+## Cesium 候选集
+
+候选集固定为 `car_a01_002`、`car_a02_002`、`car_a03_001`，以及按稳定 ID 排序的前三辆
+卡车 `truck_a01_001`、`truck_a02_001`、`truck_a03_001`。预览构建把这六个 glTF/bin 与一张
+共享 512px 贴图复制到区域输出目录并改写其 image URI；浏览器页面加载时从文件名列表随机选
+一项，所有巡航实体在本页使用相同模型。这样构建产物保持确定，随机性只属于用户可见的会话。
--- a/.trellis/tasks/08-05-lowpoly-cars-assets/implement.jsonl
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/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-lowpoly-cars-assets/implement.md
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/implement.md
@@ -0,0 +1,27 @@
+# 实施计划：LowPoly Cars 资产库
+
+1. 在 `blender/tools/` 增加可重复执行的拆分/导出工具，读取指定 `.blend`，枚举命名 Empty
+   根节点，bake 变换、规范化坐标并分别导出车辆。
+2. 让工具生成共享贴图目录、逐车 glTF/bin、缩略图、manifest 与静态图库 HTML；输出排序必须
+   按稳定 ID，避免重复运行产生无关差异。
+3. 为导出结果提供轻量结构检查：验证 manifest 路径存在、ID 唯一、几何指标为正、模型和缩略图
+   可读取；对源根节点与导出条目数量做对账。
+4. 在沙箱外运行导出与缩略图渲染，目检图库中的普通车、卡车和拖拉机，核对朝向、落地与比例。
+5. 运行 Python/Node 语法检查和现有 preview 测试，确认不触及 `vehicle-model.js`、路线 JSON 或
+   Cesium 默认预览；记录验证结果。
+6. 验收后提交资产库、工具、来源说明与必要的代码规范；不改当前默认巡航模型。
+
+## 验证
+
+```bash
+blender --factory-startup --background --python blender/tools/<tool>.py -- --source <blend> --output assets/models/custom/lowpoly_cars
+python3 blender/tools/<tool>.py --verify assets/models/custom/lowpoly_cars
+node --check scripts/lib/vehicle-model.js
+npm run test:preview-assets
+git diff --check
+```
+
+## 回滚
+
+本任务只新增独立资产库和工具。若某项导出或方向不合格，删除该新增目录和工具即可；当前区域
+构建和 Cesium 预览没有依赖它们。
--- a/.trellis/tasks/08-05-lowpoly-cars-assets/prd.md
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/prd.md
@@ -0,0 +1,53 @@
+# 拆分 LowPoly Cars 车辆资产
+
+## Goal
+
+将用户下载的 `011.+LowPoly_Cars_01_blend.blend` 拆分为可独立检查、可被后续
+Cesium 车辆预览复用的低模车辆资产库；沿用 Shapespark 植物包的资产目录、清单与
+浏览器预览体验。
+
+## Confirmed Facts
+
+- 源文件位于 `/Users/que01/Downloads/011.+LowPoly_Cars_01_blend.blend`，为 Blender
+  3.0、64 位小端格式，约 25 MB；不应直接作为仓库产物引用。
+- 当前 Blender 4.5.12 LTS 在沙箱中加载会崩溃；在沙箱外可稳定读取，故拆分和渲染应通过
+  沙箱外 Blender 调用完成。
+- 源文件有 12 个可导出 Empty 根节点：5 个普通车条目（其中 `car_a01`、`car_a02` 各有两份
+  同名变体）、4 个卡车、3 个拖拉机；每项由 11 到 19 个 mesh 组成。
+- 根节点保存了展示排布用的 `0.001` 缩放与 90°/180°旋转。拆分必须应用这些层级变换，统一
+  比例、地面基线和车辆前进轴，不能将源文件世界坐标原样导出。
+- 主体使用共享 `carmaterial`（含 base-color 图和 normal map），拆分后应共用贴图，不复制到
+  每一个车辆目录。
+- 植物包位于 `assets/models/custom/shapespark_plants/`：每个资产拥有
+  `model.gltf`、`model.bin`、`preview.png`，共享贴图放 `textures/`，并以
+  `manifest.json` 和 `index.html` 提供机器与人工检查入口。
+- 已完成的车辆连续路线系统读取预览车辆 glTF；新资产库在验收前不得破坏该默认车辆或
+  现有路线播放。
+
+## Requirements
+
+1. 稳定读取源 `.blend`，记录其集合、对象、材质、几何指标、坐标朝向和许可/来源信息。
+2. 按可独立使用的车辆变体拆分为 glTF 资产，保留正确比例、轮胎落地基线、前进朝向与
+   原始材质语义；共享贴图不得为每辆车重复复制。
+3. 在 `assets/models/custom/` 下创建与植物包一致的清晰目录、JSON manifest 与简洁的
+   HTML 图库预览；每辆车显示缩略图、三角面数、尺寸与材质信息。
+4. 预览页必须可通过本地 HTTP 查看，不依赖主场景或 QGIS；缩略图应能帮助比较车款、颜色
+   和比例。
+5. 新库经过 Blender/glTF 结构检查；从普通车中固定选 3 个、从卡车中选前 3 个组成候选集，
+   Cesium 每次打开预览时从该 6 个模型随机选一辆作为巡航车辆。
+
+## Acceptance Criteria
+
+- [ ] 能稳定枚举源文件内的可导出车辆，并把每个产物与源对象/集合对应起来。
+- [ ] 每个可用车辆有独立 `model.gltf`/二进制数据、预览图与 manifest 条目；预览图和 HTML
+      能正确加载。
+- [ ] manifest 为每项记录稳定 ID、名称、来源、几何指标、尺寸、材质和相对路径。
+- [ ] 人工查看图库可比较全部导出的车辆；没有重复贴图、明显错误的坐标轴或悬空/埋地车轮。
+- [ ] 现有目标区域的 Cesium 巡航预览仍可生成和播放。
+- [ ] 目标区域预览目录包含选定的 6 个车辆模型与一张共享贴图；页面刷新会从候选集随机选车。
+
+## Out of Scope
+
+- 不在本任务中制作车辆动画、转向轮、交通行为、LOD 或性能压缩策略。
+- 不修改 QGIS 工程、道路生成或上一轮已经确认的车辆连续路线逻辑。
+- 不引入车辆动画、逐车随机分配、性能压缩或车辆选择控件；本轮只在页面加载时随机确定一种车。
--- a/.trellis/tasks/08-05-lowpoly-cars-assets/task.json
+++ b/.trellis/tasks/08-05-lowpoly-cars-assets/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "lowpoly-cars-assets",
+  "name": "lowpoly-cars-assets",
+  "title": "拆分 LowPoly Cars 车辆资产",
+  "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."}