feat(web): finish RE 5000PBR lesson video and fix non-ASCII GLB import
Some checks failed
M6 deployable RC / quick (push) Has been cancelled
M6 deployable RC / chromium (push) Has been cancelled
M6 deployable RC / release (push) Has been cancelled

- Add 11:07 Chinese-narrated lesson video, VTT, poster and 13 chapter screenshots.
- Regenerate 20-render WebGL2 matrix and 15 operation captures on RTX 4060.
- Fix WASM staging for non-ASCII import filenames (猴头.glb); rebuild web_engine.
- Harden lesson video recording pipeline; fix stale lesson-link E2E selector.
- Add RE PBR derived libraries, lesson page, evidence and status report.

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
mes123456
2026-11-12 21:49:24 +08:00
parent a078648297
commit d5dd647881
276 changed files with 9632 additions and 314 deletions

View File

@@ -0,0 +1,140 @@
# RE 5000PBR × 猴头 GLB:渲染全面测试、HTML 教案与中文配音视频
日期:2026-11-12
状态:**功能实现完成;聚焦验证通过;整体产品验收仍由用户执行**
(`IMPLEMENTED_NOT_USER_ACCEPTED`)
## 本轮目标与范围
用户要求:在 Web Blender 中使用 `/home/mes123456/workinf_Blender_Wasm/re/5000PBR精简版`
的资产,对 `/home/mes123456/workinf_Blender_Wasm/re/猴头.glb` 做渲染功能全面测试;把操作过程截屏写成
初学者 HTML 教案;制作完整中文配音视频;发现的缺口按桌面 Blender 源码修 Web 移植,UI 缺口用 React;
需要时本地重编 WASM;全部使用绝对路径。
用户确认的范围:
- **只修实测阻塞**,不新增标准渲染设置 UI(宽高比、采样、透明背景、HDRI)。
- **只测 WebGL2 PBR**,不纳入本地原生 EEVEE/WASM(F12)或服务端 Blender。
前序批次已交付 RE 5000PBR 派生库、HTML 教案、20 张成片和 15 张操作截图;本轮补齐缺失的视频链路,
并修复实测暴露的一个真实导入缺口。
## 交付物
### 1. 中文配音视频(本轮新增)
| 项目 | 路径 / 值 |
| --- | --- |
| MP4 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/re-pbr-lesson-720p.mp4` |
| 字幕 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/re-pbr-lesson.zh-Hans.vtt` |
| 封面 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/poster.jpg` |
| 时长 | 667.04 s(11:07),13 章 |
| 编码 | H.264 / AAC,1280×720,faststart |
| MP4 SHA-256 | `6a5b3b51c52945d0594a984ad6b5ff2e557ec319c574679673bd8d6d2a8a2916` |
| 旁白混音 SHA-256 | `adc2658938ad48b278aa434cb9635343491f7241f4632b4af6c9baa9271b9220` |
| VTT SHA-256 | `4199af3a9c1ad501ebd7832e43693d43d2bbd30a646a8285343eefc08a237aa3` |
| 封面 SHA-256 | `6461410e032de2c92f3f898873d9dca9834f2538e65cd0e4b2d8f3c443d0f444` |
| 旁白 | `zh-CN-XiaoxiaoNeural`,13 章,13 条 VTT cues |
| 章节截图 | `/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video-steps/*.jpg`(13 张,1600×900) |
| 录制证据 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-VIDEO-001/{screencast.webm,timeline.json,record-report.json,narration/,diagnostics/}` |
视频由有头 Chromium(`DISPLAY=:1`)真实操作录制,GPU 探测为
`ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)`。
章节:开场、载入摄影棚、导入猴头 GLB、认识 Shading/RE 资产库、分配六种材质、设置渲染、
渲染与下载 PNG、保存与重开、诊断视图与教学曝光、位移与细分、对比视角、高清 2048 贴图、总结。
### 2. HTML 初学者教案
`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
+ `render-lesson.css`。13 节,75 个同源引用,**0 个断链**;包含真实操作截图、六种材质逐课、
20 张成片矩阵、黑图排查表和限制说明。视频、字幕、封面已嵌入。
### 3. 全面渲染测试证据(当前 wasm 重跑)
| 项目 | 路径 / 值 |
| --- | --- |
| 20 张成片 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/renders/*.png` |
| 采集报告 | `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/report.json` |
| 报告结果 | `status=PASS`、20 renders、15 steps、0 errors、20 个唯一 SHA |
| GPU | `ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)` |
| GLB SHA-256 | `60267d607b63ceb5bfc972342a9ff17310d6978ff632f240ecb963c4d5a7e003`(`re/猴头.glb`) |
| 纹理状态 | 基线 `ready:1:0:`;六材质 `ready:5:0:`;重开 `ready:5:0:` |
| 材质编译 | 六个 RE 材质均 `COMPILED` |
| 当前 wasm | `/home/mes123456/workinf_Blender_Wasm/web/app/public/vendor/blender/web_engine.wasm` SHA-256 `31550b374cc0127c9b5468cebe65be37b8558c1604a28e99ec73a34be96c13f3` |
矩阵:基线 1024;6 材质 ×(1024 场景 + 1024 视口 + 512 场景);保存/重开后复渲染。
进阶证据沿用 `/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/`:
位移 1×/100×(968 → 61,952 三角形,mean delta 0.087)、诊断视图 3 张、+2 EV、对比视角、
HQ 2048(10.8 MB 库,67,633,152 bytes 解码);`check-re-pbr-limits.mjs` 本轮 PASS。
## 本轮修复的真实缺口
### 非 ASCII 文件名 GLB 导入失败(P0,已修复)
- **现象**:用真实文件入口打开 `/home/mes123456/workinf_Blender_Wasm/re/猴头.glb` 时,对象数保持 6,
控制台报 `RuntimeError: Error: Please select a file`;ASCII 夹具 `monkey-head.glb` 正常。
- **根因**:`/home/mes123456/workinf_Blender_Wasm/blender-5.2.0/source/blender/web_engine/web_engine_main_state.cpp`
的 `web_engine_blend_main_obj_io()` 原先把浏览器传来的原始文件名直接作为 Emscripten 虚拟文件系统的暂存名。
`猴头.glb` 的 UTF-8 文件名在 WASM 侧的 VFS 路径解析中不可用,glTF 导入器拿到不可解析路径后报
“Please select a file”。
- **修复**:暂存到磁盘的文件名把非 ASCII 字节替换为 `_`(例如 `______.glb`),扩展名与 ASCII 文件名保持不变;
UI 仍显示浏览器提供的原始文件名。桌面 Blender 本身支持 UTF-8 路径,本修复只影响 Web 的 WASM 暂存层。
- **构建**:`cmake --build /home/mes123456/workinf_Blender_Wasm/build_web_blender6 --target web_engine -j8`
→ `node /home/mes123456/workinf_Blender_Wasm/tools/web/sync-web-engine-runtime.mjs`;
新 wasm SHA-256 见上表。
- **验证**:视频“导入猴头 GLB”章节真实导入成功,状态栏 `Engine: GLB imported r2 (7 objects)`,
活动对象 Suzanne;20 张采集报告 `glbSha256` 与 `re/猴头.glb` 一致。
### 视频录制脚本阻塞(工具链,已修复)
- `tools/web/record-re-pbr-lesson-video.mjs` 原先的 `openStudio()` 依赖面板按钮路径,失败时不会回退;
失败前不保存视频/时间线。本轮增加:`--out` 生效、只清理 `screencast.webm`、保留原始 webm、
服务器退出检测、面板不可用时回退到 `[data-testid="blend-file-input"]`、保存对话框处理、
每章失败截图与部分时间线保留、失败时仍保存视频、硬件 GPU 回退即失败、时长 7–12 分钟守卫。
- 验证:13 章完整录制 `status=PASS`、0 errors、667.04 s。
### E2E 文案漂移(测试修正,非产品缺口)
- `web/tests/e2e/re-pbr-render-workflow.spec.ts` 仍按旧文案“打开图文教案”查找链接;面板现为
“打开图文/视频教案”。已改为正则 `/打开图文/`,主流程用例重跑通过(3.6 分钟)。
## 验证结果
| 检查 | 结果 |
| --- | --- |
| `node tools/web/check-re-pbr-library.mjs` | PASS(6 材质、6 预览、3,707,202 bytes) |
| `node tools/web/check-re-pbr-library.mjs --hq` | PASS(6 材质、10,846,909 bytes、2048) |
| `node tools/web/check-re-pbr-lesson.mjs` | PASS(20 renders、15 steps、6 材质、0 断链) |
| `node tools/web/check-re-pbr-limits.mjs` | PASS(位移/诊断/HQ/GPU/重开) |
| `node tools/web/check-re-pbr-video.mjs` | PASS(13 章、13 cues、667.04 s、1280×720、faststart) |
| 有头 E2E `re-pbr-render-workflow.spec.ts` | **5/5 通过**(6.8 分钟;主流程 6.3 分钟,截断 GLB 负例、HEIGHT 位移、HQ 按需加载、HQ 2048 尺寸均通过) |
| 20 张采集 | PASS(20/20、unique SHA 20、0 errors、RTX 4060) |
| 教案引用 | 75/75 存在,0 断链,无远程 URL |
| 教案页面冒烟(Chromium,dev) | 56 张图片全部解码、视频 `duration=667.04`/`readyState=4`、VTT 200 + 13 cues、无 4xx |
| 生产构建 | `npm run build` PASS(typecheck + vite build;`web/dist` 含视频、字幕、poster、13 张章节截图、新 wasm) |
| 教案页面冒烟(生产 dist + 部署服务) | 56 张图片全部解码、视频 667.04 s、VTT 13 cues、无 4xx |
| 视频音频 | AAC 单声道 48 kHz;`volumedetect` mean −23.4 dB、max −2.6 dB(非静音) |
## 未验证 / 限制
- Web 渲染是 three.js WebGL2 PBR(`physical-v1`),不是 EEVEE/Cycles 路径追踪;玻璃/金属/折射/GI
与桌面物理精度不同。本机原生 EEVEE/WASM(F12)与服务端 Blender 未验证。
- 六种 RE 材质都是深色砖石/防滑表面,整体偏暗是材质本身;用诊断视图和教学曝光判断,而不是只看亮度。
- 标准渲染设置 UI(非方形宽高比、采样/抗锯齿、透明胶片、HDRI/世界环境编辑)未在本轮补齐;
用户选择“只修实测阻塞”,这些记录为已知限制。
- HQ 2048 为按需加载;mipmap 可能使实际显存比 base-level 预算高约 1/3。
- 按仓库策略只验证 Chromium;Firefox/WebKit、移动端未运行。
- 视频旁白按 13 章覆盖操作步骤;材质原生追加、PBR 渲染、HQ 加载的等待段保留真实耗时,
部分章节为静默操作画面(未做变速剪辑),这是为了不伪造操作时延。
- 未做用户实际使用验收;本轮的检查器/E2E/录制 PASS 不等于整体产品验收。
## 证据路径
- 视频:`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video/`
- 视频章节截图:`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/video-steps/`
- 教案:`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`
- 20 张成片与报告:`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/`
- 视频录制/混音证据:`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-VIDEO-001/`
- 进阶限制证据:`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/`
- 本轮源码修复:`/home/mes123456/workinf_Blender_Wasm/blender-5.2.0/source/blender/web_engine/web_engine_main_state.cpp`
- 录制脚本:`/home/mes123456/workinf_Blender_Wasm/tools/web/record-re-pbr-lesson-video.mjs`