d5dd647881
- 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>
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# PBR 渲染初学者互动教程 (pbr)
|
||
|
||
日期：2026-11-11
|
||
状态：**功能实现并完成有头 Chromium 采集与聚焦 E2E；整体产品验收仍由用户执行**
|
||
|
||
## 交付内容
|
||
|
||
- 新应用内课程 `pbr`：`/?ui=web&tutorial=pbr`（落地页）/ `?ui=web&tutorial=pbr&start=1`（编辑器中）。
|
||
- 13 步中文教程：
|
||
`intro` → `workspace-shading` → `load-studio` → `add-suzanne` → `add-cube` → `add-torus` →
|
||
`assign-metal` → `assign-glass` → `assign-wood` → `assign-emission` → `render-setup` → `download-save` → `summary`。
|
||
- 教程演示动作走真实产品入口：工作区切换、按名选择、PBR 资产库追加模型/分配材质、打开课程摄影棚、
|
||
Web PBR 渲染、PNG 下载、工程保存。
|
||
- React 接线：`TutorialContext` 增加 workspace/资产库/渲染结果；`TutorialApi` 增加工作区、选择、
|
||
资产追加、材质分配、打开场景、渲染、下载；`PbrRenderPanel` 支持外部请求与 `onRendered` 回传。
|
||
|
||
## 资产与截图
|
||
|
||
- 课程摄影棚：`web/app/public/tutorial/pbr/studio.blend`
|
||
- 相机 `PBR Studio Camera`、三点灯光 + Sun、深灰世界、地面；生成报告
|
||
`tests/golden/PBR_TUTORIAL-001/studio-build.json`。
|
||
- 教程步骤截图（有头 Chromium 实际操作）：
|
||
`web/app/public/tutorial/pbr/landing.jpg`、`steps/<stepId>.jpg`、`steps/<stepId>-view.jpg`、
|
||
`steps/00-assembly.jpg`（13 步 × 2 + 2）。
|
||
- 12 张材质对比成片：`web/app/public/tutorial/pbr/renders/<model>-<material>.{png,jpg}`
|
||
- 模型：Suzanne、Cube、Torus；材质：Metal Brushed、Glass、Wood、Emission Cyan。
|
||
- 这 12 张由桌面 Blender EEVEE 使用同一摄影棚/材质库渲染（`renderer: DESKTOP_BLENDER_EEVEE`），
|
||
因浏览器 WebGL2 路径当前对部分材质仍偏暗；教程步骤截图与交互操作仍是真实有头 Chromium。
|
||
- 生成脚本：`tools/web/generate-pbr-tutorial-renders.py`。
|
||
- 采集报告：`tests/golden/PBR_TUTORIAL-001/headed-screenshots-latest.json`
|
||
（steps=13、renders=12、status=PASS）。
|
||
|
||
## 脚本
|
||
|
||
```bash
|
||
# 生成课程摄影棚
|
||
build_blender_native/bin/blender --background --factory-startup \
|
||
--python tools/web/generate-pbr-tutorial-studio.py -- \
|
||
web/app/public/tutorial/pbr/studio.blend \
|
||
tests/golden/PBR_TUTORIAL-001/studio-build.json
|
||
|
||
# 生成 12 张材质对比参考图
|
||
build_blender_native/bin/blender --background --factory-startup \
|
||
--python tools/web/generate-pbr-tutorial-renders.py -- \
|
||
web/app/public/tutorial/pbr/studio.blend \
|
||
web/app/public/assets/pbr-library/pbr-library.blend \
|
||
web/app/public/tutorial/pbr/renders
|
||
|
||
# 有头 Chromium 采集教程步骤截图
|
||
DISPLAY=:1 CHROME_PATH=/usr/bin/google-chrome \
|
||
node tools/web/capture-parts-tutorial-screenshots.mjs --course pbr --dev --port 5176
|
||
|
||
# 校验采集产物
|
||
node tools/web/check-pbr-tutorial-captures.mjs
|
||
```
|
||
|
||
## 验证结果
|
||
|
||
- `node tools/web/check-pbr-tutorial-captures.mjs`：PASS（13 步截图齐全、12 张 PNG 1024×1024、
|
||
报告 status=PASS、studio SHA 一致）。
|
||
- `web/tests/e2e/pbr-tutorial-accessibility.spec.ts`：通过（axe 无 critical/serious）。
|
||
- `web/tests/e2e/wbv2-pbr-tutorial-production.spec.ts`：通过（13 步演示、资产库 20 卡片、
|
||
渲染结果、PNG/.blend 下载）。
|
||
- `npm run typecheck`：通过。
|
||
|
||
## 已知限制
|
||
|
||
- 浏览器 WebGL2 PBR 渲染对部分材质（尤其金属/木色）偏暗；12 张教程成片改用桌面 Blender EEVEE
|
||
生成，标注为 `DESKTOP_BLENDER_EEVEE`。交互教程与步骤截图仍为真实有头 Chromium。
|
||
- `PBR Wood` 当前为暖色哑光材质（无贴图节点），教程文案已同步为“暖色木质”，避免把未生效的
|
||
纹理链当作已验证功能。
|
||
- 14 类节点之外的任意节点、动态纹理/对象信息、EEVEE/Cycles 像素级一致性不在本教程范围。
|