74 lines
5.5 KiB
Markdown
74 lines
5.5 KiB
Markdown
# 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+ 接后端返工）。
|