# P2：三维数据集栏（坐标轴 / 比例 / 快捷视图 / Zoom）

- 日期：2026-06-15
- 分支：`feat/vtk-3d-view`
- 上游：spec `2026-06-15-vtk-3d-supplementary-design.md`（§4 行 C3–C8、§5.3、§7.2）；接 P1（`VtkSceneController`/`I3dSceneView`/`VtkSceneView` 已就位）
- 目标：给三维视图加一组**纯前端、无后端依赖**的相机/坐标轴/比例控件（补充需求"三维数据集栏"工具条的功能项）。P1 已让中央渲染复活，P2 让用户能调坐标轴、纵向比例、快捷视角、缩放。

## 范围
**范围内**：
- **快捷视图**（C7）：前/后/左/右/上/下 6 向相机预设 + **Zoom In/Out/Fit**（C8）。
- **水平/垂直比例**（C6）：可调纵向夸张（复用 P1 已有 `VtkSceneController::setVerticalExaggeration`），UI 滑块/输入；范围如 1–10，默认 2。
- **坐标轴**（C3–I5）：显示方式 标准/三维立体/不显示；刻度单位 无/米/英尺/经纬度；O 点位置；字体。
- 控件挂到三维视图工具条/浮层（**不做**完整三栏 tab 重构——留后续 UI 期；本期控件先以工具条形式接入现有三维视图）。

**范围外/后续**：三栏 tab 结构重构、二维数据集栏底图（P5）、三维分析切片（P3）。

## 关键设计
- **CameraPreset 扩展**（`src/render/CameraPreset.*`）：`applyView(vtkRenderer*, ViewDir)`，`ViewDir∈{Front,Back,Left,Right,Top,Bottom}`，设 position/focalPoint/viewUp 后 `ResetCamera`；`zoomBy(vtkRenderer*, factor)`（In=1.2/Out=1/1.2），`fit(=ResetCamera)`。世界系：x=East,y=North,z=-depth（与 actor 一致）。
- **坐标轴**（新 `src/render/actors/AxesActor.*` 或 `CubeAxes.*`）：
  - 标准 = `vtkCubeAxesActor`（包围盒 + 刻度 + 标签）；三维立体 = `vtkCubeAxesActor` 闭合立方/或叠加 `vtkAxesActor` 方向标（**语义待 1.0 确认，先合理近似**）；不显示 = 不加。
  - 刻度单位：米(原值)/英尺(×3.28084)/经纬度（用 `GeoLocalFrame` 反算）/无（隐藏刻度标签）。
  - O 点：默认数据包围盒角；字体：`SetTitleTextProperty/SetLabelTextProperty` 设字号字体。
  - 输入 = renderer bounds + frame；产出 `vtkSmartPointer<vtkCubeAxesActor>`，由 `I3dSceneView` 加入场景（经 `addViewProp`）。
- **GeoLocalFrame 补反算**：`LocalXY → (lat,lon)`，加 `toLatLon(double x,double y)`（等距圆柱反算：lon=lon0+x/mPerDegLon，lat=lat0+y/mPerDegLat）。
- **I3dSceneView 扩接口**：`setAxes(mode,unit,font,...)`、`applyCameraView(ViewDir)`、`zoom(factor)`、`fitView()`；`VtkSceneView` 实现，fake 测试记录。
- **VtkSceneController**：加 `setAxesMode/setAxesUnit/...`、`applyView/zoomIn/zoomOut/fit` 槽，转发给 view；坐标轴在 rebuild 时按当前模式重建（轴随数据包围盒变）。

## 步骤（TDD）
0. 基线：`build.bat test` 全绿。
1. **GeoLocalFrame.toLatLon**（TDD）：往返 `toLocal∘toLatLon≈恒等` 测试。
2. **CameraPreset 6 向 + zoom**（TDD）：各 ViewDir 断言 position/focalPoint/viewUp 方向正确（如 Top: pos.z>focal.z、viewUp=+y；Front: pos.y<focal、viewUp=+z 等）；zoomBy 改变 parallelScale/距离。
3. **AxesActor 构建**（TDD）：给定 bounds+unit 产出 vtkCubeAxesActor，断言单位换算（英尺/经纬度标签）、不显示返回空。
4. **I3dSceneView 扩接口 + VtkSceneView 实现 + 控制器槽**（TDD 控制器编排：fake view 断言 axes/camera 调用）。
5. **UI 接入 main.cpp**：三维视图工具条加 坐标轴下拉/刻度下拉/比例滑块/6 向快捷钮/Zoom 钮；连到控制器槽。仅三维模式显示该工具条。
6. `build.bat test` 全绿 + `build.bat app` 链接通过；目视清单交用户。
7. cpp-reviewer 审查 + 提交。

## 风险/注意
- **Ninja/工具链**：增量构建若链接错用 `cmake --build build\release --clean-first`（保留 cache），**勿删 build 目录**（vcpkg baseline 已修但仍按记忆 [[build-vs2026-vcpkg-gotchas]] 谨慎）。
- 坐标轴 "标准 vs 三维立体" 语义无 1.0 参考 → 先合理近似，UI 可切换，待 1.0 实地学习再精修（记忆 [[study-original-via-playwright]]）。
- 经纬度刻度仅在有 frame 配准的 3D 世界系下有意义；纯剖面坐标系下退化为米。
- 比例滑块改变 → 控制器 setVerticalExaggeration → 全 3D actor SetScale 同步（P1 已统一）。
- 字体：中文标签需可用字体；VTK 文本默认 Arial，中文可能缺字形 → 标签用数字/英文单位优先。