# VTK 三维视图「三栏结构重构」设计

- 日期：2026-06-16
- 分支：`feat/vtk-3d-view`
- 状态：**设计稿（经高保真原型逐项对齐用户反馈后定稿）**
- 上位文档：`2026-06-15-vtk-3d-supplementary-design.md`（总设计 v2）。本文是其 **A1 三栏结构** 的实现增量设计，**就 UI 形态与若干控件细节，取代总 spec §7.1 中"左侧新 dock / tab 二选一"的开放表述**。
- 高保真原型：`docs/superpowers/mockups/2026-06-16-three-column-layout.html`（深色令牌取自 `src/app/Theme.cpp`；默认即定稿方案）。
- 需求来源：`Geopro3.0 需求表.xlsx`「补充需求」页签（已逐行精读，行号见下文）。

---

## 0. 目标与范围（用户已确认）

把当前"旧二维/三维切换 + 三个浮层"的过渡态 UI，重组为需求 A1 的**三个子列表栏**，并接通到已有的渲染/交互能力。

### 本轮 IN
1. **三栏内嵌侧栏**（VTK 视图内左侧抽屉 + 三 tab + 可折叠）；删除旧「二维地图/三维视图」互斥切换；中央 dock 改名 **「VTK视图」**。
2. **收编三浮层**：左上 `layerPanel`（图层勾选）、右上 `axisBar`（P2 工具条）→ 并入「三维数据集」栏；左下 `sliceBar` → **删除**（切片改走三维分析右键菜单）。
3. **三维数据集栏**：工具条 4 栏位接 P2 已实现控制器；数据集列表按 `dimensionOf` 过滤 3D ds + 勾选 → 接现有 `VtkSceneController` 渲染。
4. **二维数据集栏**：列表按 2D 过滤；「地图 / 2D视图」控件做出来（底图瓦片渲染留 P5，本轮控件 UI + 2D 视图 Z 平面接通）。
5. **三维分析栏**：对象→三维体模型→切片 树；两个右键菜单 UI 完整；右键「切片」(上下/前后/左右/任意) **接已有 `SliceTool`**（替代 sliceBar）。
6. **VTK视图 + 数据详情** 标题栏右侧加**全屏按钮**。

### 本轮 OUT（菜单项可见但暂 stub/禁用，留 P4/P5）
- 切片 CRUD：保存 / 保存为 / 导出 / 删除（P4，`I3dSceneRepository` 接口已留位）。
- 色阶编辑（F26 参考 Geopro 1.0，无参考，留 P4）。
- 底图瓦片渲染（P5）、异常体管理 / 三维体详情 / 任务管理（P4）。

---

## 1. 核心架构决策（关键澄清）

**全工作台只有一个共享的中央 VTK 视图**，三栏是叠在其上的「子列表栏」，各自把数据喂进同一视图。证据（需求交叉验证）：
- 行 2「**VTK视图上**提供三个子列表栏」；行 11「显示在 VTK 中」；行 16「显示在 VTK 的 2D 视图」；行 19「显示在 vtk 的三维视图」——三处同指一个 VTK。
- 需求行 36「VTK视图」挂在「三维分析」下，**只是把视图交互（选中拖动旋转 / 双击正视）归类描述**，不代表视图归三维分析独有。

**推论（本轮落地）：**
- 旧「二维地图/三维视图」互斥分段按钮（`main.cpp:308-316` 一带）**删除**。
- 2D 不再是独立视图模式，而是 VTK 视图里的一个 **2D 图层/平面**（底图 + 2D 数据，摆在某 Z 平面），由「二维数据集」栏控制。
- 中央 dock 名 `二维地图/三维视图` → **`VTK视图`**（同时承载 2D/3D，且为需求原文叫法）。

---

## 2. 三栏物理形态（方案 C·视图内嵌侧栏）

- 三栏 = **VTK 视图内左侧的抽屉式侧栏**，三个 tab：`三维数据集 / 二维数据集 / 三维分析`，一次显一栏。
- 画布在侧栏右侧、**不被遮挡**；侧栏右缘有折叠开关（◀/▶），折叠后画布全宽。
- 侧栏与画布同属 VTK 视图容器（侧栏是视图子控件，符合"VTK视图上提供"）。
- 左侧保留现有 `ObjectTreePanel`（「对象」dock）作为**筛选来源**：三栏列表只在"被勾选对象"范围内、按维度过滤显示 ds（需求行 10/15）。两级关系：勾对象 → 三栏按维度显示其 ds。
- 现有左下「数据集」dock（详情查看）保留，与三栏列表并存（总 spec §7.1 已定的"两条线"）。

> 取舍记录：曾考虑"左侧独立 dock + tab"（方案 A）与"竖向分段"（方案 B），均被否——需求「VTK视图**上**」明确栏在视图内；浮窗式（最初的 C）遮挡画面亦否，改为抽屉式。

---

## 3. 各栏内容（逐行对齐需求，含控件形态）

### 3.1 三维数据集栏（行 3–11）
工具条 = **4 个分组栏位** + 数据集列表：

1. **坐标轴设置**（行 4–6）——表单式，每项一行、左对齐：
   - 显示方式：下拉（标准 / 三维立体 / 不显示）
   - O点位置：按钮（弹框设原点）
   - 刻度：下拉（无刻度 / 米 / 英尺 / 经纬度）
   - 字体：按钮（设刻度文字字体）
