geopro/docs/superpowers/HANDOFF-vtk-3d.md

交接：VTK 三维视图「补充需求」(feat/vtk-3d-view)

给下一个会话无缝接手用。日期 2026-06-16。分支 feat/vtk-3d-view，HEAD 07f2f25，工作树干净（仅根目录 grid-*.png/grid-snap.yml 是既有未跟踪文件，非本任务产物，勿动）。

1. 背景

• 项目：geopro 桌面客户端（Qt6 + VTK9 + ADS dock），Windows/MSVC+Ninja。
• 任务：实现需求表「补充需求」页签 = VTK 三维视图的整套交互/结构。需求源：D:\Projects\GEOPRO\Geopro3.0 需求表.xlsx「补充需求」(用 openpyxl 读，控制台中文乱码须导 UTF-8 文件再读；A1–C92)。
• 历史：做本需求前已有"基于本地样本数据的原型渲染"（帘面/体素/切片/地形/散点），但在 commit 6241eb3"CentralScene 数据驱动重构"时装配代码被摘除——render 层 actor 完整且有测试，只是没接上。本任务从复活它起步。
• 原版 web「数据视图」(tenant.geomative.cn/#/projectSpace/dataView) 已 Playwright 实地分析：3D = ThreeTile(Three.js)地球(非 Cesium)+多瓦片源；3D 结果=2D 反演剖面成竖直帘面。三栏/切片是客户端新需求(web 无三栏)。详见记忆 web-3d-view-threetile。

2. 关键约束（用户拍板）

• 后端未就绪 → 本轮全部用 LocalSampleRepository 静态样本数据驱动；但仓储接口必须按真实后端形态设计好（I3dSceneRepository 异步），将来换 Api3dRepository 不动上层。
• 严格按需求，禁止砍功能/改需求（教训：曾把 F25 砍掉、把双击正视改按钮，被用户纠正）。复刻不确定处必须实地学习(Playwright)，禁猜测。
• 全部回复中文。

3. 权威文档

• spec：docs/superpowers/specs/2026-06-15-vtk-3d-supplementary-design.md（v2，已纳入架构评审 + web 实地分析；§4 是补充需求逐行映射表；§6 接口设计；§14 分期）。
• 计划：plans/2026-06-15-vtk-3d-p1-revive-rendering.md、plans/2026-06-15-vtk-3d-p2-dataset3d-bar.md、plans/2026-06-16-vtk-3d-p3-slice-interaction.md。

4. 已完成并经用户验收（commit 范围 faee28c..07f2f25）

• P1 复活渲染(0f521c5+53ccdc0)：VtkSceneController(编排,异步)+I3dSceneRepository/LocalSample3dRepository+I3dSceneView/VtkSceneView+Scene::addViewProp(体绘制 vtkVolume 入场)。勾选对象→样本数据→渲染帘面/体素/地形。
• P2 三维数据集栏(3dea339+样式 73deb2b/86e0772)：坐标轴(标准/三维立体/不显示 vtkCubeAxesActor)、刻度(无/米/英尺/经纬度,GeoLocalFrame::toLatLon)、水平/垂直比例滑块、快捷视图6向、Zoom(In/Out/Fit)。右上工具条浮层(仅三维显示)。
• P3 切片交互(85d4ff5..07f2f25)：src/render/interact/(SlicePlaneMath/SliceTool/PickInteractorStyle/InteractionManager)。已验收：
  • 上下/前后/左右切片=固定角度可移动(G22-24)；任意切片=拖边缘旋转(F25)+拖中间移动。
  • 触碰切片→选中+亮青边框高亮(未选暗灰)。
  • 双击切片→正视(D40，靠 widget StartInteractionEvent 350ms 双击判定)。
  • 滚轮→推进选中切片(D46)；关闭→移除选中；翻转(E55)。
  • D39 以选中切片为中心旋转视图：PickInteractorStyle::Rotate() 自定义——按下不动相机、拖动时绕选中切片中心(getRotateCenter)增量旋转整个相机(T(c)·R(up)·R(right)·T(-c))→不跳。
• 构建基建修复（重要，见 §7）：build.bat vswhere/ASCII/加 rebuild；vcpkg.json 加 builtin-baseline。
• ctest 全绿 221/221。

5. 当前 UI 是"过渡态"，不是 spec A1 的三栏（已与用户讲明，属"功能先行、结构后做"的有意分期）

现状 = 旧「二维地图/三维视图」切换 + 三个浮层/工具条：

• 左上「视图详情」(layerPanel)：帘面/体素/地形 复选框；
• 右上「三维数据集栏」(axisBar)：坐标轴/刻度/比例/快捷视图/Zoom；
• 左下「切片」(sliceBar)：上下/前后/左右/任意/翻转/关闭。 渲染由 LocalSample 样本驱动：对象树勾选任意 TM → 映射成样本 ds "grid1"(main.cpp checkedTmsChanged 处)。

6. 下一步（用户即将定方向；我已建议先做①）

① 三栏结构重构（建议先做，A1 顶层框架）：把界面重组为 三维数据集 / 二维数据集 / 三维分析 三栏，各栏含：

• 数据集列表(按 ds 维度 3D/2D 过滤勾选对象的 ds，C9/C15；维度映射见 I3dSceneRepository::dimensionOf)；
• 三维分析栏的树(按 对象/三维体模型/切片 结构，C19)；
• 右键菜单创建切片(D21/F22-25：右键三维体→上下/前后/左右/任意切片；现在是用左下浮层按钮代替，须改成右键)。 ② P4 功能（结构之后或并行）：
• 切片 CRUD：保存/保存为/导出图片/导出dat/删除为数据集(F30-33/D47/E51-53)——I3dSceneRepository 已留 SliceSpec/createSlice 等接口位(spec §6.3)，本轮内存态。
• 创建异常+异常体管理(D48/E49-50/A69-C88)：异常=切片面上的 2D 多边形(复用 core::Anomaly)；异常体树/删除/属性/VTK↔列表联动/显示过滤/截图属性。
• 三维体/切片详情(A58-C67)：源数据/切片/异常/插值模型(IDW·克里金)/参数/色阶/测量(点数·体积)；切片详情参照 dd_section。
• 任务管理(A90-C92)：任务记录 + 可使用任务列表(按 ds 类型过滤 model/list)。 ③ P5 二维数据集栏：底图(天地图/Google/隐藏)+2D视图位置(关闭/Z=0/顶部/底部/自定义Z)。VTK 瓦片层+EPSG:3857→GeoLocalFrame 配准(复用 TerrainActor 流程)。
• 待精修(需 Geopro 1.0 实地参考，目前无)：F26 色阶"参考1.0"、F50 异常保存框"参考1.0"。

7. ⚠️ 构建/验证铁律（务必遵守，否则重蹈本会话覆辙）

• 构建用 build.bat（已修好）。从 Git Bash 调：cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat test"。命令：app/run/test/rebuild(--clean-first 强制全量重编+启动)/configure。
• ninja 增量偶发漏编 → 改了代码却"看不到效果"时，用 build.bat rebuild 或 touch 改过的源再编；验 exe 新鲜：stat -c '%y' build/release/src/app/geopro_desktop.exe。
• 切勿 rm -rf build/release（vcpkg.json 虽已加 baseline，但重配会从源码重编 openssl/gdal/proj，慢；增量链接错用 --clean-first，别删目录）。
• .bat 必须纯 ASCII（中文 Windows cmd 按 GBK 解析 .bat，UTF-8 中文注释会让解析崩）。
• Claude 工具跑 build 会间歇被一个 Start-Process 'C:\Users\corey\...' 钩子劫持（环境问题、非项目；只影响 Claude 工具，不影响用户终端）→ 我的构建验证有时静默没跑，会误判"已更新"；交互类改动必须让用户在其终端 build.bat rebuild 实测。
• Claude 无法 GUI 测试：VTK 交互(切片/旋转/拾取)的正确性只能靠用户实测——纯逻辑(几何/相机数学)抽成单测，widget 行为靠目视。
• app 启动需登录(真实 API，tenant.geomative.cn)；勾"记住登录(30天)"可免登。
• 详见记忆 build-vs2026-vcpkg-gotchas、build-run-verify-gotchas、build-ninja-stale-shared-header。

8. 代码地图

• src/render/actors/：Scatter/GridContour/Voxel(GPU体绘制)/Anomaly(2D)/Terrain/Curtain/MapLine/Electrode/AxesActor(P2)。
• src/render/：Scene(addActor/addViewProp/clear=RemoveAllViewProps)、CameraPreset(Top2D/Free3D/applyView6向/zoomBy/fitView)、VoxelFromScatters、ColorLutBuilder、ContourBands。
• src/render/interact/(P3)：SlicePlaneMath(纯几何,有单测)、SliceTool(封 vtkImagePlaneWidget；轴向 SetPlaneOrientationTo*+MarginSize0 禁旋转；任意 Origin/Pt1/Pt2 45°可旋转；SetLeftButtonAction(SLICE_MOTION)；onInteract 选中回调)、PickInteractorStyle(自定义 Rotate 绕支点+滚轮+手动双击)、InteractionManager(切片增删/选中/滚轮/翻转/双击正视/getRotateCenter)。
• src/controller/：VtkSceneController(QObject 编排,异步回调 QPointer+generation 守护)、I3dSceneView(抽象,解耦 VTK)。
• src/data/repo/：I3dSceneRepository(异步接口:dimensionOf/loadVolume(VolumeGrid)/loadTerrainPaths,切片/异常/任务签名留位)、LocalSample3dRepository、IDatasetRepository、LocalSampleRepository。
• src/app/：VtkSceneView(I3dSceneView 实现)、main.cpp(buildWorkbench 内全部接线 + 三个浮层/工具条 + InteractionManager 创建于 ~309)。
• 测试：tests/render/(test_scene/test_camera_preset/test_axes/test_slice_plane_math)、tests/data/(test_3d_repo)、tests/controller/(test_vtk_scene_controller)。

9. 工作方式（用户偏好）

• 派 opus subagent 实现 → 完成后我亲自独立验证构建/测试 + 派 cpp-reviewer 审查 + 查 code 与 spec 符合度 → 修 CRITICAL/HIGH。
• 不要嘴上保证"编进去了"——用证据(ctest 输出、exe mtime、读改动文件)说话。
• 抠准每条需求(本会话因没抠准 G22-24/F25/D40 反复返工，务必先逐条读「补充需求」对应行)。