geopro/docs/superpowers/plans/2026-06-15-vtk-3d-p1-revive-rendering.md

P1：复活中央 VTK 渲染（地基）

• 日期：2026-06-15
• 分支：feat/vtk-3d-view
• 上游 spec：specs/2026-06-15-vtk-3d-supplementary-design.md（§8 编排层、§5.2 Scene 缺口、§6 接口）
• 目标：把当前空壳中央 VTK 复活为数据驱动——勾选对象 → 经仓储取数据 → 调现有 actor → 渲染。复用 render 层零改 actor（除 Scene 加 vtkProp 入口）。这是后续所有 3D 功能的地基，最低风险、最快见效。
• 不在本期：三栏 UI、坐标轴、切片交互、异常体、任务面板（P2+）。本期只让"勾选→出图"重新跑通，并立起 I3dSceneRepository + VtkSceneController 两个骨架。

---

成功判据（goal-driven）

1. 启动 → 勾选样本对象 → 中央 3D 视图出现帘面（buildCurtain），2D 模式出现俯视测线（buildSurveyLine）。
2. 「视图详情」浮层勾选 体素/地形 → 对应 actor 出现/消失（不再是死代码）。
3. VtkSceneController 的编排逻辑有单测（fake repo，断言 actor 集合），不依赖 GUI。
4. main.cpp 中死掉的 rebuildCentral lambda + 裸 show* 标志被 VtkSceneController 取代；slicePlane 等未用声明清理（仅清本期引入/相关的孤儿，不动无关代码）。
5. 构建通过 + 现有测试全绿 + 新测试通过。

---

阶段（每步含 verify）

Step 0 — 基线

• 跑现有测试与构建，记录绿基线。→ verify：ctest 全绿、cmake --build 通过。

Step 1 — Scene 支持体绘制 vtkVolume（评审 HIGH，TDD）

• src/render/Scene.hpp/.cpp：新增 void addViewProp(vtkProp* p)（内部 renderer_->AddViewProp）；addActor 保留（可改为转调 addViewProp）。
• 先写测试 tests/render/test_scene.cpp：加入一个 vtkVolume（或 mock prop）后 renderer()->GetViewProps() 计数 +1；clear() 后归零。
• → verify：RED→GREEN；体绘制 prop 能进场。

Step 2 — I3dSceneRepository + LocalSample3dRepository（TDD）

• src/data/repo/I3dSceneRepository.hpp：异步接口（回调/Qt 信号范式，见 spec §6）。本期最小集：
  • DsDimension dimensionOf(const DsRow&)（同步纯函数，§6.1 映射表）。
  • loadVolume(dsId, onOk(VolumeGrid), onErr)（§6.2）。
  • loadTerrainPaths(onOk(demPath,imagePath), onErr)（包 LocalSampleRepository::demPath/imagePath）。
  • 切片/异常/任务等签名本期只声明占位（留 P3/P4），不实现。
• src/data/repo/LocalSample3dRepository.*：组合现有 LocalSampleRepository（loadVoxelScatters→VoxelFromScatters 出 VolumeGrid；DEM/影像路径直透）。同步数据包成异步壳。
• 测试 tests/data/test_3d_repo.cpp：dimensionOf 各 ddCode 映射正确；loadVolume 回调收到 vol.nx()>0 && vmax>vmin。
• → verify：RED→GREEN。

Step 3 — VtkSceneController（TDD 编排逻辑）

• src/controller/VtkSceneController.hpp/.cpp（QObject）：
  • 输入（槽/setter）：setCheckedDatasets(QStringList)、setViewMode(Map2D/View3D)、setLayer(Curtain/Voxel/Terrain, bool)、setVerticalExaggeration(double)。
  • 内部：按维度/图层决定调哪些 actor builder；缓存 VolumeGrid/Grid 避免重复取数。
  • 输出：scene.clear() → addActor/addViewProp → renderWindow->Render()。把现有 rebuildCentralScene 的帘面/测线逻辑并入，新增 voxel(buildVoxelFromScatters→addViewProp)、terrain(buildTerrain) 分支。
• 测试 tests/controller/test_vtk_scene_controller.cpp：注入 fake repo + fake scene（记录 add 的 prop 类型/数量），断言：
  • 2D 模式 + 勾选 1 ds → 1 个测线 actor；
  • 3D 模式 + showCurtain → 1 帘面 actor；+ showVoxel → 多 1 个 volume prop；+ showTerrain → 多 1 个 terrain actor；
  • 取消勾选 → clear 后无 prop。
• → verify：RED→GREEN，编排逻辑脱离 GUI 可测。

Step 4 — 接入 main.cpp（集成）

• 用 VtkSceneController 实例取代 rebuildCentral lambda（main.cpp:508）与裸 show* 标志（246–251）。
• 接线：ObjectTreePanel 勾选变化 → setCheckedDatasets；act2D/act3D → setViewMode；chkCurtain/chkVoxel/chkTerrain → setLayer；主题切换 → 触发重渲染（控制器内重跑）。
• 清理本期产生的孤儿：未用的 slicePlane 声明、被取代的 lambda/标志（只清相关项，遵守 surgical changes）。chkSlice 暂保留禁用（P3 接）。
• → verify：构建通过；启动手测达成「成功判据 1、2」。

Step 5 — 构建 + 运行验证

• cmake --build + ctest。
• 运行客户端，勾选样本对象，截图确认帘面/体素/地形渲染。
• → verify：成功判据 1–5 全达成。

Step 6 — 代码审查 + 提交

• cpp-reviewer 审查（内存安全/RAII/分层）；按需修。
• 提交：feat(vtk): P1 复活中央渲染 — VtkSceneController + I3dSceneRepository(LocalSample) + Scene 加 vtkProp 入口。

---

风险 / 注意

• Ninja 增量不可靠（记忆 build-ninja-stale-shared-header）：改 Field/RepoTypes 等共享头后，若崩溃先 clean 重编、验 obj 新鲜度。
• 体绘制 vtkVolume 经 addViewProp 进场；clear() 须用 RemoveAllViewProps 覆盖 volume（确认现有 clear() 实现）。
• LocalSample 只合成单 GS→TM→DS，勾选粒度对齐其结构即可；真实多对象/多剖面在接 Api 实现时验证。
• 接口务必异步壳，别图省事写同步（评审 HIGH，否则 P3+ 接后端返工）。