2. **水平/垂直比例**（行 7）——**单个拖动滑块 + 数值**（如 2.0×，纵向放大系数；现有 `kVerticalExaggeration`）。**非两个独立控件**。
3. **快捷视图**（行 8）——6 钮：前 / 后 / 左 / 右 / 上 / 下。
4. **缩放 Zoom**（行 9）——3 钮：放大(In) / 缩小(Out) / 适配(Fit)。
5. **数据集列表**（行 10–11）——`dimensionOf==Dim3D` 过滤勾选对象的 ds，勾选→渲染。

### 3.2 二维数据集栏（行 12–16）= 3 栏位
1. **地图**（行 13）——下拉（天地图 / Google Map / 隐藏）。**底图瓦片渲染留 P5**。
2. **2D视图**（行 14）——下拉（关闭 / Z=0 / 顶部 / 底部 / **自定义**）；选「自定义」显数值输入框。
   - **「自定义 Z」= 世界绝对高程（米），向上为正**，与「Z=0/顶部/底部」同坐标系（`GeoLocalFrame` 世界 Z）。决策依据：同一下拉里「Z=0」即绝对值，「自定义」只是输入任意绝对 Z；与业界（Petrel/Leapfrog/ParaView）水平面高度用项目 CRS 绝对高程一致。
3. **数据集列表**（行 15–16）——`dimensionOf==Dim2D` 过滤，勾选→渲染到 VTK 的 2D 视图。

### 3.3 三维分析栏（行 17–35）
- **数据集列表 = 树**（行 18）：对象 → 三维体模型数据集 → 切片。可勾选三维体/切片 → 渲染（行 19）。
- **右键菜单（按节点类型分派）：**

  **三维体数据集**（行 20–27，**直接项，无"创建切片"父级，无删除**）：
  | 菜单项 | 说明 | 本轮 |
  |---|---|---|
  | 切片 ▸ 上下 / 前后 / 左右 / 任意 | 一级「切片」父菜单 + 二级方向（上下/前后/左右=固定角度；任意=初始 45°可调）| **接已有 SliceTool** |
  | 色阶 | 参考 Geopro 1.0 | OUT（stub/禁用）|
  | 显示 / 隐藏 | actor 可见性 | IN |
  | 数据详情 | 详情栏显示 | IN（接现有详情）|

  > 注：需求字面是"上下切片/前后切片…"直接项；本轮按用户决策归入「切片」一级父菜单、二级去「切片」二字显「上下/前后/左右/任意」。

  **切片数据集**（行 28–35，**有删除**）：
  | 菜单项 | 本轮 |
  |---|---|
  | 保存 / 保存为 / 导出 / 删除 | OUT（P4 CRUD，stub/禁用）|
  | 色阶 | OUT |
  | 显示 / 隐藏 | IN |
  | 数据详情 | IN |

- **VTK视图交互**（行 36–38）、**切片分析**（行 39–51，含视图内切片右键：创建异常/保存/导出图片/导出dat/正视图/视图翻转/关闭）——属交互层，多已在 P3 实现或留 P4，本轮不在树结构范围内。

---

## 4. 全屏功能（新需求）

- 在 **「VTK视图」** 与 **「数据详情」** 两个 dock 标题栏右侧各加一个**全屏切换按钮**：点击→该视图充满工作区；再点→还原。
- 理由：两视图含图形、内容多，常需全屏操作。
- 实现方向（ADS）：给 `CDockWidget` 标题栏插入自定义 `QToolButton`，切换时把该 dock 最大化覆盖 dock 管理区（隐藏同级 / 浮动后最大化，择一，落地时定）。

---

## 5. 代码触点（落地指引，细节进 plan）

- `src/app/main.cpp::buildWorkbench`：
  - 删 `layerPanel` / `axisBar` / `sliceBar` 三浮层及其锚定器（`RightTopAnchor`/`BottomLeftAnchor`）与 `showLayerPanel` 显隐逻辑。
  - 删旧「二维地图/三维视图」分段切换；`vtkDock` 改名「VTK视图」。
  - VTK 视图容器内新建**抽屉侧栏**（QTabWidget 或自绘，三 tab）+ 折叠开关；三栏工具条/列表迁入。
  - **dock 布局持久化版本号须 bump**（见 `main.cpp:1429` 附近注释：改 dock 名/结构要升版本，否则旧布局反序列化错位）。
- 三维数据集工具条接 P2 已实现的 `VtkSceneController` 坐标轴/比例/快捷视图/zoom 槽（原 axisBar 的接线迁移，不重写控制器）。
- 数据集列表：用 `I3dSceneRepository::dimensionOf` 过滤；勾选信号接 `VtkSceneController`（复用现 `checkedTmsChanged` 一路的编排）。
- 三维分析树右键「切片」→ 调已有 `InteractionManager`/`SliceTool` 建切片（替代 sliceBar 原按钮路径）。
- 全屏按钮：ADS 标题栏自定义按钮 + 最大化/还原。

---

## 6. 待定 / 风险

- 全屏在 ADS 的最大化实现方式（隐藏同级 vs 浮动最大化）落地时定。
- 二维「地图」底图本轮仅控件，渲染 P5；需确保控件状态能持久化到 P5 不返工。
- 三栏侧栏与 ADS dock 的交互（侧栏是 VTK 容器子控件，不是 dock）——确保折叠/全屏时布局正确。
- dock 名变更后旧用户布局失效（bump 版本号后回落默认排布，可接受）。