gaozheng
/
geopro
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat/vtk-3d-view #7

Merged
gaozheng merged 301 commits from feat/vtk-3d-view into main 2026-06-27 18:43:52 +08:00
Conversation 0 Commits 301 Files Changed 425 +55844 -1148
425 changed files with 55844 additions and 1148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
.gitignore vendored
View File

@ -9,7 +9,11 @@ CMakeUserPresets.json
/vcpkg/ /vcpkg/
# ---- external source-built deps (方案②-修订: VTK 源码编到 install 前缀) ---- # ---- external source-built deps (方案②-修订: VTK 源码编到 install 前缀) ----
/external/ # 用 /external/* 而非 /external/ 忽略目录内容，使下方 vendored 子目录可被例外重新纳入
# (git 无法重新纳入被整体忽略目录内的文件)。
/external/*
# 例外：vendored 3DGPRViewer 数据生成链(原样拷贝的算法源码，版权自有)需入库。
!/external/gpr3dviewer/
# ---- Visual Studio / IDE ---- # ---- Visual Studio / IDE ----
.vs/ .vs/
@ -47,3 +51,8 @@ docs/_validate/
# ---- Large redundant archive (sample data kept unpacked in folder) ---- # ---- Large redundant archive (sample data kept unpacked in folder) ----
docs/剖面网格数据的色阶数据2等文件.tar docs/剖面网格数据的色阶数据2等文件.tar
# ---- Installer build artifacts (生成物，见 installer/README.md) ----
/installer/staging/
/installer/dist/
/installer/redist/

67
.superpowers/sdd/task-12b-report.md Normal file
View File

@ -0,0 +1,67 @@
# Task 12b 报告：SetPartitions 单 mapper fps 去风险探针
## 状态
完成（探针真实跑出，结论：渲出但未达交互级）。
## 实测环境与数据
- store（9c/12 同款单线全分辨率整卷）：`D:\Git\lanbingtech\geopro\build\tmp\gpr_store_B_001`
- 整卷维度：44476 × 29 × 162 = 208,948,248 体素，417,896,496 B（398.5 MB，VTK_SHORT）
- 离屏渲染（vtkRenderWindow SetOffScreenRenderingOn），硬件加速 OpenGL（offscreen-smoke 闸门 OK）。
## 实现要点（tools/gpr_poc/main.cpp 新增 `renderC-partitioned` 子命令）
- WholeVolumeSource 重组**整卷单个** vtkImageData（不预切块）。
- 关键：`vtkGPUVolumeRayCastMapper` 抽象基类**无** `SetPartitions`；该 API 在 OpenGL 具体实现
`vtkOpenGLGPUVolumeRayCastMapper`（工厂默认产物）上。故直接建该具体类，
`SetInputData(整卷)` + `SetPartitions(ceil(nx/16384),1,1)`。
- 分区数：沿线 44476 → `ceil(44476/16384)=3`（每区 ~14826 ≤16384）；ny=29、nz=162 → 1。
实测 `SetPartitions(3,1,1)`。
- 量化域传函复用现有 `makeI16VolumeProperty`（qmin/qmax、kBlank 透明、q.toPhys 反查 ColorScale）。
- 双闸（同 9c，绝不把空纹理假帧率当性能）：
① CapturingOutputWindow 捕获 3D 纹理维度错误；
② 真实回读像素统计非背景像素。
- 相机修正：整卷极扁长（44476:29:162），首版用 `ResetCamera()` 全体 + 仅取末帧像素时，
末帧恰好边缘视角 → 误报“非空像素=0”。修正为：以 mapper 包围盒定向 + 抬高/旋转视角让薄维度可见，
且旋转扫描中**多帧采样非背景像素取最大值**（区分“真渲不出”与“采样时机不巧”）。修正后稳定渲出。
## 核心结论：SetPartitions 单 mapper 是否真渲出 + fps + 内存 + 分区数
- **分区数**：SetPartitions(3, 1, 1)。
- **是否真渲出**：**是**。无纹理维度错误（SetPartitions 成功绕过 GL_MAX_3D_TEXTURE_SIZE=16384 纹理墙），
真实回读非背景像素 1264（非空），一个 mapper 一次 ray cast。
- **体绘制 fps**：**~8.8 ~ 11 fps**（多次实测 8.84 / 10.95 / 10.59，落在 8.8–11 区间）。
- **峰值进程内存**：~556 ~ 653 MB（整卷 398.5 MB 常驻 + 渲染开销）。
## 对照表
| 路径 | 是否渲出 | fps |
|---|---|---|
| renderB 整卷单 SmartVolumeMapper | INVALID（纹理墙，沿线 44476>16384） | — |
| renderC MultiBlock（每块一 mapper） | 渲出 | 9.5 静态 / 1.45 换页 |
| **renderC-partitioned 单 mapper SetPartitions** | **渲出** | **~8.8–11（静态整卷）** |
## 是否达交互级
**否**。目标 ≥15~30 fps，实测 8.8–11 fps，低于交互级下限。
## 判据落点
- “对的架构”（单 mapper + SetPartitions）**确实绕过了纹理墙、确实把全分辨率整卷一次性渲出**——
这点比 9c（INVALID）与 12（每块一 mapper）都更干净，证明架构方向正确。
- 但**纯 GPU ray cast 静态整卷 fps 仍只有 ~9–11**，与 renderC MultiBlock 的 9.5 静态 **基本同档**，
未拉开差距、未到交互级。即：**“每块一 mapper”不是 9.5fps 的主要元凶；瓶颈在 208M 体素全分辨率
整卷的 ray cast 本身**（采样量 + 显存带宽），单 mapper 分区并不能把它变快。
- 结论：**VTK 这条路（整卷全分辨率体绘制）的交互级天花板在本数据上已暴露**。要到交互级，
production C 必须靠 LOD/降采样/核外换块（动态分辨率），而非寄望“单 mapper 分区”本身提速。
brief 判据的“仍不到 → 评估 OpenVDS/自建 GL”一支成立。
## concerns
1. **fps 受相机框选与视图影响**：8.8–11 的波动主要来自每帧旋转中视线穿过体的采样深度差异；
该数为“静态整卷、绕轴旋转”口径，已剔除换页/解压（不像 renderC 动态 1.45 含 update）。
作为“单 mapper 分区静态整卷 fps 天花板”是诚实的，但生产中真实 fps 还会被交互缩放/平移影响。
2. **首版“空渲染”教训已修正**：极扁长体 + 末帧单采样会假报空；现多帧取最大 + 视角抬高，已稳定非空。
报告口径据此可信。
3. **本探针只验静态整卷**（遵 YAGNI，未做 LOD/换块/后台解压）。production C 的动态分辨率方案
还需单独验证其在“降采样后”能否到交互级——这是下一根要验的链子，不在本探针范围。
4. SetPartitions 在 9.6 属 `vtkOpenGLGPUVolumeRayCastMapper`（非抽象基类）；若后续 VTK 升级
该 API 位置变动需留意。
## 交付物
- 代码：`tools/gpr_poc/main.cpp`（新增 `renderC-partitioned` 子命令）。
- 结果：`docs/superpowers/plans/poc-results-C.md`（含对照表与判据结论）。
- 报告：本文件 `.superpowers/sdd/task-12b-report.md`。

80
.superpowers/sdd/task-12c-report.md Normal file
View File

@ -0,0 +1,80 @@
# Task 12c 报告：LOD-fps 探针（全量交互渲染最后一根链子）
## 状态
**完成 / PASS** —— 四件事(a/b/c/d)全做，双闸通过（无纹理维度错误 + 三段均回读非空像素），
真实实测，未编造。LOD-based C 路线在本机判据下钉死可行。
## 实测数字（本机 RTX 3060 Laptop GPU，离屏，frames=120，多次重跑稳定）
| 项 | 维度 | 结果 | 交互级判据 |
|---|---|---|---|
| (a) 粗层概览 fps | level2 整卷 11119×8×41 (~3.6M 体素) | **~752 fps**（多跑 590~759） | ✔ 远超 ≥30 |
| (b) 全分辨率局部 fps | level0 局部 256×29×162 (~120 万体素，4 brick 列) | **~380 fps**（多跑 374~422） | ✔ 远超 ≥30 |
| (c) LOD 切换过渡 | 切换帧 60/120，从远观(level2)dolly 拉近到近观局部(level0) | 平均 **1.09ms/帧**，切换帧 **~5.5ms**（尖峰 ~6×邻帧），最大 ~6.95ms | 无可感知卡顿 ✔ |
- **粗层概览 fps**：~752 fps（达交互级 ✔）
- **全分辨率局部 fps**：~380 fps（达交互级 ✔）
- **LOD 切换过渡帧耗时 / 是否卡顿**：切换帧 ~5.5ms（仍 <1 个 60Hz 帧 16.7ms）→ **无可感知卡顿**
- **截图路径**：`docs/superpowers/plans/poc-lod-shots/`
- `lod-overview.png`（level2 整线概览，全 2200m 线呈细带）
- `lod-fullres-local.png`（level0 局部，全分辨率板面有细节）
- `lod-transition-mid.png`（切换后推近的过渡中间帧）
- **是否都达交互级**：**是**。(a)/(b) 均 >>30fps；(c) 切换无可感知卡顿。
## 设计与诚实测法
- 在真实金字塔 store（`gpr_poc build ... --levels 3`，level0=44476×29×162，
level1=22238×15×81，level2=11119×8×41，level3=5560×4×21）上跑，非合成。
- (a)/(b)：把对应 level 的所有 brick 重组成单张 VTK_SHORT vtkImageData
（逻辑同 `WholeVolumeSource`，按 level 维度 + spacing×2^level / 局部段 X 偏移），
喂 `buildVoxelI16FromImage`（SmartVolumeMapper，GPU 路径），旋相机 120 帧测 fps。
level2/局部段单轴均 <16384 → 单 3D 纹理可成，无纹理墙。
- (c)：同一窗口，相机从远观（level2 整卷）dolly 拉近；第 60 帧跨越 LOD 切换那一下
把体从 level2 概览换成 level0 局部 + 焦点移到局部段中心，**逐帧记帧耗时**，
标切换帧尖峰。这是审核人加的验收点①（测切换动态，非两端静态）。
- (d)：`vtkWindowToImageFilter`+`vtkPNGWriter` 存 3 张 PNG，供人眼判
“概览糊→拉近清晰”（审核人验收点②）。
- **双闸（同 9c，绝不把空纹理假帧率当性能）**：
① `CapturingOutputWindow` 捕获 3D 纹理维度错误（实测=否）；
② 真实回读前缓冲像素，统计非背景像素（概览 1889 / 局部 167612 / 过渡 21924，
三段均非空）。两闸全过，fps 可信。
## 卡顿判据说明（避免误报）
切换帧含一次性建 actor / 换 mapper 输入，~5.5ms，是邻帧(~0.9ms)的 ~6×；但绝对值
仍 < 1 个 60Hz 帧(16.7ms)，人眼不可感。故采用**绝对耗时判据**：切换帧 >33ms(2 帧)
才记“可感知卡顿”，16.7~33ms 记“轻微抖动”，亚毫秒基线下尖峰倍数虽大但绝对值低不算
卡顿。本机切换帧 ~5.5ms → 无可感知卡顿。
## 判据结论
粗层概览 + 全分辨率局部**都达交互级**（≥30fps，远超）且切换**无不可接受卡顿**
→ 命中 brief 第一条判据：**LOD-based C 路线钉死可行**。
对照 12b：整卷全分辨率 ray cast(2.08 亿体素)~10fps 是硬上限；本探针证实
“渲更少体素 = LOD” 这根杠杆有效——粗层 ~752fps、全分辨率局部 ~380fps，两端都远
在交互级，且 LOD 切换瞬态 ~5.5ms 无卡顿。
## 最低配未验声明（审核人验收点③）
本探针**仅在本机（RTX 3060 Laptop GPU，NVIDIA 555.97，OpenGL 4.5）跑得上限数字**。
**最低配机器未验证**，需用户在目标机跑 `gpr_poc renderLOD <store>` 或提供型号后再评估。
本机数字是上限，最低配可能更低。
## 进程峰值内存
~99 MB（探针逐 level 重组单张 image，未常驻整卷；level0 局部仅取 4 brick 列）。
## Concerns
1. **截图视觉偏暗/偏细**：体绘制 `kMaxOpacity=0.15`（复用探针传函）+ 整线物理纵横比
极扁（2200m × ~1.5m × 8m），故概览图中整线呈一条细带、过渡中间帧呈小斜板。
这是物理真实呈现（整线本就是长薄带），非渲染缺陷；但作为“人眼判可接受度”素材
偏素净。若需更醒目的生产视觉，需后续调传函不透明度/着色与取景，超出探针范畴(YAGNI)。
2. **(c) 为单次脚本化切换**：测的是“从 level2 直切 level0 局部”一次硬切的瞬态；
生产里多级连续 LOD/视野自适应的换页节奏、预取与 morphing/淡入是探针过了之后的
工程（brief 明确不在本探针范围）。
3. **(b) 局部仅取 4 brick 列(256 体素宽)**：证“全分辨率局部块快”；若生产需更宽的
全分辨率窗口（仍需 <16384 或分区/分块），fps 会随体素数下降，需届时按窗口大小复测。
4. **最低配仍是最大未知**（见上声明）。

53
.superpowers/sdd/task-12d-fix-report.md Normal file
View File

@ -0,0 +1,53 @@
# Task 12d-fix 报告：修 gpr_poc view 空窗 + 控制台乱码
## 状态
DONE。两 bug 均修复，构建通过（Community vcvars64 直驱 ninja，exit 0），离屏自检通过。
## 提交短哈希
`1495d0e`（feat/vtk-3d-view 分支）
## 改动文件
仅 `tools/gpr_poc/main.cpp`（+70 -1）。
### Bug 1：概览空窗（LOD 策略错）
- 根因：`view` 每帧 `viewRefreshBlocks` 无脑走分块路径，相机概览时 `pickLevel` 选 level1（696 块）被 budget=64 砍到 64/696（9% 稀疏）→ 看着空。
- 修复：`viewRefreshBlocks` 按相机选中 level 分流（同 12c renderLOD 已验）：
- 相机选中 **level0**（最近、要全分辨率，X=44476 无法成单纹理）→ 分块 + budget（核外 LRU，原路径不变）。
- 相机选中 **level≥1**（概览/中远）→ `wholeVolumeLevelFor` 从 picked 起向粗找第一个“整卷各轴 ≤16384”的层（本数据 level0/1 的 X=44476/22238>16384 → 升 level2），用 `buildLevelImage` 整卷重组单张 image，单块喂 mapper（忽略 budget，粗层本就小）。整卷 image 按 level 缓存，仅 level 变化时重组。
- 效果：概览不再是 64/696 稀疏块，而是 **1 个整卷块**渲染完整体。
### Bug 2：控制台中文乱码（GBK）
- 修复：`main()` 入口 `#ifdef _WIN32` 下 `SetConsoleOutputCP(CP_UTF8);`（含 `<windows.h>`）。保留全文件已有中文输出，全子命令受益。
## 离屏自检结果（view --smoke，tmp\store_lod_001）
修复前：
```
[view] 预热: level=1 视野块=696/696 驻留=64 渲染块=64 ← 64/696 稀疏
```
修复后：
```
[view] 预热: level=1 视野块=696/696 驻留=64 渲染块=1 ← 整卷单块(升 level2)
=== view --smoke 离屏冒烟 ===
近观 level=1 → 拉远 level=3 → 再拉近 level=1
LOD 随缩放切换 : 是 ✔ (blocksFar=1)
纹理维度错误 : 否
渲出非空像素 : 是 (近=1024000 远拉近=1024000)
smoke 结果 : OK ✔ 不崩
```
- **概览渲染块 64 → 1（整卷）**：核心修复，整卷完整渲染而非 9% 稀疏。
- 渲出非空像素：是（1024000，无纹理错、不崩）。注：该视角整卷与原稀疏块均填满帧，像素计数饱和，故区分性证据是“渲染块 64→1（整卷）”。
- **编码正常**：`=== view --smoke 离屏冒烟 ===` 等中文在 UTF-8 控制台正确显示，无 GBK 乱码。
## 提交干净性确认
- `git diff --cached --stat` 提交前确认 index 仅含 `tools/gpr_poc/main.cpp`，无 chart/scatter/quill/rangeslider/Dialog/FormK 等并行会话文件。
- 仅 `git add tools/gpr_poc/main.cpp`（及本报告），绝无 `git add -A`。
## 给用户的重跑命令
真窗口交互（开窗即见完整粗层体，滚轮拉近变清晰/分块）：
```
build\release\tools\gpr_poc\gpr_poc.exe view tmp\store_lod_001 --exagg 8 --opacity 0.6
```
离屏自检：
```
build\release\tools\gpr_poc\gpr_poc.exe view tmp\store_lod_001 --exagg 8 --opacity 0.6 --smoke
```

45
.superpowers/sdd/task-12d-polish-report.md Normal file
View File

@ -0,0 +1,45 @@
# Task 12d-polish 报告：梯度不透明度 + 光照 打磨探针
## 状态
完成。真实离屏渲染、真实 fps，无编造。三张对比图均通过双闸（无 3D 纹理维度错 + 渲出高于背景像素）。
## 命令
`gpr_poc polish tmp\store_lod_001 --frames 90`（默认取景 El45/Az30/Zoom1.5「斜穿俯视」，视线从上方斜穿体内部而非只看端面）。
## 测试体
- 全分辨率 level0 局部段：256 x 29 x 162（沿线中段 4 brick 列 [345,349)/695），垂向夸张 exagg=8（放大薄 Y/Z 轴使截面可读）。
- 三图标量传函/配色/取景/夸张全相同，唯一变量是「梯度不透明度 / 光照」。
## 梯度幅值分布（量化域，中心差分，545211 样本，按实测标定阈值）
median=5.32，p75=20.1，p90=196.2，p99=9058.5，max=21470。
梯度不透明度 piecewise（按此分布标定，非猜）：grad≤5.32→0.0、grad=196.2(p90)→0.5、grad≥9058.5(p99)→0.9。
即：占多数的低梯度均匀区透明，仅高梯度处（层界面）不透明。
标量不透明度峰值：基线 a=0.15（与默认体绘制同档→白雾）；b/c 梯度门控压住均匀区后提到 0.6，让层界面净不透明度（标量×梯度）足够高、层面成实面。
## 三张对比图（docs/superpowers/plans/poc-lod-shots/）
| 图 | 路径 | 高于背景像素(>35) | 结构像素(>50) | 平均亮度(0-255) | fps |
|---|---|---|---|---|---|
| a 基线白雾 | polish-a-value.png | 219980 (21.5%) | 145874 (14.2%) | 20.07 | 160.8 |
| b +梯度不透明度 | polish-b-grad.png | 50358 (4.9%) | 36430 (3.6%) | 15.71 | 58.2 |
| c +梯度+光照 | polish-c-grad-shade.png | 25008 (2.4%) | 756 (0.07%) | 14.81 | 57.3 |
光照参数（c）：ShadeOn，Ambient 0.3 / Diffuse 0.7 / Specular 0.2 / SpecularPower 10。
## 目视结论：内部层是否「浮」出来了？
**部分浮出来了，但不是全身——这正是层状数据的固有限制。**
- **a（基线）**：一根平滑均匀的灰蓝色长条，没有任何内部层次，只有端面隐约可辨——就是需求描述的「体中间均匀白雾、只端面有层次」。穿透均匀水平层积分成雾。
- **b（+梯度不透明度）**：体的大部分（沿线中段那段均匀体）变透明、白雾消失，**端部/过渡区露出清晰的水平层状条纹**（层界面），底部另现一块淡蓝层状斑。证实：梯度不透明度确实把均匀积分雾抹掉、把层界面显出来了。
- **c（+梯度+光照）**：在 b 基础上端部层条纹带上轻微立体明暗（层带有了明暗起伏的层次感），但 shading 整体压暗，可见区更少更暗。
**关键如实结论**：梯度不透明度 + 光照**能消除均匀白雾、并让「确有梯度突变的层界面」浮出成可读的层状条纹**——打磨方向有效。**但对这条道路 GPR 数据，强梯度集中在端部/过渡区；沿线的长段水平层因「沿测线方向看过去是均匀的」（梯度低）会整段变透明，而不会显出层。**所以打磨**改善了「层界面可见性」**，但**无法让整条体内部都「长出层」——长均匀段的内部偏雾/偏空是层状数据本身的固有属性，不是没打磨。** 想看长段内部层，应配合切片/正交截面，而非纯体绘制穿透积分。
## fps 代价
梯度不透明度需逐采样点算梯度，fps 从基线 160 降到 ~58（约 -64%），但仍远高于交互级 15fps，**可接受**。光照（c）相对 b 近乎免费（58→57）。本机 RTX 3060 数；最低配未验。
## 提交自检
- 仅 `git add` tools/gpr_poc/main.cpp + 3 张 polish-*.png + 本报告；未 `git add -A`。
- `git diff --cached --stat` 确认无 chart/scatter/quill/rangeslider/Dialog/FormK。
- 未改任何交互默认（探针性质，仅新增 polish 子命令与三个 polish 专用辅助函数）。

173
.superpowers/sdd/task-12d-report.md Normal file
View File

@ -0,0 +1,173 @@
# Task 12d 收尾探针报告 —— 视觉调优 + fps 预算 + 可交互开窗
实测环境: 本机 RTX 3060 / VTK 9.6 / MSVC+Ninja。store: `tmp/store_lod_001`
(level0 = 44476×29×162, 4 层金字塔, brick=64, 2.09 亿体素)。
所有数字为真实离屏实测, 双闸(纹理错捕获 + 回读非空像素)防假帧率。
---
## 状态
完成。三件事全部落地、编译通过、离屏实测出数:
- ① `tune` 视觉调优: 出 `lod-tuned-local.png` / `lod-tuned-overview.png`, 打印调优前后 fps 对照。
- ② `fps-budget`: 递增全分辨率窗口 fps 表 + 每帧体素预算结论。
- ③ `view`: 真窗口 + interactor + 缩放切 LOD + 屏幕 fps 文本; 离屏 `--smoke` 通过不崩。
改动文件: `tools/gpr_poc/main.cpp` (新增 3 个子命令 + 视觉调优共享构件), 新增两张调优截图,
追加写 `docs/superpowers/plans/poc-results-C.md`。
---
## ① 视觉调优: 调优前后 fps 对照(证实视觉调优 fps 近乎中性)
`gpr_poc tune <store> --opacity 0.7 --exagg 8 --localBricks 4` (level0 256×29×162 局部段):
| 配置 | 色阶 | 不透明度 | 垂向夸张 | 局部 fps |
|---|---|---|---|---|
| 调优前(基线) | 蓝-白-红线性单斜坡 | 0.15 | 1× | 323.3 |
| 调优后 | 结构色阶(深蓝→青→白→黄→红) + 双端斜坡 | 0.7 | 8× | 349.2 |
**fps 变化 = −8.0%(即调优后反而更快)**。完全证实探针认知:
- 隔离实验(`--exagg 1`): 不透明度 0.15→0.5/0.6、换结构色阶, fps −5.5%(更快)。
→ **配色/不透明度对 fps 近乎中性, 调高不透明度甚至更快(光线提前终止)。**
- 隔离实验(`--opacity 0.9 --exagg 10`): fps 反而 +49%(更快)。
双端斜坡把占多数的近零背景设透明, 不透明片段少 + 提前终止, 抵消了夸张放大的屏占。
- 早先一版"线性单斜坡 + exagg 8"曾掉 34%, 经排查 **掉帧全部来自垂向夸张(8× 放大薄轴
→ 屏占变大 → ray-cast 片段变多), 与不透明度/配色无关**。改用双端斜坡(背景透明)后
即转为净加速。
**关键视觉修复**: GPR/地震体值集中在零附近(背景), 强反射在正负两端。原线性单斜坡让
近零背景填满体、遮住结构(实测渲出一块均匀蓝板, 无结构)。改为**双端斜坡(中段透明 +
正负两端不透明)** 后, 截面的层状反射(地层条带)清晰可辨。
调优截图:
- `docs/superpowers/plans/poc-lod-shots/lod-tuned-local.png`
—— 全分辨率局部段, 可见多条水平层状反射条带(地层结构)+ 一处相干蓝色异常体。
- `docs/superpowers/plans/poc-lod-shots/lod-tuned-overview.png`
—— 粗层(level2)概览。物理真实: 整线 2.2km×1.5m×8m 极扁, 概览就是一条细带(可接受)。
> 诚实说明: 体物理纵横比极端(X≈2.2km vs Y≈1.5m / Z≈8m), 即便取局部段 + 8× 夸张,
> 单帧里结构仍偏小、偏一隅, 背景大片黑。结构确实可辨(层状条带 + 异常体), 但"一眼炸裂"
> 受物理形态限制——这正是 brief 预期的"细带本质"。production 可配可调色阶/取景控件让
> 用户交互找最佳视角(即 ③ view)。
---
## ② fps 预算: 递增全分辨率(level0)窗口 → 每帧体素预算
`gpr_poc fps-budget <store> --bricks 4,16,64,128,256,512,695 --frames 90`
(沿线中段递增 brick 列, 单 image 整段体绘制, 双闸):
| brick 段 | 维度 | 体素数 | 体绘制 fps | ≥30 | 备注 |
|---|---|---|---|---|---|
| 4 | 256×29×162 | 1,202,688 | 218.3 | 是 | |
| 16 | 1024×29×162 | 4,810,752 | 155.7 | 是 | |
| 64 | 4096×29×162 | 19,243,008 | 240.9 | 是 | |
| 128 | 8192×29×162 | 38,486,016 | 305.8 | 是 | |
| 256 | 16384×29×162 | 76,972,032 | 329.7 | 是 | 触达 GL_MAX_3D_TEXTURE_SIZE=16384 |
| 512 | 32768×29×162 | 153,944,064 | INVALID | 否 | X=32768>16384, 纹理墙, 双闸标 INVALID |
| 695 | 44476×29×162 | 208,948,248 | INVALID | 否 | 同上 |
### 每帧体素预算结论(重要, 与 brief 框架略有出入但更真实)
- **fps 在所有可上传测点(≤16384 单轴)始终 ≫ 30(218~330fps), 全程没跌破 30。** fps 不随
体素数单调下降(甚至上升), 因 ray-cast 成本主要由屏占 × 采样步长决定, 而薄维度(Y29/Z162)
使光线路径短, 单 3D 纹理上传成功后体素总数不是瓶颈。
- **真正的硬墙是 GL_MAX_3D_TEXTURE_SIZE = 16384**: 单轴超 16384 → 整段无法成单张 3D 纹理
(512/695 行双闸正确判 INVALID, 绝不当真上报)。
- 因此本数据集上, **"单张 3D 纹理的每帧体素预算" = 单轴 ≤16384 → ≈ 7700 万体素(256 brick 列)**
跑 ~330fps 仍极宽裕; **限制 production LOD 每帧块数的不是 30fps 阈值, 而是 16384 纹理墙——
超墙必须切块(MultiBlock / SetPartitions / 本机核外 OutOfCoreSource)。**
- fps 驱动的体素预算(跌破 30)只会在远更大/更稠密体或多块叠加渲染时出现; 本数据集薄维度下
GPU 余量充足, 未触达。
> 这与 brief"找 fps<30 阈值"的设想不同, 但是实测真相: **本数据集的命门是纹理尺寸墙,
> 不是帧率墙**。如实记录。
---
## ③ `gpr_poc view <store>` —— 真窗口可交互(给用户肉眼测 + 最低配机跑)
实现要点:
- 真 `vtkRenderWindow` + `vtkRenderWindowInteractor`(`vtkInteractorStyleTrackballCamera`),
挂 `OutOfCoreSource`(核外 LOD + 视野选块, budget 限驻留, 内存恒定)。
- 相机变化(`EndInteractionEvent`)→ `source.update(camera)` 重选 LOD/视野块 → 重建 MultiBlock
→ 重渲。**缩放跨越距离/对角线档位时 LOD 真切换**(离屏 smoke 实测 level 1↔0 切换)。
- 屏幕左上角 `vtkTextActor` 实时显示 `fps | LOD level | blocks | exagg`, 每帧更新。
- 默认结构色阶 + 双端斜坡不透明度 + 垂向夸张(同 ①)。
- 参数: `--exagg N --opacity F --budget K`(K=每帧最大全分辨率块数, 接 ② 预算)。
离屏 smoke(`view --smoke`)实测:
```
预热: level=1 视野块=696/696 驻留=64 渲染块=64
近观 level=1 → 拉远 level=1 → 再拉近 level=0
LOD 随缩放切换 : 是 ✔
纹理维度错误 : 否
渲出非空像素 : 是 (近=1024000 远拉近=1024000)
smoke 结果 : OK ✔ 不崩
```
### view 命令用法
```
gpr_poc view <storeDir> [--exagg 8] [--opacity 0.6] [--budget 64] [--smoke]
```
- 不带 `--smoke` = 开真窗口可交互(留给用户跑)。
- 带 `--smoke` = 离屏建管线 + 模拟缩放验 LOD 切换 + 验不崩(CI/无显示环境用)。
---
## 给用户的肉眼测试说明(请转达用户)
**启动命令**(在已构建的仓库根目录):
```
build\release\tools\gpr_poc\gpr_poc.exe view tmp\store_lod_001 --exagg 8 --opacity 0.6 --budget 64
```
- DLL/PATH: 无需手设。CMake 已把 VTK/Qt 等运行时 DLL 拷到 exe 旁(`gpr_poc.exe` 同目录),
直接双击/命令行运行即可。
- 若换其它 store, 把 `tmp\store_lod_001` 换成你的金字塔 store 目录(需先 `gpr_poc build ... --levels 3`)。
**操作:**
- **滚轮**: 向前滚拉近 → 应看到全分辨率结构(屏幕 `LOD level` 数字变小, 0=最细);
向后滚拉远 → 变粗层概览(level 数字变大, 体变糊)。
- **左键拖动**: 旋转视角(TrackballCamera)。
- **q 键 / 关窗**: 退出。
**判断点(可接受标准):**
1. **拉近后能否看清地质结构**: 局部段应呈现水平层状反射条带(地层)+ 可辨的相干异常体。
能看出层次即可接受(受物理细带形态限制, 不会像规则立方体那样饱满)。
2. **概览(细带)可不可接受**: 拉远后是一条细长带(整线 2.2km×1.5m×8m 物理真实), 接受它是细带。
3. **拉近/拉远切 LOD 时卡不卡、糊→清过渡能不能接受**: 切换应顺滑, 无明显卡死/长 stall
(本机切换 ~5-9ms, 远小于 1 个 60Hz 帧 16.7ms, 不可感)。
4. **屏幕 fps 是否 ≥30**: 屏幕左上角实时 fps。本机(RTX 3060)远超 30(数百 fps);
**最低配机重点看这条**——拉到最细 LOD、最大夸张时 fps 是否仍 ≥30。
**最低配怎么跑:**
- 把整个 `build\release\tools\gpr_poc\` 目录(含所有 DLL)+ 一个 store 目录拷到目标机,
跑上面的 `view` 命令, 肉眼看屏幕 fps 与交互流畅度。
- 或无显示/批处理场景跑 `gpr_poc fps-budget tmp\store_lod_001` 出该机的体素-fps 表对照。
---
## 最低配未验声明
本探针仅在本机 **RTX 3060** 跑出上限数字(数百 fps, 余量充足)。**最低配机器未验证**,
需用户拿目标机跑 `gpr_poc view <store>`(肉眼判 fps≥30 + 交互流畅)或 `gpr_poc fps-budget <store>`
(出该机体素-fps 表)。production 是否对最低配可用, 以目标机实测为准。
---
## Concerns
1. **视觉天花板受物理形态限制**: 体极扁(2.2km×1.5m×8m), 单帧结构偏小偏一隅。这是数据物理
真实, 非 bug; production 应给用户交互色阶/取景/裁剪控件(view 已具备旋转缩放, 色阶可参数化)。
2. **fps 不是本数据集的瓶颈, 纹理尺寸墙(16384)才是**: 与 brief"找 fps<30 阈值"设想不同。
每帧体素预算结论是"单轴 ≤16384 即可单纹理上传, fps 仍 ≫30", 超墙必须切块。如实记录。
3. **view 的 LOD 阈值按未夸张几何标定**: `pickLevel` 用 level0 原始对角线算距离比, 而 actor
已 `SetScale(1,exagg,exagg)`。夸张会轻微平移"缩放-LOD 映射"档位, 但切换仍正常触发
(smoke 实测 level 1↔0)。若用户觉得切档时机别扭, 后续可让 pickLevel 感知夸张系数。
4. **view 连续拖动 fps 文本基于上一帧耗时估算**(单帧 wall-clock 倒数), 非滑动平均, 数字会抖;
足够给用户感知量级(几十/几百 fps), 非精密基准(精密基准走 fps-budget/renderLOD 离屏)。
5. `last-metrics.txt`(repo 根, 探针追加输出)未纳入提交——它从未被 git 跟踪, 是瞬时产物。

68
.superpowers/sdd/task-9b-report.md Normal file
View File

@ -0,0 +1,68 @@
# Task 9b 报告：gpr_poc CLI + 真实数据 headless 度量
状态：**PARTIAL / BLOCKED**
- CLI 编译链接通过；`selftest` PASS（合成数据端到端跑通整条地基）。
- 真实明星路数据 **BLOCKED**：前置 IO 层 `readIprb` 的 `traces=lastTrace+1` 严格校验
与真实文件「道数=lastTrace」系统性不符，装配阶段即抛异常，无法实测建体指标。
**未擅自修改前置/其单测**（被现有测试钉死的契约 + 跨任务边界），故真实指标暂缺，如实记录。
---
## 1. 交付物（均为本会话自有文件）
- `tools/gpr_poc/main.cpp` —— CLI：`build` / `load` / `selftest` 三子命令。
- `tools/gpr_poc/Probe.hpp` —— header-only 计时（steady_clock）+ 峰值内存（Psapi `PeakWorkingSetSize`）。
含 `NOMINMAX`/`WIN32_LEAN_AND_MEAN` 防 `<windows.h>` 宏污染 `std::numeric_limits::min/max`。
- `tools/gpr_poc/CMakeLists.txt` —— 可执行 `gpr_poc`，链 `geopro_io_gpr/geopro_core/geopro_store/geopro_render`
+ Windows `Psapi`；`vtk_module_autoinit` 注册 VTK 工厂。
- 顶层 `CMakeLists.txt` —— 加 `add_subdirectory(tools/gpr_poc)`（在 `add_subdirectory(src)` 之后）。
- `docs/superpowers/plans/poc-results-B.md` —— 实测结果（selftest PASS + 真实数据 BLOCKED 根因表）。
注：库目标实际名为 `geopro_store`（brief 写作 geopro_store/已对齐）与 `geopro_data`；
本工具链 `geopro_store`（分块存储），正确。
## 2. 构建
- 配置：`cmd /c "build.bat configure"`（preset msvc-release，build/release）成功
（cmd 被环境劫持但真实命令仍执行；以 build.ninja 出现 gpr_poc target 确认）。
- 编译：PowerShell + vcvars64 直驱 cmake `--build build/release --target gpr_poc`。
首次失败：`<windows.h>` min/max 宏污染 → 加 NOMINMAX 修复 → 二次链接成功。
- 运行需 PATH 带 Qt6/VTK/vcpkg bin（headless 工具仍依赖这些 DLL）。
## 3. selftest 结果
```
gpr_poc selftest
[selftest] GridSpec 2x2x8 dz=0.714286
[selftest] PASS (exit 0)
```
覆盖：assembleGprSurvey → buildGprVolume → write(brick=4) → buildPyramid(1) →
WholeVolumeSource，断言维度/层数/体素非 blank 全通过。
## 4. 真实数据指标
**未实测（BLOCKED）**。根因：`readIprb`（`src/io/gpr/IprbReader.cpp:16`）
`traces=lastTrace+1` 严格字节校验；真实明星路 14 通道每个恰含 `lastTrace` 道（少 1 道），
逐通道实测一致（详见 poc-results-B.md §2 表）。非 OOM/超时——装配前读入即失败，
调 `--cellXY` 无法绕过。现有 `tests/io/gpr/test_iprb_reader.cpp:30-31` 锁定该抛异常契约。
用的参数：`--line 001 --cellXY 0.2 --cellZ 0.05 --levels 2`（建体未到达）。
预估几何（非实测，供核对）：nx≈11118, ny≈8, nz≈1（深度尺度因土速单位为微米级，
cellZ=0.05 压成单层——需 POC owner 复核土速/时窗单位与 cellZ）。
## 5. 提交前自检
- 仅 `git add` 自有文件：`tools/gpr_poc/*`、顶层 `CMakeLists.txt`、
`docs/superpowers/plans/poc-results-B.md`、本报告 `.superpowers/sdd/task-9b-report.md`。
- `git diff --cached --stat` 确认无 chart/scatter/quill/rangeslider 等并行会话行。
- 顶层 CMakeLists 的暂存 diff 应仅含新增的 `add_subdirectory(tools/gpr_poc)` 一行块。
## 6. Concerns / 需 owner 决策
1. **真实数据 BLOCKER（高）**：`readIprb` 道数契约与真实数据不符。建议放宽为
「道数 = 文件字节 / (samples·2)」（容忍 ±N 道），或确认 LAST TRACE 语义后去 +1，
并同步改单测。落地后重跑两条命令即可补齐 §4 真实指标。
2. **深度尺度（中）**：SOIL VELOCITY=100 m/s（头单位 m/µs ×1e6）→ 深度跨度微米级，
cellZ=0.05 会把 Z 压成 1 层。影响真实体维度与 9c 渲染基准，需确认单位约定。
3. 顶层 CMakeLists 当前 working tree 已有他会话的修改（视觉设计/chart 等）；本会话只新增
add_subdirectory 一行,暂存时务必只 stage 该文件并核对 diff,勿带入其他未暂存改动。

44
.superpowers/sdd/task-9c-report.md Normal file
View File

@ -0,0 +1,44 @@
# Task 9c 报告：POC-B 离屏 GPU 渲染基准
状态：**DONE**（闸门通过；真实基准实测完成；关键发现如实记录，无任何编造 fps）
执行机：Windows 11，MSVC（VS18 Community）+ Ninja，Release；GPU = NVIDIA RTX 3060 Laptop GPU，OpenGL 4.5.0 NVIDIA 555.97。
日期：2026-06-23。
---
## 1. 交付物
- `tools/gpr_poc/main.cpp`：新增两个子命令
- `gpr_poc offscreen-smoke` —— 最小离屏渲染冒烟（闸门），打印 OK/FAIL + GL 能力。
- `gpr_poc renderB <storeDir> [--frames 120]` —— 离屏体绘制 + 切片扫描 fps 基准。
- `tools/gpr_poc/CMakeLists.txt`：补 VTK 组件（RenderingVolume / RenderingVolumeOpenGL2 / ImagingCore / InteractionStyle）。
- `docs/superpowers/plans/poc-results-B.md`：新增「§4 离屏 GPU 渲染基准」段（闸门 + 真实指标 + 关键发现 + 结论）。
- `build/_t9c_build.bat`：本任务用的 gpr_poc 单 target 构建脚本（vcvars64 直驱 cmake）。
## 2. 闸门结果 —— OK
`offscreen-smoke`：离屏 vtkRenderWindow（SetOffScreenRendering+SetShowWindow(false)）→ cube actor → Render() →
GetRGBACharPixelData 读回 65536 像素，非背景 28224。GL vendor=NVIDIA，硬件加速 True。**离屏 GL 可用**，继续真实基准。
## 3. 真实 GPU 指标（line 001, cellXY=0.05, cellZ=0.05）
- 体维度：**44476 × 29 × 162**；体素数 ≈2.09 亿；整卷字节 **398.54 MB**（int16）。
- **体绘制 fps：INVALID** —— 整卷 X 维 44476 超 `GL_MAX_3D_TEXTURE_SIZE=16384`，
`vtkVolumeTexture` 报 `Invalid texture dimensions [44476,29,162]`，未真正绘出体数据。
raw_fps=295.6 是空纹理假帧率，已显式标 INVALID，**不作为体绘制性能上报**。
- **切片扫描 fps：54.6 fps**（120 帧沿 Z 扫整卷，vtkImageReslice 2D 切面 + 2D 纹理；不受 3D 纹理上限约束）。≥30fps 目标达成。
- 是否进显存：**否**（瓶颈是单轴纹理维度上限 16384，非显存字节；整卷 398 MB << RTX 3060 6GB 显存）。
- GPU 显存（NVX）：**N/A**（随包 VTK 安装未带 GLEW 头，无法链 GL loader 直查；GL 扩展列表确认机器支持 NVX_gpu_memory_info）。
- 进程峰值内存：**≈509 MB**（加载整卷 398 MB + 渲染管线）。
- build 峰值内存：4830 MB（装配阶段 double survey 主导，与 §2 一致）；无 OOM，cellXY=0.05 一次通过。
## 4. concerns
1. **整卷朴素体绘制对长测线根本不可行**：X=44476 撞 OpenGL 单轴 3D 纹理上限 16384。
与显存容量无关，是硬限制。任何「整卷一次性 3D 纹理」方案对长测线都会撞墙。
这是 **Task 12（核外 / 分块 LOD / 体纹理分区 `vtkOpenGLGPUVolumeRayCastMapper::SetPartitions`）**
的硬性依据。本任务按约束未做核外，仅如实记录。
2. SmartVolumeMapper 报 GPURenderMode=2 但纹理上传失败——`GetLastUsedRenderMode()` 不能单独作为
「真的渲染出来了」的判据；renderB 已加 OutputWindow 捕获 + 维度超限双判据才下 INVALID 结论。
3. GPU 显存读数缺失（N/A）：仅因 VTK 安装未带 GLEW 头；若需要可后续单独链 GL loader 调 NVX 枚举。

16
CLAUDE.md
View File

@ -42,6 +42,22 @@ When your changes create orphans:
The test: Every changed line should trace directly to the user's request. The test: Every changed line should trace directly to the user's request.
**Exception — Tech debt must be fixed, not deferred:** When you discover a real bug,
broken behavior, or technical debt while working (even if it predates this change and
you didn't introduce it), fix it — do not use "not introduced by this round / pre-existing"
as a reason to leave it. Surface it, then handle it. (User directive, 2026-06-25, binding.)
This overrides the "don't fix what isn't broken" bias above *for genuine defects* — it does
not license cosmetic refactors or unrequested rewrites.
**Do it yourself — never offload work you can do (User directive, 2026-06-25, binding):**
If you have the tools to do something, DO IT — never tell the user to do it for you.
Read the logs yourself (`%LOCALAPPDATA%/Geomative/Geopro3/logs/geopro_*.log` via Bash/grep),
inspect data/fixtures yourself, build and link yourself (`build.bat app` via PowerShell),
diagnose by adding logging and then reading that log yourself. The ONLY things to ask the
user for are: (a) closing a running app so the exe can relink (LNK1104 — a lock only they can
release), and (b) genuine product decisions. Do not ask the user to read logs, inspect data,
run diagnostics, or interpret output — that is your job.
## 4. Goal-Driven Execution ## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.** **Define success criteria. Loop until verified.**

10
CMakeLists.txt
View File

@ -76,7 +76,17 @@ if(EXISTS "${CMAKE_SOURCE_DIR}/external/qwt-src/src")
include("${CMAKE_SOURCE_DIR}/cmake/qwt.cmake") include("${CMAKE_SOURCE_DIR}/cmake/qwt.cmake")
endif() endif()
# vendored 3DGPRViewer 数据生成链（原样拷贝，算法零改动）：geopro_gpr3dv 静态库。
# 链：多通道 .iprh/.iprb → GPRDataModel 立方体 → RadarProcessor 处理。生产管线 A 地基。
add_subdirectory(external/gpr3dviewer)
add_subdirectory(src) add_subdirectory(src)
# POC-B headless 度量 CLI（gpr_poc）。链 io_gpr/core/store/render，在真实数据上跑端到端度量。
add_subdirectory(tools/gpr_poc)
# gpr3dv 冒烟 CLI：走 vendored 原版 API（loadImpulseMultiChannel → buildVolumeData → runPipeline）。
add_subdirectory(tools/gpr3dv_smoke)
enable_testing() enable_testing()
add_subdirectory(tests) add_subdirectory(tests)

32
build.bat
View File

@ -2,11 +2,13 @@
REM ============================================================ REM ============================================================
REM geopro build helper (Windows / MSVC + Ninja, CMake presets) REM geopro build helper (Windows / MSVC + Ninja, CMake presets)
REM REM
REM Usage: build [app | all | test | run | configure] REM Usage: build [app | all | test | run | rebuild | configure]
REM app (default) build target geopro_desktop REM app (default) build target geopro_desktop (incremental)
REM all build all targets REM all build all targets (incremental)
REM test build + run unit tests via ctest REM test build + run unit tests via ctest
REM run build + launch geopro_desktop REM run incremental build + launch geopro_desktop
REM rebuild FORCE clean rebuild (--clean-first) + launch - use when
REM incremental seems stale / changes not showing up
REM configure force re-run CMake configure (after CMakeLists changes) REM configure force re-run CMake configure (after CMakeLists changes)
REM REM
REM Requires: Visual Studio 2022/2026 (Desktop C++ workload, ships REM Requires: Visual Studio 2022/2026 (Desktop C++ workload, ships
@ -25,14 +27,17 @@ if not exist "%VSWHERE%" (
echo [build] vswhere not found. Open "x64 Native Tools Command Prompt for VS" and build manually. echo [build] vswhere not found. Open "x64 Native Tools Command Prompt for VS" and build manually.
exit /b 1 exit /b 1
) )
for /f "usebackq tokens=*" %%i in (`"%VSWHERE%" -latest -property installationPath`) do set "VSPATH=%%i" REM -all -prerelease for VS2026 preview (note: -latest yields empty on this preview, and
if not defined VSPATH ( echo [build] Visual Studio not found. & exit /b 1 ) REM -products * would pull in the bundled BuildTools whose vcpkg/env breaks our preset);
REM -requires ensures the C++ toolset is present. Multiple installs -> last one wins.
for /f "usebackq tokens=*" %%i in (`"%VSWHERE%" -all -prerelease -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do set "VSPATH=%%i"
if not defined VSPATH ( echo [build] Visual Studio with C++ toolset not found. Install the VS Desktop C++ workload. & exit /b 1 )
set "VCVARS=%VSPATH%\VC\Auxiliary\Build\vcvars64.bat" set "VCVARS=%VSPATH%\VC\Auxiliary\Build\vcvars64.bat"
set "CMAKE=%VSPATH%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" set "CMAKE=%VSPATH%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe"
set "CTEST=%VSPATH%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\ctest.exe" set "CTEST=%VSPATH%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\ctest.exe"
if not exist "%VCVARS%" ( echo [build] vcvars64.bat not found: %VCVARS% & exit /b 1 ) if not exist "%VCVARS%" ( echo [build] vcvars64.bat not found: "%VCVARS%" & exit /b 1 )
if not exist "%CMAKE%" ( echo [build] cmake not found: %CMAKE% & exit /b 1 ) if not exist "%CMAKE%" ( echo [build] cmake not found: "%CMAKE%" & exit /b 1 )
REM --- activate MSVC environment (cl / link / include / lib) --- REM --- activate MSVC environment (cl / link / include / lib) ---
call "%VCVARS%" >nul call "%VCVARS%" >nul
@ -45,7 +50,8 @@ if /i "%CMD%"=="app" goto :app
if /i "%CMD%"=="all" goto :all if /i "%CMD%"=="all" goto :all
if /i "%CMD%"=="test" goto :test if /i "%CMD%"=="test" goto :test
if /i "%CMD%"=="run" goto :run if /i "%CMD%"=="run" goto :run
echo [build] unknown command "%CMD%". Use: app ^| all ^| test ^| run ^| configure if /i "%CMD%"=="rebuild" goto :rebuild
echo [build] unknown command "%CMD%". Use: app ^| all ^| test ^| run ^| rebuild ^| configure
exit /b 1 exit /b 1
:ensure :ensure
@ -77,3 +83,11 @@ call :ensure
"%CMAKE%" --build "%BUILDDIR%" --target geopro_desktop || exit /b 1 "%CMAKE%" --build "%BUILDDIR%" --target geopro_desktop || exit /b 1
"%BUILDDIR%\src\app\geopro_desktop.exe" "%BUILDDIR%\src\app\geopro_desktop.exe"
exit /b %errorlevel% exit /b %errorlevel%
:rebuild
REM Force full clean rebuild (--clean-first) then launch; avoids flaky ninja incremental.
REM If geopro_desktop is already running, link fails (LNK1104, exe locked) - close it first.
call :ensure
"%CMAKE%" --build "%BUILDDIR%" --target geopro_desktop --clean-first || exit /b 1
"%BUILDDIR%\src\app\geopro_desktop.exe"
exit /b %errorlevel%

99
docs/Geopro3.0_视觉设计规范.md
View File

@ -394,6 +394,105 @@
## 7. 表单、表格、对话框等通用组件（补充 · 原型未全部出现但客户端必备） ## 7. 表单、表格、对话框等通用组件（补充 · 原型未全部出现但客户端必备）
### 7.0 表单布局（编辑态 / 只读态）— 总则
> 本节是「编辑/只读表单」的**单一事实来源**，统一约束四类表单：①弹出编辑/新建对话框、②属性子视图（对象属性 / 数据集属性）、③动态表单（`getDynamicForm` 驱动）、④首选项设置。控件本身的样式仍引用 §7.1–7.3、§6.12–6.13；本节只定义「把这些控件组织成一张表单」的布局、分组、状态、校验与配色规则。
>
> **设计取向**（参考主流优秀客户端）：macOS 系统设置 / Windows 11 设置（分组卡片 + 左标签）、JetBrains IDE 设置（密集左标签）、Figma 右侧属性面板（紧凑内联编辑）、Linear / Stripe（清晰节奏与即时校验）。在「信息密度优先」（§0.3）前提下取其**密集左标签 + 清晰分组 + 即时校验 + 克制留白**。
#### 7.0.1 两种表单形态（先定形态，再排布局）
| 形态 | 用途 | 实现 |
|---|---|---|
| **只读表单**（展示） | 纯查看的属性详情 | 用 §6.4 **属性键值表**（键值两列，数值等宽，不可编辑） |
| **可编辑表单**（编辑/新建） | 编辑、新建、设置 | 用本节「标签 + 控件」行式表单 |
**铁律**：一张表单只要存在**任一可编辑字段**，整张表即用「可编辑表单」形态；其中的只读字段以**禁用态控件**（§7.1 禁用）呈现，**不得**在同一张表单里一半键值表、一半输入框——保证可编辑与只读字段在同一栅格中对齐一致。
#### 7.0.2 表单栅格与行结构
| 元素 | 规范 |
|---|---|
| 标签位置 | **左侧标签列**（默认，密集专业风），标签文字**右对齐**贴近字段；字段名过长或窄单列对话框可改顶部标签 |
| 标签列宽 | 可编辑表单**固定 `100px`**（`space::kFormLabelCol`，右对齐，跨表单等宽）；纯只读键值表**固定 `72px`**（`space::kDetailKeyCol`，§6.4）。**不取区间**——区间会让不同实现各选一值而漂移 |
| 标签 ↔ 字段间距 | `space/md`(12) |
| 字段控件高 | `28px`（§7.1）；行与行垂直间距 `space/sm`(8) |
| 字段宽度 | 宽面板/对话框中**不要拉满**，单字段最大宽约 `360px`（多行/长文本可更宽）；窄属性面板中填充可用宽度 |
| 表单内边距 | 对话框内 `space/xl`(24)；面板内 `space/lg`(12–16) |
| 列数 | **单列优先**；信息多用分组而非多列。仅「短字段（数值+单位）」可两列并排 |
#### 7.0.3 分组（Section）
- 分组标题：`text/heading`，上方留 `space/lg`，标题下可加 1px `divider` 贯通。
- 组**内**字段紧凑（行距 `space/sm`），组**间**留 `space/lg`–`space/xl`。
- 对话框内多组（对齐原版 `getDynamicForm` 的 基本信息 / 测线布设 / 数据质量 等）：组数多时用**锚点分组**或**分页签**，避免一屏堆叠过长。
#### 7.0.4 字段状态与标记
| 标记/态 | 规范 |
|---|---|
| **必填** | 标签后红色 `*`（`status/danger`），紧贴标签 |
| 可选 | **默认不标记**（保持干净）；确需时标签后加 `text/tertiary` 的「（可选）」 |
| **只读/禁用** | §7.1 禁用态（底 `neutral-50`/Dark `#1A1F26`、文字 `text/disabled`、禁用光标）——明确不可编辑，其值**仍随表单提交** |
| **错误** | §7.1 错误态：描边 `status/danger` + 字段下方 `text/caption` `status/danger` 说明 |
| 帮助/说明 | 字段下方 `text/caption` `text/tertiary` 一行（与错误说明**互斥**位置） |
| 单位/前后缀 | 框内右端 `text/tertiary`（§7.1 前后缀） |
#### 7.0.5 校验与提交反馈
- **即时校验**：失焦/输入时校验单字段，错误就地显示（§7.1 错误态），不打断输入。
- **提交校验**：点「保存/确定」校验全表 → 有错则**滚动并聚焦第一个错误字段** + 就地显示错误；可同时在表单顶部用**行内提示**（§7.7 inline alert）汇总「请完善 N 项」。**不要**只弹一个模糊 toast。
- **脏标记**：表单无用户修改时「保存」按钮**置灰不可点**；任一字段改动后启用（与已落地的对象属性面板一致）。
- **提交中**：主按钮 loading（spinner/禁用）防重复提交；成功后 Toast（§7.7）+ 关闭或刷新。
#### 7.0.6 弹出编辑 / 新建对话框（body）
- 外壳遵 §7.5（容器 `radius/lg` + 标题栏 + 底部操作栏）。body 即本节表单：内距 `space/xl`、单列左标签、分组按 7.0.3。
- 底部操作栏：**取消（次按钮，左）+ 主操作（确定/保存，Primary，右）**；破坏性确认用 Danger（§7.5/§7.6）。
- **新建 vs 编辑**：编辑态预填现值；不可改字段（如类型、按 API 只读的名称）用**禁用控件**而非省略；标题区分「新建 XX / 编辑 XX」。
#### 7.0.7 四类表单的归口（落地映射）
| 表单 | 形态 | 要点 |
|---|---|---|
| 对象属性面板（对象属性 Tab） | 可编辑表单 | 名称**仅顶部显示一处**且按 API 只读；只读字段禁用灰显；脏标记控制保存 |
| 数据集属性面板 | 上半 §6.4 **只读键值表** + 下半**可编辑描述**（单字段可编辑表单） | 两段职责分明 |
| 动态表单（`getDynamicForm`） | 可编辑表单 | 分组 = `formList` 组；控件按 `displayComponentType` 映射（§7.1/7.2/7.3/6.12）；必填/只读由 `requiredType`/`fieldUseType` 决定（7.0.4） |
| 首选项设置（§7.10） | 设置型表单变体 | 主从布局 + 设置行（左：标题+说明，右：控件） |
#### 7.0.8 配色与排版令牌（汇总 · 禁硬编码）
| 角色 | token |
|---|---|
| 标签文字 | `text/secondary`（必填 `*` 用 `status/danger`） |
| 字段值 / 输入文字 | `text/primary`；数值/坐标/编号用等宽 `type::kMonoFamily` |
| 分组标题 | `text/heading` |
| 分隔线 | `divider` |
| 错误（描边+说明） | `status/danger` |
| 只读字段 底/文字 | `neutral-50`（Dark `#1A1F26`）/ `text/disabled` |
| 字段 背景/边框/focus | 见 §7.1（`bg/panel`、`border/default`→`border/strong`→`border/focus`） |
#### 7.0.9 可访问性
- 标签与控件**关联**（点击标签聚焦其控件 / buddy）。
- Tab 焦点顺序自上而下、左到右；焦点环可见（§10、§12）。
- **不以颜色为唯一信息**：必填除 `*` 外，校验失败有文字说明；错误态有文字。
- 可点控件最小命中区 ≥ `24×24px`（§12）。
#### 7.0.10 实现纪律（单一实现 · 禁止手搭）
> **本节是 §7.0 能落地的关键。** 文档约束管不住代码——同类表单分散在各文件里手搭 `QFormLayout`/`QLabel`、各填各的边距与列宽，必然漂移（曾出现：三维体/切片/异常详情用裸 `QFormLayout`，与属性面板天差地别；同为下拉框，设置页无箭头、对象属性偏矮带箭头）。一致性**只能由代码复用强制**。
- **唯一实现（必须经此产出，不得另起炉灶）**：
- 只读键值详情 → `DynamicFormView`（§6.4 渲染器）。对话框用 `formkit::DetailForm`（链式 `group()/row()`）构模型，`formkit::buildDetailDialog()` 铺骨架。
- 可编辑表单 → `formkit::makeEditForm()` + `formkit::editLabel()` + `formkit::capField()` + `formkit::addSection()`。`DynamicFormEditor` 与各参数对话框（如「生成三维体」）**都走同一组**，确保标签列宽/行距/分组/字段上限逐像素一致。
- **禁止**：业务表单/对话框直接 `new QFormLayout` + `new QLabel("名"，值)` 手搭键值；禁止在表单里逐处写死边距/列宽/字号（用 `space::*`/`type::*` 令牌）。
- **精确常量（单一来源 `Theme.hpp`，禁止区间/魔数）**：可编辑标签列 `space::kFormLabelCol=100`；只读键列 `space::kDetailKeyCol=72`；字段最大宽 `space::kFormFieldMax=360`；行距 `space::kMd`；分组上间距 `space::kLg`。
- **控件构造一致性**：下拉框统一用不可编辑 `QComboBox`（无候选项的「选择」字段退化为 `QLineEdit` 自由文本，**不得**用「可编辑下拉框」——其几何/高度与不可编辑款不一致）。全局 QSS **不覆写** `QComboBox::drop-down`/`::down-arrow`，保留 Fusion 原生箭头随调色板自适应（覆写却不提供箭头图会致箭头消失）。`QComboBox` 的 `min-height`/`padding` 与 `QLineEdit` 完全对齐 → 同高。
- **新增表单的验收**：截图与既有「对象属性 / 数据详情」并排，标签列、行高、分组标题、下拉框外观应**无法区分**；做不到即说明绕开了上述唯一实现。
---
### 7.1 输入框（Text Input） ### 7.1 输入框（Text Input）
| 状态 | 规范 | | 状态 | 规范 |

76
docs/OPTIMIZATION-BACKLOG.md Normal file
View File

@ -0,0 +1,76 @@
# 待优化清单（Optimization Backlog）
> 全局「待优化 / 技术债 / 性能与体验改进」登记簿。**所有**后续发现但当下不做（或暂以折中实现）的优化点
> 都登记到此，并随进展更新状态。区别于 bug（bug 当场修，见 CLAUDE.md 技术债规则）——这里收录的是
> 「能用但不够理想、需要更大改造才能做到位」的优化项。
## 状态图例
- 🔴 Open — 待优化，尚未动工
- 🟡 In Progress — 正在做
- 🟢 Done — 已完成（保留记录，标注完成 commit/日期）
- ⚪ Won't Do — 评估后决定不做（标注原因）
## 维护约定
- 新增项用递增 ID（OPT-NNN），不复用已删 ID。
- 每项含：背景/现状、期望、难点、状态、记录日期、关联 commit。
- 状态变更时更新「状态」行与「更新」行，不删历史。
---
## OPT-001 · 放大系数(VE) 完全无重绘的即时缩放
- **状态**：🔴 Open
- **记录日期**：2026-06-25
- **背景/现状**：`VtkSceneController::setVerticalExaggeration` 当前走「保留相机重建」（commit `7ff6f18`）——
改 VE 时相机不再跳远视角、原地按新夸张重绘，但**数据/底图仍会重建并重绘一次**（有一次闪烁）。
根因：VE 被烤进几何——帘面用 `actor->SetScale(1,1,VE)`、体素把 VE 烤进 image 的 z origin/spacing、
地形烤进 `buildTerrain`；且切片附着依赖**含 VE 的 currentVolumeImage_**。
- **期望**：拖动放大系数时纯 actor 层 Z 缩放，**零重载零重绘**、即时跟手（理想可恢复拖动实时预览）。
- **难点**：
- 体素须改为「image 建在 VE=1、vtkVolume prop 用 `SetScale(1,1,VE)`」，但切片重采样依赖含 VE 的 image
几何，需同步改造切片附着/重采样链（InteractionManager）。
- 地形/帘面/体素三类 actor 的 VE 应统一走 actor 变换，避免混用（部分烤几何、部分 actor 缩放）。
- 底图(TileBasemap) VE 同步是否也能免重载需评估。
- **关联**：`7ff6f18`（当前保留相机的折中实现）。
- **更新**：—
---
## OPT-002 · 多三维体并发的切片渲染
- **状态**：🟢 Done（issue2/③/反向② `69e8790`；④ 拾取串选 `63cda56`，体 PickableOff，逻辑修复待 live 复核）
- **记录日期**：2026-06-25
- **背景/现状**：切片渲染绑定单一「当前体」——`syncSlices` 只显示 `sp.volumeDsId == currentVolumeDsId()`
的切片，`currentVolumeDsId` = 最后添加的体（`VtkSceneView::volumeOwnerDs_`）。勾选第二个三维体后它
成为 current，第一个体的切片被 `syncSlices` 隐藏（用户 issue2：选第二个体时第一个体的切片消失）。
根因：`InteractionManager` 把切片附着到单个 `currentVolumeImage_`，不支持同时挂多个体的 image。
- **期望**：多个体同时渲染时，各自的已勾选切片都能并存显示（按各切片的 `volumeDsId` 取对应体 image 重采样）。
- **难点**：`InteractionManager` 的切片附着/重采样改为「按 volumeDsId 多体管理」；`VtkSceneView` 需暴露
多个体的 image（非单 `currentVolumeImage_`）；切片拾取/选中也要按所属体区分。与 OPT 无关的切片右键
「保存/导出」依赖 selectedSlice 当前体，也需一并核对。
- **关联**：syncSlices/onVolumeChanged（`src/app/main.cpp`）、`VtkSceneView::currentVolumeImage_`。
- **同簇问题（一并改造）**：
- **③ 右键体却把切片建到 current 体**：右键三维体 A「生成切片」时仍用 `currentVolumeDsId()`（=最后渲染的
体）创建切片。需把目标体 dsId 随右键带下来，并让 addSlice 用 A 的 image（依赖多体 image 管理）。
- **④ 切片拾取串选**：已修(`63cda56`)。根因=点击落体内部时 picker 命中体、worldPoint 落体内 →
`nearestSlice` 按平面距离选错切片。修法=体 actor `PickableOff`，光标拾取只落切片平面 → worldPoint
落在光标下那张切片 → 选对（`onPick` 仅命中时触发，未命中不误选）。重叠切片仍按最前优先（合理）。
逻辑闭合但**未 live 点击验证**（工具无法交互点击 3D 切片）；若仍有偏差需 live 复核（重叠循环切换等）。
- **更新**：2026-06-25 issue2+③+反向²(`69e8790`)+④(`63cda56`) 全部实现。
---
## OPT-003 · 二维分析 C 期：dd_raster 栅格地理配准渲染（阻塞·待后端端点）
- **状态**：🔴 Open（**阻塞**：后端无栅格数据端点）
- **记录日期**：2026-06-26
- **背景/现状**：二维分析改造分期 A→B→C（spec `docs/superpowers/specs/2026-06-26-2d-analysis-topdown-elevation.md`）。
A（一场景两相机）、B（足迹高程 Z 拖动）已实现（commit `6a10975`、`bdebe54`）。**C 期=dd_raster 栅格**
（DD0623 新增 ddCode，展示模式 2D，形态=栅格/遥感影像）尚未做。
- **期望**：`dd_raster` 纳入 2D 维度过滤（`dimOf`/`dimensionOf` 加 `dd_raster`→Dim2D）；col2D 勾选渲染按
ddCode 分派（轨迹走 `loadMapLine`，栅格走**栅格加载**，不可串）；栅格取**像素 + 四至/仿射 + 投影 CRS**
作地理配准纹理平面贴到地形上（带高程，可被 B 期 Z 拖动），类似底图瓦片按经纬定位。
- **阻塞点（为何不做）**：实测后端 API 文档 `docs/apis/business_OpenAPI.json` **无任何 dd_raster / 栅格影像
端点**（仅有 grid 行/反演 grid、GPR 通道图，均非带四至+投影的栅格）。无端点 → 无像素/地理范围可加载 →
C 期无数据可渲染。**须后端提供返回「像素 + 四至/仿射 + 投影」的端点后方可落地。**
- **难点**：栅格加载路径（新）、按 ddCode 的渲染分派、地理配准纹理平面（参考 `TileBasemap` 的 `buildFlat`/
`buildWarped` 按经纬贴地形 + DEM 位移）。
- **关联**：spec §6/§9/§10/§11；handoff `docs/superpowers/HANDOFF-2026-06-26-vtk-anomaly-2d-analysis.md` §0。
- **更新**：—

544
docs/api/vtk-3d-openapi.json Normal file
View File

@ -0,0 +1,544 @@
{
"openapi": "3.0.3",
"info": {
"title": "Geopro3 三维视图 API（三维体 / 切片 / 异常 三件套）",
"version": "0.6.1-draft",
"description": "VTK 三维视图后端接口。归属结构(2026-06-24 修订)：**GS/项目根/TM → 三维体(dd_voxel) → 切片(dd_slice)**(三维体生成位置由用户在生成对话框选择,默认单GS挂该GS/跨GS挂项目根,可改为项目内任意 GS/TM；源数据集与归属解耦)，异常挂在三维体上(remarkSourceId=三维体 dsObjectId)。\n\n**总原则：实体无关的契约一律复用存量；只为各自特有、存量装不下的部分扩展。**\n- 三维体/切片对后端 = 纯元数据 dsObject：增删改查/属性复用存量 dsObject 面，各加 1 个登记端点；体素字节/切面数据全在客户端(算+存+取+渲染)，后端零数据端点。\n- 异常复用整套存量 /business/exception 端点(端点不限实体类型，三维体 id 直接塞 remarkSourceId)；**异常体(consortium)分组也是存量已有**(consortiumId/Name/Type)。3D 仅扩展两处：location 加 worldPts+plane(三维几何)、加截图(R88)。\n\n响应统一信封 `{ code:int, msg:string, data:object|array }`，code==200 成功；列表/集合放 data.value。\n\n依赖前提：异常 remarkSourceId 指向三维体，须等三维体登记出真 dsObjectId 后，3D 异常才能接真端点。"
},
"servers": [
{ "url": "/", "description": "业务网关根(各路径已含 /business 前缀)" }
],
"tags": [
{ "name": "dsObject-reuse", "description": "复用的存量统一面(三维体/切片共用增删改查+属性)" },
{ "name": "voxel-new", "description": "三维体新增：仅登记记录(体素全在客户端)" },
{ "name": "slice-new", "description": "切片新增：仅登记记录(切面全在客户端)" },
{ "name": "exception-reuse", "description": "复用的存量异常面(端点不限实体类型；3D 仅扩展 location 几何+截图)" }
],
"paths": {
"/business/projectStruct/queryProjectStruct/{projectId}": {
"get": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 查询项目结构树(GS/TM 骨架)",
"description": "存量端点。提供三维体挂载所需的 TM 节点；三维体/切片作为派生数据另经 data/page 取。",
"operationId": "queryProjectStruct",
"parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StructNodeList" } } } ] } } }
}
}
}
},
"/business/dsObject/data/page": {
"post": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 分页查询某父节点下的数据集行",
"description": "存量端点(loadRowsAsync)。查三维体：structParentId=生成位置节点 id(GS/项目根/TM)、structParentConfType=1或2；查某三维体下切片：structParentId=该三维体 dsObjectId。\n\n**实测口径(2026-06-25)**：①行在 `data.list`(非 data.value)；②返回项目结构下**各类** dsObject(文件/网格/反演/三维体/切片/异常…)，行 ddCode 非仅 voxel/slice；③客户端用 classifyType==1 时改打 `/business/dsObject/file/page`(文件型)，否则 `data/page`；④**行不返回业务字段值**(properties 为文件元数据或 null)，**装置类型(arrayType) 不在 data/page 行上**——它属测线脚本配置(ScriptInfoVO)，故客户端「类型筛选」改按行自带的 typeName/dsTypeCode 范围筛，而非 arrayType。",
"operationId": "dsObjectDataPage",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DsPageRequest" } } } },
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DsPage" } } } ] } } }
}
}
}
},
"/business/dsObject/getDetail/{dsObjectId}": {
"get": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 数据集详情(描述 + attachedParameters)",
"description": "存量端点。三维体构建参数(attachedParameters.voxelParams)、切片三点位姿(attachedParameters.slicePose)从这里读出。",
"operationId": "dsObjectGetDetail",
"parameters": [ { "$ref": "#/components/parameters/DsObjectIdPath" } ],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DsObjectDetail" } } } ] } } }
}
}
}
},
"/business/dsObject/dynamicForm/{dsObjectId}": {
"get": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 数据集属性(动态表单)",
"description": "存量端点。三维体/切片可读属性由后端为 dd_voxel/dd_slice 注册 formList 后从此返回，无需为属性新增固定字段接口。",
"operationId": "dsObjectDynamicForm",
"parameters": [ { "$ref": "#/components/parameters/DsObjectIdPath" } ],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DynamicForm" } } } ] } } }
}
}
}
},
"/business/dsObject/updateDsObject/": {
"put": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 更新数据集(描述 / attachedParameters)",
"description": "存量端点。改名/改描述/改三维体参数/改切片位姿都走这条。注意 URL 末尾斜杠为服务端实证要求。",
"operationId": "updateDsObject",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDsObjectRequest" } } } },
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
}
},
"/business/dsObject/{dsObjectId}": {
"delete": {
"tags": ["dsObject-reuse"],
"summary": "[复用] 删除数据集",
"description": "存量端点。删三维体级联其下切片/异常记录(客户端另清本地体素落盘)；删切片不影响异常(异常挂三维体、与切片解耦)。",
"operationId": "deleteDsObject",
"parameters": [ { "$ref": "#/components/parameters/DsObjectIdPath" } ],
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
}
},
"/business/dsObject/voxel/generate": {
"post": {
"tags": ["voxel-new"],
"summary": "[新增] 登记三维体记录",
"description": "在生成位置节点(GS/项目根/TM)下登记一条 dd_voxel dsObject(名称 + 构建参数写入 attachedParameters.voxelParams)，返回新 dsObjectId。只建记录、不触发后端计算——体素插值/落盘/渲染全在客户端。",
"operationId": "registerVoxel",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoxelGenerateRequest" } } } },
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedRef" } } } ] } } }
}
}
}
},
"/business/dsObject/slice/generate": {
"post": {
"tags": ["slice-new"],
"summary": "[新增] 登记切片记录",
"description": "在所属三维体下登记一条 dd_slice dsObject(名称 + 三点位姿写入 attachedParameters.slicePose)，返回新 dsObjectId。只建记录、不触发后端计算——切面据「体+位姿」在客户端重采样渲染。\n\n**实测(2026-06-25)**：客户端 mock 仓储无项目上下文，当前打印的请求体 projectId 为空；接真后端前客户端需补 nav.currentProjectId()。其余字段(volumeDsId/name/axis/三点/colorScaleId)与本 schema 一致。",
"operationId": "registerSlice",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SliceGenerateRequest" } } } },
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedRef" } } } ] } } }
}
}
}
},
"/business/exceptionType/queryExceptionTypeByProjectIdAndType/{projectId}/{remarkSourceType}": {
"get": {
"tags": ["exception-reuse"],
"summary": "[复用] 异常类型列表",
"description": "存量端点(queryExceptionTypeData)。按项目 + 标注形态(remarkSourceType=1点/2线/3面/4文字)查可用异常类型。与实体类型无关 → 3D 通用。data.value 为类型数组。",
"operationId": "queryExceptionTypes",
"parameters": [
{ "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "remarkSourceType", "in": "path", "required": true, "schema": { "type": "string", "enum": ["1", "2", "3", "4"] }, "description": "标注形态：1点/2线/3面/4文字" }
],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExceptionTypeList" } } } ] } } }
}
}
}
},
"/business/exceptionType": {
"post": {
"tags": ["exception-reuse"],
"summary": "[复用] 新增异常类型",
"description": "存量端点(addExceptionType)。异常属性 + 标注名称双 Tab 组装的类型定义(含图例/字段列表)。3D 直接复用。",
"operationId": "addExceptionType",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExceptionTypeRequest" } } } },
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
}
},
"/business/exception/getExceptionName": {
"post": {
"tags": ["exception-reuse"],
"summary": "[复用] 取建议异常名称",
"description": "存量端点(queryExceptionNameInProfileInversion)。按异常类型 + 被标注实体回填建议名。3D 把 remarkSourceId 填三维体 id 即可。data 为纯字符串(名称)。",
"operationId": "getExceptionName",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["exceptionTypeId", "remarkSourceId"],
"properties": {
"exceptionTypeId": { "type": "string" },
"remarkSourceId": { "type": "string", "description": "2D=dsObjectId；3D=三维体 dsObjectId" }
}
}
}
}
},
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "string", "description": "建议名称(纯字符串)" } } } ] } } }
}
}
}
},
"/business/exception": {
"post": {
"tags": ["exception-reuse"],
"summary": "[复用+扩展] 新增异常",
"description": "存量端点(newExceptionInProfileInversion)。2D 字段全复用；**3D 扩展**：location 增加 worldPts(三维几何) + plane(所在平面)，并增加 screenshot(R88 截图)。remarkSourceId=三维体 dsObjectId；consortiumId 归入异常体(存量已有)。",
"operationId": "newException",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewExceptionRequest" } } } },
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
},
"put": {
"tags": ["exception-reuse"],
"summary": "[复用+扩展] 更新异常",
"description": "存量端点(updateExceptionDataInProfileInversion)。改名/备注/几何；3D 同样可改扩展后的 location 与截图。",
"operationId": "updateException",
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExceptionRequest" } } } },
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
}
},
"/business/exception/{id}": {
"delete": {
"tags": ["exception-reuse"],
"summary": "[复用] 删除异常",
"description": "存量端点(deleteExceptionDataInProfileInversion)。删异常体=按 consortiumId 循环删其下异常(无专用批删端点)。",
"operationId": "deleteException",
"parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
"responses": { "200": { "$ref": "#/components/responses/StatusOk" } }
}
},
"/business/exception/queryException/{remarkSourceId}": {
"get": {
"tags": ["exception-reuse"],
"summary": "[复用+扩展] 查某实体下的异常列表",
"description": "存量端点。2D 传 dsObjectId、3D 传三维体 dsObjectId。返回该实体全部异常；客户端按 consortiumId 分组成异常体树。**3D 扩展**：返回项 location 含 worldPts+plane、并含 screenshot。",
"operationId": "queryExceptionBySource",
"parameters": [ { "name": "remarkSourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "2D=dsObjectId；3D=三维体 dsObjectId" } ],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExceptionList" } } } ] } } }
}
}
}
},
"/business/exception/queryExceptionByTmObjectId/{tmObjectId}": {
"get": {
"tags": ["exception-reuse"],
"summary": "[复用] 查某 TM 下全部异常(按异常体分组)",
"description": "存量端点(loadExceptionsByTmAsync)。返回 TM 下全部异常，含 consortiumId/consortiumName/consortiumType(异常体分组，存量已有)，客户端按 consortiumId 归组。",
"operationId": "queryExceptionByTm",
"parameters": [ { "name": "tmObjectId", "in": "path", "required": true, "schema": { "type": "string" } } ],
"responses": {
"200": {
"description": "成功",
"content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExceptionList" } } } ] } } }
}
}
}
}
},
"components": {
"parameters": {
"DsObjectIdPath": {
"name": "dsObjectId", "in": "path", "required": true,
"schema": { "type": "string" }, "description": "数据集 dsObject id"
}
},
"responses": {
"StatusOk": {
"description": "操作状态",
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }
}
},
"schemas": {
"Envelope": {
"type": "object",
"required": ["code", "msg"],
"properties": {
"code": { "type": "integer", "example": 200, "description": "200=成功，其它=失败" },
"msg": { "type": "string", "example": "操作成功" },
"data": { "description": "业务载荷(对象或数组)", "nullable": true }
}
},
"CreatedRef": {
"type": "object",
"required": ["dsObjectId"],
"properties": { "dsObjectId": { "type": "string", "description": "新建数据集 id" } }
},
"Vec3": {
"type": "array", "description": "世界系三分量(米)",
"items": { "type": "number", "format": "double" }, "minItems": 3, "maxItems": 3
},
"Pt2": {
"type": "object", "description": "2D 点(剖面系：x=距离, y=深度)",
"properties": { "x": { "type": "number", "format": "double" }, "y": { "type": "number", "format": "double" } }
},
"InterpModel": {
"type": "string", "enum": ["Idw", "Kriging"], "default": "Idw",
"description": "插值模型(本期仅 Idw 实现，Kriging 占位)"
},
"RemarkSourceType": {
"type": "string", "enum": ["1", "2", "3", "4"],
"description": "标注形态(非实体类型)：1点/2线/3面/4文字"
},
"StructNodeList": {
"type": "object", "description": "结构树信封内层(data.value)",
"properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/StructNode" } } }
},
"StructNode": {
"type": "object", "description": "项目结构扁平节点(GS/TM)，客户端按 parentId 建树",
"properties": {
"id": { "type": "string" }, "name": { "type": "string" }, "parentId": { "type": "string" },
"typeName": { "type": "string" }, "confCode": { "type": "string" },
"typeId": { "type": "string", "description": "类型 id(编辑时 getDynamicForm 必需)" },
"type": { "type": "integer" }
}
},
"DsPageRequest": {
"type": "object", "description": "存量 dsObject/data/page 请求体",
"required": ["projectId", "structParentId", "structParentConfType", "classifyTypeList", "pageNo", "pageSize"],
"properties": {
"projectId": { "type": "string" },
"structParentId": { "type": "string", "description": "查三维体填生成位置节点 id(GS/项目根/TM)；查切片填所属三维体 dsObjectId" },
"structParentConfType": { "type": "integer", "description": "父节点配置类型：1=GS/项目根 2=TM(三维体生成位置)；查切片时=三维体所在层级" },
"classifyTypeList": { "type": "array", "items": { "type": "integer" }, "description": "数据类别过滤(dd_voxel/dd_slice 的 classify code 由后端定义)" },
"pageNo": { "type": "integer", "default": 1 },
"pageSize": { "type": "integer", "default": 20 }
}
},
"DsPage": {
"type": "object", "description": "分页结果。**注意**：data/page 的行在 `data.list`（不是 data.value），与 structNode/exception 等集合用 data.value 不同（实测客户端按 data.list 解析）。",
"properties": { "total": { "type": "integer" }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/DsRow" } } }
},
"DsRow": {
"type": "object",
"description": "数据集行(data/page 通用 dsObject 行；客户端 parseDsRows 实测口径)。data/page 返回项目结构下**各类** dsObject(文件/网格/反演/三维体/切片/异常…)，非仅三维体/切片。",
"required": ["id", "ddCode"],
"properties": {
"id": { "type": "string" },
"dsName": { "type": "string", "description": "数据集名" },
"name": { "type": "string", "example": "电阻率反演数据", "description": "**数据集类型名**(客户端映射为 typeName；注意 JSON 键是 name，非 typeName)。类型筛选即按此值的范围筛。" },
"ddCode": { "type": "string", "description": "通用 dd 码：dd_voxel/dd_slice/dd_anomaly/dd_section/dd_inversion_data/dd_grid/dd_file 等(非仅 voxel/slice)" },
"dsTypeCode": { "type": "string", "nullable": true, "description": "数据集类型代码(如 'ERT platform inversion data'；分段按它归类，typeName 缺失时筛选回退它)" },
"createTime": { "type": "string", "nullable": true, "description": "创建时间(列表副标题/时间筛选用)" },
"sourceShowParentId": { "type": "string", "nullable": true, "description": "显示树父(派生数据挂源数据下)；客户端 parentId 优先取它，缺则回退 parentId" },
"parentId": { "type": "string", "nullable": true, "description": "sourceShowParentId 的回退" },
"structParentId": { "type": "string", "nullable": true, "description": "结构归属父(项目根/GS/TM)——分段树据此把 ds 挂到 GS/TM 容器下" },
"structParentConfType": { "type": "integer", "nullable": true, "description": "结构父配置类型：1=GS/项目根 2=TM" },
"properties": {
"description": "字段值(泛型 JSON)。**两种形态都可能**：数组 [{confFieldId,value}] 或对象 {confFieldId:value}；文件型 ds 此处可能是文件元数据；派生数据可能为 null。**实测 data/page 多不返回业务字段值(装置/采集时间等)，故装置类型不在此**。",
"nullable": true
},
"file": {
"type": "object", "nullable": true, "description": "文件型 ds 的文件信息",
"properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": "integer" } }
}
}
},
"DsObjectDetail": {
"type": "object", "description": "存量 dsObject/getDetail 返回。三维体/切片机器参数搭车 attachedParameters。",
"properties": {
"dsObjectId": { "type": "string" }, "name": { "type": "string" },
"description": { "type": "string", "nullable": true },
"attachedParameters": {
"type": "object", "description": "附加参数(自由结构化 blob)",
"properties": {
"deltaContent": { "type": "array", "items": { "type": "object" }, "description": "描述富文本(Quill delta ops)" },
"voxelParams": { "allOf": [ { "$ref": "#/components/schemas/VolumeBuildParams" } ], "nullable": true, "description": "dd_voxel 专属：构建参数(体素字节在客户端本地)" },
"slicePose": { "allOf": [ { "$ref": "#/components/schemas/SliceSpec" } ], "nullable": true, "description": "dd_slice 专属：三点位姿(切面在客户端重采样)" }
}
}
}
},
"DynamicForm": {
"type": "object", "description": "ds 属性动态表单(存量统一模型)",
"properties": {
"formList": {
"type": "array", "description": "分组列表",
"items": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "分组名" },
"values": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }
}
}
}
}
},
"UpdateDsObjectRequest": {
"type": "object", "required": ["dsObjectId"],
"properties": {
"dsObjectId": { "type": "string" }, "description": { "type": "string" },
"attachedParameters": {
"type": "object", "description": "改三维体参数/切片位姿放这里",
"properties": {
"deltaContent": { "type": "array", "items": { "type": "object" } },
"voxelParams": { "allOf": [ { "$ref": "#/components/schemas/VolumeBuildParams" } ], "nullable": true },
"slicePose": { "allOf": [ { "$ref": "#/components/schemas/SliceSpec" } ], "nullable": true }
}
}
}
},
"VolumeBuildParams": {
"type": "object", "description": "三维体构建参数(必存元数据；体素字节由客户端按此本地插值，不上后端)",
"required": ["sourceDatasetIds"],
"properties": {
"sourceDatasetIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "源数据集 id(≥1，被引用即锁定不可改)" },
"interpModel": { "$ref": "#/components/schemas/InterpModel" },
"cellXY": { "type": "number", "format": "double", "default": 1.0, "description": "水平网格间距(米)" },
"cellZ": { "type": "number", "format": "double", "default": 0.5, "description": "竖向网格间距(米)" },
"power": { "type": "number", "format": "double", "default": 2.0, "description": "IDW 幂" },
"maxDist": { "type": "number", "format": "double", "default": 4.0, "description": "超距 blank" },
"colorScaleId": { "type": "string", "nullable": true, "description": "色阶来源 ds(空=取首个源色阶)" }
}
},
"VoxelGenerateRequest": {
"type": "object", "required": ["projectId", "structParentId", "structParentConfType", "name", "sourceDatasetIds"],
"properties": {
"projectId": { "type": "string" },
"structParentId": { "type": "string", "description": "生成位置节点 id —— 三维体挂在所选 GS/项目根/TM 下" },
"structParentConfType": { "type": "integer", "default": 1, "description": "1=GS/项目根 2=TM；默认单GS挂该GS、跨GS挂项目根，用户可在生成对话框改为任意 GS/TM" },
"name": { "type": "string" },
"sourceDatasetIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
"interpModel": { "$ref": "#/components/schemas/InterpModel" },
"cellXY": { "type": "number", "format": "double", "default": 1.0 },
"cellZ": { "type": "number", "format": "double", "default": 0.5 },
"power": { "type": "number", "format": "double", "default": 2.0 },
"maxDist": { "type": "number", "format": "double", "default": 4.0 },
"colorScaleId": { "type": "string", "nullable": true }
}
},
"SliceSpec": {
"type": "object",
"description": "切面精确几何(三点+轴向)。法向=normalize((p1-o)×(p2-o))，可派生。存于 attachedParameters.slicePose。",
"required": ["volumeDsId", "origin", "point1", "point2"],
"properties": {
"volumeDsId": { "type": "string", "description": "所属三维体 dsObjectId" },
"axis": { "type": "integer", "enum": [0, 1, 2, 3], "default": 3, "description": "0 上下/1 前后/2 左右/3 任意" },
"origin": { "$ref": "#/components/schemas/Vec3" },
"point1": { "$ref": "#/components/schemas/Vec3" },
"point2": { "$ref": "#/components/schemas/Vec3" },
"colorScaleId": { "type": "string", "nullable": true }
}
},
"SliceGenerateRequest": {
"type": "object", "required": ["projectId", "volumeDsId", "name", "origin", "point1", "point2"],
"properties": {
"projectId": { "type": "string" },
"volumeDsId": { "type": "string", "description": "所属三维体 dsObjectId —— 切片挂在三维体下" },
"name": { "type": "string" },
"axis": { "type": "integer", "enum": [0, 1, 2, 3], "default": 3 },
"origin": { "$ref": "#/components/schemas/Vec3" },
"point1": { "$ref": "#/components/schemas/Vec3" },
"point2": { "$ref": "#/components/schemas/Vec3" },
"colorScaleId": { "type": "string", "nullable": true }
}
},
"ExceptionLocation": {
"type": "object",
"description": "异常几何载荷。2D 用 coordinate；**3D 扩展** worldPts+plane。后端须扩展 location schema 以往返保存 3D 字段。",
"properties": {
"coordinate": { "type": "array", "items": { "$ref": "#/components/schemas/Pt2" }, "description": "2D 剖面坐标点(存量)" },
"worldPts": { "type": "array", "items": { "$ref": "#/components/schemas/Vec3" }, "description": "【3D 扩展】异常多边形/折线世界 3D 点" },
"plane": {
"type": "object", "nullable": true, "description": "【3D 扩展】异常所在平面",
"properties": { "normal": { "$ref": "#/components/schemas/Vec3" }, "origin": { "$ref": "#/components/schemas/Vec3" } }
}
}
},
"ExceptionRecord": {
"type": "object",
"description": "异常记录(queryException 返回项)。前段为存量 2D 字段，末尾为 3D 扩展。",
"properties": {
"id": { "type": "string" },
"exceptionName": { "type": "string" },
"exceptionTypeId": { "type": "string" },
"exceptionTypeName": { "type": "string" },
"remark": { "type": "string", "nullable": true },
"createTime": { "type": "string" },
"markType": { "$ref": "#/components/schemas/RemarkSourceType" },
"remarkSourceId": { "type": "string", "description": "2D=dsObjectId；3D=三维体 dsObjectId" },
"remarkSourceType": { "$ref": "#/components/schemas/RemarkSourceType" },
"location": { "$ref": "#/components/schemas/ExceptionLocation" },
"latitudeLongitude": { "type": "object", "description": "经纬度坐标(存量展示用)", "properties": { "latLon": { "type": "array", "items": { "type": "object", "properties": { "longitude": { "type": "number" }, "latitude": { "type": "number" } } } } } },
"geographicalCoordinates": { "type": "object", "description": "投影坐标(存量展示用)", "properties": { "coordinates": { "type": "array", "items": { "type": "object", "properties": { "northCoord": { "type": "number" }, "eastCoord": { "type": "number" } } } } } },
"consortiumId": { "type": "string", "nullable": true, "description": "异常体分组 id(存量已有)；空=未分组 loose" },
"consortiumName": { "type": "string", "nullable": true },
"consortiumType": { "type": "string", "nullable": true },
"legend": { "type": "object", "description": "图例样式(颜色/线宽/虚实等)" },
"screenshot": { "type": "string", "nullable": true, "description": "【3D 扩展 R88】异常截图(base64 或文件引用，传输方式由后端定)" }
}
},
"ExceptionList": {
"type": "object", "description": "异常列表信封内层(data.value)",
"properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionRecord" } } }
},
"ExceptionTypeRow": {
"type": "object", "description": "异常类型项",
"properties": {
"id": { "type": "string" },
"exceptionTypeName": { "type": "string" },
"exceptionTypeCode": { "type": "string" },
"exceptionMarkType": { "$ref": "#/components/schemas/RemarkSourceType" },
"legend": { "type": "object" }
}
},
"ExceptionTypeList": {
"type": "object", "description": "异常类型列表信封内层(data.value)",
"properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionTypeRow" } } }
},
"AddExceptionTypeRequest": {
"type": "object",
"description": "新增异常类型(对照存量 addExceptionType 全字段)",
"required": ["exceptionTypeName", "exceptionMarkType", "projectId"],
"properties": {
"exceptionTypeName": { "type": "string" },
"exceptionTypeCode": { "type": "string" },
"standardNumber": { "type": "string", "nullable": true },
"standardName": { "type": "string", "nullable": true },
"description": { "type": "string", "nullable": true },
"legend": { "type": "object", "description": "按 markType 的图例样式" },
"exceptionNameList": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string" }, "fieldCode": { "type": "string" }, "sort": { "type": "integer" } } } },
"customFormat": { "type": "string", "nullable": true },
"separatorSymbol": { "type": "string", "nullable": true },
"projectId": { "type": "string" },
"exceptionMarkType": { "$ref": "#/components/schemas/RemarkSourceType" },
"type": { "type": "integer", "default": 2 }
}
},
"NewExceptionRequest": {
"type": "object",
"description": "新增异常。存量字段 + 3D 扩展(location.worldPts/plane、screenshot)。",
"required": ["exceptionName", "exceptionTypeId", "projectId", "remarkSourceId", "remarkSourceType", "location"],
"properties": {
"exceptionName": { "type": "string" },
"exceptionTypeId": { "type": "string" },
"projectId": { "type": "string" },
"remarkSourceId": { "type": "string", "description": "2D=dsObjectId；3D=三维体 dsObjectId" },
"remarkSourceType": { "$ref": "#/components/schemas/RemarkSourceType" },
"remark": { "type": "string", "nullable": true },
"location": { "$ref": "#/components/schemas/ExceptionLocation" },
"consortiumId": { "type": "string", "nullable": true, "description": "归入异常体(存量已有；空=loose)" },
"screenshot": { "type": "string", "nullable": true, "description": "【3D 扩展 R88】异常截图" }
}
},
"UpdateExceptionRequest": {
"type": "object",
"description": "更新异常(对照存量 updateException)。",
"required": ["id"],
"properties": {
"id": { "type": "string" },
"exceptionName": { "type": "string" },
"remark": { "type": "string", "nullable": true },
"location": { "allOf": [ { "$ref": "#/components/schemas/ExceptionLocation" } ], "nullable": true },
"consortiumId": { "type": "string", "nullable": true },
"screenshot": { "type": "string", "nullable": true, "description": "【3D 扩展 R88】" }
}
}
}
}
}

82
docs/questions/2026-06-16-反演剖面竖向字段(y-z-elevation)语义待确认.md Normal file
View File

@ -0,0 +1,82 @@
# 反演剖面（dd_inversion_data）竖向字段 y / z / elevation 语义待业务确认
- 日期：2026-06-16
- 背景：桌面客户端在 3D 视图里把 ERT 反演剖面（`dd_inversion_data`）渲染成**竖直帘面**。水平方向已用 `lat/lon` 摆到真实测线位置（弯曲测线渲染为曲面，已验证）。**竖直方向用哪个字段、如何定位，目前不确定**，需业务/数据方确认。
- 数据来源：线上 `GET /business/dd/ert/inversion/rows/{dsObjectId}`。
---
## 1. 接口返回的竖向相关字段
`dd/ert/inversion/rows` 的 `data` 含：
- `x`：长度 `nx`，水平轴（距离？）。
- `y`：长度 `ny`，竖直轴（含义不明，见下）。
- `v`：`[ny][nx]` 电阻率值矩阵（不规则区大量 `null`）。
- `z`：`[ny][nx]`，逐格一个数（含义不明）。
- `elevation`：长度 `nx`，疑似每列地表高程。
- `lat` / `lon`：长度 `nx`，每列经纬度（已用于水平定位）。
- `vmin` / `vmax`、`sectionType` 等。
---
## 2. 核心问题：y / z / elevation 的范围与关系**跨数据集不一致**
抽样 4 条真实 `dd_inversion_data`（**全部 `sectionType=1`**，即不是"剖面类型不同"导致）：
| 数据集 | 项目 | x 范围 | **y 范围** | **z 范围** | **elevation 范围** | z/v 空值 |
|---|---|---|---|---|---|---|
| T251230002-M-2 | 地大华睿演示 | [200.0, 437.7] | **[-35.1, -1.1]** | [-101.5, -0.09] | [-35.0, -34.1] | 0 |
| T120526003-3 | 香港威立雅 | [2.9, 74.6] | **[13.1, 26.2]** | [2.1, 15.4] | [41.6, 51.0] | 1618/1900 |
| ERT1-WS | 演示（高密度+瞬变） | [0.2, 75.7] | **[9.8, 26.7]** | [0.1, 15.4] | [36.1, 37.9] | 14911/90000 |
| ert2-ws | 射洪垃圾填埋场 | [0.04, 235.4] | **[287.6, 353.4]** | [-10.1, -0.03] | [287.8, 292.8] | 0 |
**观察到的矛盾：**
1. `y` 的范围毫无统一规律：有负（-35~-1）、有小正（9~27）、有大正（287~353）。无法判断它是"深度（向下为正）"、"相对层号"、还是"绝对高程"。
2. `z` 同样无规律：有深负（-101.5）、有小正（0~15）、有小负（-10）。
3. `elevation` 看起来最像"地表高程"（随项目所在地不同：-34 / 41~51 / 36 / 288~293），但与 `y`、`z` 的换算关系**对不上**（例：射洪 `y`≈`elevation`≈287~353，而地大 `y`=-35~-1 远小于 `elevation`=-34）。
4. `z` 的空值数恰好等于 `v` 的空值数 → `z` 随"有无数据"分布（像是逐格的某个量）。
> 结论：仅凭数据无法可靠推断竖向模型，且**不同数据集疑似采用了不同的竖向约定/基准**（可能与上传来源/格式有关）。
---
## 3. 客户端做法演变
- **早期（已废弃）**：竖直 Z = `-y[j]`（把 `y` 当"深度向下"），平顶、不随地表。加真实地形底图后暴露问题：剖面整体沉到地下。
- **当前（2026-06-17）**：竖直 Z = `+y[j]`（把 `y` 当**真实高程**），与同样按真实高程渲染的地形底图同系对齐 → 剖面顶≈地表、露出地面（复刻原版观感）。详见 §6。
- 仍**未使用 `z` 和 `alt/elevation`**。
---
## 4. 请业务/数据方确认的问题
1. **`y` 是什么？** 深度（向下为正/为负？）、相对层号、还是绝对高程？为何不同数据集范围差异巨大（-35~-1 vs 287~353）？是否存在多套竖向基准？
2. **`z`（`[ny][nx]`）是什么？** 逐格的真实高程？深度？还是别的量（如反演网格的实际竖向坐标/褶皱面）？
3. **`elevation`（`[nx]`）是什么？** 每列地表高程吗？单位、基准（海拔/相对）？
4. **3D 剖面竖向应如何定位？**
- (A) 维持现状：平顶"距离×深度"面（与 2D 详情一致）；或
- (B) 跟随地表起伏：顶面按 `elevation`/`z` 摆到真实高程、随地形上下。
若选 (B)，请给出**用哪个字段、如何换算**（Z = ?(y, z, elevation)）。
5. **垂向单位与方向**：米？向上为正还是向下为正？
6. **不同数据集的竖向差异**是数据本身的真实差异，还是上传/解析造成的不一致（需后端修正）？
---
## 5. 影响
- 现状 (A) 已能正确渲染（与 2D 详情一致），可继续使用。
- 若业务要 (B) 地形跟随，需上面第 2/3/4 项的明确定义后，客户端按真实竖向模型实现（避免凭猜测导致渲染错误）。
---
## 6. 进展（2026-06-17）：原版 web 代码已部分解答，但仍有跨数据集风险
拿到原版 `commercial-admin` 代码（`dataView/threeMap/threeMap.vue` `addEntityToMap`）后确认其做法：
- **`data.y` = 真实高程**（不是深度）。原版 `originY = data.y[0]`、`localY = data.y - originY`（相对形状），剖面世界 Z = `originY + localY = data.y`，并用 **`alt`（测线每点地表高程）** 算坡度/地表偏移；地形用 Mapbox 真实 DEM。两者同在真实高程系 → 剖面顶≈地表、露出地面。
- **无垂直夸张**（`scale.y = 1`，真实比例）。
**客户端据此已改为 Z = `+y`（§3 当前），与原版完全一致**（实证：`threeMap.vue:676` `position.z = originY + zCorrection`，`originY = data.y[0]`，注释明说"剖面底部对应真实海拔 originY"，网格 `localY = data.y - originY`，`rotateX` 后竖向 = `data.y`）。
**原版的 `alt` 仅用于**：水平定位（`geo2pos` 取 `.x/.y`）+ 坡度补偿 `zCorrection`（而对应的 `rotateZ` 在 667 行被注释掉、实际不生效）。**原版并不用 alt 把剖面顶贴地表**——之前文档此处的"alt 贴地表"为臆测，已更正。
**⚠️ §2 表中 `y` 跨数据集不一致是数据层面问题，原版同样存在**：原版也按 `data.y` 摆放，对 `y≠真实高程` 的数据集（香港 `T120526003-3` `y`=13~26 而 `elevation`=41~51）一样会整体偏离地表。客户端与原版行为一致，非客户端 bug。若要纠正，属数据/业务侧（统一 `y` 的高程基准），非渲染侧凭 alt 推算。

89
docs/questions/2026-06-17-3D地球改造-现状与约束评估.md Normal file
View File

@ -0,0 +1,89 @@
# 3D 地球改造：当前实现方式、目标、问题/约束评估
- 日期：2026-06-17
- 目的：评估桌面客户端 VTK 三维视图从「平面局部坐标场景」改造为「3D 地球（对齐原版 web）」的可行性、影响范围与约束，供决策是否立项。
- 说明：**纯文字描述，不含代码**。结论待 subagent 基于代码实测评审。
---
## 1. 原版（web）目标形态（已实地分析）
- 原版 dataView 用 **Three.js 3D 地球**（容器 `threeMap`，单 WebGL canvas；`__THREE__` 在，Cesium 加载但 `cesium-widget` 未用）。
- 底图瓦片：**Mapbox 卫星** XYZ（`api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.webp`）贴在球面。
- 反演剖面等数据按**真实经纬**贴在弯曲球面上（竖直帘面），可从太空旋转/缩放飞到地面。
- 需求表要求底图为「天地图」（与原版实际用 Mapbox 不一致）；天地图同样有卫星 WMTS（Web Mercator z/x/y），瓦片源可换、不影响"球 vs 平面"这一架构问题。
---
## 2. 当前桌面实现方式（文字描述）
**渲染技术**：桌面用 **VTK**（非 Three.js / 非 Cesium），是与 web 完全不同的另一套实现。
**坐标系：局部切平面（不是地球球面）**
- 用 `GeoLocalFrame`：等距圆柱（equirectangular）近似，把经纬度投影成以某原点为中心的**局部米平面**（x=东、y=北，单位米）。这是一个**小范围测区的平面近似**，不是地心 ECEF 球面坐标。
- 竖直方向 Z = 深度（向下为负），与经纬无关。
- 原点最近改为"按首个真实剖面 lat/lon 中心就地重锚"，使局部坐标从 0 附近起。
**各组件都建立在这个局部平面坐标系上**：
- **帘面（剖面）**：每列经纬经 `GeoLocalFrame` 投到局部米平面，Z 取深度；整体是局部平面里的一面"墙"。
- **切片交互**：在体素/剖面上沿轴向/任意角度切片，基于局部直角坐标的平面/重采样。
- **坐标轴**：取场景局部包围盒造立方体坐标轴，刻度可反算回经纬度显示。
- **相机预设**：前/后/左/右/上/下 6 向 + Zoom/Fit，都假设局部直角坐标、Z 向上。
- **拾取/选中**：在局部坐标场景里按包围盒/距离判定。
- **底图（我刚做的）**：天地图瓦片平铺成**一块平面地面**（z=0），在局部坐标系里，不是球。
**结论**：当前是"**以测区为中心的局部平面 3D 场景**"，适合近距离审视单个剖面/切片；不是地球。spec 当初有意如此选择（VTK ≠ web 球，且三栏/切片在局部直角系才好实现）。
---
## 3. 目标：3D 地球（对齐原版）
- 整个地球为球面（地心 ECEF / 椭球坐标），可从太空旋转、缩放飞到地面。
- 卫星瓦片（天地图卫星）贴满球面，随缩放 LOD 加细。
- 数据（帘面/切片/异常）按真实经纬贴在弯曲球面对应位置。
- 相机为地球导航（轨道环绕 + 飞向目标），而非 6 向局部预设。
---
## 4. 从"局部平面"到"3D 地球"的问题 / 约束（核心）
1. **坐标系根本改变**：局部切平面米 → 地心 ECEF（经纬高→三维笛卡尔球面坐标）。这不是"加个底图"，而是**整个 3D 视图的坐标基准更换**。
2. **所有依赖局部坐标的组件都要重做**：
- 帘面定位（局部米 → 球面 ECEF 的竖直面）；
- 切片几何与重采样（轴向/任意切片在球面坐标下的平面定义变复杂）；
- 立方体坐标轴（球面上"立方体轴"语义不再适用，需换成经纬网/比例尺）；
- 6 向相机预设（前/后/左/右/上/下在球面无固定意义，需改地球导航）；
- 拾取/选中（球面坐标下判定）；
- 纵向比例（垂向夸张）在球面上的语义与实现。
3. **VTK 无现成"瓦片地球"**：Cesium/Three.js 有内建的 LOD 瓦片地球；VTK 没有。要自建：球面几何 + 多级瓦片调度 + 投影贴图 + (大气/光照)，工作量大。
4. **数值精度**：ECEF 坐标量级约 6.4×10⁶ 米，GPU 渲染管线的浮点矩阵在该量级有抖动（jitter）（数据数组本身已用双精度）。标准规避法是"相机相对原点偏移"——**而当前的 `GeoLocalFrame.reanchor`（一切相对数据中心原点渲染）正是这种规避**；即局部平面方案天然避开了球面会引入的精度问题（佐证务实方案）。
4b. **【评审补充，最硬的拦路虎】体素/切片基于 `vtkImageData`（轴对齐规则栅格）**：三维体是 `vtkImageData`（`SetOrigin`/`SetSpacing` 轴对齐），切片工具对它重采样。`vtkImageData` 本质是轴对齐规则网格，**无法弯曲贴到球面**。这是真 3D 地球最根本的不兼容点，比"切片重采样变复杂"更强。
4c. **【评审补充】地形 actor（TerrainActor）也全程局部系**：DEM 顶点经 `frame.toLocal` 摆放 + 独立 EPSG 重投影/墨卡托纹理坐标，球面化都要重做。
4d. **【评审补充】纵向夸张(VE)散布三处**：帘面 `SetScale(1,1,ve)`、体素烤进 origin/spacing、地形 zScale。球面上"缩放 Z"无单一含义（Z 是径向、方向逐点变），三处都要重定义。
4e. **【评审补充】2D 俯视测线模式（Map2D）**：`applyTop2D + addSurveyLine` 也建在 z=0 局部平面，球面基准下要么单独保留平面投影、要么重新推导。
5. **小尺度上收益有限**：数据都在几百米的小测区；该尺度下地球曲率不可见——"飞到地面的地球"与"局部卫星平面"看到的卫星图基本一致。3D 地球真正多出的是"从太空看全球/转地球"的整体观感与"和原版一致"。
6. **与既有功能的冲突**：本轮已完成的三栏/帘面/切片/坐标轴/相机预设全部基于局部平面；改球面等于把这些重写或重新适配，回归风险高、且 GUI 不可由我自测。
---
## 5. 影响范围 / 工作量（定性）
- **底图本身**（瓦片源换天地图）：小。
- **平面底图 → 局部卫星平面**：小（现成 TileBasemap 换源）。
- **平面场景 → 3D 地球**：**大重构**，触及坐标系 + 帘面/切片/轴/相机/拾取/底图全链，属重新立项分期，不宜并入当前轮次。
---
## 6. 决策建议
- 3D 地球是**根本性重构**（非底图增量）；本地剖面尺度（几百米）下与"局部卫星平面"视觉收益差异有限；务实方案是"局部天地图卫星平面"，3D 地球如确需"地球观感"则单独立项分期。
## 7. 评审结论（opus 子代理 · 基于代码实测）
- §2 当前实现的 7 项描述（局部等距圆柱坐标、帘面/切片/坐标轴/相机/拾取/底图均依赖局部平面）**逐条经代码核实，全部准确**（与源码逐字吻合）。
- §4 "球=根本性重构"的判断**成立且偏保守**——文档**低估**了耦合面：另需重做 **地形 actor、体素 `vtkImageData` 轴对齐(最硬拦路虎，规则栅格无法贴球)、三处纵向夸张、2D 俯视模式**（已补入 §4b–4e）。无任何"夸大耦合"之处。
- 总体结论 **SOUND**：3D 地球触及整条 3D 管线根基，非底图增量；局部卫星平面是务实折中；站点尺度曲率视觉可忽略。其中**体素/切片基于 vtkImageData 无法弯曲贴球**是最强佐证。

100
docs/superpowers/HANDOFF-2026-06-26-vtk-anomaly-2d-analysis.md Normal file
View File

@ -0,0 +1,100 @@
# HANDOFF — VTK 3D 视图：创建异常打磨 + 切片/异常交互 + 二维分析改造（2026-06-26）
> 分支 `feat/vtk-3d-view`。桌面端 Qt6 + VTK 9.6。本会话围绕「创建异常」全链路打磨、切片/异常交互修复、全局中文化，最后转入「二维分析改造」的需求厘清 + 写 spec。**下一步＝按 spec 实现二维分析 A 期。**
---
## 0. 立刻要做的事（下个会话从这里开始）
**二维分析改造 A 期已实现**（未提交，下个会话需用户实跑反馈手感/角度）。spec：`docs/superpowers/specs/2026-06-26-2d-analysis-topdown-elevation.md`（commit `227ee8f`）。分期 A→B→C：
- **A（已实现 ✅，build+439测试全绿，未提交）**：一场景两相机。切「二维分析」tab → 近俯视(下压12°≈78°俯角)+禁旋转(左键改平移、仅平移/缩放)；按维度翻 actor `SetVisibility`（轨迹↔体/帘面/异常，**不清空**）；切片 `SetEnabled` 显隐（不销毁）；地形+底图常驻；切回三维还原相机快照。**待用户实跑**：①近俯视角度是否合适②切换是否瞬时③左键平移手感④切回三维视角还原是否自然。
- 改动文件：`CameraPreset.{hpp,cpp}`(applyNearTop2D)、`PickInteractorStyle.{hpp,cpp}`(setLock2D)、`SliceTool.{hpp,cpp}`(setVisible)、`InteractionManager.{hpp,cpp}`(setMode2D)、`VtkSceneView.{hpp,cpp}`(setAnalysisMode2D+mapLineDs_+相机快照)、`ColumnDrawer.{hpp,cpp}`(analysisModeChanged 信号)、`main.cpp`(接信号)。
- 已知小风险：2D 取景 `computeDataBounds` 含隐藏的 3D 体包围盒（地形主导，影响小）；切片 `SetEnabled` 显隐属 GUI 不可自测项。
- **B（已实现 ✅，build+441测试全绿，未提交，待实跑）**：二维里选中足迹（单/Ctrl 多选）→ 竖向拖动只改**高程 Z**、锁 XY、顶部实时高程读数浮层；Z 偏移按 dsId 持久（切走再回/全量重建保留）。手势：单击足迹=选中、Ctrl+单击=多选切换、点空白=取消+平移、（多）选后竖向拖动=整体改 Z。
- 实现：`VtkSceneView` 加 `pickMapLineAt/nudgeSelectedMapLinesZ/selectedMapLineZ/clearMapLineSelection`（vtkCellPicker+PickFromList 只拾可见足迹、选中高亮黄加粗、`mapLineZOffset_` 持久）；`PickInteractorStyle` lock2D 下命中足迹→Z 拖动(`onPick2D/onDrag2D/onDrag2DEnd`+`worldPerPixelZ` 像素→世界Z)、否则平移；`InteractionManager::pickStyle()` 暴露样式；`main.cpp` 接回调 + 高程读数浮层(复用提示样式)。
- **待用户实跑**：①拾取灵敏度(tol 0.012)②拖动 Z 灵敏度/方向(上移=抬高)③多选拖动④读数是否合理(现为 actor 包围盒中心世界 Z，含 placement+偏移，未除 VE)。
- **C（下一步）**：dd_raster 纳入 2D 过滤 + 按 ddCode 分派渲染 + 栅格地理配准贴地形。**阻塞：dd_raster 数据端点未确认**（需后端给「像素 + 四至/投影」端点）。
---
## 1. 环境 / 命令 / 铁律（必读）
- **构建**：用 PowerShell 工具跑 `cmd /c "D:\Git\lanbingtech\geopro\build.bat app"`（Claude 的 Bash 跑 build 会被环境劫持，用 PowerShell）。测试 `build.bat test`（ctest，**439 用例**）。`vswhere.exe not recognized` 噪声无害。LNK1104=exe 被运行中的 app 锁，需用户关 app 才能链接。
- **回复用中文**（用户要求）。
- **CLAUDE.md 两条绑定规则**：①发现技术债当场修，不以"非本轮引入"搪塞；②**能自己做的绝不让用户做**——日志(`%LOCALAPPDATA%/Geomative/Geopro3/logs/geopro_*.log`)/数据/构建/诊断都自己来，只在 LNK1104 关 app、或真正产品决策才找用户。
- **git**：精确 `git add <files>`（仓库有并行 GPR 会话的脏文件 `.superpowers/sdd/*`、`docs/.../poc-lod-shots/*.png`，**勿误提交**）。提交无 Co-Authored-By（全局禁）。
- **后端 token（可访问真实接口，用户给的）**：`geomativeauthorization: Geomative e6c1259748644c8da0954d864bb82604`；base URL `http://tenant.geomative.cn/pop-api`；样例 projectId `1439735554211840`。可用 curl 查接口。
---
## 2. 本会话已完成（提交清单，新→旧）
**创建异常全链路（核心工作量）**
- `227ee8f` 二维分析 spec（doc）。
- `c1a824e` 二维维度分类对齐数据字典 DD0623（去 3 个已删除轨迹类型，dimensionOf/dimOf/测试）。
- `e8bb2f8`/`1648ccb`/`f230ca8` 异常绘制提示：vtkTextActor 渲染不出中文 → 改 **app 层 QLabel 浮层**（右上角、深底方角、不挡鼠标）；列表切到别对象清切片选中（`deselectSlice`）。
- `9782a2b` 删除切片/异常加确认框 + **弹框按钮全局中文化**（Qt zh_CN 翻译器 + `formkit::addDialogButtons` 默认「确定/取消」+ 打包补 qtbase_zh_CN.qm）。
- `306d7bc` 提示移右上角 + **线双击结束含双击位置**（去回滚）。
- `d7ab770` **切片保存后定稿锁定**（`SetInteraction(0)` 不可移动/旋转）+ VTK/列表菜单去「保存·另存」。
- `91a7106` **结束手势**：点=单击即完成、线=双击、面=**点回起点闭合**（近起点 12px 吸附+橡皮筋指向起点）。
- `1a70ca0` 异常对话框加**样式预览**（选中类型 legend 可视化：点球/线/面）。
- `4ae8286` **异常截图配色与切面一致**：取 widget 自身 `GetColorMap()` 输出（非另建 LUT）→ 逐像素一致 + RGBA 外区透明消蓝边。
- `d470dc8` 双击/单击隔离（后被 `306d7bc` 改回"含双击位置"）+ 异常类型下拉误显「暂无数据」（`EmptyAwareComboBox::realItemCount` 用错 flags 角色→改 `model()->flags()`）。
- `04af569` 返工（点交互/点渲染小球/截图/类型空态）。
- `75c1327`→`3ed1ea7`→`58544ff`→`c6756aa` 截图相机方案A(已废)、**异常类型接平台真实类型**(`listExceptionTypes` 按形态)、**点/线/面三态**子菜单、**样式接平台 legend**(`getExceptionTypeDetail`)。
- 截图最终方案：**只从切片 2D 剖面图、按异常几何 buffer 裁剪**（`captureAnomalyShotFromSlice`，GIS buffer+掩膜，点圆/线胶囊/面外扩多边形）。
**其它**
- `56e4b3a` 登录验证码容器白底。
- `8563693` 分段折叠向上收起（stretch 动态：展开=1/折叠=0+尾弹簧）。
- `d6e52cb` 三维分析分段面板视觉打磨（chevron 段头/描边新增按钮/顶部留白）。
- `fb911a9` 坐标轴面板硬编码色 token 化。
- `cdd7613` vtk-3d-openapi 文档对齐实测（DsPage 行在 `data.list`、DsRow 全字段、装置不在 data/page）。
- `2f6ec7d`→`1742b75`→`31ad7a4` **装置筛选**：data/page 行不带 properties→改按行自带 `typeName/dsTypeCode` 筛选；parseDsRows 兼容对象形态。
- 期间生成了一次安装包：`installer/dist/Geopro_Setup_3.0.0-20260625.exe`（脚本 `installer/build_installer.ps1`，含 windeployqt+样本+PROJ+vc_redist）。
---
## 3. 创建异常功能现状（已落地，端到端可用，mock 保存）
入口：VTK 切片右键 →「创建异常 → 点/线/面」。流程：圈定(AnomalyDrawTool)→草稿渲染→**从切片2D图buffer裁剪截图**→对话框(名称/异常类型[接平台]/样式预览/备注/截图)→保存(mock)→刷新树+渲染异常 actor。
- **关键文件**：`src/render/interact/AnomalyDrawTool.{hpp,cpp}`（三态绘制：点单击完成/线双击/面点起点闭合，Esc取消/Backspace撤点）；`src/app/AnomalySaveDialog.{hpp,cpp}`（接 `cmdRepo.listExceptionTypes`/`getExceptionTypeDetail`，样式预览）；`src/app/SliceExport.{hpp,cpp}`（`captureAnomalyShotFromSlice`）；`src/render/actors/AnomalyActor.cpp`（点=球/线=折线/面=闭合多边形）；`src/app/main.cpp`（onSliceContextMenuRequested ~509 起：菜单+绘制+对话框+保存接线，QLabel 提示浮层）。
- **样式来源**：选中平台异常类型 → `getExceptionTypeDetail` 取 legend（polylineColor/Width/Shape, pointColor…）→ 套到异常 lineColor/lineWidth/dashed。
- **截图**：只裁切片那张 2D 剖面图（`InteractionManager::selectedSliceColorImage` 现取 `SliceTool::coloredResliceImage()`=widget ColorMap 输出，与屏幕同源）。
### 仍卡在后端（P3，非客户端问题）
- **异常真保存 `newException`** 卡：异常 `remarkSourceId` 须指向真实 dsObjectId（三维体/切片），但真后端**无任何登记三维体/切片为 dsObject 的端点**（实测 `voxel/generate`、`slice/generate`、通用 `dsObject create` 全无）。当前 `saveAnomaly` 是内存 mock。后端补登记端点后整链可接真。
- 平台「点」类异常类型该项目为空（线/面有）→ 画点时类型下拉空属正常。
---
## 4. 二维分析改造——已确认的设计决策（与用户逐条敲定）
1. **不分两个场景**：一个 3D 地形场景（带高程）+ 底图贴地形，两栏只是相机不同。"二维分析只是 3D 的固定视角"。
2. **二维相机**：锁定**近俯视(75–80°，非绝对正俯视)**，禁旋转，仅平移+缩放。（绝对正俯视看不出高程→留倾斜）
3. **切 tab 显隐**：翻另一方数据集 `SetVisibility`（**不显示，非清空**）→ 性能零代价（VTK 跳过不可见 actor）、切换瞬时、只占内存。地形+底图常驻。**绝不清空**（重体素重建会卡）。
4. **高程拖动(C1)**：二维里选中 2D 内容（单/多选）→ 竖向拖动只改**高程 Z**、锁 XY、实时读数。用途=分离叠在一起的 2D 层。
5. **维度过滤**：2D = `dd_trajectory_data`（+ C 期 `dd_raster`）；`dd_radar_2d/3d` 是 3D（不进 2D）。已对齐 DD0623（`c1a824e`）。
6. **雷达客户反馈**：只影响数据模型 + **3D 视图**渲染（二维雷达=线、三维雷达=切面、带打标）+ 详情页校准——**均属另立任务，不在本次 2D 改造**。2D 只显示轨迹线、打标暂不做（与本设计一致）。
---
## 5. 关键代码锚点（二维分析改造用）
- 切 2D 视图模式钩子：`Column2DDataset::view2DModeChanged` → `main.cpp` 接 `sceneCtrl`（搜 `view2DModeChanged`）。
- 维度分类：`src/app/DatasetDimension.cpp::dimOf`（col2D 用）；`src/data/api/Api3dRepository.cpp` + `src/data/repo/LocalSample3dRepository.cpp::dimensionOf`。
- 2D 内容注入：`main.cpp` ~502 `col2D->setDatasets(splitByDimension(...).dim2D)`；勾选渲染 `Column2DDataset::checkedDatasetsChanged` → `loadMapLine`/`MapLineActor`。
- 场景/相机/可见：`VtkSceneView`（actor 管理）、`VtkSceneController`、`InteractionManager`（拾取/选中，新增 `deselectSlice`）。
- 地形+底图：`buildTerrain`（带高程，VE 垂直夸张相关）、`TileBasemap`（天地图按经纬贴）。
- 数据字典：`D:\Projects\GEOPRO\DD0623.xlsx`（46 个 ddCode，列：序号/ddCode/领域/含义/状态/**展示模式(2D/3D)**/**展示形态**/备注…）。解析：openpyxl 可用，中文 GBK 终端会乱码→导 UTF-8 文件再 Read。
---
## 6. 待确认/风险
- **dd_raster 数据端点**（像素+四至/投影）未确认 → C 期阻塞。
- 近俯视角度需实机调；高程是否落库暂定会话内（不落库）。
- §3 翻可见标志需可靠区分每个 actor 的维度归属。
- 切相机/可见与现有 view2DModeChanged、底图、地形 VE 逻辑勿打架。
- **GUI 无法登录自测**：相机/截图/交互类改动我只能保证编译+逻辑，视觉/手感需用户实跑反馈。
---
## 7. 相关记忆/文档
- 记忆库 `MEMORY.md`（如 login-chain-truth、vtk-3d-persistence-structure、build-vs2026-vcpkg-gotchas、deploy-hardcoded-dev-paths 等）。
- vtk-3d API 设计草案：`docs/api/vtk-3d-openapi.json`（已对齐实测，0.6.1）。
- 真后端 API：`docs/apis/business_OpenAPI.json`。
- 二维分析 spec：`docs/superpowers/specs/2026-06-26-2d-analysis-topdown-elevation.md`。

84
docs/superpowers/HANDOFF-vtk-3d-backend-api.md Normal file
View File

@ -0,0 +1,84 @@
# 交接：VTK 三维视图 后端 API 设计（三维体 / 切片 / 异常）
> 给下一个会话无缝接手用。更新日期 2026-06-24。分支 `feat/vtk-3d-view`。本会话**纯设计 + 产出对接文档，未改业务代码**。配套实现交接见 [`HANDOFF-vtk-3d.md`](./HANDOFF-vtk-3d.md)。
>
> **进度速览**：澄清了"三维体/切片/异常存为 ds、能否复用存量 ds 接口"的全部疑问，产出后端对接 Swagger `docs/api/vtk-3d-openapi.json`（OpenAPI 3.0.3，15 路径/26 schema），已提交 `9d3b103`（未推送）。记忆 [[vtk-3d-persistence-structure]] 已同步定论。**无半成品**。下一会话方向：① 把这份契约交付后端排期；② 后端就绪后做客户端切真实（接口不动，换 `Api3dRepository` 实现）。
## 1. 背景
- 代码库 `D:\Git\lanbingtech\geopro` = 原版 web 系统移植的 Qt 桌面客户端；原版 web 源码 `D:\Git\lanbingtech\commercial-admin` 是复刻权威。
- 三维体/切片/异常的渲染/交互**已实现**（见另一份 handoff），但持久化全是 **mock**（`I3dSceneRepository` 留缝、`Api3dRepository` 内存 map）。
- 本会话起点问题：三维体/切片要存为 ds、异常要挂三维体，**现有 ds 接口能否复用？** 由此推导出后端要补哪些端点，并产出 Swagger。
## 2. 本会话已完成
- **摸清存量两套仓储 + 真实端点**（见 §6 代码地图）。
- **澄清一系列关键设计点**（§3）。
- **产出 `docs/api/vtk-3d-openapi.json`**：三件套后端对接设计稿，JSON 校验通过、无悬空/未用 schema。
- **提交** `9d3b103`（仅该文件，未推送；按全局设置未加署名）。曾有中间产物 `docs/api/voxel-slice-openapi.json`，迭代后已删并合入 vtk-3d-openapi.json。
- **更新记忆** [[vtk-3d-persistence-structure]]，加全部定论 + 文档路径 + commit 号。
## 3. 设计定论（多轮被用户纠正后收敛，**这是核心交付**）
1. **三维体/切片对后端 = 纯元数据 dsObject**
- 增删改查/属性**复用存量 dsObject 面**：`projectStruct`树 / `dsObject/data/page`列表 / `getDetail`详情 / `dynamicForm`属性 / `updateDsObject`更新 / `dsObject/{id}`删除。
- 各只加 **1 个登记端点**（`/dsObject/voxel/generate`、`/dsObject/slice/generate`）——存量"建 ds = 文件 import"对生成类不适用；登记只建记录、**不触发后端计算**。
2. **体素字节/切面数据全在客户端，后端零数据端点**
- 连 GPR 大体（13.6G）体素也**不上传**、即使落盘也在客户端本地（`ChunkedVolumeStore`）；后端只持有 dsObject 记录。
- 故**无** meta/brick/上传/切片位姿端点（设计途中曾加过，全删）。params/voxel 是否本地落盘是纯客户端策略，后端不感知。
3. **小块结构化数据搭车 `attachedParameters`**
- 三维体构建参数（`voxelParams`）、切片三点位姿（`slicePose`）存这里，读走 `getDetail`、写走 `updateDsObject`（与描述 `deltaContent` 同机制）。`dynamicForm` 只放给人看的键值属性。
4. **归属结构：TM → 三维体(dd_voxel) → 切片(dd_slice)**，异常挂三维体
- **三维体挂在 TM 下**（本会话纠正，之前记忆误写"对象/GS"）。`structParentConfType=2`(TM)。
5. **异常复用整套 `/business/exception` 端点**（实体无关，三维体 id 直接塞 `remarkSourceId`）
- **异常体(consortium)分组是存量已有**（`parseExceptions` 已解析 `consortiumId/Name/Type`，`queryExceptionByTmObjectId` 按其分组）——**非 3D 新增**（此前误判已纠正）。
- 3D 仅扩展两处、都在 body/返回字段（**不新增端点**）：① `location` 加 `worldPts`（三维多边形点）+`plane`（所在平面），存量是 2D `coordinate[{x,y}]`+经纬/投影坐标；② 截图（R88）。
## 4. 剩余工作（按依赖顺序）
**后端**（阻塞一切，把 `vtk-3d-openapi.json` 交付排期）：
1. 注册 `dd_voxel`/`dd_slice` 两个 dd 类型 + 各自 `classifyType` code。
2. 实现两个登记端点（`voxel/generate`、`slice/generate`），返回真 `dsObjectId`。
3. 为这两类型注册 `dynamicForm`（属性表单）。
4. 扩展异常 `location` schema 容纳 3D `worldPts`+`plane` 并保证往返不丢。
5. 加异常 `screenshot` 字段 + 定传输方式。
**客户端**（后端就绪后；接口 `I3dSceneRepository` 不动，留缝就是为此）：
6. `Api3dRepository` 内存 map 换成调真实端点。
7. `main.cpp:450-451` 手动 append 三维体/切片行改成走后端树。
8. 3D 异常路径从 `I3dSceneRepository`(mock) 切到 `IDatasetCommandRepository`(真)，`remarkSourceId`=三维体真 id。
## 5. 待确认问题
- `classifyTypeList` 里 dd_voxel/dd_slice 的具体 code（后端定）。
- `location` 3D 字段精确结构（后端定）。
- 截图传输：base64 内联 vs 单独上传（后端定）。
- **未验证风险**：原系统 `remarkSourceId` 只挂过 2D dsObject，没挂过三维体 id；`listExceptionTypes`/`getExceptionName` 挂三维体时是否如预期，需后端整链就绪后实测。
## 6. 代码地图（本会话查证过的关键文件）
| 文件 | 作用 |
|---|---|
| `src/data/repo/I3dSceneRepository.hpp` | mock 留缝接口（三维体/切片/异常/任务 CRUD）|
| `src/data/api/Api3dRepository.{hpp,cpp}` | mock 实现（`volumes_`/`slices_`/`anomalies_` 内存 map）|
| `src/data/repo/LocalSample3dRepository.cpp` | 本地样本 stub |
| `src/data/repo/IDatasetCommandRepository.hpp` | **真实**异常端点 + ds 详情写操作 |
| `src/data/api/ApiProjectRepository.cpp` | **真实** dsObject 面（getDetail/dynamicForm/data/page/delete/update/import/projectStruct）|
| `src/core/model/Anomaly.hpp` | 异常模型（2D: localPts/lonLat/eastNorth；3D: worldPts/plane）|
| `src/data/repo/VolumeBuildParams.hpp` | 三维体构建参数 |
| `src/data/store/ChunkedVolumeStore.hpp` | GPR 分块体存储（客户端本地落盘）|
| `src/app/main.cpp` | 接线（450-451 合并注入、577/661/745 createSlice/createVolume）|
| `src/data/dto/NavDto.cpp:374` | `parseExceptions`（含 consortium 字段，证实异常体存量已有）|
| `src/data/dto/DatasetChartDto.cpp` | 异常 location/坐标系解析 |
| `docs/api/vtk-3d-openapi.json` | **本会话产出** |
**后端响应信封**：`{code:int, msg:string, data:object|array}`，`code==200` 成功，列表/集合放 `data.value`。
## 7. 铁律 / 注意
- **贴源码/日志，别凭印象**：本会话多次因臆测（"装不下"、"异常体是 3D 新增"、自造端点不贴存量）被用户纠正——任何接口字段/语义都先去代码里核实。
- **复用优先于新建**：实体无关的契约一律复用存量；只有"生成动作"和"3D 几何/截图"这种存量真装不下的才扩展。
- 全部回复中文。
## 8. 相关
- 记忆：[[vtk-3d-persistence-structure]]（已含本会话定论）、[[gpr-volume-design-trio]]、[[dataset-list-is-tree]]、[[vtk96-hdfwriter-no-imagedata]]。
- 实现交接：[`HANDOFF-vtk-3d.md`](./HANDOFF-vtk-3d.md)。

115
docs/superpowers/HANDOFF-vtk-3d.md Normal file
View File

@ -0,0 +1,115 @@
# 交接：VTK 三维视图（feat/vtk-3d-view）
> 给下一个会话无缝接手用。更新日期 2026-06-18（#4 异常功能全部收口后）。分支 `feat/vtk-3d-view`，工作树：仅根目录 `grid-list-original.png`/`grid-list-small.png`/`grid-snap.yml`/`orig-dataview.png` 及 `docs/superpowers/specs/2026-06-17-web-embed-subpage-mount-design.md` 是**既有未跟踪文件，非本任务产物，勿动/勿提交**（曾被 `git add -A` 误纳、已撤回）。
>
> **进度速览（2026-06-18）**：补充需求 #1 生成三维体 ✅、#2 切片交互 ✅、#3 切片生命周期 ✅、#4 异常（圈定/保存/列表/异常体/过滤/显隐/删除/选中高亮/属性对话框）✅、#6 体/切片数据详情对话框 ✅ 全部完成、编译绿、用户实测通过。最新提交 `b97ea68`（#6 详情对话框）。**剩下全是收尾/打磨项**（见 §4 末「下一步候选」），无进行中的半成品。下一会话应先问用户选哪个方向，或直接接其指定项。
>
> **附**：Windows 安装包打包工具已落地（`installer/`，提交 `0504129`）：`build.bat app` 后 `powershell -File installer\build_installer.ps1` 一键出 Inno Setup 安装包（自动 windeployqt 补 Qt 运行时+绕过 ADS 卡死、补 VC 运行时、中文向导）。
## 1. 背景
- 项目：geopro 桌面客户端（Qt6 + VTK9 + Qt-ADS dock），Windows/MSVC+Ninja，`build.bat`。
- 任务：实现需求表「补充需求」页 = VTK 三维视图整套结构/交互。需求源：`D:\Projects\GEOPRO\Geopro3.0 需求表.xlsx`「补充需求」页。
- 原版 web 源码在 **`D:\Git\lanbingtech\commercial-admin`**（Vue + three-tile），是**复刻的权威参照**（threeMap.vue / mapSource.js / src/apis/）。
- 三栏结构（三维数据集 / 二维数据集 / 三维分析）+ 真实 ERT 反演剖面（帘面）+ 底图地形——这些**已完成**。本会话主要做了**底图/地形 + 剖面垂直配准 + 增量渲染**，并为下一阶段（三维体/切片/异常）做了**设计定稿**。
## 2. 本会话已完成（均已编译绿 + 提交；用户验收"差不多了"）
**底图 + 真实地形**（核心在 `src/app/TileBasemap.{hpp,cpp}`）：
- 影像=**天地图卫星**(`img_w`，tk 内嵌)；地形=**Mapbox terrain-RGB DEM**(原版同源，pk token 内嵌；`elev=-10000+(R*65536+G*256+B)*0.1`)。
- **四叉树多级 LOD**（按瓦片屏幕像素误差递归细分，近细远粗）。根 `kRootZoom=9`、阈值 `kTargetPx=384`、叶上限 `kMaxLeaves=200`。
- **视锥剔除只用 4 个侧面**（不用近/远裁剪面——远裁剪面随已加载几何变化会误剔除远块）。`frustum_[24]` 用焦点自校正法向。
- **并发限流** `kMaxConcurrent=12`（请求队列 `netQueue_`/`pumpNetQueue`）。
- **缓存**：影像纹理 `texCache_` + DEM `demCache_`，跨隐藏/重选保留 → 重选秒出。
- **合并渲染** `requestRender()`（Qt 队列合并同轮多次渲染请求为一帧；并在渲染前 `ResetCameraClippingRange`）。
- **动态范围**：底图最大距离 = 剖面合并范围半径×10，夹 [2km,30km]，随勾选增删自动伸缩（`dataRadiusProvider_` 查 `VtkSceneView::dataHorizontalRadius()`）。**超过范围的粗瓦也强制细分**（否则一块巨瓦盖住中心、绕过距离剔除）。
- **地形半透明 0.55**（`kTerrainOpacity`）——地下剖面可从任意角度透过地面看到（地球物理标准做法；解决"前后左右预设看不到剖面=不透明地形遮挡地下"）。
- **近裁剪容差 1e-5**（`SetNearClippingPlaneTolerance`，VtkSceneView 构造）——远处底图把近裁剪面顶出去会切掉近处剖面，调小修复。
- **就近优先加载**（离相机近的瓦片先拉）。
- 瓦片纹理 mipmap + 各向异性 16x + edgeClamp。
**剖面垂直配准 + VE**：
- 剖面 Z = **`+g.y`（真实高程）**——与原版一致（实证 `threeMap.vue:676`：剖面世界竖向 = data.y）。地形也用真实高程 → 同系对齐、剖面顶≈地表露出。（早期错把 y 当深度 `-y`，已改。）
- 垂直夸张默认 **1.0**，收敛为**单一来源** `kVerticalExaggeration`（main.cpp），下发控制器/底图/UI。剖面与地形用同一 VE。
**增量渲染**（`VtkSceneController` + `VtkSceneView`）：
- 勾选/取消 = **按 dsId 增删图元**，不再整场 clear + 全量重建；`clear()` 保留底图；增量不重置相机（视角不跳）；首批数据/全量重建才 `fitView`。
- `computeDataBounds()` 只算数据图元（不含底图）→ 坐标轴/取景/预设(前后左右)不被公里级底图撑大/推远。
- `onCameraChanged` 回调：相机程序化变化（取景/预设/缩放）后通知底图按新视锥重算覆盖（治"首帧部分瓦片要微动才出"）。
- 默认底图=天地图；首个剖面重锚 frame 后经 `onFrameReanchored` 在数据位置加载底图。
- VTK 全屏含左侧三栏（drawer 在 vtkDock 内 + 进入全屏展开）。
## 3. 当前状态（2026-06-18 更新）
- 底图/地形/剖面配准/增量渲染：**完成且可用**。编译绿。所有改动已提交到 `feat/vtk-3d-view`。
- **#1 客户端「生成三维体」流程：已实现并经本会话大量使用验证**（切片/异常都在生成的体上操作过，间接验收）。详见计划 `docs/superpowers/plans/2026-06-17-vtk-3d-volume-create-flow.md`。
- 已落地：`data::VolumeBuildParams`（不冻结 gridSpec，源 ds 锁定不变式）；`core::buildVolume` 共享管线（LocalSample/Api 同源）；`Api3dRepository` 内存体存储 + `createVolume/volumeRows/isVolumeDataset` + 多源 `loadVolume`（复用 `loadSection`，竖向=g.y 高程，与帘面对齐；`fitAxis` 按 extent 增大 cell 以覆盖跨 TM 全范围）；`loadVolume` 回调交付 `(VolumeGrid, ColorScale)`；`Column3DDataset` 多选+右键「生成三维体」(按**勾选框**选中集，非行选)+ `VolumeParamsDialog`；**生成的体归三维分析栏**(`Column3DAnalysis`)，main.cpp `refreshAnalysis` 合并注入 + `pushChecked` 两栏勾选聚合；`VtkSceneController` 按 `isVolumeDataset` 分流体素/帘面。
- **#2/#3 切片：完成且用户实测通过**（提交 afdd98f+d56e35f）。四向创建/滚轮推进/双击正视/翻转/关闭/选中高亮；VTK 右键菜单(创建异常/保存/导出▸图片·dat/正视/翻转/关闭)；未保存↔已保存统一状态模型(保存按状态分派、无重复切片)；精确三点几何持久化；场景↔列表勾选双向同步。导出 `SliceExport`。切片持久化=`Api3dRepository` 内存 mock。
- **#4 异常：完成且用户实测通过**（见 §4 第 4 项，4a→4c-3，最新 c83f63a）。圈定→保存→渲染→列表→异常体分组→过滤→显隐→删除→选中高亮→双击属性，全链 mock。
- **剩余 = 收尾/打磨项**（§4 末「下一步候选」表）：体/切片详情面板、真实色阶编辑、三级树根层、坐标轴弹框、真实后端对接(阻塞)、收口 PR。**无进行中的半成品**。
## 4. 下一步计划（三维体 / 切片 / 异常）
**权威设计文档**：`docs/superpowers/specs/2026-06-17-vtk-3d-volume-slice-anomaly-design.md`（数据模型 + 交互流 + 后端vs mock + 代码现状 + 实现拆解 + 持久化策略）。已与用户拍板的关键决策：
- **创建三维体 = 客户端**：「三维数据集」栏多选剖面 → 选插值模型/参数 → `core::IdwInterpolator` 生成体素。
- **异常 = 接真实后端端点**（已从 web 源码挖到，见设计文档 §3）：`POST/PUT/DELETE /business/exception` + `exceptionType/*` + `exceptionConsortium/*` + 读 `queryException*`/`queryExceptionTree`。`remarkSourceId/Type` 填切片数据集。
- **三维体网格 / 切片持久化 / 三维分析任务 = 后端无端点 → 先本地 mock**（保持 `I3dSceneRepository` 接口不变，端点就绪只换实现）。
- **持久化策略**（设计文档 §7）：三维体保存时 **参数(源数据+插值模型/参数+色阶) + 网格规格 GridSpec 必存，明细 values 可选**；加载时有明细直接渲染、无明细按参数重算填入固定 GridSpec（锚定切片/异常坐标）。带切片/异常或大/慢的体建议存明细。
- 数据模型层级：**三维体(源数据+插值参数) → 切片(属于体,保存后成 dd_slice) → 异常(画在切片平面,圈定保存)**，三者皆可持久化。
**实现拆解（设计文档 §6，按依赖排序）**：
1. ~~三维体 mock 渲染~~ **✅ 已实现（编译绿，待 GUI 实测）**——见 §3 与计划 `2026-06-17-vtk-3d-volume-create-flow.md`。`Api3dRepository::loadVolume` 已接通（多源复用 loadSection → IDW → VolumeGrid + 色阶交付）；`VolumeBuildParams` 必存参数、values 惰性重算+缓存（**不冻结 gridSpec**，改用源 ds 锁定不变式，留校验 TODO）。
2. ~~切片交互接通三维体~~ **✅ 已有**（`SliceTool`/`InteractionManager`：四向创建/滚轮推进/双击正视/翻转/关闭/选中高亮全在）。
3. **✅ 完成(3a/3b/3c，已提交 afdd98f+d56e35f，用户实测通过)**——切片完整生命周期(未保存↔已保存统一状态模型)：
- VTK 视图切片右键菜单(`PickInteractorStyle`右键→`InteractionManager`高优先级(1.0)交互器观察者抢右键→`onSliceContextMenuRequested`→main 弹 QMenu)：创建异常(占位#4)/保存/导出▸(图片·dat)/正视图/翻转/关闭。
- **保存按状态分派**：未保存→`createSlice`+`tagSelectedSlice`链接当前切片+列表自动勾选(`setItemChecked`)；已保存→`saveSlice`覆盖位姿。**无重复切片**。
- **精确几何持久化**：`SliceSpec`存 axis+Origin/Point1/Point2 三点；`SliceTool`还原构造逐点重建→重渲染尺寸/朝向一致。
- **已保存切片重渲染**：分析栏勾选→`syncSlices`在当前活动体上还原(`showSavedSlice`)，取消→移除；靠`onVolumeChanged→syncSlices`解决父体异步到场。dd_slice 不进控制器(避免 loadSection 失败)，main 编排走 InteractionManager。
- **场景↔列表同步**：VTK「关闭」已保存切片→`onSliceClosed`→列表取消勾选。`Column3DAnalysis::setDatasets`按 dsId 保留勾选+仅勾选集变化才发信号(修"保存切片连带取消体勾选/列表重置")。
- 导出：`SliceExport.{hpp,cpp}`(图片=切片上采样2048上色 PNG；dat=重采样标量网格)。切片持久化=`Api3dRepository` createSlice/saveSlice/deleteSlice 内存 mock + sliceRows/isSliceDataset/sliceSpec。
4. 异常（**进行中**，全量含异常体/列表/过滤，计划见 `plans/2026-06-18-vtk-3d-anomaly.md`）。**异常挂三维体**(非切片非源ds，见记忆 vtk-3d-persistence-structure)；mock 持久化(三维体/切片端点未就绪)。
- **4a ✅ 已提交(4e1b8e7)**：`core::Anomaly` 补 3D(id/volumeDsId/consortiumId/worldPts/plane)；`buildAnomaly3D`；`I3dSceneView`+`VtkSceneView` addAnomaly/removeAnomaly/clearAnomalies/setAnomalyVisible(按id跟踪actor)；`Api3dRepository` 异常 mock(saveAnomaly/loadAnomalyTree按volumeDsId+consortiumId分组/delete)。**附带修复测试漂移→228/228 绿**。地基、尚不可见。
- **4b ✅ 已提交**：圈定工具(切片平面画多边形,黄点+橡皮筋虚线,双击/右键/Enter 闭合,Esc 取消,屏幕提示)+保存对话框(名称/类型 mock/备注/截图预览)+切片右键「创建异常」接通 → 画→存→显示→删闭环。修复:闭合手势误触切片(abort 先于 finish/teardown)。
- **4c-1 ✅ 已提交**：三维分析栏「异常」组(QSplitter:数据集树 + 异常 QGroupBox)；过滤下拉(全部显示/随GS/随数据集/全部隐藏,默认随数据集)；删除按 consortiumId 分组；`refreshAnomalies` 各路径补 `renderWindow->Render()`(修过滤勾选与 VTK 显隐脱节)。
- **4c-2 ✅ 已提交(44d31a8)**：列表选中异常→VTK 高亮联动(R84,list→VTK)；`setSelectedAnomaly`(选中 actor 加粗线宽/点尺寸,其余恢复);anomalyProps_ 改 vtkActor。**反向(VTK点异常→回选列表)未做**(需异常 actor 拾取)。
- **4c-3 ✅ 已提交(c83f63a)**：异常属性对话框(R83,双击异常列表项弹只读:名称/类型/标记类型/归属三维体/异常体/顶点世界坐标/备注)；`AnomalyPropertiesDialog`。**截图字段:模型/端点均无,不展示**(保存对话框截图为 mock 未持久化)。
- **#4 异常功能收口** ✅(4a→4c-3 全做完,编译绿+用户实测通过)。**剩余已知限制**:① 反向(VTK 点异常→回选列表)未做(需异常 actor 拾取);② 单条显隐状态跨 refresh 不持久;③ 全链 mock(三维体/切片端点未就绪),端点就绪后切真实。
5. 分析栏右键接线：**已完成**(切片 保存/保存为/导出▸/删除 全接；体 切片▸/详情/色阶)；`colorScaleRequested` **已接 P1 色阶编辑器**(详见下表)。已移除"显示/隐藏"(勾选即显隐)。
6. 三维体/切片/异常详情：**✅ 全部完成**——异常详情对话框(4c-3)；体/切片详情对话框(#6,提交 b97ea68)。形态统一为只读属性对话框,非停靠面板。
- **其它小欠项**：三维分析栏完整三级树"对象→三维体→切片"里"对象"根层未套(体目前是顶层)；真实色阶编辑。
**其它小项**：坐标轴「O点位置」「字体」弹框仍是 stub（main.cpp:382 TODO P4）。
### 下一步候选（2026-06-18，主体功能已完结，以下均为收尾/打磨；下一会话先与用户确认方向）
| 候选 | 性质 | 阻塞 | 要点 |
|---|---|---|---|
| ~~**#6 三维体/切片 数据详情**~~ ✅ 已完成 | 功能补全 | 否 | **已做(提交 b97ea68)**：只读属性对话框(非面板,仿异常详情)`VolumePropertiesDialog`/`SlicePropertiesDialog`，右键「数据详情」按 ddCode 分派。体=参数+统计(值域/网格/测点数/范围,仅 loaded 时显)；切片=位姿/参数(不含统计,切面网格仓储不持久化)。`Api3dRepository::volumeInfo` getter + `StoredVolume.pointCount` 持久化；接口/LocalSample 零改。设计见 `specs/2026-06-18-vtk-3d-volume-slice-detail-dialog-design.md`。**已知限制**:切片采样分辨率/值域需渲染层回写仓储才有,当前不展示。 |
| **真实色阶编辑（P1–P4 ✅ 全期完成，2D/3D 共享）** | 功能 | 否 | 编辑器**与数据集视图(2D)共用**，复刻原版四件套(`colorLevel/contourLevel/contourLine/colorEditor.vue` + `colorUtils.js`)。**P1** 主表 `ColorScaleConfigDialog`(层级/颜色 + 新增/删除 + 双击改值/改色)。**P2 层级⚙** `ContourLevelDialog`(normal/log/equalArea + 间隔↔层数双向 + 校验) + 纯算法 `ContourLevels`(6 单测) + `interpColor`(mapColors)。**P2 线形⚙** `ContourLineDialog`(线型/线显/线色/标注显/标注色) + `ContourLineConfig`。**P3 颜色⚙** `ColorGradientDialog` + 自绘 `GradientEditWidget`(可拖拽连续渐变) + 预设/反向/整体透明度 → 按层级位置采样回填。**P4** 文件 IO `ColorScaleIO.{hpp,cpp}`(纯函数 `.lvl`/`.clr` 解析生成,4 单测,与原系统互通)：主表 导入/导出=`.lvl`,颜色⚙ 导入/导出=`.clr`。**接入**：① 3D 右键「色阶」→ `VtkSceneController::setVolumeColorScale` 重建体素+切片(用 colorScale 含透明度,mock 持久 `volumeScaleCache_`)；② 2D `GridDataChartView`「色阶配置」→ 同编辑器 → 色阶 + 线形/标注到 `ContourPlotItem`。设计见 `specs/2026-06-19-vtk-3d-color-scale-editor-design.md`。**已知边界**：模板库(后端)以文件导入导出替代；`RawDataChartView`「色阶配置」仍占位(原始散点无等值线网格);帘面(源剖面)独立色阶不联动。 |
| **收口提 PR 合 main** | 流程 | 否 | 分支已积大量提交。`git diff main...HEAD` 起草摘要+测试计划，`-u` 推送。注意勿纳未跟踪文件。 |
| **三级树 对象→三维体→切片** | 结构打磨 | 否 | `Column3DAnalysis` 体目前是顶层，缺"对象"根层(R 结构)。 |
| **坐标轴 O点/字体弹框** | 打磨 | 否 | main.cpp 内 stub(TODO P4)落实。 |
| **真实后端对接** | 切真实 | **是** | 三维体/切片端点未就绪，现全 mock(`Api3dRepository` 内存)。端点就绪后只换 `I3dSceneRepository` 实现，接口不动。异常端点已挖到(§4 头)，但其挂载目标(三维体)仍 mock，故异常也整链 mock。 |
## 5. 相关文档
- **`docs/superpowers/specs/2026-06-17-vtk-3d-volume-slice-anomaly-design.md`** ← 下一阶段主依据。
- `docs/questions/2026-06-16-反演剖面竖向字段(y-z-elevation)语义待确认.md` ← 已解：y=高程，z=+y 与原版一致；跨数据集 y 不一致是数据层问题（原版同样存在），非客户端 bug。
- `docs/questions/2026-06-17-3D地球改造-现状与约束评估.md` ← 已决：维持局部平面方案，不做真 3D 地球（opus 评审：球面=根本性重构）。
- 旧 spec/plans（`2026-06-15-vtk-3d-*`、`three-column-refactor*`）为历史，留档。
## 6. 关键铁律 / 坑（务必遵守）
- **构建**：`build.bat rebuild` 会**自动启动 app**（后台命令不返回）；编译验证用 **`build.bat app`**。Claude 无法 GUI 验证 VTK 渲染。
- **不能靠猜**：渲染/裁剪类问题用**日志取证**（`%LOCALAPPDATA%\Geomative\Geopro3\logs\geopro_YYYYMMDD.log`，含 `[basemap]`/`[view]` 的 qInfo/qWarning），或读真实数据/原版源码。本会话多次因臆测被用户纠正——**贴源码/日志，别凭印象**。
- **勿动未跟踪文件**（见顶部）；**勿用 `git add -A`**（会误纳）。逐个文件 `git add`。
- **API 凭证不得提交**（探测脚本用完即删）。
- 原版 web 源码 `D:\Git\lanbingtech\commercial-admin` 是复刻权威；需求 xlsx 用 `python openpyxl` 读到 UTF-8 临时文件再看（控制台中文乱码）。
- 内嵌 token：天地图 tk + Mapbox pk（公开客户端 token，同原版，可提交）。
- 全部回复中文。
## 7. 代码地图（关键文件）
- `src/app/TileBasemap.{hpp,cpp}` — 底图+地形（四叉树/剔除/限流/缓存/动态范围/半透明/合并渲染）。
- `src/app/VtkSceneView.{hpp,cpp}` — I3dSceneView 实现：clear/addCurtain(dsId)/addVolume(dsId)/removeDataset/render/renderIncremental/computeDataBounds/dataHorizontalRadius；近裁剪容差；onCameraChanged/onFrameReanchored 回调。
- `src/controller/VtkSceneController.{hpp,cpp}` — 增量渲染编排（setCheckedDatasets diff、addDatasetAsync、fitOnArrival）。
- `src/render/actors/CurtainActor.cpp` — 帘面（Z=+g.y 真实高程）。
- `src/render/interact/{SliceTool,InteractionManager,SlicePlaneMath}.*` — 切片交互。
- `src/render/{VoxelFromScatters,actors/VoxelActor}.*` + `src/core/algo/IdwInterpolator.*` — 体素插值/绘制（三维体复用）。
- `src/data/repo/I3dSceneRepository.hpp` — 接口（loadVolume/createSlice/saveSlice/deleteSlice/loadAnomalyTree/saveAnomaly/.../loadTaskRecords）。
- `src/data/repo/LocalSample3dRepository.cpp`（内存 mock 参考实现）、`src/data/api/Api3dRepository.cpp`（真实路径，多为 stub `kNotReady`，待按设计文档实现）。
- `src/app/panels/columns/{Column3DDataset,Column2DDataset,Column3DAnalysis,ColumnDrawer}.*` — 三栏 UI（信号定义全、main.cpp 未全接）。
- `src/app/main.cpp` — 装配/接线（搜 `basemap`/`colAnalysis`/`onCameraChanged`/`kVerticalExaggeration`）。
- `src/data/dto/DatasetChartDto.cpp` — `parseInversionGrid`（x/y/v/lat/lon；**未解析 elevation/alt**）。

207
docs/superpowers/HANDOFF-vtk-category-view-refactor.md Normal file
View File

@ -0,0 +1,207 @@
# 交接：VTK 三维分析视图重构（按数据类型分组 + 对象树联动）
> 给下一个会话无缝接手。日期 2026-06-24。分支 `feat/vtk-3d-view`。
> 本会话**产出 spec + 实施 plan + openapi 修订，未改业务代码**——下一步是按 plan 执行实现。
>
> **速览**：把 VTK 左侧三 tab 重构为「按数据类型大类分组」两 tab；经真实接口实测定分类/字段、opus 子代理评审、客户两轮交互确认后定稿。产出 spec（`specs/2026-06-24-vtk-category-view-refactor-design.md`）+ 实施 plan（`plans/2026-06-24-vtk-category-view-refactor.md`，8 phase/12 task）+ openapi v0.6（`docs/api/vtk-3d-openapi.json`）。
---
## ⏩ 实施进度（2026-06-24 续会话）
**Task 1-10 完成 + Task 12 大部分 + Task 11 Step 1-4a 完成。剩 4 项（见末尾「剩余真实状态」）。**
### 续会话第二批提交（在 `d539fc1` 之后）
```
6edfad9 feat(app): VtkViewToolbar 接入中央画布(view/zoom/fit+axesSettings弹窗) # Task12 工具条✓
1d744ba feat(app): 对象树拉取改 checkedSourcesChanged+confType 分流(GS直挂ds) # Task12 #1✓
2f07e60 feat(app): 三维体段「体→切片/异常」三级树注入+异常排除渲染勾选+即时进树 # Task11 Step4a✓
9899d5f→修正 feat(app): 创建异常按切片是否已保存挂体/切片(resolveAnomalyMount) # Task11 Step3✓
07be3ae feat(data): Api3dRepository.anomalyRows 按 remarkSourceId 供三级树注入 # Task11 Step2✓
52830bb feat(core): Anomaly volumeDsId→remarkSourceId + resolveAnomalyMount # Task11 Step1✓
6e3c810 docs: 异常归属设计修订(取消独立异常区,挂体/切片+三级树) # spec/plan
901c84e feat(app): 对象树→splitByCategory→5段数据流+勾选分流渲染+生成入口 # Task12 阶段A✓
```
⚠️ 教训：`git diff --cached` 必须当 STOP 闸门——9899d5f 曾误带并行 GPR 会话已暂存的新文件，已 reset 拆分修正。
### 🚧 剩余真实状态（续会话第三批更新）
**已再完成**：#2 装置枚举接口(`listArrayTypes` GET `/business/script/arrayTypeList`→`DatasetFieldDictionary.arrayTypeEnum`→段头装置下拉显示+过滤，commit b9a6551)、#4 VolumeParamsDialog 扩展(左侧源列表可增删+生成位置下拉 GS/TM→`req.structParentId/confType`，a41b428)、Task11 异常双击详情(`anomalyById`→AnomalyPropertiesDialog，cfd242c)。
**仅剩 #6 退役旧栏**——⚠️ **不是纯删，直接删会丢功能**，须先补迁：
1. **垂直夸张(VE)滑块**：现挂旧 c3(main :1032/1036 + Column3DDataset VE 滑块)；退役后无 UI 入口，需迁 `VtkViewToolbar` 或段头 + 接 `sceneCtrl->setVerticalExaggeration`。
2. **切片勾选同步**：main :624/663 `colAnalysis()->setItemChecked`（切片保存自动勾选 / 关闭取消勾选）；需给 `CategoryAnalysisTab` 加 `setItemChecked(dsId,bool)`（按 dsId 在 voxel 段树定位项设勾选），main 改调它。
3. `refreshAnomalies` 去 ca 依赖（:420-446 用 `ca->anomalyFilterMode()/setAnomalies()`）→ 改全渲染（异常显隐档位是边缘功能，简化为全显示）。
4. 删 main 中 c3/ca 共 ~35 处接线（:463/666-700/794-796/800-981/1032-1036）+ ColumnDrawer `col3D_/colAnalysis_` 成员/访问器/实例 + `Column3D*` include + 旧 `createVolume(VolumeBuildParams,name)` 重载（无调用者后）。
5. `splitByDimension` 保留（refreshAnalysis 仍用其 dim2D 喂 col2D）。
**#6 不影响当前功能**（旧栏已 hide、app 完整可用），是独立清理工程，无法 headless 验证——建议新会话清爽做。
#### （历史）剩余真实状态（4 项，均无法 headless 验证）
1. **Task11 Step4b — 异常/切片树内交互**：三级树「展示」已通（Step4a）；缺 dd_anomaly 双击详情（main detailRequested 加 dd_anomaly 分支→需 Api3d 加 `anomalyById`→AnomalyPropertiesDialog）、右键删除（CategorySection 加右键菜单+信号→main deleteAnomaly/deleteSlice）、切片保存位姿、per-anomaly 显隐。现 refreshAnomalies 仍用隐藏 colAnalysis 的 filterMode（异常默认全渲染，可接受）。
2. **Task12 #2 dict 填充 — 真实阻塞**：装置类型筛选需 `DatasetFieldDictionary` 填充，但 `parseFieldMapping` 需**原始 dynamicForm JSON**（含 confFieldId/optionsObject），而现有 `loadDatasetFormAsync` 返回的是解析后 `DynamicForm`（仅 name/value，丢了 optionsObject）。**需新增"拉原始 dynamicForm JSON"异步接口**；且装置 value→中文字典源 spec §11 本就标注待坐实。当前 dict=nullptr，装置筛选退化不筛、日期筛选回退 createTime（数据照常出）。
3. **Task12 #4 — VolumeParamsDialog 扩展**：左侧勾选源 ds 树(按 GS 分组·可二次增删) + 右侧「生成位置」下拉(项目内 GS/TM，默认单GS→该GS/跨GS→项目根)→填 req.structParentId/structParentConfType。现用基础 VolumeParamsDialog（归属走默认）。
4. **Task12 #6 — 退役旧栏**：删 main 中 c3/ca 旧接线(:653区 c3 view/zoom/gen、:730区 ca 接线)、col3D()/colAnalysis() 调用、Column3D* 实例；删 ColumnDrawer col3D_/colAnalysis_ 成员+访问器；refreshAnomalies 去 ca 依赖(改全渲染)。**须先做 Step4b 把 ca 的切片删除/保存/异常详情功能迁到新树**，否则删 ca=丢功能。splitByDimension 保留(dim2D 用)。
> 已就绪未删：旧 `Column3DDataset/Column3DAnalysis` 仍实例化但隐藏，`checkedTmsChanged` 信号与新 `checkedSourcesChanged` 并存（主接线已切新信号，旧信号仅剩 :1369 nav 接线在用）。
### （历史）Task 1-10 完成记录
**已提交、可编译、逻辑层单测全绿（425 测试，5 个失败均为 PROJ_DATA 环境性、非回归）。**
提交链（在 `a7d558b` docs 之后）：
```
a06d9e8 feat(data): createVolume(VoxelGenerateRequest) 重载+fromRequest 派生+请求体打印(mock) # Task10
3af7e44 feat(ui): VtkViewToolbar 画布工具条 + AxesSettingsDialog 坐标轴设置 # Task9
98114a3 feat(ui): CategoryAnalysisTab(QScrollArea 5段)+ColumnDrawer 两tab(旧栏隐藏过渡) # Task8
30e990d feat(ui): CategorySection 类型段组件 + DatasetFieldDictionary 缓存类 # Task7
40646f7 refactor(tree): 评审修复-抽 recomputeAllGsStates 去 nullptr 信号 hack # Task4-6 review 修复
c5b3907 feat(data): DatasetFieldDictionary 解析 arrayType/collectTime 映射+装置字典 # Task6
1978a31 feat(tree): GS 三态状态机(停 AutoTristate)+右键 ds/tm + checkedSourcesChanged # Task4+5(合并)
6b39901 test(data): 补 properties[1] 日期项断言
f00a214 feat(data): VoxelGenerateRequest/SliceGenerateRequest DTO + toJson # Task3
07cf75d feat(app): CategoryConfig 映射表 + splitByCategory # Task2
5a719ca feat(data): DsRow 加 dsTypeCode/properties + parseDsRows 解析 # Task1
```
**已就绪的新构件（均编译通过）**：
- 逻辑层：`DsRow` 扩字段、`splitByCategory`(CategoryConfig 5 段)、`Vtk3dRequests`(Voxel/Slice DTO + toJson + `fromRequest`)、`DatasetFieldDictionary`(parseFieldMapping + 缓存类)、`ObjectTreeSelection`(aggregateGsState/dedupeSources)。
- 对象树：`ObjectTreePanel` GS 三态状态机(停 AutoTristate)+ 右键「选择▸ds/tm」+ `checkedSourcesChanged(QList<DataSource>)` 信号（**与旧 `checkedTmsChanged` 并存**，Task 12 删旧）。
- UI 组件：`CategorySection`(段头装置/日期筛选+段体可勾选树+「+新增三维体」+双击详情)、`CategoryAnalysisTab`(QScrollArea 5 段，setBuckets/section/勾选并集)、`ColumnDrawer` 已改两 tab(三维分析=analysisTab / 二维分析=col2D；**旧 col3D_/colAnalysis_ 仍实例化但 hide()、不入 tab**，保留访问器供 main 过渡)、`VtkViewToolbar`、`AxesSettingsDialog`。
- data：`Api3dRepository::createVolume(VoxelGenerateRequest)` 重载(组装真实请求体+打印+`lastVoxelRequest`)，旧 `createVolume(VolumeBuildParams,name)` 保留。
**⚠️ 当前过渡态**：app 可编译运行，但「三维分析」tab 是**空的 CategoryAnalysisTab**（数据接线在 Task 12）；旧三维数据集/三维分析功能已隐藏。对象树 GS 三态+右键 ds/tm **已在现 app 生效**（旧 checkedTmsChanged 仍兼容），可立即真实验证（plan Task 4 Step 7 清单）。
**偏离 plan 的决策（已记录理由）**：① Task 4+5 合并一个 commit（plan Task4 右键已引用 Task5 的 emitCheckedSources，循环依赖）；② DatasetFieldDictionary 异步拉取下放 main（data 层无网络，类只内存缓存）；③ CategorySection 段体先平铺（populateDatasetList），「项目根/GS/TM 容器节点分层」推迟 Task 12 接真实 StructNode；④ createSlice 虚接口未改签名，SliceGenerateRequest 组装并入 Task 12 main 层。
### 🔧 Task 11+12 待做（main.cpp 接线总成，最高风险，须真实 app 验证）
`main.cpp` 1943 行，接线密集。关键现状符号位置：
- `:361` `new ColumnDrawer(centerWidget)` —— 需改传 dict（构造已支持第2参 `DatasetFieldDictionary* dict=nullptr`）。
- `:397 refreshAnomalies` / `:448 refreshAnalysis` 闭包用 `drawer->colAnalysis()`。
- `:442 c3 = drawer->col3D()`；`:641` c3 checkedDatasetsChanged→sceneCtrl；`:653` c3 generateVolumeRequested→createVolume；`:898/902` c3 verticalExaggeration。
- `:579/745` createSlice 调用（补 projectId + 组装 SliceGenerateRequest）。
- `:584/623` `colAnalysis()->setItemChecked`；`:666 ca=colAnalysis()`。
- `:1117/1267` 对象树 `checkedTmsChanged` 接线（→改 `checkedSourcesChanged` + confType 分流 `loadRowsAsync(projId, src.id, src.confType, 3, ...)`）。
- `:1134 splitByDimension`→`splitByCategory` + `analysisTab()->setBuckets`；`:1135 col3D/col2D setDatasets`。
- `:1215 clearCentral`。`:1328 drawer->expand()`。
**Task 11 缺口**：`CategoryAnalysisTab`/`CategorySection` 尚无 colAnalysis 的 `setItemChecked`、异常子区 API；三维体段需迁入 Column3DAnalysis 异常控件（参 `src/app/panels/columns/Column3DAnalysis.{hpp,cpp}` + main `:397 refreshAnomalies`）。
**Task 12 要点**（plan §Task12 Step1-8 已详列）：① 对象树勾选→confType 分流拉取→splitByCategory→analysisTab setBuckets；② analysisTab checkedDatasetsChanged→并入 checkedProfiles/checkedAnalysis→pushChecked；③ generateVolumeRequested→`VolumeParamsDialog` 扩展（左侧勾选源树·可二次增删 + 右侧「生成位置」下拉=项目内 GS/TM）→组装 `VoxelGenerateRequest`→`createVolume(req)`；④ 工具条 `VtkViewToolbar` 叠加中央 QVTK + AxesSettingsDialog 接坐标轴；⑤ createSlice 补 `nav.currentProjectId()`；⑥ 删旧 checkedTmsChanged/col3D()/colAnalysis()/splitByDimension/Column3D* 引用 + setStructure 传对象树同源 StructNode（容器分层）。
#### ✅ Task 12 阶段 A 已完成（commit 901c84e）—— 核心数据流接通
- `refreshAnalysis` 重构为统一入口：`lastSourceRows + volumeRows + sliceRows` → `splitByCategory` → `analysisTab->setBuckets`（5 段出数据）+ `splitByDimension(...).dim2D` → `col2D`。
- 对象树 `checkedTmsChanged` 接线：finish 改 `*lastSourceRows=*acc; refreshAnalysis()`（仍用 checkedTmsChanged，**confType 分流见剩余①**）。
- `analysisTab` 三接线：checkedDatasetsChanged→按 isSlice/isVolume 分流(切片→checkedSliceIds+syncSlices / 体素→checkedAnalysis / 反演剖面→checkedProfiles)→pushChecked；generateVolumeRequested→VolumeParamsDialog→组装 `VoxelGenerateRequest`→`createVolume(req)`；detailRequested→Slice/Volume 属性对话框。
- `clearCentral` 改走 lastSourceRows/refreshAnalysis。
- **现可验**：勾对象树 TM → 电阻率/视/瞬变段出数据 → 勾选段内 ds → 帘面渲染；生成三维体 → voxel 段出现 → 勾选渲体；切片段同理。
#### 🔧 Task 12 剩余精修（6 项，新会话做，每步 build + 真实验证）
1. **confType 分流**：对象树接线从 `checkedTmsChanged(QStringList tmIds)` 换 `checkedSourcesChanged(QList<DataSource>)`，`loadRowsAsync(projId, src.id, src.confType, 3,1,100000)` 第3参传 src.confType（支持 GS 直挂 ds，现仅 TM）。改 main `:~1171` 对象树接线 + `:~1330` 第二个 checkedTmsChanged→nav 接线。
2. **dict 填充**：main 创建 `DatasetFieldDictionary` 并传 `new ColumnDrawer(centerWidget, &dict)`；对每个反演 dsType 调 `loadDatasetFormAsync`→`parseFieldMapping`→`dict.setFields`（装置/日期筛选才生效，现 dict=nullptr 退化不筛）。
3. **工具条接入**：实例化 `VtkViewToolbar` 叠加中央 QVTK，信号接 sceneCtrl（viewRequested/zoom/fit 接现有 c3 对应槽 :647 区；axesSettingsRequested→弹 `AxesSettingsDialog`→应用坐标轴）；VE 控件迁工具条。
4. **VolumeParamsDialog 扩展**：左侧勾选源 ds 树(按 GS 分组·可二次增删) + 右侧「生成位置」下拉(项目内 GS/TM，默认 源单GS→该GS/跨GS→项目根)→ 填 `req.structParentId/structParentConfType`。
5. **三维体段三级树 + 异常按归属挂体/切片（Task 11 本体，已重新设计，见 spec §8 / plan Task 11）**：**取消独立异常区**——异常作叶子挂归属实体（体/切片）下。归属链 `异常→所在切片→切片所属体`，挂载目标由「切片是否已保存成 dd_slice」决定（已存挂切片、临时挂体）。改 `Anomaly`(volumeDsId→remarkSourceId+remarkSourceType)、Api3d 异常 mock 按归属存查、main 创建逻辑判断切片是否保存、三维体段「体→切片/异常」三级树。多体渲染本就支持(`dsProps_` 按 dsId)，`volumeOwnerDs_`=当前切片源体。
6. **退役旧栏**：删 main 中 c3/ca 旧接线(:641/669-760 区)、col3D()/colAnalysis() 调用、`Column3D*` 实例；删 ColumnDrawer 的 col3D_/colAnalysis_ 成员+访问器；评估删 splitByDimension（dim2D 改轻量过滤）。
- 切片保存/关闭(:584/623 setItemChecked)、createSlice projectId(:579/745) 随 #5/#1 一并处理。
> 下方为初版交接（spec/plan 设计定论，仍有效）。
## 1. 背景
- 代码库 = 原版 web 系统（`D:\Git\lanbingtech\commercial-admin`，复刻权威）移植的 Qt6 桌面客户端。
- 现状 VTK 视图左侧 `ColumnDrawer` 是三 tab（三维数据集/二维数据集/三维分析），`splitByDimension` 按 `ddCode` 分 3 维度。
- 需求（用户截图设计）：把「三维数据集」并入「三维分析」，改成**按数据类型大类分组**（电阻率/视电阻率/瞬变电磁/三维体/切片），每类各自筛选+操作；对象树勾选联动、支持 GS/项目直挂数据；全局视图控制移 VTK 画布工具条。
## 2. 本会话已完成
1. **摸透现状源码**（ColumnDrawer/Column3D*/DatasetDimension/DatasetListPanel/ObjectTreePanel/RepoTypes/NavDto/Api3dRepository/main.cpp 接线等）。
2. **真实接口实测定关键事实**（用用户给的 token 直连后端，见 §6）——纠正了多个二手猜测。
3. **brainstorming 澄清全部设计决策**（容器布局、分类策略、对象树三态交互、装置类型、生成入口等）。
4. **产出 spec** 并经 **opus 子代理评审 + 据评审修订**（GS 三态停 AutoTristate、properties 两接口形态澄清、帘面勾选链承接等）。
5. **产出实施 plan**（8 phase/12 task，TDD bite-sized，逻辑层完整测试代码、UI 层 build+手动验证）。
6. **客户两轮交互确认**收敛生成三维体交互（见 §3 第 5 条），同步更新 spec/openapi(v0.6)/plan。
7. **openapi 修订**：三维体归属层级 TM → GS/项目根 → 再放开 GS/项目根/TM。
## 3. 最终设计定论（核心，已写入 spec）
1. **两 tab**：「三维分析」（5 段）+「二维分析」（现 `Column2DDataset` 不动）。
2. **大类分类按 `dsTypeCode`**（不是 ddCode）——电阻率/视电阻率/瞬变电磁三者 ddCode 同为 `dd_inversion_data`，只 dsTypeCode 不同。映射表 `CategoryConfig` 驱动；三维体/切片按 ddCode（`dd_voxel`/`dd_slice`）识别。
3. **对象树联动**：
- 非根 GS = **三态复选框**（聚合「GS 自身 ds 开关」+「子 TM 勾选」）+ 右键「选择▸ds/tm」；**必须停用 `Qt::ItemIsAutoTristate`、手动维护三态**（UserRole 存 ds 开关）。
- 项目根 = 无复选框、直挂 ds 固定显示、其下 TM 各自二态勾选。
- 信号 `checkedTmsChanged` → `checkedSourcesChanged(QList<DataSource{id,confType}>)`，按 `structParentConfType`(1=GS/项目, 2=TM) 分流 `loadRowsAsync`。
4. **装置类型/采集时间筛选**：是 ds 结构化属性（`arrayType`/`collectTime`），值在 ds 行 `properties[]`（confFieldId），经 `DatasetFieldDictionary`（按 dsType 拉一次 `dynamicForm` 取 confFieldId↔fieldCode 映射 + 装置 value→中文字典）解析。装置类型只电阻率/视电阻率段有。日期筛选按 collectTime（三维体/切片回退 createTime）。
5. **新增三维体（客户两轮确认定稿）**：
- **入口**：数据类型**段头**「+新增三维体」按钮（电阻率/视电阻率/瞬变段），**不在**对象树/容器节点右键。
- **源数据集** = 三维分析中**当前勾选的同类型 ds**（本段类型、可跨 GS）。
- 点击 → `VolumeParamsDialog`：**左侧**树状（按 GS 分组）展示勾选源、**可勾选/取消供确认或二次修改**；**右侧**参数：名称、**生成位置**下拉、插值模型、水平/竖向间距、IDW 幂次、最大影响距离。
- **生成位置（归属）**：默认 = 源同属单 GS→该 GS、源跨 GS→项目根；用户可改为**项目内任意 GS/TM**（`structParentConfType` 1 或 2）。源与归属解耦。
6. **VTK 画布工具条**：全局视图控制（坐标轴/比例/快捷视图/缩放）移到中央 VTK 竖排工具条；设置→`AxesSettingsDialog`(X/Y/深度 显示+min/max)；快捷视图按钮文字「前/后/上/下/左/右」；复位=现「适配」。
7. **请求体 DTO**：`createVolume/createSlice` 扩参，内部按 `VoxelGenerateRequest/SliceGenerateRequest` 组装真实请求体结构（仍 mock 存储、假 id），`toJson` 序列化；重构落地即可从 UI 产出给后端联调的真实请求体。
8. **三维体/切片/异常**仍 `Api3dRepository` mock；异常迁入三维体段。
## 4. 剩余工作 = 执行 plan
`plans/2026-06-24-vtk-category-view-refactor.md`，8 phase/12 task，依赖顺序：
- **Phase 1-2**（Task 1-3）：DsRow 扩展+parseDsRows / CategoryConfig+splitByCategory / 请求体 DTO —— **纯逻辑完整 TDD**。
- **Phase 3-4**（Task 4-6）：GS 三态状态机+checkedSourcesChanged / DatasetFieldDictionary —— 逻辑可单测。
- **Phase 5-6**（Task 7-9）：CategorySection / CategoryAnalysisTab+ColumnDrawer / VtkViewToolbar+AxesSettingsDialog —— build+手动验证。
- **Phase 7-8**（Task 10-12）：Api3d 扩参组装请求体 / 段重组(异常迁三维体段) / main.cpp 接线总成 + 退役 Column3DDataset/Column3DAnalysis。
**建议**：subagent-driven（每 task 新 subagent + task 间两阶段 review）+ 独立 git worktree 隔离。每 task 自带测试/验证+commit；Phase 间「新旧信号并存→Task 12 统一切换删旧」保证每次可编译。
**plan 中 Task 7 段头按钮 + Task 12 `VolumeParamsDialog` 扩展（左侧源列表二次增删 + 生成位置下拉）已按 §3.5 定稿写好。**
## 5. 待确认 / 风险
- **装置类型 value→中文 字典源**（唯一待坐实，不阻塞实现）：实测 `arrayType` 原始值（如 `1429468249448449`）**不在**该字段 `optionsObject`（另一套 id `1456095451258368…`）里；`parseDynamicForm:208` 也不翻译；但用户说客户端属性面板显中文。Task 6 先用 optionsObject 建表 + 缺失回退原值。**需用户提供客户端数据集属性面板截图**以定位现有翻译路径（候选：`fieldConfigJsonObject.fieldDataRadius` 指向的全局字典 / `script/arrayTypeList`）。
- **段体容器树建法**（Task 7 核心）：段体要呈现「项目根/GS/TM 容器节点→ds」层级，需 main 传 `setStructure`（对象树同源 StructNode）+ ds 的 `structParentId/structParentConfType`（Task 1 已解析）建容器节点。
- 三维体/切片/异常仍 mock；后端就绪后切真实（`I3dSceneRepository` 留缝，见 `HANDOFF-vtk-3d-backend-api.md`）。
## 6. 关键实测事实 + 接口（直连后端核实）
- 后端基址 `http://tenant.geomative.cn/pop-api`；header `geomativeauthorization: Geomative <token>`（token 本会话由用户提供，下会话需重新索取）。
- 样本项目「演示项目（高密度+瞬变）」`1438889436225536`：项目根 GS `1438889436291072` 下直挂 TM（ERT1-8 confCode=ERT、TEM1-15 confCode=TEM01），**无中间 GS 层**（印证「项目根本质是 GS」「TM 可直挂项目根」）。
- **大类 dsTypeCode**：电阻率=`ERT platform inversion data`、视电阻率=`visual resistivity data`、瞬变电磁反演剖面=`DD TRANSIENT ELECTROMAGNETIC INVERSION`（三者 ddCode 同 `dd_inversion_data`）。
- **ds 行 `properties`**（`dsObject/data/page`）= `[{confFieldId,value}]` 数组；**`dynamicForm` 的 `properties`** = `{fieldCode:value}` map（两接口形态不同，勿混）。
- 装置类型字段 `arrayType`、采集时间 `collectTime`（fieldCode）；装置枚举 `GET /business/script/arrayTypeList` → `[{itemValue,name}]`（15 项）。
- 层级 `structParentConfType`：1=GS/项目根，2=TM；`loadRowsAsync` 第 3 参即透传它（现状 main.cpp:1142 写死 2）。
- 详情接口 `dsObject/getDetail/{id}`、动态表单 `dsObject/dynamicForm/{id}`（客户端 `loadDatasetFormAsync`→`parseDynamicForm`）。
## 7. 代码地图
**现状关键文件（重构基础）：**
| 文件 | 作用 |
|---|---|
| `src/app/panels/columns/ColumnDrawer.{hpp,cpp}` | 现三 tab 容器（→两 tab） |
| `src/app/panels/columns/Column3DDataset/Column3DAnalysis/Column2DDataset` | 三栏现状（前两退役、二维不动） |
| `src/app/DatasetDimension.{hpp,cpp}` | splitByDimension（→splitByCategory 替代） |
| `src/app/panels/DatasetListPanel.cpp` | populateDatasetList/卡片委托/applyDatasetFilter（复用） |
| `src/app/panels/ObjectTreePanel.{hpp,cpp}` | 对象树（GS:123 AutoTristate、:174 itemChanged、:207 右键） |
| `src/data/repo/RepoTypes.hpp` | DsRow（扩 dsTypeCode/properties/structParent*） |
| `src/data/dto/NavDto.cpp` | parseDsRows:116 / parseDynamicForm:179 |
| `src/data/api/Api3dRepository.{hpp,cpp}` | 三维体/切片/异常 mock（createVolume/createSlice 扩参） |
| `src/data/repo/VolumeBuildParams.hpp` / `src/core/model/Anomaly.hpp` | 三维体参数 / 异常模型 |
| `src/app/main.cpp` | 接线（:388-460 异常/勾选、:1113-1225 对象树→分类分发） |
| `src/data/api/ApiProjectRepository.cpp` | loadRowsAsync parentConfType 透传 |
**新建（plan §文件结构）：** `CategoryConfig.hpp`、`DatasetCategory.{hpp,cpp}`、`Vtk3dRequests.{hpp,cpp}`、`DatasetFieldDictionary.{hpp,cpp}`、`CategorySection.{hpp,cpp}`、`CategoryAnalysisTab.{hpp,cpp}`、`VtkViewToolbar.{hpp,cpp}`、`AxesSettingsDialog.{hpp,cpp}` + 对应 tests。
**契约文档：** `docs/api/vtk-3d-openapi.json`（v0.6-draft）、真实 schema `docs/apis/business_OpenAPI.json`（DsObjectDataVO/DsTypeVO/ArrayTypeVO）。
## 8. 铁律 / 注意
- **贴源码/实测，别凭印象**：本会话多次因二手猜测（"装置类型要后端补字段"、"properties 形态矛盾"、归属层级）被用户/实测纠正——任何字段/语义先去代码或真实接口核实。
- **复用优先**：DatasetListPanel/Api3dRepository/Column2DDataset 复用，不重写。
- **每 task TDD + 可编译 + commit**；不留 TODO 占位。
- 全部回复中文。
## 9. 相关
- spec：`docs/superpowers/specs/2026-06-24-vtk-category-view-refactor-design.md`
- plan：`docs/superpowers/plans/2026-06-24-vtk-category-view-refactor.md`
- 后端契约交接：`docs/superpowers/HANDOFF-vtk-3d-backend-api.md`（三维体/切片/异常端点）
- 记忆：`vtk-3d-persistence-structure`、`dataset-detail-types-catalog`、`web-3d-view-threetile`、`gpr-volume-design-trio`
- 提交：`eceb964`（spec+openapi v0.5）、`ef10c35`（plan + 客户变动 + openapi v0.6）

495
docs/superpowers/mockups/2026-06-16-three-column-layout.html Normal file
View File

@ -0,0 +1,495 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>三栏结构重构 · 高保真原型对比</title>
<style>
/* ===== 真实 app 深色令牌（src/app/Theme.cpp dark 列） ===== */
:root{
--bg-app:#0E1116; --bg-panel:#161A20; --bg-panel-subtle:#161B22; --bg-header:#12161C;
--bg-hover:#1B2129; --bg-selected:#16243F;
--border:#262C35; --border-strong:#333B45;
--text:#E6E9EF; --text-2:#A4ADBB; --text-3:#7A8494; --text-dis:#5A626F;
--accent:#5E8DF5; --accent-h:#93B4FA;
--canvas-bg:#0B1320; --canvas-soft:#111B2D; --canvas-grid:#1E2A3D;
--canvas-text:#E6ECF5; --canvas-dim:#8A97AC;
--danger:#FF6166; --warn:#F5A623; --ok:#46C07A;
--r:6px;
}
*{box-sizing:border-box;margin:0;padding:0;}
html,body{height:100%;}
body{
font-family:"Microsoft YaHei UI","Segoe UI",system-ui,sans-serif;
background:#05080d;color:var(--text);font-size:13px;
display:flex;flex-direction:column;height:100vh;overflow:hidden;
}
/* ===== 顶部方案切换条（原型控制，非 app 一部分） ===== */
.meta{
display:flex;align-items:center;gap:14px;padding:10px 16px;
background:#11151c;border-bottom:1px solid var(--border);flex:0 0 auto;
}
.meta .lbl{color:var(--text-3);font-size:12px;}
.meta .opts{display:flex;gap:8px;}
.meta button{
font:inherit;font-size:12.5px;color:var(--text-2);background:var(--bg-panel);
border:1px solid var(--border);border-radius:20px;padding:6px 16px;cursor:pointer;
transition:.12s;
}
.meta button:hover{border-color:var(--accent);color:var(--text);}
.meta button.on{background:var(--accent);border-color:var(--accent);color:#fff;font-weight:600;}
.meta .tag{margin-left:auto;font-size:11.5px;color:var(--text-3);}
.meta .tag b{color:var(--ok);}
/* ===== app 外壳 ===== */
.app{flex:1 1 auto;display:flex;flex-direction:column;min-height:0;background:var(--bg-app);}
/* TopBar */
.topbar{
height:46px;flex:0 0 auto;display:flex;align-items:center;gap:14px;padding:0 14px;
background:var(--bg-header);border-bottom:1px solid var(--border);
}
.topbar .logo{width:24px;height:24px;border-radius:6px;background:linear-gradient(135deg,var(--accent),#3B73EC);}
.topbar .ws{font-weight:600;color:var(--text);}
.topbar .ws small{color:var(--text-3);font-weight:400;margin-left:6px;}
.topbar .spacer{flex:1;}
.topbar .ico{width:30px;height:30px;border-radius:6px;display:grid;place-items:center;color:var(--text-2);}
.topbar .ico:hover{background:var(--bg-hover);}
.topbar .avatar{width:30px;height:30px;border-radius:50%;background:var(--accent);color:#fff;display:grid;place-items:center;font-size:12px;font-weight:700;}
/* dock 网格 */
.dockgrid{flex:1 1 auto;display:grid;gap:6px;padding:6px;min-height:0;}
/* 默认（A/B）：左 / 中 / 右 三列 */
.dockgrid.cols{grid-template-columns:288px 1fr 248px;grid-template-rows:1fr;}
.col{display:flex;flex-direction:column;gap:6px;min-height:0;min-width:0;}
/* dock 面板 */
.dock{
background:var(--bg-panel);border:1px solid var(--border);border-radius:var(--r);
display:flex;flex-direction:column;min-height:0;overflow:hidden;
}
.dock-hd{
height:30px;flex:0 0 auto;display:flex;align-items:center;gap:6px;padding:0 10px;
background:var(--bg-header);border-bottom:1px solid var(--border);
font-size:12.5px;font-weight:600;color:var(--text-2);
}
.dock-hd .badge{margin-left:auto;font-size:10.5px;font-weight:600;color:var(--text-3);
background:var(--bg-hover);border-radius:9px;padding:1px 7px;}
.dock-bd{flex:1 1 auto;overflow:auto;padding:8px 10px;min-height:0;}
.dock.flex1{flex:1 1 auto;}
.dock.flexN{flex:0 0 auto;}
/* 对象树 / 列表项 */
.tree{list-style:none;}
.tree li{padding:4px 2px;color:var(--text);white-space:nowrap;border-radius:4px;}
.tree li:hover{background:var(--bg-hover);}
.tree li.sel{background:var(--bg-selected);}
.tree .ind1{padding-left:18px;}
.tree .ind2{padding-left:34px;}
.tree .ind3{padding-left:50px;}
.ck{display:inline-block;width:13px;height:13px;border:1px solid var(--border-strong);border-radius:3px;
vertical-align:-2px;margin-right:7px;position:relative;background:var(--canvas-bg);}
.ck.on{background:var(--accent);border-color:var(--accent);}
.ck.on::after{content:"";position:absolute;left:4px;top:1px;width:3px;height:7px;border:solid #fff;border-width:0 2px 2px 0;transform:rotate(45deg);}
.tw{color:var(--text-3);margin-right:4px;font-size:10px;}
.muted{color:var(--text-3);}
.pill{font-size:10px;color:var(--accent-h);border:1px solid var(--canvas-grid);border-radius:8px;padding:0 6px;margin-left:6px;}
/* 工具条 */
.toolbar{display:flex;flex-wrap:wrap;gap:6px;align-items:center;padding:8px 10px;
border-bottom:1px solid var(--border);background:var(--bg-panel-subtle);}
.toolbar.canvas{background:var(--canvas-soft);border-color:var(--canvas-grid);}
select.mini,.btnm{
font:inherit;font-size:11.5px;color:var(--text);background:var(--canvas-bg);
border:1px solid var(--canvas-grid);border-radius:4px;padding:3px 7px;cursor:pointer;
}
.btnm:hover{background:var(--bg-hover);border-color:var(--accent);}
.grp{display:flex;gap:3px;flex-wrap:wrap;}
.grp .btnm{padding:3px 8px;}
/* 工具条分组栏位 */
.toolbar.col{flex-direction:column;align-items:stretch;gap:0;}
.tgrp{display:flex;flex-wrap:wrap;align-items:center;gap:5px;padding:6px 0;border-bottom:1px dashed var(--canvas-grid);}
.tgrp:last-child{border-bottom:none;}
.tgrp .glbl{width:100%;font-size:11px;font-weight:600;color:var(--canvas-dim);margin-bottom:2px;}
.flbl{font-size:11px;color:var(--canvas-dim);display:inline-flex;align-items:center;gap:2px;}
.zin{font:inherit;font-size:11px;width:52px;color:var(--text);background:var(--canvas-bg);
border:1px solid var(--canvas-grid);border-radius:4px;padding:2px 5px;}
/* 表单行：标签固定宽 + 控件填满，不再流式折行 */
.frow{display:flex;align-items:center;gap:8px;width:100%;}
.frow .flbl{width:58px;flex:0 0 auto;}
.frow select.mini{width:132px;flex:0 0 auto;}
.frow .track{flex:1;}
.sval{font-size:11px;color:var(--canvas-text);width:36px;text-align:right;flex:0 0 auto;}
/* 滑块：独立类，不再依赖 .slider 父级（之前那样导致 track 0 高度看不见） */
.track{height:5px;background:var(--canvas-grid);border-radius:3px;position:relative;min-width:80px;}
.track .knob{position:absolute;top:-4px;width:13px;height:13px;border-radius:50%;
background:var(--accent);box-shadow:0 0 0 3px rgba(94,141,245,.22);cursor:pointer;}
.track .fill{position:absolute;left:0;top:0;bottom:0;background:var(--accent);border-radius:3px;opacity:.55;}
/* VTK 视图区 */
.vtk{
flex:1 1 auto;position:relative;min-height:0;border-radius:var(--r);overflow:hidden;
background:radial-gradient(120% 120% at 50% 18%,#16243f 0%,var(--canvas-bg) 60%);
border:1px solid var(--border);
}
.vtk .hd{position:absolute;top:0;left:0;right:0;height:30px;display:flex;align-items:center;padding:0 10px;
background:rgba(18,22,28,.72);border-bottom:1px solid var(--canvas-grid);font-size:12px;color:var(--text-2);z-index:4;backdrop-filter:blur(2px);}
/* 全屏按钮（VTK视图 + 数据详情 标题栏右侧） */
.fsbtn{margin-left:auto;width:22px;height:20px;display:grid;place-items:center;cursor:pointer;
border-radius:4px;color:var(--text-3);font-size:13px;}
.fsbtn:hover{background:var(--bg-hover);color:var(--accent);}
.fs-on{position:fixed !important;inset:0;z-index:90;border-radius:0;width:auto !important;height:auto !important;}
/* 假三维：两片帘面 + 体素盒 + 切片 */
.scene{position:absolute;inset:30px 0 0 0;perspective:900px;display:grid;place-items:center;}
.stage{transform-style:preserve-3d;transform:rotateX(60deg) rotateZ(-28deg);}
.curtain{position:absolute;width:230px;height:120px;left:-115px;top:-60px;
background:linear-gradient(90deg,#2a4a8f,#3aa0c0 35%,#7ec96f 60%,#e8c84a 78%,#d9603a);
opacity:.92;border:1px solid rgba(255,255,255,.18);box-shadow:0 0 24px rgba(94,141,245,.25);}
.curtain.b{transform:rotateZ(90deg) translateZ(0);opacity:.78;}
.axes{position:absolute;left:-130px;top:70px;width:0;height:0;}
.axes i{position:absolute;height:2px;transform-origin:left center;}
.ax-x{width:150px;background:#e5605f;}
.ax-y{width:120px;background:#46c07a;transform:rotate(-90deg);}
.grid-floor{position:absolute;width:300px;height:300px;left:-150px;top:-150px;
background-image:linear-gradient(var(--canvas-grid) 1px,transparent 1px),linear-gradient(90deg,var(--canvas-grid) 1px,transparent 1px);
background-size:30px 30px;opacity:.35;transform:translateZ(-2px);}
.slice3d{position:absolute;width:160px;height:90px;left:-80px;top:-45px;
background:repeating-linear-gradient(45deg,rgba(94,141,245,.35) 0 8px,rgba(94,141,245,.12) 8px 16px);
border:2px solid var(--accent);transform:rotateY(0deg) rotateZ(28deg) translateZ(40px);box-shadow:0 0 18px rgba(94,141,245,.4);}
.legend{position:absolute;right:12px;bottom:12px;width:14px;height:96px;border-radius:3px;
background:linear-gradient(#d9603a,#e8c84a,#7ec96f,#3aa0c0,#2a4a8f);border:1px solid var(--canvas-grid);z-index:3;}
.legend::after{content:"Ω·m";position:absolute;left:-24px;top:40px;font-size:10px;color:var(--canvas-dim);}
/* tabs（方案 A） */
.tabbar{display:flex;gap:2px;border-bottom:1px solid var(--border);background:var(--bg-header);flex:0 0 auto;}
.tabbar .tab{padding:7px 14px;font-size:12.5px;color:var(--text-3);cursor:pointer;border-bottom:2px solid transparent;}
.tabbar .tab:hover{color:var(--text);}
.tabbar .tab.on{color:var(--accent);border-bottom-color:var(--accent);font-weight:600;}
.tabpane{display:none;flex-direction:column;min-height:0;flex:1 1 auto;}
.tabpane.on{display:flex;}
/* 折叠分段（方案 B） */
.section .sec-hd{display:flex;align-items:center;gap:6px;padding:7px 10px;cursor:pointer;
background:var(--bg-header);border-top:1px solid var(--border);font-weight:600;color:var(--text-2);font-size:12.5px;}
.section:first-child .sec-hd{border-top:none;}
.section .sec-hd .tw{font-size:11px;}
.section .sec-bd{padding:6px 10px 10px;}
/* 视图内嵌侧栏（方案 C 修正版）：抽屉式，画布在右、不遮挡 */
.vtk.with-drawer .scene{left:var(--drawer-w,300px);transition:left .18s;}
.view-drawer{position:absolute;top:30px;left:0;bottom:0;width:300px;z-index:6;
background:rgba(17,27,45,.94);border-right:1px solid var(--canvas-grid);
display:flex;flex-direction:column;backdrop-filter:blur(3px);transition:width .18s;overflow:hidden;}
.view-drawer .tabbar{background:rgba(18,22,28,.55);}
.drawer-toggle{position:absolute;top:38px;z-index:7;left:300px;width:18px;height:46px;
background:rgba(17,27,45,.94);border:1px solid var(--canvas-grid);border-left:none;
border-radius:0 6px 6px 0;display:grid;place-items:center;color:var(--canvas-dim);cursor:pointer;
font-size:11px;transition:left .18s;}
.drawer-toggle:hover{color:var(--accent);}
.vtk.drawer-collapsed .view-drawer{width:0;border-right:none;}
.vtk.drawer-collapsed .scene{left:0;}
.vtk.drawer-collapsed .drawer-toggle{left:0;}
/* 右键菜单 */
.ctx{position:absolute;z-index:30;min-width:150px;background:var(--bg-panel);border:1px solid var(--border-strong);
border-radius:6px;box-shadow:0 10px 30px rgba(0,0,0,.6);padding:4px;display:none;}
.ctx.show{display:block;}
.ctx .it{padding:6px 12px;border-radius:4px;font-size:12.5px;color:var(--text);cursor:pointer;white-space:nowrap;}
.ctx .it:hover{background:var(--accent);color:#fff;}
.ctx .sep{height:1px;background:var(--border);margin:4px 6px;}
.ctx .it.sub::after{content:"▸";float:right;color:var(--text-3);margin-left:18px;}
.hint{font-size:11px;color:var(--text-3);padding:6px 10px;border-top:1px dashed var(--border);}
.note{font-size:11.5px;color:var(--warn);background:rgba(245,166,35,.08);border:1px solid rgba(245,166,35,.25);
border-radius:5px;padding:6px 9px;margin:8px 10px;}
kbd{background:var(--bg-hover);border:1px solid var(--border-strong);border-radius:3px;padding:0 5px;font-size:11px;}
</style>
</head>
<body>
<div class="meta">
<span class="lbl">三栏结构重构 · 布局方案</span>
<div class="opts">
<button data-opt="C" class="on">方案 C · 视图内嵌侧栏（修正·推荐）</button>
<button data-opt="A">方案 A · 左侧独立 dock</button>
<button data-opt="B">方案 B · 竖向分段 dock</button>
</div>
<span class="tag">配色取自 <b>Theme.cpp</b> 深色令牌 · 右键「三维分析」树里的三维体试试创建切片</span>
</div>
<!-- ============ APP 外壳 ============ -->
<div class="app">
<div class="topbar">
<div class="logo"></div>
<div class="ws">地大演示项目 <small>· 工作区</small></div>
<div class="spacer" style="flex:1"></div>
<div class="ico">⌗</div><div class="ico">⚙</div>
<div class="avatar">GZ</div>
</div>
<div class="dockgrid cols" id="grid">
<!-- 左列：内容随方案变 -->
<div class="col" id="leftcol"></div>
<!-- 中列：VTK + 详情 -->
<div class="col" style="min-width:0">
<div class="dock flex1" style="padding:0;border:none;background:transparent">
<div class="vtk" id="vtk">
<div class="hd">VTK视图 · 地大演示项目<span class="fsbtn" data-fs title="全屏 / 还原">⛶</span></div>
<div class="scene"><div class="stage">
<div class="grid-floor"></div>
<div class="curtain"></div>
<div class="curtain b"></div>
<div class="slice3d"></div>
<div class="axes"><i class="ax-x"></i><i class="ax-y"></i></div>
</div></div>
<div class="legend"></div>
</div>
</div>
<div class="dock flexN" style="height:120px">
<div class="dock-hd">数据详情<span class="fsbtn" data-fs title="全屏 / 还原">⛶</span></div>
<div class="dock-bd muted" style="font-size:12px">选中数据集查看详情（源数据 / 切片 / 异常 / 插值模型 / 色阶 / 测量）</div>
</div>
</div>
<!-- 右列：异常/属性 -->
<div class="col">
<div class="dock flex1">
<div class="dock-hd">异常 / 对象属性</div>
<div class="dock-bd">
<ul class="tree">
<li><span class="tw">▾</span>异常体 A <span class="pill">随GS</span></li>
<li class="ind1"><span class="tw">▾</span>分组-1</li>
<li class="ind2 muted">异常 #1</li>
<li class="ind2 muted">异常 #2</li>
</ul>
</div>
</div>
<div class="dock flexN" style="height:150px">
<div class="dock-hd">数据集属性</div>
<div class="dock-bd muted" style="font-size:12px">名称 / 类型 / 维度 / 创建时间…</div>
</div>
</div>
</div>
</div>
<!-- 三维体数据集 右键菜单（原文行21-27：切片/色阶/显隐/详情，无删除） -->
<div class="ctx" id="ctx">
<div class="it sub" data-act="slice">切片</div>
<div class="it">色阶</div>
<div class="it">显示 / 隐藏</div>
<div class="it">数据详情</div>
</div>
<div class="ctx" id="ctxSub">
<div class="it">上下</div>
<div class="it">前后</div>
<div class="it">左右</div>
<div class="it">任意</div>
</div>
<!-- 切片数据集 右键菜单（原文行29-35：保存/保存为/导出/删除/色阶/显隐/详情） -->
<div class="ctx" id="ctxSlice">
<div class="it">保存</div>
<div class="it">保存为</div>
<div class="it">导出</div>
<div class="it" style="color:var(--danger)">删除</div>
<div class="sep"></div>
<div class="it">色阶</div>
<div class="it">显示 / 隐藏</div>
<div class="it">数据详情</div>
</div>
<script>
// ===== 三栏内容片段 =====
function dataset3DList(){return `
<ul class="tree">
<li><span class="ck on"></span>反演剖面-L1 <span class="pill">帘面</span></li>
<li><span class="ck on"></span>反演剖面-L2 <span class="pill">帘面</span></li>
<li><span class="ck"></span>体素模型-V1 <span class="pill">dd_voxel</span></li>
<li><span class="ck"></span>地形 DEM+影像</li>
</ul>`;}
function dataset2DList(){return `
<ul class="tree">
<li><span class="ck on"></span>测线-T1 <span class="pill">俯视</span></li>
<li><span class="ck"></span>轨迹-Tr1 <span class="pill">trajectory</span></li>
</ul>`;}
function analysisTree(){return `
<ul class="tree" id="anaTree">
<li><span class="ck on"></span><span class="tw">▾</span>GS-地大演示</li>
<li class="ind1" data-vol="1"><span class="ck on"></span><span class="tw">▾</span>三维体模型-V1 <span class="pill">右键</span></li>
<li class="ind2" data-slice="1"><span class="ck on"></span><span class="tw">▸</span>切片·上下-01 <span class="pill">右键</span></li>
<li class="ind2" data-slice="1"><span class="ck"></span><span class="tw">▸</span>切片·任意-02</li>
<li class="ind1" data-vol="1"><span class="ck"></span><span class="tw">▸</span>三维体模型-V2</li>
</ul>
<div class="hint">右键<b>三维体</b>→切片▸(上下/前后/左右/任意)·色阶·显隐·详情；右键<b>切片</b>→保存/保存为/导出/删除·色阶·显隐·详情。</div>`;}
function toolbar3D(canvas){return `
<div class="toolbar col ${canvas?'canvas':''}">
<div class="tgrp"><span class="glbl">坐标轴设置</span>
<div class="frow"><span class="flbl">显示方式</span><select class="mini"><option>标准</option><option>三维立体</option><option>不显示</option></select></div>
<div class="frow"><span class="flbl">O点位置</span><span class="btnm">设置…</span></div>
<div class="frow"><span class="flbl">刻度</span><select class="mini"><option>无刻度</option><option selected>米</option><option>英尺</option><option>经纬度</option></select></div>
<div class="frow"><span class="flbl">字体</span><span class="btnm">设置…</span></div>
</div>
<div class="tgrp"><span class="glbl">水平/垂直比例</span>
<div class="frow"><span class="track"><span class="fill" style="width:24%"></span><span class="knob" style="left:24%"></span></span><span class="sval">2.0×</span></div>
</div>
<div class="tgrp"><span class="glbl">快捷视图</span>
<span class="grp"><span class="btnm">前</span><span class="btnm">后</span><span class="btnm">左</span><span class="btnm">右</span><span class="btnm">上</span><span class="btnm">下</span></span>
</div>
<div class="tgrp"><span class="glbl">缩放 (Zoom)</span>
<span class="grp"><span class="btnm">放大</span><span class="btnm">缩小</span><span class="btnm">适配</span></span>
</div>
</div>`;}
function toolbar2D(canvas){return `
<div class="toolbar col ${canvas?'canvas':''}">
<div class="tgrp"><span class="glbl">地图</span>
<div class="frow"><span class="flbl">底图源</span><select class="mini"><option>天地图</option><option>Google Map</option><option>隐藏</option></select></div>
</div>
<div class="tgrp"><span class="glbl">2D视图</span>
<div class="frow"><span class="flbl">位置</span><select class="mini" onchange="document.getElementById('zwrap').style.display=this.value==='自定义'?'inline-flex':'none'">
<option>关闭</option><option selected>Z=0</option><option>顶部</option><option>底部</option><option>自定义</option></select></div>
<div class="frow" id="zwrap" style="display:none"><span class="flbl">Z 值</span><input class="zin" type="number" value="0"><span class="flbl">m</span></div>
</div>
</div>`;}
// 对象树 dock（A/B/C 都有，作为勾选源）
function objectDock(){return `
<div class="dock flexN" style="height:170px">
<div class="dock-hd">对象 <span class="badge">勾选源</span></div>
<div class="dock-bd">
<ul class="tree">
<li class="sel"><span class="ck on"></span><span class="tw">▾</span>GS-地大演示</li>
<li class="ind1"><span class="ck on"></span>TM-反演成果</li>
<li class="ind1"><span class="ck"></span>TM-轨迹</li>
<li><span class="ck"></span><span class="tw">▸</span>GS-威立雅</li>
</ul>
</div>
</div>`;}
// ===== 三种方案的左列 =====
function buildA(){ // Tab 切换
return objectDock() + `
<div class="dock flex1">
<div class="tabbar" id="tabbarA">
<div class="tab on" data-t="0">三维数据集</div>
<div class="tab" data-t="1">二维数据集</div>
<div class="tab" data-t="2">三维分析</div>
</div>
<div class="tabpane on">${toolbar3D(false)}<div class="dock-bd">${dataset3DList()}</div></div>
<div class="tabpane">${toolbar2D()}<div class="dock-bd">${dataset2DList()}</div></div>
<div class="tabpane"><div class="dock-bd">${analysisTree()}</div></div>
</div>`;
}
function buildB(){ // 竖向分段
return objectDock() + `
<div class="dock flex1">
<div class="dock-hd">数据集 / 分析 <span class="badge">全可见</span></div>
<div class="dock-bd" style="padding:0">
<div class="section">
<div class="sec-hd"><span class="tw">▾</span>三维数据集</div>
<div class="sec-bd">${toolbar3D(false)}${dataset3DList()}</div>
</div>
<div class="section">
<div class="sec-hd"><span class="tw">▾</span>二维数据集</div>
<div class="sec-bd">${toolbar2D()}${dataset2DList()}</div>
</div>
<div class="section">
<div class="sec-hd"><span class="tw">▾</span>三维分析</div>
<div class="sec-bd">${analysisTree()}</div>
</div>
</div>
</div>`;
}
function buildC(){ // 视图内嵌侧栏（修正）：左列保留对象列表（三栏的筛选来源）+ 详情
return objectDock() + `
<div class="dock flex1">
<div class="dock-hd">数据集（详情查看）</div>
<div class="dock-bd">
<ul class="tree">
<li class="muted">反演剖面-L1</li><li class="muted">体素模型-V1</li><li class="muted">测线-T1</li>
</ul>
<div class="note" style="color:var(--accent-h);background:rgba(94,141,245,.08);border-color:rgba(94,141,245,.3)">方案 C（修正）：三个「子列表栏」内嵌在 VTK 视图左侧（抽屉式侧栏），三 tab 切换。画布在其右侧、不被遮挡；点侧栏右缘 <b>◀</b> 可折叠让画布全宽。这正是需求「VTK视图上提供三个子列表栏」的形态。左侧「对象」列表是三栏的筛选来源（需求：筛勾选对象中的 ds）。</div>
</div>
</div>`;
}
function viewDrawerHTML(){return `
<div class="view-drawer">
<div class="tabbar">
<div class="tab on" data-t="0">三维数据集</div>
<div class="tab" data-t="1">二维数据集</div>
<div class="tab" data-t="2">三维分析</div>
</div>
<div class="tabpane on">${toolbar3D(true)}<div class="dock-bd">${dataset3DList()}</div></div>
<div class="tabpane">${toolbar2D(true)}<div class="dock-bd">${dataset2DList()}</div></div>
<div class="tabpane"><div class="dock-bd">${analysisTree()}</div></div>
</div>
<div class="drawer-toggle" id="drawerToggle">◀</div>`;}
// ===== 渲染 =====
const grid=document.getElementById('grid');
const vtk=document.getElementById('vtk');
function render(opt){
document.querySelectorAll('.meta button').forEach(b=>b.classList.toggle('on',b.dataset.opt===opt));
const left=document.getElementById('leftcol');
// 清掉方案 C 的内嵌侧栏
vtk.classList.remove('with-drawer','drawer-collapsed');
vtk.querySelectorAll('.view-drawer,.drawer-toggle').forEach(e=>e.remove());
if(opt==='A'){ left.innerHTML=buildA(); wireTabs(); }
if(opt==='B'){ left.innerHTML=buildB(); wireSections(); }
if(opt==='C'){
left.innerHTML=buildC();
vtk.classList.add('with-drawer');
vtk.insertAdjacentHTML('beforeend', viewDrawerHTML());
wireTabs(vtk.querySelector('.view-drawer'));
const tg=document.getElementById('drawerToggle');
tg.onclick=()=>{const c=vtk.classList.toggle('drawer-collapsed');tg.textContent=c?'▶':'◀';};
}
wireCtx();
}
function wireTabs(scope){
(scope||document).querySelectorAll('.tabbar .tab').forEach(t=>{
t.onclick=()=>{
const bar=t.parentElement, panes=bar.parentElement.querySelectorAll(':scope > .tabpane');
bar.querySelectorAll('.tab').forEach(x=>x.classList.remove('on'));
t.classList.add('on');
panes.forEach((p,i)=>p.classList.toggle('on',i===+t.dataset.t));
};
});
}
function wireSections(){
document.querySelectorAll('.section .sec-hd').forEach(h=>{
h.onclick=()=>{const bd=h.nextElementSibling, tw=h.querySelector('.tw');
const open=bd.style.display!=='none'; bd.style.display=open?'none':''; tw.textContent=open?'▸':'▾';};
});
}
// 右键菜单：三维体(ctx+ctxSub子菜单) / 切片(ctxSlice)
const ctx=document.getElementById('ctx'), ctxSub=document.getElementById('ctxSub'),
ctxSlice=document.getElementById('ctxSlice');
function popAt(menu,e){e.preventDefault();hideCtx();
menu.style.left=e.pageX+'px';menu.style.top=e.pageY+'px';menu.classList.add('show');}
function wireCtx(){
document.querySelectorAll('[data-vol]').forEach(li=>li.oncontextmenu=(e)=>popAt(ctx,e));
document.querySelectorAll('[data-slice]').forEach(li=>li.oncontextmenu=(e)=>popAt(ctxSlice,e));
ctx.querySelector('[data-act=slice]').onmouseenter=()=>{
const r=ctx.getBoundingClientRect();
ctxSub.style.left=r.right+'px';ctxSub.style.top=r.top+'px';ctxSub.classList.add('show');
};
}
function hideCtx(){[ctx,ctxSub,ctxSlice].forEach(m=>m.classList.remove('show'));}
document.addEventListener('click',hideCtx);
document.addEventListener('scroll',hideCtx,true);
// 全屏切换：VTK视图 / 数据详情
document.querySelectorAll('[data-fs]').forEach(b=>b.onclick=(e)=>{
e.stopPropagation();
const panel=b.closest('.vtk')||b.closest('.dock');
const on=panel.classList.toggle('fs-on');
b.textContent=on?'🗗':'⛶';
});
document.querySelectorAll('.meta button').forEach(b=>b.onclick=()=>render(b.dataset.opt));
render('C');
</script>
</body>
</html>

73
docs/superpowers/plans/2026-06-15-vtk-3d-p1-revive-rendering.md Normal file
View File

@ -0,0 +1,73 @@
# 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+ 接后端返工）。

43
docs/superpowers/plans/2026-06-15-vtk-3d-p2-dataset3d-bar.md Normal file
View File

@ -0,0 +1,43 @@
# 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，中文可能缺字形 → 标签用数字/英文单位优先。

48
docs/superpowers/plans/2026-06-16-vtk-3d-p3-slice-interaction.md Normal file
View File

@ -0,0 +1,48 @@
# P3：三维分析·切片交互（核心）
- 日期：2026-06-16
- 分支：`feat/vtk-3d-view`
- 上游：spec `2026-06-15-vtk-3d-supplementary-design.md` §9（交互层）、§4 行 F22–F25/C38–D46/E54–E56；接 P1/P2（VtkSceneController/VtkSceneView/Scene/体素管线已就位）
- 目标：补充需求最重模块。在 P1 的 LocalSample 体素上实现**切片交互**：轴向/任意切片、滚轮推进、拾取选中、双击正视。让用户能在三维体上切出带色阶的剖面并交互调整。
## 范围
**范围内（P3 核心）**：
- 新建 `src/render/interact/` 交互层（README 早有规划但目录不存在）。
- **切片工具**：轴向（上下=水平面/前后/左右，角度固定，F22–F24）+ 任意切片（初始 45°、可旋转，F25），对体素 `vtkImageData` 重采样出**带色阶剖面**。
- **滚轮切片**（D46）：选中切片，滚轮沿切面法向推进/后退。
- **拾取选中 + 联动**（C38/D39/D40/E54/E55/E56）：拾取三维体/切片 → 以其中心为相机焦点（拖动绕其旋转）；双击切片 → 相机正视切面法向；视图翻转（水平 180°）；关闭切片。
- 切片剖面随体素纵向夸张一致（复用 P2 VE）。
- UI 入口：在三维视图加一组**切片按钮**（上下/前后/左右/任意/关闭），最小可用即可（完整右键菜单 + 三维分析树留 P4）。
**范围外（留 P4）**：切片**保存/保存为/导出图片/导出dat/删除**为数据集（§6.3 CRUD）、三维分析栏树列表、右键上下文菜单、异常圈定 + 异常体管理、三维体/切片详情。
## 关键设计
- **体素 image 暴露**：`VtkSceneView::addVolume` 改用 `buildVoxel(...,outImage)` 重载，保留 `currentVolumeImage_`（含 VE 烤入的 origin/spacing），供切片工具附着。无体素时切片按钮禁用/无效。
- **切片工具**（`src/render/interact/SliceTool.{hpp,cpp}`）：
- 方案优选 **`vtkImagePlaneWidget`** 同时覆盖轴向与任意：`SetPlaneOrientationToXAxes/Y/Z` 给轴向（关闭旋转交互=角度固定）；任意 = 设初始法向 45° 并允许旋转。它内部 reslice + 纹理显示剖面，`SetLookupTable` 套我们的色阶 LUT（`ColorLutBuilder`）。
- 若 `vtkImagePlaneWidget` 旋转/滚轮交互不满足，再退 `vtkImplicitPlaneWidget2 + vtkImageReslice + vtkImageActor`（spec §9.1 钉死 reslice，**不用 vtkCutter**）。
- 持 `vtkPlane`(origin/normal)；产出当前切面（供 P4 保存时转 Grid）。
- **滚轮推进**：自定义 interactor 观察者截 `MouseWheelForward/BackwardEvent`，对选中切片沿法向平移 origin → 更新 widget。
- **拾取 + 自定义 InteractorStyle**（`src/render/interact/PickInteractorStyle.{hpp,cpp}`，继承 `vtkInteractorStyleTrackballCamera`）：
- `vtkPropPicker` 拾取 → 选中 prop（高亮）→ 相机 focalPoint=prop 包围盒中心（绕其旋转）。
- 双击切片 → 相机 position=center+normal·dist、viewUp 取法向正交（法向竖直时兜底备用 up）→ 正视（E54）。视图翻转=Azimuth(180)（E55）。
- **InteractionManager**（`src/render/interact/InteractionManager.{hpp,cpp}`）：持 interactor + 活动切片工具列表 + 选中态；管理创建/关闭切片、滚轮分发、拾取联动。app 层 VtkSceneView 持有它并接 UI 按钮。
## 步骤（TDD；交互件靠 build+目视，纯逻辑单测）
0. 基线 `build.bat test` 全绿。
1. **切面几何/法向数学**（TDD 纯逻辑）：轴向法向（上下=(0,0,1)/前后=(0,1,0)/左右=(1,0,0)）、任意初始 45°；滚轮平移 origin=origin+normal·step；双击正视的相机 position/viewUp 计算（含法向竖直兜底）。抽成可测纯函数（如 `SlicePlaneMath`）。
2. **VtkSceneView 暴露体素 image**：addVolume 保留 currentVolumeImage_；clear 置空。测试/目视体素仍正常。
3. **SliceTool**（vtkImagePlaneWidget 封装）：构建/附着 image/设色阶 LUT/轴向 vs 任意配置/关闭。可测部分：plane origin/normal 设置、LUT 套用；widget 交互目视。
4. **PickInteractorStyle + InteractionManager**：拾取→focal、双击→正视、滚轮→推进、翻转、关闭。纯逻辑（focal/相机计算）单测；拾取/事件目视。
5. **UI 接入 main.cpp**：三维视图切片按钮组（上下/前后/左右/任意/关闭），连 InteractionManager；仅三维 + 有体素时可用。深色主题（复用 P2 工具条样式）。
6. `build.bat test` 全绿 + `build.bat app` 链接；目视清单交用户。
7. cpp-reviewer 审查 + 提交。
## 风险/注意
- **vtkImagePlaneWidget 生命周期**：须 `SetInteractor`(QVTK 的 `renderWindow->GetInteractor()`) + `On()`；vtkSmartPointer 持有防析构；场景 clear/切视图时正确 Off()+释放，避免悬挂观察者/崩溃。
- **纵向夸张一致**：切片附着的 image 已烤入 VE（P1 体素管线），切面几何与体绘制对齐；VE 变化触发体素重建 → 切片须重附着或关闭重建。
- **2D 模式无切片**：切片仅三维视图；切到二维须 Off 所有切片工具。
- **自定义 InteractorStyle 与 QVTK 默认**：替换 style 后须保留相机拖动等基本交互（继承 TrackballCamera）。
- **构建**：增量链接错用 `cmake --build build\release --clean-first`，**勿删 build 目录**（[[build-vs2026-vcpkg-gotchas]]）；app 在运行致 LNK1104 则以 ctest 为准、提示关 app 重链。
- **交互件难单测**：VTK widget 需 render window/interactor，CI 无显示环境多半跳过；故纯逻辑（plane/相机数学）尽量抽出单测，widget 行为靠目视。报告标清目视项。
- 切片"标准/任意"手感、色阶、正视/翻转细节若需对齐 Geopro 1.0，先合理实现，待 1.0 实地学习再精修（[[study-original-via-playwright]]）。

70
docs/superpowers/plans/2026-06-16-vtk-3d-p5-2d-dataset-bar.md Normal file
View File

@ -0,0 +1,70 @@
# P5 二维数据集栏渲染 + 底图 Implementation Plan
> 接续：三栏结构重构(已完成) + 真实 ERT 帘面(已完成)。本计划做「二维数据集」栏的真实渲染 + 天地图底图。
> GUI 渲染正确性须用户实测（Claude 不能 GUI 测；见构建铁律）。
**Goal:** 「二维数据集」栏勾选 → 在 VTK 视图的 2D 俯视面渲染：轨迹线(dd_trajectory_data)、网格面(dd_grid)，并叠加天地图底图（可切换 天地图/Google/隐藏）。
**Architecture:** 复用现有 `VtkSceneController`(已有 ViewMode::Map2D + addSurveyLine) + `GeoLocalFrame`(已重锚真实数据) + 天地图 token/WMTS(已存在于 trajectory_map.html)。新增：2D 数据异步加载(轨迹/网格) + 2D actor + 底图瓦片层(VTK)。
**已确认事实（真实 API/代码）：**
- 天地图 token：`TK=aca91d8c9f59a4f779f39061b8a07737`，WMTS XYZ：`http://t{0-7}.tianditu.gov.cn/{layer}_w/wmts?...&tileMatrixSet=w&TileMatrix={z}&TileRow={y}&TileCol={x}&style=default&format=tiles&tk=TK`（图层 `vec`街道/`img`卫星 + `cva`/`cia`注记，EPSG:3857，原生 z18）。见 `src/app/resources/map/trajectory_map.html`。
- 轨迹数据：`GET /business/dd/ert/trajectory/line?dsObjectId={id}&frontCrsCode=EPSG:4326` → `data.electrodelList`[]，每项 `{electrodeNo, electrodeCoordinate}`（经纬度）。
- 网格数据：`dd/ert/grid/rows/{id}`(GET) 实测 404 → **本计划 Task 0 先确认正确端点**（疑似 query 参数或 POST；参考 `src/app/panels/chart/GridStrategy.hpp` + `ApiDatasetRepository` 的 `gridRowsBatch`/`makeGridRows`）。
- `dimensionOf`：`dd_trajectory_data`→Dim2D（已）；`dd_grid`→当前 Other（**需加 Dim2D**）。
- col2D(`Column2DDataset`) 信号 `basemapChanged/view2DModeChanged/customZChanged/checkedDatasetsChanged` 在 main.cpp **当前未接线**(T7 留待本期)。
---
## Task 0：确认 dd_grid 端点 ✅（已做，结论纠正本计划）
- `dd_grid` = **「白化数据」分页坐标点表**：`GET /business/dd/ert/grid/rows?dsObjectId=&pageNo=&pageSize=` → `data={rowList[{x,y,id}], gridHeaderDisplay[x,y], total}`（见 `ApiDatasetRepository::gridRowsBatch` + `GridStrategy.hpp`）。
- **结论：dd_grid 是表格数据、不是 2D 地图面**，不作渲染层 → 维持 `Other`（仅在「数据详情」看表）。
- **2D 地图可渲染类型只剩 `dd_trajectory_data`（轨迹线）+ 底图**。Task 1 取消（不把 dd_grid 归 2D）；Task 2/3/4 只做轨迹。
## Task 1：（取消）dd_grid 非地图渲染类型，维持 Other。
## Task 2：2D 数据异步加载（轨迹 + 网格）
在 `Api3dRepository`(真实) + `LocalSample3dRepository`(样本 stub) 加异步方法（照 `loadSection` 范式）：
- `loadTrajectory(dsId, onOk(vector<LatLon>), onErr)`：真实走 `trajectory/line`，解析 `electrodelList[].electrodeCoordinate` → 经纬序列。
- `load2dGrid(dsId, onOk(SectionData/Grid), onErr)`：按 Task 0 的端点解析网格面。
- `I3dSceneRepository` 加这两个虚方法（接口扩展，LocalSample stub 返回样本/空）。
- 验证：编译绿；FakeSceneRepo 加 override。
## Task 3：2D actor（render 层）
- 轨迹线：新增 `render/actors/TrajectoryActor`（或复用 `MapLineActor`）：经 `GeoLocalFrame.toLocal` 把经纬序列 → 局部米折线，摆在 Z=0 平面（或 2D视图 Z）。橙色（对齐轨迹详情 `#ff8c00`）。
- 网格面：复用 `MapLineActor`(俯视红线) 或 `GridContourActor`(着色面，需 frame)。
- 单测：纯几何（经纬→局部米折线点数/坐标）抽出可测。
## Task 4：VtkSceneView + Controller 接 2D 渲染
- `I3dSceneView`/`VtkSceneView` 加 `addTrajectory(...)`、`add2dGrid(...)`。
- `VtkSceneController`：Map2D 分支里，对勾选的 2D ds 按维度调 `loadTrajectory`/`load2dGrid` → addTrajectory/add2dGrid（异步 + QPointer/gen 守护，照帘面范式）。
- `setViewMode`：col2D 的「2D视图位置」(关闭/Z=0/顶部/底部/自定义Z) 控制 2D 面的 Z（自定义Z=世界绝对米，见三栏 spec）。
## Task 5：main.cpp 接 col2D 信号
- `drawer->col2D()` 的 `checkedDatasetsChanged` → 渲染 2D ds（同 col3D 模式，按维度过滤后的真实 dsId）。
- `view2DModeChanged/customZChanged` → setViewMode + 2D 面 Z。
- `basemapChanged` → Task 6 底图开关。
- 验证：编译绿 + 用户实测（勾选轨迹 ds → 俯视面出橙色测线；网格 ds → 面）。
## Task 6：天地图底图瓦片层（最复杂，可独立验证）
新增 `render/ground/TileGroundLayer`：
- 输入：当前数据地理范围（从已渲染 actor 的 lat/lon 包围盒，或 GeoLocalFrame 原点 + 视域）→ 选合适 zoom（数据跨度→z）。
- 瓦片数学：EPSG:3857 经纬→TileRow/Col（标准 Web Mercator 瓦片公式），取覆盖范围的瓦片集。
- 异步拉取：`QNetworkAccessManager` GET 天地图 WMTS URL（token/子域见上）→ QImage → vtkTexture。
- 摆放：每块瓦片的地理 bbox → 四角经纬 `GeoLocalFrame.toLocal` → 局部米 → `vtkPlaneSource` + texture，置于 Z=底图平面。
- 切换：`basemapChanged`(0天地图/1Google/2隐藏)；Google 可后置（国内可用性），先天地图 + 隐藏。
- LOD/随相机更新：本期可固定一档 zoom（覆盖数据范围），相机驱动 LOD 后置。
- **配准是精度敏感点**：3857 瓦片范围反算到 GeoLocalFrame 必须与帘面/轨迹同一 frame，否则底图与数据错位。**须用户实测对齐**（Claude 不能 GUI 测）。
- 单测：瓦片数学（经纬→z/x/y、瓦片 bbox→经纬）纯函数抽出可测。
---
## ④ 三维分析栏交互（本期受限，附记）
- 树/右键菜单已是 UI。`detailRequested`→`detailCtrl.openDataset` 已接（T7）。`显示/隐藏` 可接 actor 可见性。
- **真切片**需 3D 体模型(dd_voxel/dd_Structual3D)，后端缺 → 受限，待后端。
- 切片 CRUD/色阶/异常 = P4，接口已留位(②a)，待后端 + 1.0 参考。
## 风险/验证
- 全部渲染须用户 `build.bat rebuild` 实测（Claude 不能 GUI 测）。
- 底图配准、2D 面 Z、轨迹/网格定位都是精度敏感点 → 小步验证。
- Task 0(grid 端点) 不明会卡 Task 2 的网格分支 → 先确认。

869
docs/superpowers/plans/2026-06-16-vtk-3d-three-column-refactor.md Normal file
View File

@ -0,0 +1,869 @@
# VTK 三栏结构重构 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 把 VTK 工作台的"旧二维/三维切换 + 三浮层"过渡态，重构成需求 A1 的「三个子列表栏」（三维数据集 / 二维数据集 / 三维分析），内嵌在唯一的中央「VTK视图」左侧，并接通已有渲染/切片能力；同时给 VTK视图 + 数据详情 加全屏按钮。
**Architecture:** 三栏抽成独立 widget（`src/app/panels/columns/`），各自只发信号、不依赖控制器；`ColumnDrawer` 作为 `vtkWidget` 在 HBox 中的**左侧兄弟控件**（非 GL 浮层，规避原生 GL 浮层 z 序/圆角伪影），可折叠。`main.cpp::buildWorkbench` 删三浮层+分段切换，改挂三栏并把信号接到既有 `VtkSceneController`/`InteractionManager`/`DatasetDetailController`。数据集列表由 `WorkbenchNavController` 取 `DsRow`、按 `I3dSceneRepository::dimensionOf` 过滤后分发到三栏。
**Tech Stack:** C++17, Qt6 Widgets, VTK9, Qt-ADS。构建 `build.bat`（见"构建/验证铁律"），测试 GoogleTest/CTest。
---
## ⚠️ 构建/验证铁律（每个 Task 都遵守）
- 构建：从 Git Bash 调 `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat test"`。命令：`app`/`test`/`rebuild`(全量)/`configure`。
- **ninja 偶发漏编** → 改头/布局后用 `build.bat rebuild`；验 exe 新鲜：`stat -c '%y' build/release/src/app/geopro_desktop.exe`。
- **切勿 `rm -rf build/release`**（vcpkg 重编依赖极慢）。
- **Claude 工具跑 build 偶被 Start-Process 钩子劫持静默不跑** → **所有"用户实测"步骤必须由用户在其终端 `build.bat rebuild` 跑并目视**。Claude 不能 GUI 测 VTK 交互。
- 纯逻辑（如维度过滤）抽函数 + GoogleTest 单测；UI/交互靠 build 绿 + 用户实测清单。
## 测试方式约定（本计划特例，覆盖默认 TDD-everywhere）
- **逻辑步骤**（标 `[逻辑]`）：先写失败测试 → 跑红 → 实现 → 跑绿 → 提交。
- **UI 步骤**（标 `[UI]`）：实现 → `build.bat rebuild` 编绿 → **用户实测清单** → 提交。Claude 不声称"已验证"交互，只验证编译通过 + 代码读校。
---
## File Structure
**新建：**
- `src/app/panels/columns/ColumnDrawer.hpp/.cpp` — 抽屉容器（QTabWidget 三 tab + 折叠开关）。
- `src/app/panels/columns/Column3DDataset.hpp/.cpp` — 三维数据集栏（4 工具条栏位 + 3D 数据集树）。
- `src/app/panels/columns/Column2DDataset.hpp/.cpp` — 二维数据集栏（地图/2D视图控件 + 2D 数据集树）。
- `src/app/panels/columns/Column3DAnalysis.hpp/.cpp` — 三维分析栏（对象→三维体→切片 树 + 两个右键菜单）。
- `src/app/DatasetDimension.hpp/.cpp` — 纯函数 `splitByDimension(...)`（可单测）。
- `tests/app/test_dataset_dimension.cpp` — 维度过滤单测。
**修改：**
- `src/app/main.cpp` — `buildWorkbench`：删三浮层(393-556)/分段切换(380-389,832-843)/showLayerPanel(804-827)/相关 connect；改挂 ColumnDrawer；接信号；rename vtkDock；bump dockState 版本；接维度过滤；全屏按钮。
- `src/app/Glyphs.hpp/.cpp` — 加 `Glyph::Fullscreen` + SVG。
- `src/app/CMakeLists.txt` — 加新源文件。
- `tests/CMakeLists.txt`（或对应）— 加 test_dataset_dimension。
---
## Task 1: 加 Fullscreen 图标 [UI]
**Files:**
- Modify: `src/app/Glyphs.hpp:15-35`（Glyph 枚举）
- Modify: `src/app/Glyphs.cpp`（SVG path 映射，参照现有 case）
- [ ] **Step 1: 在 Glyph 枚举加 Fullscreen**
`src/app/Glyphs.hpp`，在 `Collapse,` 之后加：
```cpp
Collapse, // 折叠（双箭头）
Fullscreen, // 全屏 / 最大化
```
- [ ] **Step 2: 在 Glyphs.cpp 的 svg 映射加 case**
找到 `makeGlyph`/svg path 的 `switch`（参照 `case Glyph::Collapse:`），加：
```cpp
case Glyph::Fullscreen:
return QStringLiteral("<path d='M8 3H5a2 2 0 0 0-2 2v3m13-5h3a2 2 0 0 1 2 2v3"
"M21 16v3a2 2 0 0 1-2 2h-3M8 21H5a2 2 0 0 1-2-2v-3'/>");
```
（若已有 restore/缩小语义图标可复用，但需一个独立 Fullscreen 项。）
- [ ] **Step 3: 编译**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat app"`
Expected: 编译通过（exe 重新生成）。
- [ ] **Step 4: 提交**
```bash
git add src/app/Glyphs.hpp src/app/Glyphs.cpp
git commit -m "feat(vtk): 加 Glyph::Fullscreen 图标(三栏重构全屏按钮用)"
```
---
## Task 2: 维度过滤纯函数 [逻辑]
把"DsRow 列表 → 按维度分三组"抽成可单测纯函数。`dimensionOf` 已在 `I3dSceneRepository`（接口），这里做的是**列表分流**。
**Files:**
- Create: `src/app/DatasetDimension.hpp`
- Create: `src/app/DatasetDimension.cpp`
- Test: `tests/app/test_dataset_dimension.cpp`
- Modify: `src/app/CMakeLists.txt`、`tests/CMakeLists.txt`
- [ ] **Step 1: 写失败测试**
`tests/app/test_dataset_dimension.cpp`：
```cpp
#include <gtest/gtest.h>
#include "app/DatasetDimension.hpp"
#include "data/repo/RepoTypes.hpp"
using geopro::data::DsRow;
using geopro::app::splitByDimension;
using geopro::app::DimBuckets;
static DsRow row(const char* id, const char* ddCode) {
DsRow r; r.id = id; r.ddCode = ddCode; return r;
}
TEST(DatasetDimension, SplitsByDdCode) {
std::vector<DsRow> in{
row("a", "dd_section"), // 3D
row("b", "dd_voxel"), // 3D
row("c", "dd_trajectory_data"), // 2D
row("d", "dd_slice"), // Analysis
row("e", "dd_unknownxyz"), // Other → 不入任何栏
};
DimBuckets b = splitByDimension(in);
ASSERT_EQ(b.dim3D.size(), 2u);
EXPECT_EQ(b.dim3D[0].id, "a");
EXPECT_EQ(b.dim3D[1].id, "b");
ASSERT_EQ(b.dim2D.size(), 1u);
EXPECT_EQ(b.dim2D[0].id, "c");
ASSERT_EQ(b.analysis.size(), 1u);
EXPECT_EQ(b.analysis[0].id, "d");
}
TEST(DatasetDimension, EmptyInput) {
DimBuckets b = splitByDimension({});
EXPECT_TRUE(b.dim3D.empty());
EXPECT_TRUE(b.dim2D.empty());
EXPECT_TRUE(b.analysis.empty());
}
```
- [ ] **Step 2: 跑测试确认失败**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat test"`
Expected: FAIL（`DatasetDimension.hpp` 不存在 / 链接失败）。
- [ ] **Step 3: 写实现**
`src/app/DatasetDimension.hpp`：
```cpp
#pragma once
#include <vector>
#include "data/repo/RepoTypes.hpp"
namespace geopro::app {
struct DimBuckets {
std::vector<geopro::data::DsRow> dim3D;
std::vector<geopro::data::DsRow> dim2D;
std::vector<geopro::data::DsRow> analysis;
};
// 按 ddCode 把 ds 分流到 三维数据集 / 二维数据集 / 三维分析 三栏。
// Other 维度不入任何栏（保留 parentId 顺序，调用方可直接喂 populateDatasetList）。
DimBuckets splitByDimension(const std::vector<geopro::data::DsRow>& rows);
} // namespace geopro::app
```
`src/app/DatasetDimension.cpp`：
```cpp
#include "app/DatasetDimension.hpp"
namespace geopro::app {
namespace {
// 与 LocalSample3dRepository::dimensionOf 同一映射（spec §6.1）。
// 抽到此处以便纯函数单测；将来后端返 dimension 字段时此函数改读字段即可。
enum class Dim { D3, D2, Analysis, Other };
Dim dimOf(const std::string& c) {
if (c == "dd_voxel" || c == "dd_Structual3D" || c == "dd_Property3D" ||
c == "dd_section" || c == "dd_inversion_data")
return Dim::D3;
if (c == "dd_slice") return Dim::Analysis;
if (c == "dd_trajectory_data") return Dim::D2;
return Dim::Other;
}
} // namespace
DimBuckets splitByDimension(const std::vector<geopro::data::DsRow>& rows) {
DimBuckets b;
for (const auto& r : rows) {
switch (dimOf(r.ddCode)) {
case Dim::D3: b.dim3D.push_back(r); break;
case Dim::D2: b.dim2D.push_back(r); break;
case Dim::Analysis: b.analysis.push_back(r); break;
case Dim::Other: break;
}
}
return b;
}
} // namespace geopro::app
```
> 注：`dimensionOf` 同时存在于 `LocalSample3dRepository`（渲染编排用）。此处复制映射是**有意**——纯函数便于单测、且与"将来后端返 dimension 字段"解耦。后续若收敛为单一真源，再让本函数调用注入的 repo。落地时若 reviewer 要求单一真源，可改签名 `splitByDimension(rows, const I3dSceneRepository&)`，本期按纯函数。
- [ ] **Step 4: 注册到 CMake**
`src/app/CMakeLists.txt`：把 `DatasetDimension.cpp` 加入 app 目标源列表（仿照同目录 .cpp 的加法）。
`tests/CMakeLists.txt`（或 tests/app）：把 `test_dataset_dimension.cpp` 加入测试目标（仿照 `test_3d_repo` 的注册）。
- [ ] **Step 5: 跑测试确认通过**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat test"`
Expected: `DatasetDimension.*` 2 项 PASS；总数 ≥ 223/223。
- [ ] **Step 6: 提交**
```bash
git add src/app/DatasetDimension.hpp src/app/DatasetDimension.cpp tests/app/test_dataset_dimension.cpp src/app/CMakeLists.txt tests/CMakeLists.txt
git commit -m "feat(vtk): 维度过滤纯函数 splitByDimension + 单测"
```
---
## Task 3: 三维数据集栏 widget [UI]
独立 widget：4 工具条栏位（坐标轴设置 / 水平垂直比例 / 快捷视图 / 缩放）+ 数据集树。只发信号。控件创建可**搬运** `main.cpp:433-516`（axisBar）的 combo/slider/button 构造与样式，重排成 4 分组（参照原型 `docs/superpowers/mockups/2026-06-16-three-column-layout.html` 的 `toolbar3D`）。
**Files:**
- Create: `src/app/panels/columns/Column3DDataset.hpp/.cpp`
- Modify: `src/app/CMakeLists.txt`
- [ ] **Step 1: 写头文件（信号 API）**
`src/app/panels/columns/Column3DDataset.hpp`：
```cpp
#pragma once
#include <QWidget>
#include <QStringList>
#include <vector>
#include "controller/I3dSceneView.hpp" // AxesMode/AxesUnit/ViewDir
#include "data/repo/RepoTypes.hpp"
class QTreeWidget;
namespace geopro::app {
// 三维数据集栏：坐标轴设置 + 水平/垂直比例 + 快捷视图 + 缩放 + 3D 数据集列表。
class Column3DDataset : public QWidget {
Q_OBJECT
public:
explicit Column3DDataset(QWidget* parent = nullptr);
// 用 3D 维度的 ds 填充列表（调用 populateDatasetList）。
void setDatasets(const std::vector<geopro::data::DsRow>& rows);
signals:
void axesModeChanged(geopro::controller::AxesMode mode);
void axesUnitChanged(geopro::controller::AxesUnit unit);
void verticalExaggerationChanged(double ve);
void viewRequested(geopro::controller::ViewDir dir);
void zoomInRequested();
void zoomOutRequested();
void fitRequested();
void oPointClicked(); // O点位置按钮（本期弹框留 stub）
void fontClicked(); // 字体按钮（本期 stub）
void checkedDatasetsChanged(const QStringList& dsIds); // 列表勾选变化
private:
QTreeWidget* list_ = nullptr;
};
} // namespace geopro::app
```
- [ ] **Step 2: 写实现（构造 4 分组 + 列表）**
`src/app/panels/columns/Column3DDataset.cpp`：用 `QVBoxLayout` 堆 4 个分组 `QGroupBox`/`QFrame`（标题 + 表单行）+ `QTreeWidget` 列表。控件构造照搬 `main.cpp:464-500`（axesModeCombo/axesUnitCombo/veSlider/btnFront..btnFit），样式用 `applyTokenizedStyleSheet` 照搬 `main.cpp:437-457`。各控件 `connect` 到本类 `emit ...`。要点（完整骨架）：
```cpp
#include "app/panels/columns/Column3DDataset.hpp"
#include <QVBoxLayout>
#include <QHBoxLayout>
#include <QFormLayout>
#include <QComboBox>
#include <QSlider>
#include <QPushButton>
#include <QLabel>
#include <QTreeWidget>
#include "app/Theme.hpp"
#include "app/panels/DatasetListPanel.hpp" // populateDatasetList
using geopro::controller::AxesMode;
using geopro::controller::AxesUnit;
using geopro::controller::ViewDir;
namespace geopro::app {
Column3DDataset::Column3DDataset(QWidget* parent) : QWidget(parent) {
auto* root = new QVBoxLayout(this);
root->setContentsMargins(space::kMd, space::kMd, space::kMd, space::kMd);
root->setSpacing(space::kMd);
// —— 坐标轴设置 组：显示方式▾ / O点位置(按钮) / 刻度▾ / 字体(按钮) ——
{
auto* form = new QFormLayout();
auto* mode = new QComboBox();
mode->addItem(QStringLiteral("标准"), static_cast<int>(AxesMode::Standard));
mode->addItem(QStringLiteral("三维立体"), static_cast<int>(AxesMode::Stereo));
mode->addItem(QStringLiteral("不显示"), static_cast<int>(AxesMode::None));
connect(mode, qOverload<int>(&QComboBox::currentIndexChanged), this,
[this, mode](int){ emit axesModeChanged(static_cast<AxesMode>(mode->currentData().toInt())); });
auto* oPoint = new QPushButton(QStringLiteral("设置…"));
connect(oPoint, &QPushButton::clicked, this, &Column3DDataset::oPointClicked);
auto* unit = new QComboBox();
unit->addItem(QStringLiteral("无刻度"), static_cast<int>(AxesUnit::None));
unit->addItem(QStringLiteral("米"), static_cast<int>(AxesUnit::Meter));
unit->addItem(QStringLiteral("英尺"), static_cast<int>(AxesUnit::Feet));
unit->addItem(QStringLiteral("经纬度"), static_cast<int>(AxesUnit::LatLon));
unit->setCurrentIndex(1);
connect(unit, qOverload<int>(&QComboBox::currentIndexChanged), this,
[this, unit](int){ emit axesUnitChanged(static_cast<AxesUnit>(unit->currentData().toInt())); });
auto* font = new QPushButton(QStringLiteral("设置…"));
connect(font, &QPushButton::clicked, this, &Column3DDataset::fontClicked);
form->addRow(QStringLiteral("显示方式"), mode);
form->addRow(QStringLiteral("O点位置"), oPoint);
form->addRow(QStringLiteral("刻度"), unit);
form->addRow(QStringLiteral("字体"), font);
root->addWidget(new QLabel(QStringLiteral("坐标轴设置")));
root->addLayout(form);
}
// —— 水平/垂直比例 组：单个滑块 + 数值 ——
{
auto* row = new QHBoxLayout();
auto* slider = new QSlider(Qt::Horizontal);
slider->setMinimum(1); slider->setMaximum(10); slider->setValue(2);
auto* val = new QLabel(QStringLiteral("2.0×"));
connect(slider, &QSlider::valueChanged, this, [this, val](int v){
val->setText(QStringLiteral("%1.0×").arg(v));
emit verticalExaggerationChanged(static_cast<double>(v));
});
row->addWidget(slider, 1); row->addWidget(val);
root->addWidget(new QLabel(QStringLiteral("水平/垂直比例")));
root->addLayout(row);
}
// —— 快捷视图 组：前/后/左/右/上/下 ——
{
auto* row = new QHBoxLayout();
struct V { const char* t; ViewDir d; };
for (V v : { V{"前",ViewDir::Front}, V{"后",ViewDir::Back}, V{"左",ViewDir::Left},
V{"右",ViewDir::Right}, V{"上",ViewDir::Top}, V{"下",ViewDir::Bottom} }) {
auto* b = new QPushButton(QString::fromUtf8(v.t));
ViewDir d = v.d;
connect(b, &QPushButton::clicked, this, [this, d]{ emit viewRequested(d); });
row->addWidget(b);
}
root->addWidget(new QLabel(QStringLiteral("快捷视图")));
root->addLayout(row);
}
// —— 缩放 组：放大/缩小/适配 ——
{
auto* row = new QHBoxLayout();
auto* in = new QPushButton(QStringLiteral("放大"));
auto* out = new QPushButton(QStringLiteral("缩小"));
auto* fit = new QPushButton(QStringLiteral("适配"));
connect(in, &QPushButton::clicked, this, &Column3DDataset::zoomInRequested);
connect(out, &QPushButton::clicked, this, &Column3DDataset::zoomOutRequested);
connect(fit, &QPushButton::clicked, this, &Column3DDataset::fitRequested);
row->addWidget(in); row->addWidget(out); row->addWidget(fit);
root->addWidget(new QLabel(QStringLiteral("缩放")));
root->addLayout(row);
}
// —— 数据集列表（3D 维度）——
list_ = new QTreeWidget();
list_->setHeaderHidden(true);
list_->setRootIsDecorated(true);
applyDatasetCardDelegate(list_);
connect(list_, &QTreeWidget::itemChanged, this, [this](QTreeWidgetItem*, int){
QStringList ids;
for (QTreeWidgetItemIterator it(list_); *it; ++it)
if ((*it)->checkState(0) == Qt::Checked)
ids << (*it)->data(0, /*kDsIdRole*/ Qt::UserRole + 1).toString();
emit checkedDatasetsChanged(ids);
});
root->addWidget(list_, 1);
}
void Column3DDataset::setDatasets(const std::vector<geopro::data::DsRow>& rows) {
populateDatasetList(list_, rows, /*append=*/false);
// 列表项需可勾选：populateDatasetList 后给每项加 Qt::ItemIsUserCheckable + Unchecked。
for (QTreeWidgetItemIterator it(list_); *it; ++it) {
(*it)->setFlags((*it)->flags() | Qt::ItemIsUserCheckable);
if ((*it)->checkState(0) == Qt::Unchecked || (*it)->checkState(0) == Qt::Checked) {}
else (*it)->setCheckState(0, Qt::Unchecked);
}
}
} // namespace geopro::app
```
> 注 1：`kDsIdRole` 的真实值见 `src/app/panels/DatasetListPanel.cpp`（`Qt::UserRole+? `）。落地时 include 该常量或用其公开定义，勿硬编码 `UserRole+1`——读 DatasetListPanel.hpp/.cpp 取真实 role 常量。
> 注 2：`populateDatasetList` 生成的项默认不可勾选；本栏需勾选渲染，故 setDatasets 后补 `ItemIsUserCheckable` + `Unchecked`（见上）。
> 注 3：分组标题/表单样式照原型；可用 `applyTokenizedStyleSheet` 套深色令牌（搬 `main.cpp:437-457`）。
- [ ] **Step 3: 注册 CMake + 编译**
`src/app/CMakeLists.txt` 加 `panels/columns/Column3DDataset.cpp`。
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat app"`
Expected: 编译通过。
- [ ] **Step 4: 提交**
```bash
git add src/app/panels/columns/Column3DDataset.hpp src/app/panels/columns/Column3DDataset.cpp src/app/CMakeLists.txt
git commit -m "feat(vtk): 三维数据集栏 widget(4工具条栏位+3D数据集列表,只发信号)"
```
---
## Task 4: 二维数据集栏 widget [UI]
**Files:**
- Create: `src/app/panels/columns/Column2DDataset.hpp/.cpp`
- Modify: `src/app/CMakeLists.txt`
- [ ] **Step 1: 写头文件**
`Column2DDataset.hpp`：
```cpp
#pragma once
#include <QWidget>
#include <QStringList>
#include <vector>
#include "data/repo/RepoTypes.hpp"
class QTreeWidget;
namespace geopro::app {
class Column2DDataset : public QWidget {
Q_OBJECT
public:
explicit Column2DDataset(QWidget* parent = nullptr);
void setDatasets(const std::vector<geopro::data::DsRow>& rows);
signals:
void basemapChanged(int index); // 0 天地图 / 1 Google / 2 隐藏
void view2DModeChanged(int index); // 0 关闭 /1 Z=0 /2 顶部 /3 底部 /4 自定义
void customZChanged(double z); // 世界绝对高程(米),向上为正
void checkedDatasetsChanged(const QStringList& dsIds);
private:
QTreeWidget* list_ = nullptr;
};
}
```
- [ ] **Step 2: 写实现**
`Column2DDataset.cpp`：地图 combo（天地图/Google Map/隐藏）→ `basemapChanged`；2D视图 combo（关闭/Z=0/顶部/底部/自定义）→ `view2DModeChanged`，选"自定义"时显一个 `QDoubleSpinBox`（范围 ±1e6，后缀 " m"）→ `customZChanged`；`QTreeWidget` 列表同 Task3（可勾选 + setDatasets 用 populateDatasetList）。骨架同 Column3DDataset 模式（QFormLayout 两组 + 列表），此处不赘述控件 connect（与 Task3 同形）。自定义 Z 输入框默认 `setVisible(false)`，在 `view2DModeChanged` 槽里 `zEdit->setVisible(index==4)`。
- [ ] **Step 3: 注册 CMake + 编译**
`src/app/CMakeLists.txt` 加 `panels/columns/Column2DDataset.cpp`。
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat app"`
Expected: 编译通过。
- [ ] **Step 4: 提交**
```bash
git add src/app/panels/columns/Column2DDataset.hpp src/app/panels/columns/Column2DDataset.cpp src/app/CMakeLists.txt
git commit -m "feat(vtk): 二维数据集栏 widget(地图/2D视图+自定义Z输入+2D列表)"
```
---
## Task 5: 三维分析栏 widget + 两个右键菜单 [UI]
**Files:**
- Create: `src/app/panels/columns/Column3DAnalysis.hpp/.cpp`
- Modify: `src/app/CMakeLists.txt`
- [ ] **Step 1: 写头文件**
`Column3DAnalysis.hpp`：
```cpp
#pragma once
#include <QWidget>
#include <QStringList>
#include <vector>
#include "data/repo/RepoTypes.hpp"
#include "render/interact/SlicePlaneMath.hpp" // SliceAxis
class QTreeWidget;
class QTreeWidgetItem;
namespace geopro::app {
// 三维分析栏：对象→三维体模型→切片 树 + 三维体/切片两套右键菜单。
class Column3DAnalysis : public QWidget {
Q_OBJECT
public:
explicit Column3DAnalysis(QWidget* parent = nullptr);
void setDatasets(const std::vector<geopro::data::DsRow>& rows); // Analysis 维度(三维体/切片)
signals:
// 三维体右键：切片▸(上下/前后/左右/任意)
void sliceRequested(geopro::render::interact::SliceAxis axis);
void colorScaleRequested(const QString& dsId); // 三维体&切片(本期 stub)
void visibilityToggled(const QString& dsId); // 显示/隐藏
void detailRequested(const QString& dsId, const QString& ddCode, const QString& name);
// 切片右键(本期 stub,菜单可见但发信号给上层提示"待实现")
void sliceSaveRequested(const QString& dsId);
void sliceSaveAsRequested(const QString& dsId);
void sliceExportRequested(const QString& dsId);
void sliceDeleteRequested(const QString& dsId);
void checkedItemsChanged(const QStringList& dsIds);
private:
void onContextMenu(const QPoint& pos);
QTreeWidget* tree_ = nullptr;
};
}
```
- [ ] **Step 2: 写实现（树 + 右键分派）**
`Column3DAnalysis.cpp`：`tree_` 设 `setContextMenuPolicy(Qt::CustomContextMenu)`，connect `customContextMenuRequested` → `onContextMenu`。节点类型用 `item->data(0, role)` 区分"三维体" vs "切片"（建树时按 ddCode：`dd_voxel/dd_Structual3D/dd_Property3D/dd_section` 为三维体；`dd_slice` 为切片）。右键分派（核心）：
```cpp
void Column3DAnalysis::onContextMenu(const QPoint& pos) {
QTreeWidgetItem* it = tree_->itemAt(pos);
if (!it) return;
const QString dsId = it->data(0, kDsIdRole).toString();
const QString ddCode = it->data(0, kDsDdCodeRole).toString();
const QString name = it->data(0, kDsNameRole).toString();
const bool isSlice = (ddCode == QStringLiteral("dd_slice"));
QMenu menu(this);
if (!isSlice) {
// 三维体数据集：切片▸(上下/前后/左右/任意) / 色阶 / 显示·隐藏 / 数据详情
QMenu* sub = menu.addMenu(QStringLiteral("切片"));
using SA = geopro::render::interact::SliceAxis;
sub->addAction(QStringLiteral("上下"), this, [this]{ emit sliceRequested(SA::UpDown); });
sub->addAction(QStringLiteral("前后"), this, [this]{ emit sliceRequested(SA::FrontBack); });
sub->addAction(QStringLiteral("左右"), this, [this]{ emit sliceRequested(SA::LeftRight); });
sub->addAction(QStringLiteral("任意"), this, [this]{ emit sliceRequested(SA::Oblique); });
menu.addAction(QStringLiteral("色阶"), this, [this, dsId]{ emit colorScaleRequested(dsId); });
menu.addAction(QStringLiteral("显示 / 隐藏"), this, [this, dsId]{ emit visibilityToggled(dsId); });
menu.addAction(QStringLiteral("数据详情"), this, [this, dsId, ddCode, name]{ emit detailRequested(dsId, ddCode, name); });
} else {
// 切片数据集：保存/保存为/导出/删除 — 色阶/显示·隐藏/数据详情
menu.addAction(QStringLiteral("保存"), this, [this, dsId]{ emit sliceSaveRequested(dsId); });
menu.addAction(QStringLiteral("保存为"), this, [this, dsId]{ emit sliceSaveAsRequested(dsId); });
menu.addAction(QStringLiteral("导出"), this, [this, dsId]{ emit sliceExportRequested(dsId); });
menu.addAction(QStringLiteral("删除"), this, [this, dsId]{ emit sliceDeleteRequested(dsId); });
menu.addSeparator();
menu.addAction(QStringLiteral("色阶"), this, [this, dsId]{ emit colorScaleRequested(dsId); });
menu.addAction(QStringLiteral("显示 / 隐藏"), this, [this, dsId]{ emit visibilityToggled(dsId); });
menu.addAction(QStringLiteral("数据详情"), this, [this, dsId, ddCode, name]{ emit detailRequested(dsId, ddCode, name); });
}
menu.exec(tree_->viewport()->mapToGlobal(pos));
}
```
> `kDsIdRole/kDsDdCodeRole/kDsNameRole`：用 DatasetListPanel 的公开 role 常量（读 DatasetListPanel.hpp）。树构建：用 `populateDatasetList(tree_, analysisRows, false)` 起步（它已按 parentId 建树：切片挂三维体下），再补可勾选标志（同 Task3 注 2）。
- [ ] **Step 3: 注册 CMake + 编译**
`src/app/CMakeLists.txt` 加 `panels/columns/Column3DAnalysis.cpp`。
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat app"`
Expected: 编译通过。
- [ ] **Step 4: 提交**
```bash
git add src/app/panels/columns/Column3DAnalysis.hpp src/app/panels/columns/Column3DAnalysis.cpp src/app/CMakeLists.txt
git commit -m "feat(vtk): 三维分析栏 widget(对象→三维体→切片树+两套右键菜单)"
```
---
## Task 6: 抽屉容器 ColumnDrawer [UI]
**Files:**
- Create: `src/app/panels/columns/ColumnDrawer.hpp/.cpp`
- Modify: `src/app/CMakeLists.txt`
- [ ] **Step 1: 写头文件**
`ColumnDrawer.hpp`：
```cpp
#pragma once
#include <QWidget>
namespace geopro::app {
class Column3DDataset; class Column2DDataset; class Column3DAnalysis;
// VTK视图左侧内嵌抽屉：三 tab(三维数据集/二维数据集/三维分析) + 折叠开关。
class ColumnDrawer : public QWidget {
Q_OBJECT
public:
explicit ColumnDrawer(QWidget* parent = nullptr);
Column3DDataset* col3D() const { return col3D_; }
Column2DDataset* col2D() const { return col2D_; }
Column3DAnalysis* colAnalysis() const { return colAnalysis_; }
public slots:
void toggleCollapsed(); // 折叠/展开(宽度切换)
private:
Column3DDataset* col3D_ = nullptr;
Column2DDataset* col2D_ = nullptr;
Column3DAnalysis* colAnalysis_ = nullptr;
QWidget* body_ = nullptr; // QTabWidget 容器,折叠时隐藏
bool collapsed_ = false;
};
}
```
- [ ] **Step 2: 写实现**
`QTabWidget` 三页（三维数据集/二维数据集/三维分析）放入 `body_`；旁边一个细长折叠按钮（◀/▶，调 `toggleCollapsed`）。`toggleCollapsed`：`collapsed_ = !collapsed_; body_->setVisible(!collapsed_);` 并切按钮箭头。固定展开宽度约 300（`setFixedWidth` 或 `setMaximumWidth`，折叠时设 0/隐藏 body）。
- [ ] **Step 3: 注册 CMake + 编译**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat app"`
Expected: 编译通过。
- [ ] **Step 4: 提交**
```bash
git add src/app/panels/columns/ColumnDrawer.hpp src/app/panels/columns/ColumnDrawer.cpp src/app/CMakeLists.txt
git commit -m "feat(vtk): ColumnDrawer 抽屉容器(三tab+折叠)"
```
---
## Task 7: main.cpp 装配——删三浮层/切换，挂抽屉，接信号，改名 [UI]
这是核心整合。**一次性**替换，因 axisBar/sliceBar/layerPanel 的 connect 互相牵连，无法逐控件保持编译。改完一次编绿。
**Files:**
- Modify: `src/app/main.cpp`（多处，见下）
- [ ] **Step 1: 删旧 UI 构造**
删除：
- `layerPanel` 块（393-429）、`axisBar` 块（433-516）、`RightTopAnchor`（520）、`sliceBar` 块（525-556）、`BottomLeftAnchor`（556）。
- 分段切换：`buildSegmentedHeader`/`viewHeader`/`act2D`/`act3D`（380-389）改为**简单标题头**（见 Step 3）。
- `showLayerPanel` lambda（804-827）及其所有调用。
- `updateSliceButtons`（559-569）、`addSlice`（572-575）、sliceBar 按钮 connect（576-590）。
- 旧 connect：layer checkboxes（846-851）、axisBar 控件（857-889）、act2D/act3D（832-843）。
- 保留 `interactionMgr` 创建（309-321）、`emptyState`、`sceneCtrl`、`vtkWidget`。
- [ ] **Step 2: 建 ColumnDrawer + 改 centerWidget 布局为 [抽屉 | GL]**
在 `centerWidget` 构造处（374 一带）改为：顶部一个标题头（Step 3），下面一个 `QHBoxLayout` 装 `drawer` + `vtkWidget`：
```cpp
#include "app/panels/columns/ColumnDrawer.hpp"
#include "app/panels/columns/Column3DDataset.hpp"
#include "app/panels/columns/Column2DDataset.hpp"
#include "app/panels/columns/Column3DAnalysis.hpp"
// ...
auto* drawer = new geopro::app::ColumnDrawer(centerWidget);
auto* viewRow = new QHBoxLayout();
viewRow->setContentsMargins(0,0,0,0); viewRow->setSpacing(0);
viewRow->addWidget(drawer); // 左侧抽屉
viewRow->addWidget(vtkWidget, 1); // 右侧 GL 画布
// centerLayout: [标题头] + [viewRow]
centerLayout->addWidget(viewHeader); // Step 3 的新标题头
centerLayout->addLayout(viewRow, 1);
```
> 设计：抽屉是 vtkWidget 的**布局兄弟**（非 GL 子浮层），规避 `main.cpp:397-399` 注释提到的原生 GL 浮层圆角/底色伪影。视觉等同原型（栏在左、画布在右）。
- [ ] **Step 3: 新标题头(含全屏按钮,Task 8 接线)**
替换分段头为 `buildPanelHeader`：
```cpp
auto* viewHeader = geopro::app::buildPanelHeader(
geopro::app::Glyph::Map, QStringLiteral("VTK视图"),
{{geopro::app::Glyph::Fullscreen, QStringLiteral("全屏")}});
```
（全屏按钮的 connect 在 Task 8。）
- [ ] **Step 4: 接三维数据集栏信号 → VtkSceneController**
```cpp
auto* c3 = drawer->col3D();
QObject::connect(c3, &geopro::app::Column3DDataset::axesModeChanged, sceneCtrl, &VtkSceneController::setAxesMode);
QObject::connect(c3, &geopro::app::Column3DDataset::axesUnitChanged, sceneCtrl, &VtkSceneController::setAxesUnit);
QObject::connect(c3, &geopro::app::Column3DDataset::verticalExaggerationChanged, sceneCtrl, &VtkSceneController::setVerticalExaggeration);
QObject::connect(c3, &geopro::app::Column3DDataset::viewRequested, sceneCtrl, &VtkSceneController::applyView);
QObject::connect(c3, &geopro::app::Column3DDataset::zoomInRequested, sceneCtrl, &VtkSceneController::zoomIn);
QObject::connect(c3, &geopro::app::Column3DDataset::zoomOutRequested, sceneCtrl, &VtkSceneController::zoomOut);
QObject::connect(c3, &geopro::app::Column3DDataset::fitRequested, sceneCtrl, &VtkSceneController::fit);
// O点位置/字体本期 stub：connect 到一个提示(可空 lambda)。
```
> 类型匹配：`Column3DDataset` 的枚举即 `geopro::controller::AxesMode/AxesUnit/ViewDir`（同 I3dSceneView.hpp），与 `setAxesMode/setAxesUnit/applyView` 形参一致，可直接连。
- [ ] **Step 5: 接三维分析栏「切片」→ InteractionManager**
```cpp
auto* ca = drawer->colAnalysis();
QObject::connect(ca, &geopro::app::Column3DAnalysis::sliceRequested, vtkWidget,
[interactionMgr](geopro::render::interact::SliceAxis axis){
interactionMgr->addSlice(axis);
});
QObject::connect(ca, &geopro::app::Column3DAnalysis::detailRequested, &detailCtrl,
[&detailCtrl](const QString& dsId, const QString& ddCode, const QString& name){
detailCtrl.openDataset(dsId, ddCode, name);
});
// colorScale/visibility/slice CRUD 本期 stub：connect 到提示 lambda（如 statusBar 显"待实现"）。
```
- [ ] **Step 6: 编译（维度过滤接线在 Task 9，此处先空列表）**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat rebuild"`
Expected: 全量编译通过，exe 刷新。
- [ ] **Step 7: 用户实测清单**（用户在其终端跑）
- [ ] app 启动，中央改名「VTK视图」，左侧出现三 tab 抽屉。
- [ ] 旧「二维地图/三维视图」分段按钮已消失；左上/右上/左下三浮层消失。
- [ ] 抽屉折叠开关：点 ◀ 收起、画布变宽；点 ▶ 展开。
- [ ] 三维数据集栏工具条：坐标轴下拉/比例滑块/快捷视图 6 钮/缩放 3 钮可点（功能接通后续 Task 9 验，但点击不崩）。
- [ ] 三维分析栏右键三维体 → 出「切片▸(上下/前后/左右/任意)/色阶/显隐/详情」；右键切片 → 出「保存/保存为/导出/删除/色阶/显隐/详情」。
- [ ] **Step 8: 提交**
```bash
git add src/app/main.cpp
git commit -m "refactor(vtk): 删三浮层+分段切换,改挂三栏抽屉,接信号,中央改名VTK视图"
```
---
## Task 8: dockState 版本 bump + 全屏按钮 [UI]
**Files:**
- Modify: `src/app/main.cpp`（dockState 键 1428-1442；全屏 connect）
- [ ] **Step 1: bump dock 布局版本**
`main.cpp:1430` 与 1440：把 `ui/dockState_v2` 两处改为 `ui/dockState_v3`（dock 名/结构已变，旧布局须丢弃回落默认排布；遵循 1428-1430 注释）。
- [ ] **Step 2: 全屏切换实现**
全屏 = 隐藏其余 dock，仅留目标 dock 充满 dock 区；再点还原。用 ADS `CDockWidget::toggleView(bool)`。加一个 lambda + 状态：
```cpp
// 全屏：隐藏其余 dock,仅留 target;再点还原。docks 列表见 hideDockTitleBars(733-740)。
bool* vtkFs = new bool(false); // 或用 QObject property,避免裸 new:可挂到 window
auto makeFullscreen = [dockManager](ads::CDockWidget* target, const QList<ads::CDockWidget*>& others, bool on){
for (ads::CDockWidget* d : others) d->toggleView(!on); // on→隐藏其余
Q_UNUSED(target);
};
```
> 落地建议：用 `QToolButton::setCheckable(true)` 的全屏按钮 + `toggled(bool)` 切换；状态存按钮 checked，免裸指针。`others` = 除目标外的全部 dock（vtkDock 全屏时 others={leftDock,datasetDock,detailDock,rightDock,propDock}；detailDock 全屏时 others={其余}）。
- [ ] **Step 3: 接全屏按钮**
用 `findHeaderAction(box, Glyph::Fullscreen)`（main.cpp:1016-1020 的 helper）取到 VTK视图标题头与 数据详情头里的全屏按钮，connect 到 `makeFullscreen`。VTK视图头是 Step3(Task7) 的 `viewHeader`；数据详情头是 `detailDock` 的 `wrapWithHeader`（654-663）——给它加 `{{Glyph::Fullscreen,"全屏"}}` action。
```cpp
// 数据详情头加全屏 action（修改 654-663 的 wrapWithHeader 调用，加 actions 参数）。
// 然后:
auto* vtkFsBtn = findHeaderAction(viewHeader, geopro::app::Glyph::Fullscreen);
auto* detFsBtn = findHeaderAction(detailHeaderBox, geopro::app::Glyph::Fullscreen);
// 各自 setCheckable(true) + connect(&QToolButton::toggled, ... makeFullscreen ...)
```
- [ ] **Step 4: 编译**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat rebuild"`
Expected: 编译通过。
- [ ] **Step 5: 用户实测清单**
- [ ] 点 VTK视图标题栏右侧全屏按钮 → VTK视图充满工作区（其余 dock 隐藏）；再点 → 还原。
- [ ] 点 数据详情标题栏全屏按钮 → 同理。
- [ ] 首次启动（旧布局丢弃）dock 排布为默认，无错位。
- [ ] **Step 6: 提交**
```bash
git add src/app/main.cpp
git commit -m "feat(vtk): dockState bump v3 + VTK视图/数据详情 全屏按钮(隐藏其余dock)"
```
---
## Task 9: 维度过滤接线——三栏数据集列表数据驱动 [UI+逻辑]
把"勾选对象 → 取 ds → 按维度分三栏"接通，替换 `main.cpp:891-899` 的 "grid1" 假实现。
**Files:**
- Modify: `src/app/main.cpp`
- [ ] **Step 1: 取勾选对象的 ds 行**
现状：`checkedTmsChanged(QStringList tmIds)` → 假 "grid1"。改为：用 `WorkbenchNavController`/`repo_.loadRowsAsync` 对每个勾选 TM 取 `DsRow`，汇总。`nav` 已有 `datasetsLoaded(tmObjectId, rows, total, append)` 信号（WorkbenchNavController.hpp:52）。**最简路径**：复用 nav 的取数，但 nav 现按"单击对象"取数（selectObject），勾选多 TM 需逐个取并合并。
实现：在 `checkedTmsChanged` 槽里，对每个 tmId 调 `nav.selectObject(tmId, 2)` 不合适（会刷左下列表）。改为直接调 repo：
```cpp
// 汇总所有勾选 TM 的 ds，按维度分三栏。projectRepo 是 IAsyncProjectRepository。
QObject::connect(objectTree, &geopro::app::ObjectTreePanel::checkedTmsChanged, &window,
[&projectRepo, drawer, sceneCtrl, emptyState, &window](const QStringList& tmIds){
emptyState->setVisible(tmIds.isEmpty());
auto acc = std::make_shared<std::vector<geopro::data::DsRow>>();
auto remaining = std::make_shared<int>(tmIds.size());
if (tmIds.isEmpty()) {
drawer->col3D()->setDatasets({});
drawer->col2D()->setDatasets({});
drawer->colAnalysis()->setDatasets({});
sceneCtrl->setCheckedDatasets({});
return;
}
for (const QString& tm : tmIds) {
// classifyType=3, pageNo=1, 大 pageSize 取整树(同 WorkbenchNavController kFetchAllPageSize)
geopro::data::NavRequest* req = projectRepo.loadRowsAsync(
currentProjectIdStdString, tm.toStdString(), /*parentConfType*/2, /*classifyType*/3, 1, 100000);
req->onDone = [acc, remaining, drawer](const geopro::data::DsPage& page){
acc->insert(acc->end(), page.rows.begin(), page.rows.end());
if (--(*remaining) == 0) {
geopro::app::DimBuckets b = geopro::app::splitByDimension(*acc);
drawer->col3D()->setDatasets(b.dim3D);
drawer->col2D()->setDatasets(b.dim2D);
drawer->colAnalysis()->setDatasets(b.analysis);
}
};
// req->onFail 同样 --remaining 并在归零时刷新(避免一个失败卡死)。
}
});
#include "app/DatasetDimension.hpp"
```
> 注：`NavRequest` 的回调字段真名见 `src/data/repo/IAsyncProjectRepository.hpp` / NavRequest 定义（onDone/onFail 或 done/failed）——落地按真实字段。`currentProjectIdStdString` 取当前项目 id（main.cpp 里已有项目 id 来源，搜 `currentProjectId`/`projectId`）。
- [ ] **Step 2: 勾选数据集 → 渲染**
三栏列表勾选 → `setCheckedDatasets`。汇总三栏勾选的 dsId：
```cpp
auto pushChecked = [drawer, sceneCtrl]{
QStringList ids;
// 收集三栏当前勾选(各栏暴露 checkedDatasetsChanged;此处也可各自直接连)
// 简化:各栏 checkedDatasetsChanged 直接 setCheckedDatasets(合并)。
};
QObject::connect(drawer->col3D(), &geopro::app::Column3DDataset::checkedDatasetsChanged,
sceneCtrl, &VtkSceneController::setCheckedDatasets);
// 若需三栏合并,改为聚合后再 setCheckedDatasets;本期可先只接 col3D(3D 渲染主路径)。
```
> 本期渲染主路径是 3D 数据集（帘面/体素/地形），故先接 `col3D` 的勾选 → `setCheckedDatasets`。2D/分析渲染随各自维度后续完善。
- [ ] **Step 3: 编译**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat rebuild"`
Expected: 编译通过。
- [ ] **Step 4: 用户实测清单**
- [ ] 勾选含 ds 的对象 → 三维数据集栏列表出现 3D 维度 ds（样本 "剖面网格数据1" dd_section）。
- [ ] 勾选三维数据集栏里的 ds → 中央渲染帘面（原 grid1 路径效果）。
- [ ] 取消全部勾选 → 三栏列表清空、中央清场、引导层 emptyState 显示。
- [ ] （样本数据若无 2D/切片 ds，2D/分析栏为空属正常；可后续在 LocalSample 加样本演示。）
- [ ] **Step 5: 提交**
```bash
git add src/app/main.cpp
git commit -m "feat(vtk): 三栏数据集列表按维度过滤数据驱动(替换grid1假实现)"
```
---
## Task 10: 全量回归 + 收尾 [逻辑]
- [ ] **Step 1: 全量 build + ctest**
Run: `cmd.exe /c "chcp 65001 >nul && cd /d D:\Git\lanbingtech\geopro && .\build.bat rebuild && .\build.bat test"`
Expected: 编译通过；ctest 全绿（≥ 223/223，含新 DatasetDimension.* 2 项）。
- [ ] **Step 2: 派 cpp-reviewer 审查本分支改动**
对 `src/app/panels/columns/*`、`DatasetDimension.*`、`main.cpp` diff 跑 cpp-reviewer，修 CRITICAL/HIGH（重点：裸 new/生命周期、信号槽断连、ADS toggleView 还原正确性、role 常量硬编码）。
- [ ] **Step 3: 对照 spec 验收**
逐条核对 `2026-06-16-vtk-3d-three-column-refactor-design.md` §0 IN 项全部落地、OUT 项为 stub/禁用。
- [ ] **Step 4: 用户最终实测**（完整走查实测清单 Task7/8/9）
- [ ] **Step 5: 提交收尾（如有修改）**
```bash
git add -A && git commit -m "chore(vtk): 三栏重构 review 修复 + 回归"
```
---
## Self-Review（写计划后自查）
**Spec 覆盖：**
- A1 三栏 → Task 3-7 ✅；单一 VTK视图/删切换/改名 → Task 7 ✅；三浮层收编 → Task 7 ✅；维度过滤列表 → Task 2+9 ✅；三维数据集 4 栏位 → Task 3 ✅；二维 地图/2D视图/自定义Z → Task 4 ✅；三维分析树+两右键菜单+切片接 SliceTool → Task 5+7 ✅；全屏 → Task 1+8 ✅；自定义Z绝对高程 → Task 4(spec 已记) ✅；dock 版本 bump → Task 8 ✅。
- OUT 项（CRUD/色阶/底图/异常体/详情/任务）→ stub 信号(Task 5)，不实现 ✅。
**占位符扫描：** 已用真实 API/行号；少数"读真实 role 常量/NavRequest 字段名"是**有意指向源文件**（避免硬编码错值），非 TODO。
**类型一致性：** `AxesMode/AxesUnit/ViewDir`(I3dSceneView.hpp) 跨 Task3/7 一致；`SliceAxis`(SlicePlaneMath.hpp) 跨 Task5/7 一致；`DsRow/DsPage/DimBuckets` 跨 Task2/3/9 一致；`splitByDimension` 签名 Task2 定义、Task9 使用一致。
**风险：** Task 9 的多 TM 异步汇总 + NavRequest 回调字段名是最大不确定点（落地前先读 IAsyncProjectRepository.hpp 确认）；全屏 toggleView 还原需保证 dock 顺序/可见性正确（Task8 用户实测把关）。

138
docs/superpowers/plans/2026-06-17-vtk-3d-volume-create-flow.md Normal file
View File

@ -0,0 +1,138 @@
# 实现计划：客户端「生成三维体」完整流程（#1）
- 日期：2026-06-17
- 分支：`feat/vtk-3d-view`
- 上位设计：`docs/superpowers/specs/2026-06-17-vtk-3d-volume-slice-anomaly-design.md`（§2.4 客户端创建、§6 拆解、§7 持久化策略）
- 决策：用户已拍板「完整生成三维体客户端流程」（非最小 mock）。
- 原则：缺后端端点 → 内存 mock，保持 `I3dSceneRepository` 接口可替换；客户端能做的先做。
## 0. 现状取证（file:line）
| 事实 | 证据 |
|---|---|
| 运行路径用 `Api3dRepository`（非 LocalSample） | `main.cpp:254` |
| `Api3dRepository::loadVolume` 是 stub | `Api3dRepository.cpp:57-60` |
| 控制器→loadVolume→addVolume 管线已接好，但 voxel 路径靠全局 `showVoxel_=false` 且无 UI 触发 | `VtkSceneController.cpp:70-89`、`VtkSceneController.hpp:70` |
| 取源散点最干净路径 | `dsRepo_.loadAsync("inversion.scatter", dsId)` → `core::ScatterPayload`（`ApiDatasetRepository.cpp:152-165`；散点含 projX/projY + z(hlist=高程) + v，`DatasetChartDto.cpp:39-46`） |
| 帘面/地形竖向 = +elevation（Z=+g.y） | 交接文档 §2；`CurtainActor.cpp` |
| LocalSample loadVolume 参考实现（散点→配准→GridSpec→IDW），但用 `-s.y` 深度且固定样本 | `LocalSample3dRepository.cpp:68-147` |
| 散点→GridSpec→IDW 在 LocalSample/Api 重复，已有 TODO 标记漂移风险 | `LocalSample3dRepository.cpp:31-37` |
| 数据集列表后端全量加载、每次勾选测线变化全量覆盖 | `main.cpp:626-665`；`DatasetListPanel.cpp:187-216`（append=false） |
| `DsRow` 字段 | `RepoTypes.hpp:10-15`（id/dsName/typeName/ddCode/parentId/...） |
| 维度分流 dd_voxel→Dim3D | `DatasetDimension.cpp:8-15`；`Api3dRepository::dimensionOf` |
| Column3DDataset 列表是 checkbox 勾选（渲染），无多选/右键 | `Column3DDataset.cpp:114-128` |
| col3D 信号接线 | `main.cpp:362-386` |
## 1. 数据模型：VolumeBuildParams（设计 §7.4）
新增 `src/data/repo/VolumeBuildParams.hpp`（贴近消费它的 `I3dSceneRepository`/`Api3dRepository`）：
```cpp
struct VolumeBuildParams {
std::vector<std::string> sourceDatasetIds; // 源数据集 id（≥1）
enum class Model { Idw, Kriging };
Model interpModel = Model::Idw;
double cellXY = 1.0, cellZ = 0.5, power = 2.0, maxDist = 4.0; // interpParams
std::string colorScaleId; // 取哪个源的色阶（默认首个源）
double vmin = 0.0, vmax = 0.0; // 派生（缓存）
struct Measure { long points = 0; double volume = 0.0; } measure; // 派生（缓存）
};
```
> **不冻结 gridSpec**（用户决策 2026-06-17）：gridSpec 每次从源散点**确定性重算**（IDW 确定 + 源锁定 → 结果必然一致），不存为"冻结锚点"。
> 切片/异常坐标的稳定性由**源 ds 锁定**不变式保证（见 §9），而非冻结派生网格。
> 若三维体变了 ⇒ 源 ds 被动过 ⇒ 旧 gridSpec 本身已失效，冻结只会掩盖问题。
## 2. 共享管线：core::algo（解决 TODO 漂移）
新增 `src/core/algo/VolumeBuilder.{hpp,cpp}`（纯 core，不碰 CRS）：
```cpp
struct BuiltVolume { core::ScalarVolume vol; core::GridSpec spec; double vmin, vmax; };
// 入参：世界局部米点集 + cell/power/maxDist。
// 包络→GridSpec(角点对齐, clampDim)→IDW→ScalarVolume→vmin/vmax(优先外部色阶 stops，否则实测)。
// 确定性：同点集同参数 → 同 GridSpec 同体（不需冻结，见计划 §1 决策）。
BuiltVolume buildVolume(const core::PointSet& pts, double cellXY, double cellZ,
double power, double maxDist);
```
- 把 `LocalSample3dRepository.cpp:95-137` 的「包络→GridSpec→IDW→vmin/vmax」逻辑提进来。
- `LocalSample3dRepository::loadVolume` 改为调用它（行为不变，回归保护）。
- `clampDim`/kMaxDim 一并移入。
## 3. Api3dRepository：体存储 + loadVolume + createVolume（已实现）
构造注入：`Api3dRepository(IAsyncDatasetRepository& dsRepo, std::shared_ptr<core::GeoLocalFrame> frame)`。
- **只需 frame**（与帘面/底图同一共享 shared_ptr，含 reanchor）；**不需 projectCrs/refElev**——因取源走 `loadSection` 的 `Grid`，其节点已带 lat/lon + 高程轴 g.y，无须 CRS 正变换。
内存 mock 存储（成员）：
```cpp
struct StoredVolume { VolumeBuildParams params; std::string name; std::optional<VolumeGrid> cachedGrid; };
std::map<std::string, StoredVolume> volumes_; // dsId → 体
int volumeCounter_ = 0;
```
新增公有方法（concrete，main.cpp 持具体指针调用）：
- `std::string createVolume(VolumeBuildParams params, const std::string& name)`：生成 `vol-N` dsId、存入 `volumes_`、返回 id（不立即插值；插值在首次 loadVolume 惰性做 + 缓存）。
- `std::vector<DsRow> volumeRows() const`：转 `DsRow{id, dsName=name, ddCode="dd_voxel", typeName="三维体"}`，供列表合并。
- `bool isVolumeDataset(const std::string& dsId) const`：`volumes_.count`。
`loadVolume(dsId)` 实现（异步 N 源扇出，**复用 loadSection 保证与帘面同系对齐**）：
1. 查 `volumes_[dsId]`；无 → onErr。
2. 有 `cachedGrid` → 直接 onOk（明细命中）。
3. 否则：对每个 sourceId 调 `this->loadSection(srcId)`（即 `inversion.grid` 路径），`shared_ptr<Agg>` 聚合 N 个回调（全到齐再继续；任一 failed → 整体 onErr 一次）。
4. `appendGridPoints`：对每个源 Grid 的**有限值**节点，按 CurtainActor 同口径定位 →
`frame.toLocal(g.lat[i], g.lon[i])` 作 (x,y)；**世界 Z = g.y[j]（高程）**；v = g.valueAt(i,j)。跳过 NaN 格（与帘面消隐一致）。
5. 取首个到达源的色阶定 vmin/vmax（否则 buildVolume 数据实测）。
6. `core::buildVolume(pts, cellXY/cellZ/power/maxDist)`（每次从源确定性重算 gridSpec）。
7. `cachedGrid` 缓存；onOk(VolumeGrid)。
> 契约：onOk/onErr 主线程回调。`DetailLoad::done` 在主线程发，扇出聚合用主线程共享 `Agg`（无锁）。
> 路径选择说明：弃用 `inversion.scatter` 端点（其 y=深度/z=高程语义是交接文档警告的坑）；
> 改复用已正确的 `loadSection`(`inversion.grid`)，与帘面**构造性对齐**，且免 CRS 正变换。
`I3dSceneRepository` 接口加纯虚 `virtual bool isVolumeDataset(const std::string& dsId) const = 0;`（LocalSample 恒 false）。
## 4. 控制器：按类型分流 curtain vs voxel
`VtkSceneController::addDatasetAsync`（`VtkSceneController.cpp:49-90`）改：
- `if (sceneRepo_.isVolumeDataset(dsId))` → 走 loadVolume/addVolume 路径；
- `else` → 走 loadSection/addCurtain 路径。
- 移除对全局 `showVoxel_`/`showCurtain_` 作为分流条件的依赖（保留成员或删，二者均不再 gating 单 ds 分流；图层开关语义后续再议）。
## 5. UI：Column3DDataset（源数据栏）多选 + 右键「生成三维体」
> 归属修正（2026-06-17，用户指出）：**源选择**在三维数据集栏（剖面池）；**生成的体**进**三维分析栏**（§7）。
`Column3DDataset.{hpp,cpp}`（源数据栏）：
- 列表 `setSelectionMode(ExtendedSelection)`（多选高亮，独立于 checkbox 渲染勾选）。
- `setContextMenuPolicy(CustomContextMenu)` + 槽：右键弹菜单「生成三维体」，仅当选中项 ≥1 且均为可作源的 ddCode（dd_section/dd_inversion_data）时启用。
- 新信号 `void generateVolumeRequested(const QStringList& sourceDsIds);`（取选中项的 kDsIdRole）。
## 6. UI：插值参数对话框
新增 `src/app/VolumeParamsDialog.{hpp,cpp}`（QDialog，与现有对话框同放 app 根目录）：
- 名称、插值模型（IDW；克里金项 disabled 占位）、cellXY/cellZ/power/maxDist（QDoubleSpinBox，默认同 §1）。
- `accept` → `volumeName()` / `params()`（不含 sourceDatasetIds，由调用方填）。
## 7. 装配：main.cpp 接线（体→三维分析栏 + 两栏勾选聚合）
- main.cpp 改 `Api3dRepository` 构造，传 `frame`（shared_ptr，§3 不需 projectCrs/refElev）。
- **体归三维分析栏**：`lastAnalysisRows` 缓存后端 Analysis 行(dd_slice)；`refreshAnalysis()` = `colAnalysis()->setDatasets(lastAnalysisRows + scene3dRepo->volumeRows())`。三维数据集栏(col3D)恢复直接 `setDatasets(b.dim3D)`（仅后端剖面，源池）。
- **渲染勾选聚合**：`checkedProfiles`(col3D 勾选剖面) + `checkedAnalysis`(colAnalysis 勾选体/切片) → `pushChecked()` 并集下发 `setCheckedDatasets`（控制器全量 diff，必须并集，否则一栏清掉另一栏）。
- 连接 `c3.generateVolumeRequested` → `VolumeParamsDialog` → 填 `params.sourceDatasetIds` → `scene3dRepo->createVolume` → `refreshAnalysis()`（新体出现在三维分析栏）。
- 连接 `c3.checkedDatasetsChanged`→更新 checkedProfiles；`ca.checkedItemsChanged`→更新 checkedAnalysis；均 `pushChecked()`。
- 后端加载回调：col3D 直接 `setDatasets(b.dim3D)`；analysis 经 `refreshAnalysis()`，保证体在测线重勾后仍驻留。
## 8. 阶段与验收（每阶段编译绿 = build.bat app）
- **阶段 A（模型+管线+loadVolume）**：§1 §2 §3。可单测 `buildVolume`；loadVolume 单源/多源逻辑成形。无 UI，不可见但编译绿 + 回归 LocalSample 不变。**✅ 编译绿**
- **阶段 B（创建流 UI）**：§5 §6 §7。可见：数据集栏多选剖面→右键生成→参数→新体行出现在**三维分析栏**→勾选渲染体。**✅ 编译绿**
- **阶段 C（分流）**：§4。dd_voxel 渲染为体、dd_section 渲染为帘面，二者可共存。**✅ 编译绿**
- 验收：用户启动 app 实测（Claude 无法 GUI 验证 VTK，按交接铁律用 `build.bat app` 仅编译验证；渲染问题查 `%LOCALAPPDATA%\Geomative\Geopro3\logs`）。
## 9. 风险 / 待确认
- **散点端点对反演剖面是否真有 hlist(高程)**：若某些数据 z 为空，竖向退化。落地时加日志取证，必要时回退用 grid.elevation（loadSection 路径）。
- **克里金**：UI 占位 disabled，仅 IDW 实现（设计 §1.1 列了克里金，但 core 仅 IdwInterpolator）。
- **mock 持久化形态**：本期纯内存（重启丢失），符合设计 §5「次要待确认」；本地文件持久化留后续。
- **源 ds 锁定不变式**（替代 gridSpec 冻结，用户决策）：被三维体引用的源 ds **不可修改/删除**——保证 IDW 重算确定一致、切片/异常坐标稳定。
- 本期：内存 mock，仅留 TODO（在源 ds 删除/编辑入口校验"是否被某三维体引用，是则禁止/告警"）。
- 推论：不冻结 gridSpec；若源真被改 ⇒ 体应失效重建，而非套旧锚点（旧锚点已是脏数据）。

100
docs/superpowers/plans/2026-06-18-vtk-3d-anomaly.md Normal file
View File

@ -0,0 +1,100 @@
# 实现计划：VTK 三维异常（#4，全量含异常体/列表/过滤）
- 日期：2026-06-18
- 分支：`feat/vtk-3d-view`
- 上位设计：`docs/superpowers/specs/2026-06-17-vtk-3d-volume-slice-anomaly-design.md`；补充需求 R49-56(切片右键创建异常) + R58-65(三维体详情·异常) + R69-88(异常/异常体列表/属性/过滤)。
- 关键决策（用户 2026-06-18 定）：
- **异常挂「三维体」**（`remarkSourceId`=三维体 ds id），不挂切片(切片是临时圈定载体)、不挂源 ds。见记忆 `vtk-3d-persistence-structure`。
- **全做**：圈定 + 保存(含截图) + 3D 渲染 + 异常/异常体列表(对象→异常体→异常) + 选中联动 + 显示过滤 + 删除/删除分组。
- **不参考 Geopro1.0**：按需求 + 行业最佳实践(标准多边形圈定)。
- **持久化 mock**：三维体/切片/异常端点后端均未就绪 → 全 mock(内存)走 `I3dSceneRepository`，整链端点就绪再切真实。截图先存本地(R88 截图属性待后端新增)。
## 0. 现状（可复用 vs 新建，实证见探查）
| 资产 | 现状 |
|---|---|
| `core::Anomaly`(name/typeName/markType点线面/localPts Vec2/线样式) | ✅ 有，但**2D**(localPts=x距离·y深度)，需补 3D 几何 |
| `I3dSceneRepository` 异常接口(loadAnomalyTree/saveAnomaly/deleteAnomaly/deleteAnomalyGroup + AnomalyTree/AnomalyBody) | ✅ 接口齐，**实现是 stub**(Api 回 onErr/空树) |
| `ObjectExceptionPanel`(对象→异常体→异常 树) | ✅ 只读树完整，**无勾选/选中/删除/过滤交互** |
| `render::buildAnomalies`(点/线/面 vtkActor) | ✅ 有，但坐标=2D(x,−depth,0)，需 3D(世界点) |
| 异常 DTO(parseExceptions/groupByConsortium) + 真实读取(loadExceptionsByTmAsync) | ✅ 真实读取链路通(后端就绪后用) |
| `I3dSceneView` 异常方法 / VtkSceneController 异常逻辑 / 3D 圈定工具 / 选中联动(3D) / 过滤 | ❌ 全无，需新建 |
## 1. 数据模型：core::Anomaly 补 3D 几何
`src/core/model/Anomaly.hpp` 增（保留现有 2D 字段，新增 3D）：
- `struct Vec3 { double x,y,z; };`
- `std::vector<Vec3> worldPts;`：异常多边形/折线/点的**世界 3D 坐标**（落在所在切片平面上）。
- `Vec3 planeNormal{0,0,1}, planeOrigin{};`：所在切片平面(法向+一点)——供重定位/正视，及与切片解耦后仍能定位。
- 持久化补充字段(不入 core，入仓储存储或 Anomaly 扩展)：`id`、`volumeDsId`(=remarkSourceId)、`exceptionTypeId`/`typeName`、`remark`、`screenshotPath`、`consortiumId`(异常体分组，空=未分组)。
> core::Anomaly 保持渲染/几何纯数据；id/归属/截图等持久化元数据放仓储的 StoredAnomaly 包装(同 StoredVolume/StoredSlice)。
## 2. 渲染：3D 异常 actor + I3dSceneView 接口
- `render::buildAnomalies3D(const std::vector<core::Anomaly>&)`（新增或改造 AnomalyActor）：用 `worldPts` 直接建点/折线/闭合多边形 actor（世界坐标，不再 ×−1 深度）；样式复用(lineColor/width/dashed)；选中高亮(加粗/变色)。
- `I3dSceneView` 新增：
- `addAnomaly(const core::Anomaly&)` / `removeAnomaly(id)` / `clearAnomalies()`
- `setAnomalyVisible(id, bool)` / `setAnomalySelected(id, bool)`（选中联动）
- `pickedAnomalyId()` 或经回调 `onAnomalyPicked(id)`（VTK 点选异常→列表）
- `VtkSceneView` 持 `map<id, actor>`，实现上述。
## 3. 圈定工具（切片平面上画多边形）
`src/render/interact/AnomalyDrawTool.{hpp,cpp}`（新）：
- 输入：当前选中切片的平面(origin/normal) + interactor + renderer。
- 交互(行业标准)：左键逐点加顶点(投影到切片平面)；右键/双击/回车闭合；Esc 取消；实时预览折线。点类型=单击一点；面=多边形闭合；(线/文字按 markType)。
- 产物：`worldPts`(平面上的世界点) + planeNormal/origin → 回调上层。
- 入口：VTK 视图切片右键「创建异常」(已占位) → 启动本工具(以光标拾取点为起点，R49)。
## 4. 保存对话框 + 截图
`src/app/AnomalySaveDialog.{hpp,cpp}`（新，参考 VolumeParamsDialog 风格）：
- 字段：异常名称、异常类型(下拉，**mock 几个类型**；真实类型端点 `exceptionType/*` 只读、后续可接)、备注。
- 截图(R50)：圈定结束截当前 VTK 视图(或异常包络区) → 存本地文件 → 路径+大小入异常记录(`SliceExport` 同款 PNG 写)。
- accept → 组装 `core::Anomaly`(markType/worldPts/plane/样式) + 元数据(name/typeId/remark/screenshot) → `saveAnomaly`。
## 5. 持久化 mock（Api3dRepository，挂三维体）
- `StoredAnomaly { core::Anomaly geom; id; volumeDsId; exceptionTypeId/typeName; remark; screenshotPath; consortiumId; }`；`map<id, StoredAnomaly> anomalies_`。
- `saveAnomaly(a, screenshotPath, onOk(id), onErr)`：生成 `anomaly-N`，存，回 id。（接口已含 screenshotPath 参数）
- `loadAnomalyTree(objectId, onOk(tree), onErr)`：按 objectId 下所有三维体聚合异常 → 组 `AnomalyTree`(bodies=异常体分组 + loose=未分组)。mock 阶段：以 volumeDsId 关联，未分组进 loose。
- `deleteAnomaly(id)` / `deleteAnomalyGroup(bodyId)`：删/删组。
- 异常体(consortium)分组：mock 内存(`map<bodyId, {name,typeName,memberIds}>`)；真实端点 `exceptionConsortium/*` 后续接。
- 接口签名不变；后端整链就绪仅换实现。
## 6. 异常展示与控制的摆放（用户 2026-06-18 定，需求实证 R28/R36/R58-88）
需求结构：R58/R67/R69/R90 均为 C1 顶级分节 = **数据详情栏**的各类详情内容；R28/R36「数据详情 → 在数据详情栏显示」。R84 选中联动、R86-87 VTK 显示过滤 = **3D 场景操作**。结论(职责拆分，互补不重复)：
- **三维分析区 = 3D 异常的"场景控制"**（本期 4c 重点，3D 异常现为 mock）：
- 树：对象 → 三维体 → 异常（异常挂三维体，R61；非切片非源 ds，见记忆 `vtk-3d-persistence-structure`）。
- **显示过滤 4 档(R86-87)**：全部显示 / 随GS / 随数据集 / 全部隐藏 —— **独立于体勾选**控制 VTK 异常可见性（解决"异常被体勾选绑死"）。
- 每条异常**单独显隐**（复用 AnomalyListPanel 的"眼睛"）。
- **VTK 选中双向联动(R84)**：列表选中 ↔ VTK 高亮。
- 删除异常 / 删除分组(R79-81, deleteAnomaly/deleteAnomalyGroup)。
- **右侧「对象异常」面板(现有 `ObjectExceptionPanel`) = 异常全集 master**：对象下所有异常总表。**本期保持不动**（仍连后端 2D 异常）；后端三维体/切片/异常整链就绪后，3D 异常并入此处成全集。
- **三维体数据详情(R58-65)**：源数据/切片/**异常列表(R61,只读摘要)**/插值参数/色阶/测量——经右键「数据详情」打开。
> 不在右侧总表里塞 3D 场景控制（过滤/联动属 3D 操作，归三维分析区）；不在三维分析区重复全集总表。
## 7. main.cpp 编排
- 切片右键「创建异常」→ 启动 `AnomalyDrawTool`(当前选中切片平面) → 圈定 → `AnomalySaveDialog` → `saveAnomaly` → 渲染(addAnomaly) + 刷新三维分析区异常列表。**[4b 已实现]**
- 体到场/移除(onVolumeChanged) → `loadAnomalyTree(volumeId)` → 渲染该体已存异常(reloadAnomalies)。**[4b 已实现，= "随数据集" 档默认]**
- 三维分析区异常列表：选中/显隐/过滤/删除 → 驱动 view 的 setAnomalyVisible/Selected + 仓储删；VTK 点选异常 → 列表选中(联动)。**[4c]**
## 8. 阶段（每阶段编译绿 + 用户实测）
- **4a 基础 ✅ 已提交(4e1b8e7)**：§1 模型 + §2 渲染/接口 + §5 mock 持久化 + 测试修复(228/228 绿)。
- **4b 圈定+保存 ✅ 已实现(未提交，用户已测通)**：§3 `AnomalyDrawTool`(切片平面圈定，射线-平面求交，左键加点/双击·右键·回车闭合/Esc 取消/屏幕提示) + §4 `AnomalySaveDialog`(名称/类型 mock/备注/截图预览) + 切片右键「创建异常」接通 + onVolumeChanged→reloadAnomalies(随体重载渲染)。闭环:画→存→显示→跨重勾持久。
- 同批交互修复(待提交)：生成体**按勾选集合**(非行高亮/右键项)、buildVolume 网格**覆盖全程**(跨 TM 多剖面不截断)、滚轮推进选中切片(点切片外取消选中→恢复缩放)。
- **4c 三维分析区 3D 异常控制（下一步）**：§6 —— 三维分析区异常树(对象→三维体→异常) + **显示过滤 4 档(R86-87)** + **VTK 选中双向联动(R84)** + 每条显隐 + 删除/删组 + 异常属性(R83)。异常体分组 mock。右侧总表不动。
- **后续**：三维体/切片数据详情(R58-65/R67)；真实端点整链就绪后切真实(异常并入右侧全集)。
## 9. 风险/待确认
- **core::Anomaly 改动影响 2D 路径**：补字段不动现有 2D 字段，2D 渲染(ContourPlotItem/buildAnomalies)不受影响；3D 走新 worldPts 路径。
- **异常体(consortium)创建入口**：需求 R71 有异常体，但"如何把异常归入异常体"的 UI 入口需求未细化 → 4c 落地时按最佳实践补(多选异常→成组)，或先只做 loose + 展示分组。
- **截图属性后端缺**(R88 待新增)：先本地存，后端加字段再上传。
- **真实类型/异常体端点只读可接**：mock 阶段先 mock，降耦合；可选接真实只读。

383
docs/superpowers/plans/2026-06-23-gpr-volume-poc.md Normal file
View File

@ -0,0 +1,383 @@
# GPR 三维体 POC（B & C 双方案）实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 用真实 13G 雷达数据为 B（整卷上 GPU）与 C（分块+金字塔+核外）两套对等方案做 POC，验证技术可行性并挖出 spec 未预见的阻塞；POC 代码即生产地基与接口实现，不返工。
**Architecture:** 共用地基（解析/几何/结构化建体/int16 量化体/分块存储）+ `IVolumeRenderSource` 渲染接缝；`WholeVolumeSource`(B) 与 `OutOfCoreSource`(C) 是接口下两个永久并存实现，用户运行时按数据规模切换。落盘从第一天就分块，B 的裸分块格式是 C 金字塔/核外的基座。
**Tech Stack:** C++17, Qt6, VTK 9.6（`RenderingVolumeOpenGL2` GPU ray cast，自带 `vtkzlib`），GoogleTest，nlohmann-json（sidecar），现有 `src/{core,data,render,app}` 分层。
## Global Constraints
- **dtype**：雷达体走 **int16**（`vtkShortArray`），不污染反演剖面的 double 主路径（`ScalarVolume` 保持 `std::vector<double>`，`src/core/model/Field.hpp:8-26`）。
- **量化**：物理值 ↔ int16 经 `scale/offset`，**必须贯穿**传递函数采样、色阶 LUT（`src/render/interact/SliceTool.cpp:37`）、取值/详情反量化（见 spec B §3.5）。
- **落盘**：**不用 `vtkHDFWriter`**（VTK 9.6 写不了 `vtkImageData`，记忆 `vtk96-hdfwriter-no-imagedata`）。用裸 int16 分块 + sidecar(json) + 逐块 `vtkzlib`。
- **渲染接缝**：上层（场景/切片）只面向 `IVolumeRenderSource`；B/C 是其两个实现。
- **结构化建体**：X(沿线)/Z(深度) 规则落格，仅 Y(14 通道) 向 1D 插值；**不**对雷达用全 3D 散点 IDW（现有 `IdwInterpolator` 无空间索引暴力，`src/core/algo/IdwInterpolator.cpp:15-33`）。
- **真实数据判定**：POC 用 `D:\Downloads\明星路`（450MHz/14通道/821采样/~45306道/线/20线/int16/13.6GB）。POC 过 = 在该真实数据上跑通并达标，不许避重就轻。
- **测试数据头实证**：`.iprh` 文本键值（`SAMPLES/LAST TRACE/CHANNELS/TIMEWINDOW/SOIL VELOCITY/DISTANCE INTERVAL`）；`.iprb` = `int16[samples × traces]`，`samples×traces×2 == 文件大小`；`.ord` = 通道横向偏移（14 有效）。
---
## 文件结构（决定分解与复用）
```
src/io/gpr/ ← 新增：雷达 IO（共用地基）
IprHeader.{hpp,cpp} 解析 .iprh → 结构体
IprbReader.{hpp,cpp} 读 .iprb int16 B-scan（mmap/分块读）
GprGeometry.{hpp,cpp} .ord 通道偏移 + .gps/.cor 逐道经纬 + 深度轴
GprSurvey.{hpp,cpp} 一个工区 = 线[]×通道[] + 几何（建体输入）
src/core/model/
ScalarVolumeI16.hpp int16 体 + Quant{scale,offset} （新增，与 ScalarVolume 并列）
src/core/algo/
GprVolumeBuilder.{hpp,cpp} 结构化建体：X/Z 落格 + Y 向 1D 插值 → ScalarVolumeI16
src/data/store/
ChunkedVolumeStore.{hpp,cpp} 分块 int16 + zlib + sidecar；读/写/按块取（B/C 共用，C 加金字塔）
src/render/source/
IVolumeRenderSource.hpp 渲染接缝（接口）
WholeVolumeSource.{hpp,cpp} B：读全块 → 1 个 vtkImageData
OutOfCoreSource.{hpp,cpp} C：金字塔 + brick 分页 → 工作集
src/render/actors/
VoxelActor.cpp Modify：buildVoxel 增 int16 重载 + 量化域传函
tests/io/gpr/ tests/core/ tests/data/store/ ← 对应测试
tools/gpr_poc/ ← POC 度量台（建体/加载/显存/fps 探针 + CLI）
```
POC 度量统一进 `tools/gpr_poc`（建体耗时、输出维度、落盘体积/压缩比、加载耗时、显存、切片/体绘制 fps），B/C 用同一套指标对照。
> **POC vs 生产**：Task 1–6（地基）+ 7–8、10–11（接口/存储）是**生产代码，走 TDD、有完整代码**。Task 9、12–13 是**可行性探针**：给出明确实验、被测未知、通过/失败判据与度量，不预先杜撰我们正要验证的 VTK 核外内部实现——这是 POC 的本质，强行写"完整代码"等于造假。
---
## Phase 0 — 地基（共用，生产级 TDD）
### Task 1: .iprh 头解析
**Files:**
- Create: `src/io/gpr/IprHeader.hpp`, `src/io/gpr/IprHeader.cpp`
- Test: `tests/io/gpr/test_ipr_header.cpp`
**Interfaces:**
- Produces: `struct IprHeader { int samples; long lastTrace; int channels; double timeWindowNs; double soilVelocity; double distanceInterval; };` + `IprHeader parseIprHeader(const std::string& text);`
- [ ] **Step 1: 写失败测试**
```cpp
#include "io/gpr/IprHeader.hpp"
#include <gtest/gtest.h>
using geopro::io::gpr::parseIprHeader;
TEST(IprHeader, ParsesKeyFieldsFromRealSample) {
const std::string t =
"SAMPLES: 821\nLAST TRACE: 45305\nCHANNELS: 14\n"
"TIMEWINDOW: 160.352\nSOIL VELOCITY: 100.000000\nDISTANCE INTERVAL: 0.049084\n";
auto h = parseIprHeader(t);
EXPECT_EQ(h.samples, 821);
EXPECT_EQ(h.lastTrace, 45305);
EXPECT_EQ(h.channels, 14);
EXPECT_DOUBLE_EQ(h.timeWindowNs, 160.352);
EXPECT_DOUBLE_EQ(h.soilVelocity, 100.0);
EXPECT_NEAR(h.distanceInterval, 0.049084, 1e-9);
}
```
- [ ] **Step 2: 运行确认失败** — `ctest -R IprHeader`，预期 编译/链接失败（未定义）。
- [ ] **Step 3: 最小实现** — `parseIprHeader` 逐行 `key: value` 拆分，按字段名填结构体；缺字段抛 `std::runtime_error`。
- [ ] **Step 4: 运行确认通过** — `ctest -R IprHeader`，预期 PASS。
- [ ] **Step 5: 提交** — `git commit -m "feat(gpr): parse .iprh header fields"`
### Task 2: .iprb B-scan 读取
**Files:**
- Create: `src/io/gpr/IprbReader.{hpp,cpp}`
- Test: `tests/io/gpr/test_iprb_reader.cpp`
**Interfaces:**
- Consumes: `IprHeader`
- Produces: `struct BScan { int samples; long traces; std::vector<int16_t> data; /* [trace*samples + s] */ };` + `BScan readIprb(const std::string& path, const IprHeader& h);`（校验 `samples*traces*2 == fileSize`）
- [ ] **Step 1: 写失败测试**（用临时文件造 4 道×3 采样 int16）
```cpp
TEST(IprbReader, ReadsInt16AndValidatesSize) {
// 写 tmp：samples=3, traces=4 → 24 bytes
std::vector<int16_t> raw{0,1,2, 10,11,12, 20,21,22, 30,31,32};
auto path = writeTmp(raw); // helper
geopro::io::gpr::IprHeader h{}; h.samples=3; h.lastTrace=3; // traces=lastTrace+1=4
auto b = geopro::io::gpr::readIprb(path, h);
EXPECT_EQ(b.samples, 3); EXPECT_EQ(b.traces, 4);
EXPECT_EQ(b.data[1*3 + 2], 12); // 第1道第2采样
}
```
- [ ] **Step 2: 运行确认失败**。
- [ ] **Step 3: 最小实现** — `traces = lastTrace+1`；读全文件为 int16；不匹配大小抛错。
- [ ] **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(gpr): read .iprb int16 b-scan with size check"`
### Task 3: 几何（通道偏移 + 逐道经纬 + 深度轴）
**Files:**
- Create: `src/io/gpr/GprGeometry.{hpp,cpp}`
- Test: `tests/io/gpr/test_gpr_geometry.cpp`
**Interfaces:**
- Produces:
- `std::vector<double> parseChannelXOffsets(const std::string& ordText);`（取第 4 列==1 的有效通道横偏，明星路应得 14 个 -0.686..+0.686）
- `double depthOfSample(int s, const IprHeader& h);`（`= s * (timeWindowNs/(samples-1)) * soilVelocity*1e-9/2`，单位米；soilVelocity 100 m/µs = 1e8 m/s）
- [ ] **Step 1: 写失败测试**
```cpp
TEST(GprGeometry, ParsesActiveChannelOffsets) {
const std::string ord = "0 -0.686000 -1.5 1\n1 -0.581000 -1.5 1\n14 0 -1.5 0\n";
auto xs = geopro::io::gpr::parseChannelXOffsets(ord);
EXPECT_EQ(xs.size(), 2u); // 仅 2 个有效（末列=1）
EXPECT_NEAR(xs[0], -0.686, 1e-6);
}
TEST(GprGeometry, DepthOfLastSampleMatchesPhysics) {
geopro::io::gpr::IprHeader h{}; h.samples=821; h.timeWindowNs=160.352; h.soilVelocity=1e8;
EXPECT_NEAR(geopro::io::gpr::depthOfSample(820, h), 8.0, 0.05); // ~8m
}
```
> 注：`soilVelocity` 单位换算在 Task 1 读入时统一成 m/s（100 m/µs = 1e8 m/s），在此基础上测试。
- [ ] **Step 2: 失败**。
- [ ] **Step 3: 实现** — `.ord` 按空白拆列、末列=="1" 收集第 2 列；`depthOfSample` 按公式。
- [ ] **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(gpr): channel offsets + depth axis geometry"`
### Task 4: int16 量化体类型
**Files:**
- Create: `src/core/model/ScalarVolumeI16.hpp`
- Test: `tests/core/test_scalar_volume_i16.cpp`
**Interfaces:**
- Produces:
```cpp
struct Quant { double scale = 1.0; double offset = 0.0;
int16_t toQ(double v) const; // round((v-offset)/scale)，钳到[INT16_MIN+1,INT16_MAX]
double toPhys(int16_t q) const; }; // q*scale+offset
class ScalarVolumeI16 { // 行优先 idx=((k*ny+j)*nx+i)，与 vtkImageData 一致
ScalarVolumeI16(int nx,int ny,int nz);
int16_t& at(int i,int j,int k); int nx()const; ...; std::vector<int16_t>& data();
static constexpr int16_t kBlank = INT16_MIN; }; // 空值哨兵→透明
```
- [ ] **Step 1: 写失败测试**（量化往返 + 索引布局 + blank）
```cpp
TEST(ScalarVolumeI16, QuantRoundTripAndLayout) {
geopro::core::Quant q{0.5, -10.0};
EXPECT_EQ(q.toQ(-10.0), 0); EXPECT_NEAR(q.toPhys(q.toQ(3.0)), 3.0, 0.25);
geopro::core::ScalarVolumeI16 v(2,2,2);
v.at(1,0,1) = 7; EXPECT_EQ(v.data()[(1*2+0)*2+1], 7);
}
```
- [ ] **Step 2: 失败** → **Step 3: 实现** → **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(core): int16 scalar volume + quantization"`
### Task 5: 结构化建体 GprVolumeBuilder
**Files:**
- Create: `src/core/algo/GprVolumeBuilder.{hpp,cpp}`
- Test: `tests/core/test_gpr_volume_builder.cpp`
**Interfaces:**
- Consumes: `GprSurvey`(线×通道 BScan + 几何)、`GridSpec`(复用 `src/core/algo/IInterpolator.hpp:7-13`)
- Produces: `struct BuiltI16 { ScalarVolumeI16 vol; Quant quant; std::array<double,3> origin, spacing; double vminPhys, vmaxPhys; };`
`BuiltI16 buildGprVolume(const GprSurvey& s, const GridSpec& spec);`
- **算法**：X(沿线)/Z(深度) 最近邻或线性落格（道已规则）；**Y 向**对落在该 (x,z) 的 14 通道值做 1D 线性插值填充横向网格；maxDist/无覆盖 → `kBlank`。量化 scale/offset 由全体 min/max 定。
- [ ] **Step 1: 写失败测试**（2 通道、各 1 道×2 采样的人造 survey，验横向中点插值 + 维度）
```cpp
TEST(GprVolumeBuilder, InterpolatesAcrossChannelsOnly) {
auto s = makeTwoChannelSurvey(/*ch0 val=0, ch1 val=100, 横偏 0 和 1m*/);
geopro::core::GridSpec spec{/*nx=*/3,/*ny=*/1,/*nz=*/1, 0,0,0, 0.5,1,1, 2.0, 9.9};
auto b = geopro::core::buildGprVolume(s, spec);
EXPECT_NEAR(b.quant.toPhys(b.vol.at(1,0,0)), 50.0, 1.0); // 横向中点≈50
}
```
- [ ] **Step 2: 失败** → **Step 3: 实现**（先单线程，循环结构留可并行）→ **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(core): structured GPR volume builder (Y-only interp)"`
### Task 6: 分块存储 ChunkedVolumeStore（B/C 共用基座）
**Files:**
- Create: `src/data/store/ChunkedVolumeStore.{hpp,cpp}`
- Test: `tests/data/store/test_chunked_volume_store.cpp`
**Interfaces:**
- Produces:
```cpp
struct StoreMeta { int nx,ny,nz; int brick; // e.g. 64
std::array<double,3> origin, spacing; Quant quant; double vminPhys,vmaxPhys; };
class ChunkedVolumeStore {
static void write(const std::string& dir, const BuiltI16& b, int brick=64); // 分块+zlib+sidecar.json
static StoreMeta readMeta(const std::string& dir);
std::vector<int16_t> readBrick(int bx,int by,int bz) const; // 解压单块
// Task 10 追加：pyramid 层；Task 11 用 readBrick 做工作集
};
```
- **格式**：`meta.json`(StoreMeta + 分块索引/偏移/压缩长度) + `data.bin`(逐块 zlib 压缩流)。zlib 用 VTK 自带 `vtkzlib` 或直接 zlib C API。
- [ ] **Step 1: 写失败测试**（write→readMeta→readBrick 往返 + 压缩后小于原始）
```cpp
TEST(ChunkedVolumeStore, RoundTripBrickAndCompresses) {
auto b = makeBuilt(128,128,128, /*可压缩模式*/);
geopro::data::ChunkedVolumeStore::write(tmpDir, b, 64);
auto m = geopro::data::ChunkedVolumeStore::readMeta(tmpDir);
EXPECT_EQ(m.nx, 128); EXPECT_EQ(m.brick, 64);
geopro::data::ChunkedVolumeStore s(tmpDir);
auto blk = s.readBrick(0,0,0);
EXPECT_EQ(blk.size(), 64u*64*64);
EXPECT_LT(fileSize(tmpDir+"/data.bin"), 128u*128*128*2); // 压缩生效
}
```
- [ ] **Step 2: 失败** → **Step 3: 实现** → **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(data): chunked int16 volume store (zlib + sidecar)"`
### Task 7: VoxelActor int16 重载 + 量化域传递函数
**Files:**
- Modify: `src/render/actors/VoxelActor.cpp`（增 int16 重载，参照现 double 版 `:41-79`）
- Test: `tests/render/test_voxel_i16_smoke.cpp`（无窗渲染冒烟 / 或断言 image 标量类型与传函控制点在量化域）
**Interfaces:**
- Produces: `vtkSmartPointer<vtkVolume> buildVoxelI16(const ScalarVolumeI16& vol, const Quant& q, const ColorScale& cs, double ox,..,dz, vtkSmartPointer<vtkImageData>& outImage);`
- **要点**：`vtkShortArray` 填值；传函/不透明度在**量化域 qmin/qmax** 加点（`q.toQ(vminPhys)`..`q.toQ(vmaxPhys)`），`kBlank→0` 不透明；`vtkSmartVolumeMapper`。
- [ ] **Step 1: 写失败测试**（构造小 int16 体，断言 `outImage->GetScalarType()==VTK_SHORT` 且传函在量化域采样不崩）。
- [ ] **Step 2: 失败** → **Step 3: 实现** → **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(render): int16 voxel actor with quantized transfer fn"`
---
## Phase 1 — POC-B（整卷上 GPU）
### Task 8: IVolumeRenderSource + WholeVolumeSource（B）
**Files:**
- Create: `src/render/source/IVolumeRenderSource.hpp`, `src/render/source/WholeVolumeSource.{hpp,cpp}`
- Test: `tests/render/test_whole_volume_source.cpp`
**Interfaces:**
- Produces:
```cpp
class IVolumeRenderSource { public: virtual ~IVolumeRenderSource()=default;
virtual StoreMeta meta() const = 0;
virtual void update(const Camera& cam) = 0; // B：首次载全量；C：按相机换块
virtual std::vector<vtkSmartPointer<vtkImageData>> currentProps() const = 0; // B：1 个；C：工作集
virtual vtkImageData* sliceSource() const = 0; }; // 供 SliceTool reslice
class WholeVolumeSource : public IVolumeRenderSource { // 读全块拼 1 个 int16 vtkImageData
explicit WholeVolumeSource(const std::string& storeDir); };
```
- [ ] **Step 1: 写失败测试**（从 Task 6 写出的 store 构造 WholeVolumeSource，`currentProps().size()==1`，维度==meta）。
- [ ] **Step 2: 失败** → **Step 3: 实现**（遍历所有 brick 填进整卷 image）→ **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(render): IVolumeRenderSource + whole-volume source (B)"`
### Task 9: POC-B 真实数据度量（探针，含通过判据）
**Files:**
- Create: `tools/gpr_poc/main.cpp`（CLI：`gpr_poc build|renderB <明星路目录>`）、`tools/gpr_poc/Probe.{hpp,cpp}`（计时/显存/fps）
- 复用：Task 1–8 全部。
**被验证的未知 / 阻塞点：** ①int16 GPU ray cast 在真机正常出图；②真实建体耗时与输出体积；③整卷 5~10GB 加载耗时、显存峰值；④切片拖动 fps、体绘制 fps；⑤超显存时 `vtkSmartVolumeMapper` 的 `LowResResample`(`MaxMemoryInBytes`) 自动降质观感。
- [ ] **Step 1:** `gpr_poc build 明星路` → 跑 Task 1–6，输出：建体耗时、`nx×ny×nz`、落盘体积、压缩比。记录。
- [ ] **Step 2:** `gpr_poc renderB` → WholeVolumeSource 上 `vtkSmartVolumeMapper`，量化传函着色，真窗口显示。
- [ ] **Step 3:** Probe 采集：加载耗时、显存峰值、切片拖动 fps（脚本化相机/切片移动）、体绘制旋转 fps。
- [ ] **Step 4:** 设 `MaxMemoryInBytes` 低于体大小，验证 `LowResResample` 自动降质路径出图。
- [ ] **Step 5:** 写 `docs/superpowers/plans/poc-results-B.md`：指标表 + 结论。
- **B 通过判据**：真实数据建体可完成且体积/耗时可接受；整卷在目标显存内出图；**切片拖动 ≥ 可用帧率（目标 ≥30fps）**；超显存时 LowRes 兜底可用。任一硬阻塞（如 GPU 不吃 short、显存必爆且 LowRes 不可接受）→ 记为 B 的落地风险并反馈 spec。
- [ ] **Step 6: 提交** — `git commit -m "test(gpr): POC-B real-data metrics harness + results"`
---
## Phase 2 — POC-C（分块+金字塔+核外，含最小真实分页器）
### Task 10: 金字塔生成（ChunkedVolumeStore 增量）
**Files:**
- Modify: `src/data/store/ChunkedVolumeStore.{hpp,cpp}`（加 LOD 层 + 每块 min/max）
- Test: `tests/data/store/test_pyramid.cpp`
**Interfaces:**
- Produces: `void buildPyramid(int levels);`（逐级 2× 降采样，每层独立分块 + 每块 `int16 min,max` 存 meta）；`std::vector<int16_t> readBrick(int level,int bx,int by,int bz);`；`std::pair<int16_t,int16_t> brickRange(int level,int bx,int by,int bz);`
- [ ] **Step 1: 写失败测试**（建 1 层金字塔，断言 level1 维度≈半、brickRange 命中真实 min/max）。
- [ ] **Step 2: 失败** → **Step 3: 实现** → **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(data): volume pyramid + per-brick min/max"`
### Task 11: brick 分页器（LRU 工作集，生产级 TDD）
**Files:**
- Create: `src/render/source/BrickPager.{hpp,cpp}`
- Test: `tests/render/test_brick_pager.cpp`
**Interfaces:**
- Produces:
```cpp
class BrickPager { // 内存恒定：驻留 ≤ budgetBricks 个解压块
BrickPager(const ChunkedVolumeStore& store, size_t budgetBricks);
void requestVisible(const std::vector<BrickId>& visible, int level); // 载入缺失、LRU 淘汰
const std::vector<int16_t>* get(BrickId id, int level) const; // 命中返回，未命中 nullptr
size_t residentCount() const; };
```
- [ ] **Step 1: 写失败测试**（budget=4，请求 6 块 → residentCount==4，最早的被淘汰，命中/未命中正确）。
- [ ] **Step 2: 失败** → **Step 3: 实现**（LRU + 从 store 解压载入）→ **Step 4: 通过**。
- [ ] **Step 5: 提交** — `git commit -m "feat(render): bounded-memory brick pager (LRU)"`
### Task 12: OutOfCoreSource（C）— 最高风险探针：核外体绘制
**Files:**
- Create: `src/render/source/OutOfCoreSource.{hpp,cpp}`（实现 `IVolumeRenderSource`）
- 复用：Task 10/11。
**被验证的未知 / 阻塞点（C 的命门，必须正面撞）：**
1. **VTK 能否渲染"动态换入换出的块工作集"为体**——把 BrickPager 的工作集作为多个 `vtkImageData` 喂给 `vtkMultiBlockVolumeMapper`（注意其"试图全量加载"语义，须只喂视野块）或多个 `vtkVolume` 叠加；验证可行性与正确性。
2. **块边接缝**：相邻 brick 渲染交界是否可见；试 `vtkMultiBlockVolumeMapper` 的抖动是否压得住。
3. **LOD 切换**：相机拉远用粗层、拉近换细层，切换是否闪烁/可接受。
4. **热路径解压**：拖动每帧换块时 zlib 解压是否拖垮帧率（CPU 瓶颈）。
> 本任务**不预写完整实现**——它就是要发现上面四点的真实结论。步骤是受控实验，产物是"能跑的最小版本 + 实测结论"。
- [ ] **Step 1:** `update(cam)` 内：算视野相交 brick + 选 LOD → `BrickPager::requestVisible` → `currentProps()` 返回工作集 image。
- [ ] **Step 2:** 用 `vtkMultiBlockVolumeMapper`（或 N×`vtkVolume`）渲染工作集，量化传函复用 Task 7。先静态相机出图，确认正确。
- [ ] **Step 3:** 接相机移动 → 动态换块；Probe 测 residentCount/内存恒定、换块 fps。
- [ ] **Step 4:** 逐项记录未知 1–4 的实测结论（接缝截图、LOD 切换录屏指标、解压占帧时间）。
- [ ] **Step 5:** 写 `poc-results-C.md`：四个未知的结论 + 是否构成阻塞 + 缓解手段。
- **C 通过判据**：工作集体绘制能正确出图且**内存恒定**；接缝/闪烁/解压三项**各自有可接受方案或明确缓解**（不可接受则记为阻塞并反馈 spec C，这正是 POC 的目的）。
- [ ] **Step 6: 提交** — `git commit -m "test(gpr): POC-C out-of-core volume render probe + results"`
### Task 13: 切片核外 + B/C 切换贯通
**Files:**
- Modify: `src/render/source/OutOfCoreSource.cpp`（`sliceSource()`：只读切面相交块拼子体供 reslice）
- 复用现有 `SliceTool`（`src/render/interact/SliceTool.cpp`）对 source 给出的 image 切片。
**被验证的未知：** 切片只读相交块时的内存/fps；同一 `IVolumeRenderSource` 下 B↔C 运行时切换无缝。
- [ ] **Step 1:** `OutOfCoreSource::sliceSource()` 按当前切面算相交 brick → 拼最小子体 image。
- [ ] **Step 2:** `SliceTool` 对该 image reslice，拖动切片测 fps、内存。
- [ ] **Step 3:** POC 台加 `renderC` 与 `--source whole|ooc` 开关，验证同一上层代码切两实现。
- [ ] **Step 4:** 补 `poc-results-C.md`：切片核外指标 + 切换验证。
- [ ] **Step 5: 提交** — `git commit -m "feat(render): slice out-of-core + runtime B/C source switch"`
---
## Self-Review（对照 spec 检查）
**1. spec 覆盖**
- spec B：int16 路径(Task 4/7)、结构化建体(Task 5)、裸分块落盘(Task 6)、量化贯穿(Task 4/7/Global)、整卷渲染(Task 8/9)、LowResResample(Task 9) ✓
- spec C：分块(Task 6)、金字塔+min/max(Task 10)、brick 分页(Task 11)、核外体绘制(Task 12)、切片核外(Task 13)、B/C 切换(Task 13) ✓
- 共有地基：.iprb/.iprh 解析(Task 1/2)、几何/配准(Task 3)、GPR→体(Task 5) ✓
- **缺口（POC 不覆盖，明确记录）**：ddCode 接入数据集树/UI、后端持久化对接、异常/色阶编辑器接线——POC 阶段不做（spec A §2 / B §6 列为成品阶段），不影响复用。
**2. 占位符扫描**：地基任务(1–8,10,11)均有完整测试代码与实现描述；POC 探针(9,12,13)按设计**有意不写杜撰实现**，代之以受控实验 + 通过判据（已在任务内注明本质）。无 "TODO/TBD/适当处理" 类空话。
**3. 类型一致性**：`ScalarVolumeI16`/`Quant`/`BuiltI16`/`StoreMeta`/`IVolumeRenderSource`/`BrickPager` 在定义任务与消费任务间签名一致；`buildGprVolume`/`buildVoxelI16`/`ChunkedVolumeStore::{write,readMeta,readBrick}`/`requestVisible` 全程同名。
---
## 关键风险（开工即知）
- **Task 12 是月级生产工程的"最小探针"**：POC 只需证可行 + 撞出阻塞，不追求生产质量分页器；但若未知 1（VTK 渲染动态工作集）撞墙，是 C 的根本阻塞，须立刻反馈 spec C 并评估替代（OpenVDS / 自建 GL）。
- **真实 13G 在合理分辨率下可能装得进显存** → B 顺过、C 的核外价值要靠"细分辨率/拼全路段大体"的真实配置才能压出（Task 9/12 的网格参数留 CLI 可调，用同一份真实数据调出超显存体来考验 C）。
- **量化贯穿**漏一处即色阶/读数错（Global 约束 + Task 4/7），Self-Review 已盯。

1127
docs/superpowers/plans/2026-06-24-vtk-category-view-refactor.md Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
docs/superpowers/plans/poc-lod-shots/lod-fullres-local.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/superpowers/plans/poc-lod-shots/lod-overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
docs/superpowers/plans/poc-lod-shots/lod-transition-mid.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.2 KiB

BIN
docs/superpowers/plans/poc-lod-shots/lod-tuned-local.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/superpowers/plans/poc-lod-shots/lod-tuned-overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.9 KiB

BIN
docs/superpowers/plans/poc-lod-shots/polish-a-value.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 99 KiB

BIN
docs/superpowers/plans/poc-lod-shots/polish-b-grad.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/superpowers/plans/poc-lod-shots/polish-c-grad-shade.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-default.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-near.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 267 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-var1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 236 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-var2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 200 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-var3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 208 KiB

BIN
docs/superpowers/plans/poc-lod-shots/view-var4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 250 KiB

179
docs/superpowers/plans/poc-results-B.md Normal file
View File

@ -0,0 +1,179 @@
# POC-B 实测结果（gpr_poc headless 度量）
工具：`tools/gpr_poc`（CLI），构建产物 `build/release/tools/gpr_poc/gpr_poc.exe`。
执行机：Windows 11，MSVC（VS18 Community）+ Ninja，Release（/O2）。
日期：2026-06-23。
整条地基链路：
`assembleGprSurvey → buildGprVolume → ChunkedVolumeStore::write → buildPyramid → WholeVolumeSource(load)`。
---
## 1. selftest（合成极小数据）—— PASS
命令：`gpr_poc selftest`
- 构造 2 通道合成 survey（samples=8，traces=12），写临时 `.iprb/.iprh/.ord`，
走完整 `assembleGprSurvey → buildGprVolume → write(brick=4) → buildPyramid(1) → WholeVolumeSource`。
- 断言：ntraces/samples/channels、channelY 升序、GridSpec `2x2x8`、建体维度、
金字塔层数==2、整卷维度一致、(0,0,0) 非 blank。
- 结果：**PASS**（退出码 0）。
结论：除真实 `.iprb` 读入外，**整条地基管线在合成数据上端到端跑通**
（装配几何、建体量化、分块压缩落盘、金字塔降采样、整卷重组加载均正确）。
---
## 2. 真实数据（D:\Downloads\明星路，线 001）—— **PASS（实测）**
> 更新（任务 9b，2026-06-23）：先前 BLOCKED 的根因（`readIprb` 硬假设
> `traces = lastTrace + 1`）已修复。`readIprb` 改为**以文件大小为权威**
> （`traces = fileBytes / (samples·2)`），真实数据装配通过。
命令：
```
gpr_poc build "D:\Downloads\明星路" --line 001 --cellXY 0.2 --cellZ 0.05 --out <store> --levels 2
gpr_poc load <store>
```
### 根因回顾（off-by-one：lastTrace+1 vs 真实道数）
旧 `readIprb` 硬编码 `traces = h.lastTrace + 1` 并对文件字节做严格相等校验。
真实明星路每个通道文件恰好含 `lastTrace` 条道（少 1 道），逐通道实测：
| 通道 | 文件字节 | samples | LAST TRACE | 旧期望(=samples·(lastTrace+1)·2) | 实际道数(=bytes/(samples·2)) |
|------|----------|---------|------------|----------------------------------|------------------------------|
| A01 | 74390810 | 821 | 45305 | 74392452 | 45305 |
| A02 | 74394094 | 821 | 45307 | 74395736 | 45307 |
| A12 | 74392452 | 821 | 45306 | 74394094 | 45306 |
**规律一致**：所有通道「实际道数 == LAST TRACE」。修复后 `readIprb` 不再用 `lastTrace`
决定道数，装配按各通道道数最小值对齐（min=45305）。
### build 实测指标（line 001, cellXY=0.2, cellZ=0.05, levels=2）
| 指标 | 值 |
|------|-----|
| 发现通道数 | 14 |
| 装配后 ntraces / samples / channels | 45305 / 821 / 14 |
| dx / dz（米） | 0.049084 / **0.00977756** |
| GridSpec（nx×ny×nz） | **11120 × 8 × 162** |
| 体素数 | 14,411,520 |
| 原始体积（int16） | 28,823,040 B（27.49 MB） |
| 落盘 data.bin（含金字塔各级） | 15,317,628 B（14.61 MB） |
| 压缩比（原始/落盘） | **1.88×** |
| 装配耗时 | 12,551 ms |
| 建体耗时 | 1,926 ms |
| 落盘耗时 | 3,597 ms |
| 金字塔耗时 | 3,923 ms |
| build 端到端墙钟 | ≈22.6 s |
| 峰值内存 | **4,975 MB** |
### load 实测指标
| 指标 | 值 |
|------|-----|
| 加载耗时 | 335 ms |
| 整卷维度 | 11120 × 8 × 162 |
| 整卷字节 | 28,823,040 B（27.49 MB） |
| 峰值内存 | 38 MB |
无 OOM、无超时，未调粗 cellXY 即一次通过。
### 峰值内存说明（4.98 GB）
峰值由**装配阶段**主导：同时持有 14 通道 BScan（14×74 MB ≈ 1 GB int16）
+ `GprSurvey.values` 以 **double** 存（14×45305×821×8 B ≈ 4.2 GB）。
建体/落盘/加载本身很轻（load 仅 38 MB）。若后续要压内存，可让 survey.values
改存 int16 或流式装配，但当前规模单机可承受，POC 不做此优化。
---
## 3. 深度/Z 尺度诊断结论（任务 9b）
先前 §3 预估「nz=1、深度量级 8e-6 m」是在 SOIL VELOCITY **未正确换算**时写下的
（当时按 100 m/s 计算）。Task 1 已将 `SOIL VELOCITY`（头文件单位 m/µs）×1e6 存为 m/s，
本任务实测确认整条 Z 链路正确：
- 头：SAMPLES=821，TIMEWINDOW=160.352 ns，SOIL VELOCITY=100（→ 1e8 m/s）。
- `depthOfSample(820) = 1e8 × 160.352e-9 / 2 ≈ **8.018 m**`（深度跨度合理）。
- `dz = depthOfSample(1) = 8.018/820 ≈ **0.009778 m**`（实测 0.00977756，吻合）。
- 故 cellZ=0.05 下 `nz = ceil(8.018/0.05)+1 = **162**`（实测 162，非 1）。
**结论**：`assembler`/`GprGeometry`/CLI `specFromSurvey` 的 Z 计算**全部正确**，
无需改 CLI。先前的 nz=1 症状是 soilVelocity 换算缺失时代的遗留，现已不复存在。
CLI 的 `specFromSurvey` 用的是 `survey.dz`（来自 `depthOfSample`），未误用原始 100，未漏乘。
---
## 4. 离屏 GPU 渲染基准（任务 9c，2026-06-23）
工具新增子命令：`gpr_poc offscreen-smoke`（闸门）、`gpr_poc renderB <store> [--frames N]`。
执行机 GPU：**NVIDIA GeForce RTX 3060 Laptop GPU**，OpenGL 4.5.0 NVIDIA 555.97，硬件加速 True。
### 4.1 闸门：offscreen-smoke —— **OK（离屏 GL 可用）**
命令：`gpr_poc offscreen-smoke`
- 离屏 `vtkRenderWindow`（`SetOffScreenRendering(1)`+`SetShowWindow(false)`，256×256）
→ 加 cube actor → `Render()` → `GetRGBACharPixelData` 读回。
- 读回 65536 像素，非背景像素 **28224**（cube 正确画出）。
- GL vendor=NVIDIA Corporation，renderer=RTX 3060 Laptop GPU，硬件加速 True。
- **结论：离屏 GPU 渲染在本机可用**，继续真实基准（非编造）。
### 4.2 基准数据（line 001，更细一档 cellXY=0.05）
命令：`gpr_poc build "D:\Downloads\明星路" --line 001 --cellXY 0.05 --cellZ 0.05 --out <store> --levels 1`
| 指标 | 值 |
|------|-----|
| 体维度（nx×ny×nz） | **44476 × 29 × 162** |
| 体素数 | 208,948,248（≈2.09 亿） |
| 整卷字节（int16，进显存判据） | 417,896,496 B（**398.54 MB**） |
| data.bin（含金字塔） | 199.43 MB（压缩比 2.00×） |
| build 峰值内存 | 4,830 MB（装配阶段 double survey 主导，同 §2.4） |
| 整卷加载耗时（renderB load） | ≈2.8–4.0 s |
| renderB 进程峰值内存 | **≈509 MB**（加载整卷 398 MB + 渲染管线） |
无 build OOM，cellXY=0.05 一次通过，未调粗。
### 4.3 renderB 实测指标 —— **关键发现：整卷体绘制不可行**
命令：`gpr_poc renderB <store> --frames 120`
| 指标 | 值 |
|------|-----|
| 离屏闸门复检 | OK |
| **体绘制 fps** | **INVALID（整卷超 3D 纹理上限）** |
| ├ raw_fps（空纹理渲染，不可信） | 295.6（仅作记录，非真实帧率） |
| ├ SmartVolumeMapper 渲染模式 | 2 = GPURenderMode |
| └ vtkVolumeTexture 报错 | `Invalid texture dimensions [44476, 29, 162]` |
| **切片扫描 fps** | **54.6 fps**（120 帧沿 Z 扫整卷，reslice+纹理） |
| 整卷进显存 | **否**（X=44476 > GL_MAX_3D_TEXTURE_SIZE=16384） |
| 降质重采样（LowRes） | 否（未触发；是直接纹理维度超限失败，非显存不足降质） |
| GPU 显存（NVX） | **N/A**（随包 VTK 安装未带 GLEW 头，无法直查 `NVX_gpu_memory_info`；
但 GL 扩展列表确认该扩展存在，机器支持，仅本工具未链 GL loader） |
| 进程峰值内存 | ≈509 MB |
#### 关键发现（务必看）
1. **整卷体绘制在本机离屏下不可行**：测线 001 的 X 维（沿测线方向）= **44476**，
远超本机 OpenGL `GL_MAX_3D_TEXTURE_SIZE = 16384`。`vtkSmartVolumeMapper`
走 GPU 路径（mode=2）但底层 `vtkVolumeTexture` **无法将整卷上传为单张 3D 纹理**，
报 `Invalid texture dimensions`。此时 `Render()` 实际未绘出体数据，
故所谓 295 fps 是**空纹理渲染的假帧率，已如实标 INVALID，绝不上报为体绘制性能**。
2. **切片扫描真实流畅**：切片走 `vtkImageReslice` 输出 2D 切面 + 2D 纹理着色，
**不受 3D 纹理维度上限约束**，实测 **54.6 fps ≥ 30fps 目标**，整卷切片交互流畅。
3. **进显存判据**：整卷 398 MB 远小于 GPU 显存（RTX 3060 6GB），显存容量不是瓶颈；
真正的瓶颈是**单轴纹理维度上限（16384）**，而非显存字节数。
#### 结论
- **切片**：✅ 本机离屏下整卷切片 ≥30fps（54.6fps），交互流畅，满足目标。
- **整卷体绘制**：❌ 在「整卷成单张 3D 纹理」的朴素路径下**不可行**——
长测线 X 维超 GL 单轴上限。这正是 **Task 12（核外 / 分块 LOD / 体纹理分区
`vtkOpenGLGPUVolumeRayCastMapper::SetPartitions`）** 必须解决的问题：
要么沿 X 分区/分块上传，要么按视相机做 LOD 工作集。本任务（9c）按约束**不做核外**，
仅如实记录此限制作为 Task 12 的硬性依据。
- 该限制与显存容量无关，是 OpenGL 纹理维度硬上限；任何「整卷一次性 3D 纹理」方案
对长测线都会撞同一面墙。

72
docs/superpowers/plans/poc-results-C.md Normal file
View File

@ -0,0 +1,72 @@
# POC-C 单 mapper SetPartitions 整卷体绘制探针结果
## 体
- 维度: 44476 x 29 x 162 (体素 208948248)
- 整卷字节: 417896496 B (398.537 MB, VTK_SHORT)
- store: D:\Git\lanbingtech\geopro\build\tmp\gpr_store_B_001
## 单 mapper SetPartitions
- mapper: vtkOpenGLGPUVolumeRayCastMapper (整卷单 image,不预切块)
- 分区数: SetPartitions(3, 1, 1) 每区上限 ≤16384
- 纹理维度错误: 否
- 渲出非空像素: 是 (非背景像素 1264)
- 体绘制 fps: 10.951667
- 达交互级(≥15fps): 否
- 进程峰值内存: 652.84 MB
- 源构造耗时: 2873.19 ms
## 对照表
| 路径 | 是否渲出 | fps |
|---|---|---|
| renderB 整卷单 SmartVolumeMapper | INVALID(纹理墙) | — |
| renderC MultiBlock(每块一 mapper) | 渲出 | 9.5 静态/1.45 换页 |
| renderC-partitioned 单 mapper SetPartitions | 渲出 | 10.951667 |
## 判据结论
单 mapper SetPartitions 整卷体绘制【真渲出但未达交互级】(10.9517 fps <15)。VTK 这条路天花板暴露,需评估 OpenVDS/自建 GL。
# POC-C LOD-fps 探针结果（Task 12c）
金字塔 store: tmp\store_lod_001（level0=44476x29x162，总 4 层）
| 项 | 维度 | 结果 |
|---|---|---|
| (a) 粗层概览 fps | level2 11119x8x41 | 752.061589 fps (交互级) |
| (b) 全分辨率局部 fps | level0 局部 256x29x162 | 374.625725 fps (交互级) |
| (c) LOD 切换过渡 | 切换帧 60/120 | 平均 1.09062ms，切换帧 5.4629ms（尖峰 6.04704×），无可感知卡顿 |
- 卡顿判据：切换帧绝对耗时 >33ms(2 个 60Hz 帧)才记可感知卡顿；16.7~33ms 记轻微抖动；亚毫秒基线下尖峰倍数大但绝对值低不算卡顿。
- 双闸：纹理维度错误=否；三段均渲出非空像素=是（概览 1889 / 局部 167612 / 过渡 21924）。
- 截图（人眼判“概览糊→拉近清晰”）：docs/superpowers/plans/poc-lod-shots/lod-overview.png、lod-fullres-local.png、lod-transition-mid.png
- 进程峰值内存: 99.2266 MB
## 判据结论
粗层概览 + 全分辨率局部【都达交互级】且切换【无不可接受卡顿】→ LOD-based C 路线钉死可行。
**最低配未验声明**：本探针仅在本机（RTX 3060）跑得上限数字，最低配机器未验证，需用户在目标机跑或提供型号。
# POC-C fps 预算探针结果（Task 12d ②）
金字塔 store: tmp/store_lod_001（level0=44476x29x162，brick=64）
递增 level0 局部窗口（沿线中段 brick 列）体绘制 fps：
| brick段 | 体素数 | 体绘制 fps | ≥30fps |
|---|---|---|---|
| 4 | 1202688 | 218.251659 | 是 |
| 16 | 4810752 | 155.708373 | 是 |
| 64 | 19243008 | 240.948244 | 是 |
| 128 | 38486016 | 305.837001 | 是 |
| 256 | 76972032 | 329.654511 | 是 |
| 512 | 153944064 | INVALID | 否 |
| 695 | 208948248 | INVALID | 否 |
- **每帧体素预算（fps≥30 上限）**: 76972032 体素（256 brick 列）
- 首个跌破 30 的窗口: 无（需更大 --bricks 段触达天花板）
- 双闸：纹理维度错误=是；每段均按非空像素校验。
- production LOD 应把【每帧渲染的全分辨率块】卡在此预算以内。
- **本机 RTX 3060 上限数；最低配需用户在目标机跑 fps-budget/view。**

94
docs/superpowers/plans/poc-results-trackB.md Normal file
View File

@ -0,0 +1,94 @@
# Track B 总验收实测结果（build-stream 多线合并流式建体）
工具：`tools/gpr_poc`（CLI），子命令 `build-stream`。
执行机：Windows 11，MSVC（VS18 Community）+ Ninja，Release（/O2），开发机（RTX 3060 Laptop GPU 旁）。
日期：2026-06-23。
整条流式链路（B1→B5 成果在 B6 串起来）：
`assembleGprSurveySlab（道窗口）→ sampleGprPoint（结构化插值）→ StreamingVolumeWriter（增量 zlib 写 brick）→ buildPyramidStreaming（从盘 brick 逐级降采样）→ WholeVolumeSource(load)`。
> Track B 的核心命题：把建体管线改成沿 X 分段（slab）流式（逐段读道→插值→写 brick→释放），
> 使建「20 线合并大体」的峰值内存**有界、不随线数增长**、无 OOM，且产物可被 `load` 读回。
> 对比基线：旧 double-survey 非流式方案，单线装配峰值 ≈4.2 GB，20 线 ≈84 GB → 装配阶段必然 OOM。
---
## 1. 验收命令
```
gpr_poc build-stream "D:\Downloads\明星路" --cellXY 0.2 --cellZ 0.05 --out <storeDir> --levels 2
gpr_poc load <storeDir>
```
- 合并方式：**沿 X 顺序排列**（退路近似）——各线按 brick 对齐的 X 偏移依次拼入一个连续 store。
真实 RTK 几何拼接（按各线实际平面坐标拼成路网大体）留 **Track D**。
- 量化 scale/offset **全局一致**：先扫一遍全部 20 线得全局 min/max（流式下不能每 slab 各算），
再以全局值域逐线逐 slab 写 brick。
---
## 2. build-stream 实测指标（20 线合并大体，cellXY=0.2，cellZ=0.05，levels=2）
| 指标 | 值 |
|------|-----|
| 合并测线数 | **20** |
| 合并体维度（nx×ny×nz） | **156544 × 8 × 82** |
| 体素数 | **102,692,864**（≈1.03 亿） |
| 原始体积（int16，进显存判据） | **195.871 MB** |
| 落盘 data.bin（含金字塔各级） | **105.422 MB** |
| 压缩比（原始/落盘） | **1.858×** |
| 扫全局量化区间耗时 | **181,288 ms**（一次性读全 14 GB 原始道） |
| 建体（流式 slab→写 brick）耗时 | **89,927 ms** |
| 流式金字塔耗时 | **6,972 ms** |
| build-stream 端到端墙钟 | **278,788 ms（≈4.6 min）** |
| **峰值内存** | **246.164 MB** |
### 峰值内存全程稳定（核心结论证据）
20 线全程峰值内存稳在 **≈246 MB**（245.973 MB → 246.164 MB），**不随合并线数增长**：
| 阶段 | 峰值内存 |
|------|----------|
| 扫全局量化 / 起始线 | 245.973 MB |
| 第 20 线写入完成 | 246.164 MB |
即流式建体的峰值内存**有界**——只随单个 slab + 一行 brick 的工作集，与合并总量（线数/体素数）无关。
对比旧 double-survey 非流式方案 20 线需 ≈84 GB，本方案以 246 MB 建出 1 亿体素的合并大体，**无 OOM**。
---
## 3. load 实测指标 —— 产物可读 ✓
命令：`gpr_poc load <storeDir>`
| 指标 | 值 |
|------|-----|
| 加载耗时 | **1,756 ms** |
| 整卷维度 | **156544 × 8 × 82** |
| 峰值内存 | **214.55 MB** |
流式产出的合并大体 store 可被 `WholeVolumeSource` 完整加载、维度一致、**产物可读**。
---
## 4. Track B 总验收结论
- ✅ **峰值内存有界、与总量无关**：20 线合并大体建体全程峰值稳在 ≈246 MB
（245.973→246.164），不随线数增长。这是 Track B 的核心目标，达成。
- ✅ **无 OOM**：旧非流式方案 20 线 ≈84 GB 必 OOM；流式方案 246 MB 即建出 1 亿体素合并体。
- ✅ **产物可读**：`load` 在 1,756 ms 内读回，维度一致（156544×8×82），峰值 214.55 MB。
- ✅ **压缩与落盘正常**：原始 195.871 MB → data.bin 105.422 MB（含金字塔各级），压缩比 1.858×。
### 已知约束 / 留待后续
1. **扫全局量化 181 s 是「读全 14 GB 原始道」的 I/O 开销**——为保证量化 scale/offset
全局一致必须先全扫一遍 min/max。可后续优化（如复用建体阶段的单遍读、或用头估值域），本次不做。
2. **合并几何用退路近似（沿 X 顺序排列，brick 对齐）**——非真实路网平面几何。
真实 RTK 几何拼接（按各线实际平面坐标拼成路网大体）留 **Track D**。
3. **最低配未验**：仅在本机（RTX 3060 Laptop 开发机）实测；最低配机器内存/磁盘表现待补测。
### 与 Track C 的衔接
Track B 已证「大体能建（246 MB 有界）+ 能读（1.76 s 加载）」。Track C 在此大 store 上做
视野自适应 LOD 体绘制（视锥裁剪+视距选层 → 视野区域单纹理重组 → 平滑切换+后台预取），
解决 POC-B §4 记录的「整卷 X 维超 GL 单轴纹理上限（16384）」问题。

392
docs/superpowers/specs/2026-06-15-vtk-3d-supplementary-design.md Normal file
View File

@ -0,0 +1,392 @@
# VTK 三维视图「补充需求」设计
- 日期：2026-06-15
- 分支建议：`feat/vtk-3d-view`
- 状态：**设计稿 v2（已纳入架构评审 + web 端实地分析）**。本轮只产出设计，实现分期另立 plan。
- 需求来源：`D:\Projects\GEOPRO\Geopro3.0 需求表.xlsx` →「补充需求」页签（已逐行通读，§4 全文映射）；交叉参考「DD类型」页签；原版 web 实地分析见 §1.5、记忆 [[web-3d-view-threetile]]。
- 关键约束（用户已拍板）：
1. **后端 API 尚未就绪** —— 本轮用 `LocalSampleRepository` 静态数据驱动渲染与交互，**但仓储接口必须按真实后端形态设计好**（§6），将来后端到位只换实现、不动上层。
2. 三维相关 ddCode（`dd_Structual3D`/`dd_Property3D`/切片/异常体/任务记录）后端、客户端**都还没做**，是净增建。
3. **三栏结构 + 切片是客户端新需求**（web 端没有三栏，见 §1.5）。故这两块**以 xlsx 为规格、按 VTK 工程新设计**，不受"复刻须先实地学习"约束；而"参考 Geopro 1.0"的色阶/异常框（F26/F50）属复刻项、目前无 1.0 参考、先近似后精修。
---
## 0. TL;DR（一页结论）
「补充需求」整页都是 **VTK 中央视图**的规格：把视图区拆成三个子列表栏（**三维数据集 / 二维数据集 / 三维分析**），并补齐坐标轴、相机预设、底图、**切片交互**、**异常体管理**、三维体详情、任务管理。
**当前真实状态（已源码核实，非推测）：中央 VTK 是空壳。**
- `rebuildCentral`（`src/app/main.cpp:508-512`）只捕获 `showCurtain`，喂入**空 `sections`**；启动后中央区只有背景色 + 相机，不渲染任何数据。
- 浮层勾选框 `chkVoxel/chkSlice/chkTerrain`（`main.cpp:603-617`）只改 `bool`，而 `rebuildCentralScene`（`src/app/CentralScene.cpp:16-47`）只处理 `is2D`/`showCurtain` 两支 —— 体素/切片/地形勾选**当前什么都不做**。
- `slicePlane`（`vtkImagePlaneWidget`，`main.cpp:251`）声明后**全代码零使用**；`buildVoxelFromScatters/buildTerrain/loadVoxelScatters` 在 app 层**零调用**。
**好消息：render 层 actor 全部完整且有测试**（§5.1），数据源 `LocalSampleRepository` 也在。"之前用静态数据做的原型渲染"（git `7007619`/`9b77d07` 等）的**装配代码**在 `6241eb3`"CentralScene 数据驱动重构"时被摘除，但**渲染原语没丢**。
> 一句话：地基（actor 管线）稳固，缺的是「编排层 + 交互层 + 三栏 UI + 真实/样本数据接入」。
**评审已纳入的硬伤修正**（详见各节）：① `Scene` 只能加 `vtkActor`、加不了体绘制 `vtkVolume`，"actor 零改动复活"对三维体不成立 → §5.2/§8 增 `vtkProp` 入口；② `I3dSceneRepository` 必须**异步**（项目已 ApiChain 异步化，同步签名会让"换实现不动上层"破产）→ §6；③ 任意切片**钉死 `vtkImageReslice`**（`vtkCutter` 切体素只出交线不出着色剖面）→ §9.1；④ 接口数据结构去裸 `double[]`/出参 → §6.2/§6.3。
---
## 1. 背景与问题
需求表「补充需求」页签定义的是 Geopro 1.0 风格的三维工作台 —— VTK 视图不再是"二维地图/三维视图"二选一的展示器，而是一个带**子列表 + 工具栏 + 右键菜单 + 切片/异常交互**的分析环境。
当前客户端（M1）的 VTK 现状与之差距：
1. **结构不符**：现在是单一 `QVTKOpenGLStereoWidget` + 顶部「二维地图/三维视图」互斥分段按钮（`main.cpp:308-316`），左下一个统一数据集列表。需求要的是**视图内置三个子列表栏**。
2. **不渲染数据**：见 §0，编排层喂空数据，所有图层勾选是死代码。
3. **无坐标轴 / 无相机预设 / 无底图 / 无切片交互 / 无拾取联动 / 无 3D 异常体 / 无任务面板**：这些都是净增建。
4. **后端缺接口**：已核对 `ApiClient` 端点（§6.0），只有 2D ERT 那套；三维体模型/切片保存/异常创建/任务记录端点客户端都没有，且后端也未做。
---
## 1.5 原版（web）实地分析结论（Playwright + JS 逆推，2026-06-15）
实地分析 `http://tenant.geomative.cn/#/projectSpace/dataView`（详见记忆 [[web-3d-view-threetile]]）：
- **渲染技术栈**：web 3D 地球是 **ThreeTile（Three.js 瓦片地球）**——DOM 无 `cesium-widget`、单 WebGL2 canvas、`__THREE__` 在；Cesium 1.107 虽加载但本页未用。⇒ 桌面用 VTK 是**另一套实现**，三栏/切片是桌面新设计，不存在"web 怎么做桌面照搬"。
- **底图多源已确证**（`threeMap` chunk）：天地图/Google/Bing/高德/腾讯/ArcGIS/Mapbox/中科星图 ⇒ 坐实补充需求 C13 底图需求，桌面 VTK 需自建瓦片层。
- **3D 数据通路已确证**（网络）：勾选 ERT 对象 → 批量 `dd/ert/inversion/rows/{id}`(2D 反演剖面) + `lvl/colorGradation` → 在 3D 地理空间摆成**竖直帘面**（= 桌面 `CurtainActor` 目标）。
- **3D 分析功能集已确证**（index chunk i18n `three*` 键）：模型 选/移/转/缩放/恢复 + X·Y·Z 轴分散；剖切面 开/关/显/隐/平移/旋转；创建异常/异常列表；导出 dat/grd/bin/lvl。3D 模型从 URL 加载。⇒ 这些功能桌面要做，但**实现自定**（web 用 Three.js，桌面用 VTK）。
- **web 不是三栏**：web 是 左(数据筛选+对象树)/中(地球+显示隐藏地图+滑块)/右(异常列表)。补充需求的三栏(三维数据集/二维数据集/三维分析)是**桌面新结构**。
- **威立雅项目只有 2D 反演剖面（帘面），无真正三维体模型**；真三维体（`dd_Structual3D`,"地大展示"）很可能在别的项目，待用户指认后再实地学习其切片/异常几何（不阻塞 P1–P3，因切片可对 LocalSample 体素开发）。
---
## 2. 目标与范围
### 2.1 总目标
在现有 render actor 地基上，复活并扩展中央 VTK 为「补充需求」描述的三维分析工作台；**用静态样本数据驱动**，但所有数据出入口走**为真实后端预留的仓储接口**（§6）。
### 2.2 范围内（本设计覆盖）
- 三子列表栏 UI 结构（三维数据集 / 二维数据集 / 三维分析）。
- 三维数据集栏：坐标轴设置、水平/垂直比例、快捷视图（前后左右上下）、Zoom（In/Out/Fit）、数据集勾选 → 渲染。
- 二维数据集栏：底图（天地图/Google/隐藏）、2D 视图切面位置、数据集勾选 → 渲染。
- 三维分析栏：体模型/切片树、右键菜单、切片交互工具、拾取选中联动、切片分析（含创建异常、保存为数据集、导出、正视/翻转/关闭）。
- 三维体数据集详情、切片数据集详情。
- 异常/异常体管理（树、删除、属性、VTK 联动、显示过滤、截图属性）。
- 任务管理（任务记录 + 可使用任务列表）。
- **仓储接口设计**（§6）—— 本设计的重头，决定将来接后端的成本。
### 2.3 范围外 / 后续
- 后端真实接口实现（本轮仅设计接口 + LocalSample 实现）。
- 克里金插值（IDW 已有；克里金作为插值模型选项后续补）。
- 二维底图的高保真瓦片缓存/离线（本轮先打通"能显示底图"）。
- 与 Web 端完全像素级一致的色阶编辑器（沿用现有 colorBar 解析）。
### 2.4 设计原则
- **render 层零业务**：actor 只吃 `core::*` 数据结构（`Grid/ScalarVolume/ScatterField/Anomaly`），不认 ds/API。复活编排即可，不改 actor。
- **接口先行**：上层只依赖 `I3dSceneRepository`（§6），`LocalSample3dRepository` 与未来 `Api3dRepository` 可互换。
- **交互独立成层**：新建 `src/render/interact/`（README 早有规划但目录不存在），切片/拾取/圈异常都是 `InteractionTool`。
---
## 3. 与既有架构的关系
```
┌─────────────────────────── 中央 VTK 工作台 ───────────────────────────┐
ObjectTreePanel │ ┌ 子列表栏（三选一/并列）────────┐ ┌ VTK 视图区 ──────────────────┐ │
(左上,勾选对象) │ │ [三维数据集] [二维数据集] [三维分析]│ │ Scene(renderer) + actors │ │
│勾选 │ │ · 坐标轴/比例/快捷视图/Zoom 工具条 │ │ + CubeAxes + 底图层 │ │
▼ │ │ · 数据集勾选列表(按维度属性筛) │ │ + InteractionManager(切片/拾取)│ │
VtkSceneController ─┼─→ I3dSceneRepository ─→ core::数据 ─→ render actors ─→ Scene │ │
│ └────────────────────────────────┘ └──────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
右栏: 三维体/切片 详情 · 异常体树 · 任务管理(任务记录 + 可用任务列表)
```
- `VtkSceneController`（新）取代当前散落在 `main.cpp` 的 lambda 编排，订阅"勾选对象/数据集/图层/视图模式"变化，经 `I3dSceneRepository` 取数据，调 render actor 重建场景。
- 现有 `WorkbenchNavController`（对象/数据集导航）、`DatasetDetailController`（详情）保持职责不变，新控制器与之并列。
---
## 4. 「补充需求」全文逐行映射（权威对照表）
> 维度属性来源：需求称"ds 类型的显示属性为 3D/2D"，即**维度属性挂在 ds 类型上**（非单条 ds）。`DsRow` 当前无此字段（`src/data/repo/RepoTypes.hpp:10`），须由 §6.1 的类型→维度映射补。
| 行 | 需求原文（摘） | 现状 | 落地方式 |
|---|---|---|---|
| A1 | VTK 提供三子列表栏：三维数据集/二维数据集/三维分析 | 单一 2D/3D 切换 | §7.1 三栏 UI |
| C3–I3 | 坐标轴显示方式：标准/三维立体/不显示 | 无坐标轴 | `vtkCubeAxesActor`（标准）/`vtkAxesActor`（立体）/隐藏；§7.2 |
| D4 | O 点位置 | 无 | 坐标轴原点配置（世界系原点 / 数据包围盒角）|
| D5–I5 | 刻度：无刻度/米/英尺/经纬度/字体 | 无 | 刻度单位换算 + 经纬度用 `GeoLocalFrame` 反算 + 字体设置 |
| C6 | 水平/垂直比例 | 硬编码 `kVerticalExaggeration=2.0`（`main.cpp:208`）| 做成可调，作用于全部 3D actor `SetScale(1,1,VE)` |
| C7 / D7–I7 | 快捷视图：前/后/左/右/上/下 | `CameraPreset` 仅 Top2D/Free3D | 新增 6 方向预设（§5.3）|
| C8 / D8–F8 | Zoom：In/Out/Fit | 仅 `ResetCamera`(=Fit) | In/Out 调 `camera->Zoom()`；Fit=ResetCamera |
| C9–D10 | 三维数据集列表：筛勾选对象中 ds 维度=3D；勾选多个显示 | sections 为空 | §6.1 维度筛选 + §8 编排复活 |
| C13–F13 | 地图：天地图/Google Map/隐藏 | 中央无底图 | §7.3 底图层（VTK 瓦片）|
| C14 | 2D 视图：关闭/Z=0/顶部/底部/自定义 Z | 无 | 切面高度控制 |
| C15–D16 | 二维数据集列表：ds 维度=2D | 同上 | §6.1 + §8 |
| C19–D20 | 三维分析列表：按 对象/三维体模型/切片 树 | 无 | §7.4 分析树 |
| D21,F22–G22 | 右键·三维体：上下切片 | 无 | §9 轴向切片工具（水平面）|
| F23 | 前后切片 | 无 | §9 轴向切片 |
| F24 | 左右切片 | 无 | §9 轴向切片 |
| F25 | 任意切片（初始 45°，可任意调整）| 无 | §9 任意角度切片（`vtkPlaneWidget` 控面 + **`vtkImageReslice`** 重采样着色，非 `vtkCutter`）|
| F26 | 色阶（参考 Geopro 1.0 优化）| 有 colorBar 解析 | 复用 `ColorScale` + 色阶编辑入口 |
| F27 | 显示/隐藏 | 无 | actor 可见性 |
| F28–G28 | 数据详情 → 详情栏 | 详情面板在 | §10 三维体详情类型 |
| E29,F30–F36 | 右键·切片数据集：保存/保存为/导出/删除/色阶/显隐/详情 | 无 | §6.3 切片 CRUD 接口 + §10 |
| C38,D39 | 选中三维体/切片为中心拖动旋转 | 无拾取/自定义 style | §9.3 拾取 + 自定义 InteractorStyle |
| D40 | 双击切片 → 正视该切片 | 无 | §9.3 双击→相机正视切面法向 |
| C44,D44 | 右键三维体创建切片工具 | 无 | §9 |
| D45 | 双击切片工具正视 | 无 | §9.3 |
| D46 | 选中切片滚轮 → 内外切片（对象=所属三维体）| 无 | §9.2 滚轮沿法向平移切面 |
| D47 | 切片任一位置可保存为新切片数据集 | 无 | §6.3 createSlice |
| D48,E49,F49–F50 | 创建异常：异常工具，光标拾取起点；结束保存弹框（确定截图大小/异常坐标，参考 1.0）| 有 2D `AnomalyActor`，无创建流 | §9.4 异常圈定工具 + §6.4 saveAnomaly + 截图 |
| E51–F51 | 保存为数据集 | 无 | §6.3 |
| E52–F52 | 导出为图片 | 无 | `vtkWindowToImageFilter` |
| E53–F53 | 导出到 dat | 无 | 切面采样导出 |
| E54–F54 | 正视图 | 无 | §9.3 |
| E55–F55 | 视图翻转（水平旋转 180°）| 无 | 相机 `Azimuth(180)` |
| E56–F56 | 关闭（取消当前切片）| 无 | 移除切片工具 |
| A58,B59–B65 | 三维体详情：源数据/切片数据/异常/插值模型(克里金,IDW)/插值参数/色阶参数/测量(点数,体积)| 详情引擎在，类型未做 | §10.1 |
| A67 | 切片详情：参照 dd_Section | `dd_section` 渲染已有 | §10.2 复用 |
| A69,B70,C71–D77 | 异常体列表树：异常体→分组→异常 | `ObjectExceptionPanel` 只读树在 | §11 扩展为可操作 |
| C79,D80–D81 | 操作：删除/删除分组 | 无 | §6.4 delete/deleteGroup |
| C83,C84 | 异常属性 + VTK↔列表 双向选中联动 | 无联动 | §9.3 + §11 |
| B86,C87–F87 | 异常体显示过滤：全部显示/随GS/随数据集/全部隐藏 | 无 | §11 过滤模式 |
| B88,C88 | 异常增加截图属性（保存标识时截图）| 无 | §6.4 截图字段 |
| A90,C90 | 任务管理：任务记录 + 可使用任务列表 | 有 `model/list`，无任务面板 | §12 |
| B91,C91 | 任务记录：当前数据集调用任务的记录 | 无 | §6.5 taskRecords |
| B92,C92 | 可使用任务列表：与 ds 类型相符的任务插件 | `ModelInfo`(model/list) 在 | §6.5 usableTasks(按 ddType 过滤) |
---
## 5. 现状资产盘点（render 层，已源码核实）
### 5.1 可直接复用的 actor（完整 + 有测试）
| 组件 | 文件 | 吃什么 | 产出 | 复用于补充需求 |
|---|---|---|---|---|
| ScatterActor | `src/render/actors/ScatterActor.*` | `ScatterField+ColorScale` | 散点 actor | 三维体源数据点 |
| GridContourActor | `actors/GridContourActor.*` | `Grid+ColorScale` | 色带+等值线 | 切片面着色 |
| VoxelActor | `actors/VoxelActor.*` | `ScalarVolume+ColorScale+原点/间距` | **GPU 体绘制 `vtkVolume`**，可导出内部 `vtkImageData` | 三维体模型渲染 + 切片输入 |
| VoxelFromScatters | `render/VoxelFromScatters.*` | 多剖面散点+CRS+frame | IDW→体绘制+image | 三维体（散点插值）|
| AnomalyActor | `actors/AnomalyActor.*` | `vector<Anomaly>` | 点/折线/多边形（**2D 剖面**）| 切片上异常圈定（需扩 3D 异常体）|
| TerrainActor | `actors/TerrainActor.*` | DEM+影像 GeoTIFF | 纹理地形 | 三维场景地形图层 |
| CurtainActor | `actors/CurtainActor.*` | `Grid+ColorScale+frame` | 竖直帘面 | dd_section 三维帘面 |
| MapLineActor | `actors/MapLineActor.*` | `Grid+frame` | 俯视红线 | 二维数据集测线 |
| ElectrodeActor | `actors/ElectrodeActor.*` | `Grid` | 电极 ▼ | 剖面电极 |
| ColorLutBuilder / ContourBands | `render/ColorLutBuilder.*` `ContourBands.*` | colorBar | LUT / 离线等值线几何 | 色阶 / 导出 |
### 5.2 缺口（净增建）
- **Scene 加不了体绘制**（评审 HIGH）：`Scene::addActor(vtkActor*)`（`src/render/Scene.hpp`）只收 `vtkActor`，而 VoxelActor 产物 `vtkVolume` 是 `vtkProp3D`、**不是** `vtkActor`。三维体（核心需求）渲染必经此口 → P1 须给 Scene 加 `addViewProp(vtkProp*)`（或 `addVolume(vtkVolume*)`），5 行小改，但"actor 零改动复活"对三维体不成立。
- **坐标轴**：无 `vtkCubeAxesActor`/`vtkAxesActor`。
- **相机预设**：`CameraPreset.cpp` 仅 `applyTop2D`/`applyFree3D`，缺前后左右上下 + Zoom In/Out。
- **底图**：无 VTK 瓦片底图层（README 提的 `ground/TileGroundLayer` 未实现）。
- **切片交互**：`vtkImagePlaneWidget` 声明未用；无 reslice/cutter/任意角度切片；`src/render/interact/` 目录不存在。
- **拾取/选中联动**：无 picker、无自定义 `vtkInteractorStyle`。
- **3D 异常体**：`AnomalyActor` 仅 2D 剖面；无三维异常体 actor、无 VTK↔列表联动。
- **截图**：无 `vtkWindowToImageFilter` 接线。
- **编排层**：`rebuildCentralScene` 喂空数据；图层勾选死代码。
### 5.3 CameraPreset 扩展（小量、低风险，可独立先做）
新增 `applyView(vtkRenderer*, ViewDir)`，`ViewDir ∈ {Front,Back,Left,Right,Top,Bottom}`，设置 position/focalPoint/viewUp 后 `ResetCamera`；`zoomIn/zoomOut` 调 `camera->Zoom(1.2 / 0.83)` 后 `Render`。
---
## 6. 仓储接口设计（本设计重头 —— 用户要求"接口设计好"）
> 现状：`IDatasetRepository`（`src/data/repo/IDatasetRepository.hpp`）已有 2D 那套（loadGrid/Scatter/ColorScale/Anomalies）。本设计**新增并列接口 `I3dSceneRepository`**，承载三维体/切片/异常体/任务。本轮 `LocalSample3dRepository` 实现（读样本文件 + 内存态增删），将来 `Api3dRepository` 换实现。
> **接口必须异步（评审 HIGH）**：项目已 ApiChain/`IAsyncProjectRepository` 异步化。`I3dSceneRepository` 取数方法**一律走回调/Qt 信号**（如 `void loadVolume(dsId, std::function<void(VolumeGrid)> onOk, OnErr onErr)`，或返回 `ApiChain`），LocalSample 同步数据也包成异步壳。否则将来换 Api 实现会阻塞 UI、上层全要改，"换实现不动上层"破产。下文签名为**简化示意（省略回调形参）**，落地按异步范式。
### 6.0 后端端点现状（已核对，非推测）
现有 `ApiClient` 仅：`dd/ert/{grid,inversion,measurement,trajectory}`、`dsObject` CRUD/import/detail、`exception/queryException`（**只读**）、`model/list`、`lvl/colorGradation`、`templateExport`。
**缺**：三维体模型数据、切片 CRUD、异常**创建/保存**、任务记录。→ 本轮接口为这些预留方法签名，LocalSample 内存实现。
### 6.1 维度属性（解决"ds 维度=3D/2D"筛选）
```cpp
enum class DsDimension { Dim2D, Dim3D, Analysis3D, Other };
// 由 ds 类型（ddCode / dsTypeId）决定。LocalSample 用内置映射表；
// 未来后端可在 dsObject/getDetail 返回 dimension 字段。
DsDimension dimensionOf(const DsRow& ds) const; // 列表筛选用
```
> LocalSample 映射（依据「DD类型」页签语义）：`dd_Structual3D`/`dd_Property3D`/`dd_voxel` → `Dim3D`/`Analysis3D`；`dd_section`/`dd_inversion_data` 帘面可入 3D，俯视测线入 2D；`dd_trajectory_data` → `Dim2D`。
### 6.2 三维体模型数据集
```cpp
struct VolumeModelMeta {
std::string dsId, name;
std::string interpMethod; // "IDW" / "Kriging" / ...
std::vector<DynamicFormField> interpParams; // 插值参数（复用既有动态表单字段）
std::string colorScaleId; // 色阶参数引用
double pointCount = 0, volume = 0; // 测量数据（点数/体积）
std::vector<std::string> sourceDsIds; // 源数据集
std::vector<std::string> sliceDsIds; // 切片数据集
std::vector<std::string> anomalyBodyIds; // 异常体
};
// 规则体 + 原点/间距聚合返回（去 double& 出参，评审 MEDIUM）
struct VolumeGrid {
geopro::core::ScalarVolume vol;
std::array<double,3> origin; // ox,oy,oz
std::array<double,3> spacing; // dx,dy,dz
double vmin = 0, vmax = 0;
};
VolumeModelMeta loadVolumeMeta(const std::string& dsId); // 异步示意
VolumeGrid loadVolume(const std::string& dsId); // 异步示意
```
> LocalSample：用 `VoxelFromScatters` 把样本两条交叉剖面散点 IDW 成 `ScalarVolume` 当作一个三维体模型（产物即含 `vtkImageData`，切片直接复用）。
### 6.3 切片数据集（CRUD —— 后端缺，先内存实现）
```cpp
struct SliceSpec {
std::string volumeDsId; // 所属三维体
std::array<double,3> origin; // 切面一点（去裸数组，评审 MEDIUM）
std::array<double,3> normal; // 切面法向（轴向/任意）
std::string colorScaleId;
};
struct SliceDataset { std::string dsId, name; SliceSpec spec; geopro::core::Grid section; };
// 落库 CRUD（进仓储）：
std::string createSlice(const SliceSpec& spec, const std::string& name); // 保存为数据集→返回新 dsId
void saveSlice(const std::string& dsId, const SliceSpec& spec); // 保存
void deleteSlice(const std::string& dsId);
// 导出：导图片/dat 由 UI 层用 vtkWindowToImageFilter / 采样写文件（不入仓储）
```
> **实时切片不进仓储（评审 MEDIUM）**：交互拖切面时每帧重采样应直接走 VTK 管线（`vtkImageReslice` 挂在切片工具上，§9.1），**不**经 repository 回算 `Grid`（避免慢路径）。仓储只管"切片保存为数据集"这种持久化动作。
### 6.4 异常 / 异常体（树 + CRUD + 截图）
```cpp
struct AnomalyBody { // 对应"异常体"（树中间层）
std::string id, name, typeName;
std::vector<core::Anomaly> members; // 组内异常（复用既有 2D Anomaly；3D 用包围几何）
};
struct AnomalyTree { // 对象 → 异常体/分组 → 异常
std::vector<AnomalyBody> bodies;
std::vector<core::Anomaly> loose; // 未分组异常
};
AnomalyTree loadAnomalyTree(const std::string& objectId);
std::string saveAnomaly(const core::Anomaly& a, const std::string& screenshotPngPath); // 截图属性
void deleteAnomaly(const std::string& anomalyId);
void deleteAnomalyGroup(const std::string& bodyId);
// 显示过滤是 UI/渲染层状态，不进仓储：enum AnomalyFilter{All,FollowGs,FollowDs,None}
```
### 6.5 任务管理
```cpp
struct TaskRecord { std::string id, taskName, status, createTime; }; // 任务记录
struct UsableTask { std::string scriptId, scriptCode, name; int opType; }; // = 既有 ModelInfo
std::vector<TaskRecord> loadTaskRecords(const std::string& dsId); // 当前 ds 的调用记录（后端缺→空/样本）
std::vector<UsableTask> loadUsableTasks(const std::string& ddCode); // 按 ds 类型过滤插件（复用 model/list）
```
---
## 7. UI 设计
### 7.1 三子列表栏（客户端新设计 —— web 无三栏）
> 已确认（§1.5）：web 端**没有三栏**，三栏是补充需求为桌面定义的新结构，以 xlsx 为准设计。
在 VTK dock 内（或左侧新 dock）放三个可切换 tab/分段：**三维数据集 / 二维数据集 / 三维分析**。每栏顶部是该栏专属工具条，下方是数据集勾选列表（按 §6.1 维度筛选当前勾选对象的 ds）。
**职责切分（决策，不再是开放问题）**：保留现有 `ObjectTreePanel`（左上勾选对象）作为"对象勾选源"；三栏列表只在被勾选对象范围内、按维度过滤显示 ds。**左下数据集列表服务"详情查看"，三栏列表服务"VTK 渲染勾选"**——两条线并存。依据：web 端本身也是"对象树勾选 + 独立异常列表"的多列表结构，两条线与原版心智一致；且补充需求明确三栏服务于 VTK 渲染，与详情查看是不同动作。
### 7.2 三维数据集栏工具条
坐标轴下拉（标准/立体/不显示）+ O 点 + 刻度（无/米/英尺/经纬度）+ 字体 | 水平/垂直比例（滑块/输入）| 快捷视图（前后左右上下 6 钮）| Zoom（In/Out/Fit）。
### 7.3 二维数据集栏
底图下拉（天地图/Google/隐藏）+ 2D 视图位置（关闭/Z=0/顶部/底部/自定义 Z）。
**底图层（评审 HIGH：被低估，单列风险子项）**：web 用 ThreeTile 多源瓦片（§1.5 已确证：天地图/Google/Bing/高德/腾讯…）。桌面 VTK 无现成瓦片图层，需自建小型瓦片引擎：可视范围 → 瓦片行列号 → 异步拉 PNG → 贴 `vtkPlaneSource`+texture → 随相机换 LOD。**关键配准**：天地图瓦片是 EPSG:3857，须把每块瓦片范围反算到 `GeoLocalFrame` 局部米才能与帘面/体素对齐（复用 `TerrainActor` 已有的 3857→4326→frame 流程）。本轮先打通"天地图能显示+隐藏"，Google/缓存/LOD 后续。**排 P5**（复杂度高、依赖天地图 token）。
### 7.4 三维分析栏
树：对象 → 三维体模型数据集 → 切片。右键菜单按节点类型分派（三维体 / 切片，见 §4 行 D21–F36）。
---
## 8. 渲染编排层 `VtkSceneController`（复活原型）
职责：聚合"勾选对象 + 当前栏 + 图层开关 + 视图模式"→ 经 `I3dSceneRepository` 取 `core::*` → 调 actor → `Scene`。**取代 `main.cpp` 里的 `rebuildCentral` lambda 与死掉的图层标志。**
```cpp
class VtkSceneController : public QObject {
// 输入信号：勾选对象变 / 栏切换 / 图层勾选 / 比例变 / 快捷视图 / 切片增删
// 内部：维护 ScalarVolume/Grid 缓存，按需重建；统一 SetScale(1,1,VE)
// 输出：scene.clear()+addActor()+renderWindow->Render()
};
```
落地第一步（最低风险、最快见效）：把 `extractSlice`/`loadVolume`/`buildCurtain`/`buildVoxelFromScatters`/`buildTerrain` 用真实勾选 ds 接通 —— **render actor 零改动即复活**。
---
## 9. 交互层 `src/render/interact/`（新目录，最重模块）
### 9.1 切片工具
- **轴向切片**（上下/前后/左右）：`vtkImagePlaneWidget` 贴体素 `vtkImageData`（VoxelActor 已能导出 image），沿固定轴向、自动重采样着色，角度不可调（符合 G22–G24）。
- **任意切片**（F25）：`vtkPlaneWidget`（控制面位姿）+ **`vtkImageReslice`**（按斜面对体素重采样出着色剖面），初始 45°，可任意旋转。**不用 `vtkCutter`**（评审 HIGH：cutter 切 `vtkImageData` 只产几何交线/多边形，得不到带标量的连续剖面图）。
- 统一抽象 `SliceTool`：持切面位姿 + `vtkImageReslice`，直接产出贴 `vtkImageActor` 的着色剖面（避免回算 `core::Grid` 的绕路；仅"保存为数据集"时才转 Grid 落库）。
### 9.2 滚轮切片（D46）
选中切片 → 自定义 InteractorStyle 截 `OnMouseWheel` → 沿切面法向平移 origin → 重算切面。
### 9.3 拾取 + 选中联动（C38/D39/D40/C84）
`vtkPropPicker` + 自定义 `vtkInteractorStyle`：
- 选中三维体/切片 → 以其包围盒中心设相机 focalPoint（拖动绕其旋转）。
- 双击切片 → 相机正视切面法向（D40/D45/E54）。
- 拾取异常体 ↔ 异常树列表双向高亮（C84）。
### 9.4 异常圈定工具（D48/E49/F49–F50）
自定义 widget：光标拾取起点 → 连续描点成多边形（复用 `core::Anomaly` Polygon）→ 结束弹保存对话框（截图大小 / 异常坐标，参考 Geopro 1.0）→ `saveAnomaly(a, screenshot)`。截图用 `vtkWindowToImageFilter`。
> **异常几何 = 切片面上的多边形（决策，不再是开放问题）**：需求 F49"以光标拾取点为起点圈异常"+ web 同款（在切片上描点），即异常是**画在切片平面上的多边形**——本质 2D-in-3D，把多边形顶点存为切面局部坐标 + 切面位姿即可在 3D 中定位。**不需要真三维体几何**。故 `core::Anomaly`(2D 多边形) 复用成立，§6.4 `AnomalyBody.members` 用 `core::Anomaly` + 所属切面引用即可。截图属性（B88）即圈定时的视图截图。
---
## 10. 详情视图
### 10.1 三维体详情类型（新）
详情面板（`DatasetDetailPanel`，ddCode 驱动）新增三维体详情：源数据 / 切片数据 / 异常 / 插值模型(IDW·克里金) / 插值参数 / 色阶参数 / 测量(点数·体积)。数据来自 `VolumeModelMeta`（§6.2），多为表单/列表展示。
### 10.2 切片详情
参照 `dd_section`（已有渲染），复用现有等值面+等值线引擎。
---
## 11. 异常体管理面板
扩展现有 `ObjectExceptionPanel`（当前只读树）为可操作：
- 树：对象 → 异常体 → 异常（含未分组异常）。
- 操作：删除 / 删除分组（§6.4）。
- 异常属性面板（选中异常显详情）。
- VTK↔列表双向选中联动（§9.3）。
- 显示过滤：全部显示 / 随 GS / 随数据集 / 全部隐藏（渲染层可见性状态）。
- 异常截图属性（保存时存截图，§6.4）。
---
## 12. 任务管理面板（新）
两段：
- **任务记录**：当前数据集的任务调用记录（`loadTaskRecords`，后端缺→样本/空态）。
- **可使用任务列表**：按当前 ds 的 ddCode 过滤的任务插件（`loadUsableTasks`，复用 `model/list`）。
---
## 13. 开放问题 / 待确认
### 已决（评审 + 实地分析后关闭）
- ✅ **三栏 vs 左下列表**：两条线并存（三栏=渲染勾选、左下=详情查看），web 本身即多列表结构（§7.1）。
- ✅ **异常 3D 表达**：异常 = 切片面上的 2D 多边形，复用 `core::Anomaly`，无需真三维体几何（§9.4）。
- ✅ **任意切片技术**：`vtkImageReslice`，非 `vtkCutter`（§9.1）。
- ✅ **接口异步 + 数据结构**：异步范式 + `VolumeGrid`/`std::array` 聚合（§6）。
### 仍开放（不阻塞 P1/P2，相关期开工前定）
1. **坐标系单位 / O 点**（§7.2，P2）：刻度"经纬度"用 `GeoLocalFrame` 反算；"米/英尺"基于世界米。O 点默认世界原点还是数据包围盒角？→ P2 开工前定，倾向"数据包围盒角"。
2. **切片"保存为数据集"落库形态**（§6.3，P3）：本轮 LocalSample 内存态；是否持久化到本地文件以便重启可见？
3. **真三维体项目**（§1.5，P3/P4）：威立雅无真三维体；需用户指认有 `dd_Structual3D` 的项目，实地学习其切片/异常几何与交互细节。**不阻塞 P3**（切片对 LocalSample 体素先开发）。
4. **"参考 Geopro 1.0"**（F26 色阶 / F50 异常保存框，P4）：目前无 1.0 参考 → 先用现有 colorBar 解析 + 标准保存框近似，拿到 1.0 后精修。
5. **底图 token / Google 可用性**（§7.3，P5）：天地图需 token；Google 国内可用性。本轮先天地图 + 隐藏。
---
## 14. 分期建议（详细 plan 另立，此处仅排序）
1. **P1 复活渲染（地基，低风险）**：`VtkSceneController` + `I3dSceneRepository`/`LocalSample3dRepository` + 勾选 ds → 真实/样本数据 → actor。复活帘面/体素/地形/切面着色。
2. **P2 三维数据集栏（纯前端，独立）**：坐标轴 + 水平/垂直比例 + 快捷视图 6 向 + Zoom。
3. **P3 三维分析·切片交互（最重）**：`interact/` + 轴向/任意切片 + 滚轮 + 拾取联动 + 双击正视 + 正视/翻转/关闭 + 切片 CRUD + 导出。
4. **P4 异常体 + 圈异常 + 详情 + 任务**：异常圈定工具 + 异常体树管理 + 三维体详情 + 任务面板（依赖 1.0 参考）。
5. **P5 二维底图**：天地图瓦片层 + 2D 视图位置。
> 依赖：P1/P2/P3 均可用 xlsx + 现有代码 + LocalSample 开工（切片对 LocalSample 体素开发，§1.5）。P4 的色阶/异常框精修依赖 Geopro 1.0 参考（先近似）；P3/P4 的真三维体细节待用户指认 3D 项目后实地补。P5 底图依赖天地图 token。
>
> **可立即开工：P1（含 Scene 加 vtkProp 入口）+ P2。** 评审结论：spec 修订后可作为 plan 基础。

130
docs/superpowers/specs/2026-06-16-vtk-3d-three-column-refactor-design.md Normal file
View File

@ -0,0 +1,130 @@
# 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 版本号后回落默认排布，可接受）。

183
docs/superpowers/specs/2026-06-17-vtk-3d-volume-slice-anomaly-design.md Normal file
View File

@ -0,0 +1,183 @@
# VTK 三维：三维体 / 切片 / 异常 —— 数据模型与客户端交互设计
- 日期：2026-06-17
- 范围：桌面客户端 VTK 三维视图里的「三维体模型(体素) / 切片 / 异常」三类数据及其交互。是补充需求页"三维分析"栏的落地设计。
- 依据：①《Geopro3.0 需求表.xlsx》「补充需求」页（行号见引用）；② 与产品方就 6 个设计问题的确认；③ 现有代码。
- 原则：缺后端端点的**先本地 mock**（保证功能可见可用），端点就绪后切真实；能纯客户端做的先做。
> **⚠ 更正（2026-06-18，本文档以下异常部分已被修订，以此为准）**——实现计划见 `plans/2026-06-18-vtk-3d-anomaly.md`，结构铁律见记忆 `vtk-3d-persistence-structure`：
> 1. **异常挂「三维体」**（`remarkSourceId` = 三维体 ds id），**不挂切片**（§1.3 的 `parentSliceId` 作废）——切片是临时圈定载体，业务语义上异常属于三维体（需求 R61）。
> 2. **`remarkSourceType` = 标注形态**（1点/2线/3面/4文字），**不是**"来源实体类型"（§3 原表述更正，实证 `commercial-admin/contourPage.vue:386`）。接口不限定挂载实体类型，`remarkSourceId` 放谁 id 挂谁。
> 3. 异常请求体**无截图字段**；补充需求 **R88「增加截图属性」**证实截图是待新增属性 → 现 mock 本地存。
> 4. **摆放**：3D 异常的"场景控制"（树+显示过滤 R86-87+VTK 选中联动 R84+显隐+删除）放**三维分析区**；右侧「对象异常」面板 = 异常全集 master（暂连后端 2D，整链就绪后并入 3D）。
> 5. 异常**独立显隐**靠 R86-87 过滤（全部显示/随GS/随数据集/全部隐藏），**不被三维体勾选绑死**。
---
## 1. 核心数据模型
三者都是**可持久化的数据集**，层级关系：`三维体 → 切片 → 异常`。
### 1.1 三维体（VolumeModel）
ddCode：`dd_voxel` / `dd_Structual3D` / `dd_Property3D`（需求行 245/290/291）。
- `id` / `name`
- **`sourceDatasetIds[]`（源数据）**：一组输入数据集，用于插值生成本体（需求行 401）。
- **`interpModel`**：插值模型，克里金 / IDW（需求行 404）。
- **`interpParams`**：插值参数（cellXY/cellZ/power/maxDist 等，需求行 405）。
- `colorScale`（色阶参数，行 406）。
- `grid`：体素网格 = `ScalarVolume` + `origin/spacing/vmin/vmax`（= 现有 `VolumeGrid`）。
- `measure`：测量数据，点数/体积（行 407，派生量）。
- 派生：`slices[]`、`anomalies[]`（汇总该体下所有切片圈定的异常，行 403）。
**来源（行业经验）**：① 多条 2D 反演剖面/散点/钻孔点 → IDW/克里金插成 3D 体（最常见）；② 直接 3D 采集（三维高密度等，本身即 3D，单数据集）。`sourceDatasetIds` 为 1 个或多个。
### 1.2 切片（Slice）
ddCode：`dd_slice`。
- `id` / `name`
- **`parentVolumeId`**：所属三维体（行 389：切片对象=所属三维体模型）。
- **`plane`**：切面 = `SliceSpec`（轴向/原点/法向/偏移）。
- `colorScale`。
- 生命周期：交互式"切片工具"是**临时**的（在体上实时切）；**保存后才成为持久化的 `dd_slice` 数据集**，进入三维分析栏列表（行 390）。
### 1.3 异常（Anomaly）
- `id` / `name`
- **`parentSliceId`**：异常画在某切片平面上、附着于该切片（行 392 创建异常在切片右键）。
- `polygon`：圈定多边形（切片平面内的坐标）。
- `screenshot` + 元信息（截图大小、异常坐标，行 393）。
- 向上归属：三维体详情的"异常"= 汇总该体下所有切片圈定的异常（行 403）。
---
## 2. 客户端交互流（需求"三维分析"栏 + VTK 视图右键）
### 2.1 三维分析栏（列表）
- 按「**对象 / 三维体模型 / 切片**」三级树显示（行 366）。
- 勾选一个或多个三维体或切片 → 显示在三维视图（行 367）。
- **三维体右键**（行 368–375）：切片▸（上下/前后/左右/任意）、色阶、显示/隐藏、数据详情。
- **切片右键**（行 376–383）：保存、保存为、导出、删除、色阶、显示/隐藏、数据详情。
### 2.2 切片工具（行 369–372, 387–389）
- 上下/前后/左右切片：在三维体中心或光标位置打开**水平切片工具，角度不可调**。
- 任意切片：初始角度 = 当前视图 45°，可任意调整。
- 选中切片滚轮 → 沿法向往内/外推进；切片对象 = 所属三维体（行 389）。
- 双击切片 → 视角调正为正视该切片（行 386/388）。
### 2.3 VTK 视图里对切片的右键（行 391–399）
- **创建异常**：弹异常工具，以光标拾取点为起点圈定；结束保存时弹对话框（截图大小、异常坐标），参考 Geopro1.0。
- **保存**：保存为数据集（切片数据集）。
- **导出为图片** / **导出到 dat**。
- **正视图** / **视图翻转(水平 180°)** / **关闭**。
### 2.4 创建三维体（**已定：客户端创建**）
产品确认创建三维体在**客户端**侧。
- 「三维数据集」栏多选若干 3D 数据集（反演剖面）→ 菜单「生成三维体」→ 选插值模型/参数 → 客户端 `IdwInterpolator` 插值 → 三维体。
- 持久化：后端**无三维体端点**（见 §3）→ 先本地 mock（内存/本地文件），端点就绪后切真实。
---
## 3. 后端依赖 vs 本地 mock（已核对 web 源码 `commercial-admin/src/apis`）
| 能力 | 现有端点 | 方案 |
|---|---|---|
| 展示已有三维体（取网格） | ❌ 无（`/model/*` 只有 ResIPy 反演/雷达，无三维体网格） | **mock**：以源数据集散点 IDW 出体（`IdwInterpolator`） |
| 创建三维体（插值） | ❌ 无（无三维空间插值端点） | **客户端做**（IdwInterpolator）；持久化 mock |
| 三维体/切片**持久化** | ❌ 无写端点 | **mock**：内存/本地存；端点就绪后切真实 |
| 切片创建/交互 | — 纯客户端 | ✅ 已有（`SliceTool`/`InteractionManager`） |
| 切片保存/另存/导出/删除 | ❌ 无切片端点 | 保存/删除 → mock(内存)；导出图片/dat → **客户端做**（截图/写文件） |
| 异常**读取** | ✅ `POST /exception/queryExceptionTree`、`queryException`/`queryExceptionByTmObjectId` | **接真实** |
| 异常**新增** | ✅ `POST /business/exception` | **接真实** |
| 异常**更新** | ✅ `PUT /business/exception` | **接真实** |
| 异常**删除** | ✅ `DELETE /business/exception/{exceptionId}` | **接真实** |
| 异常类型 | ✅ `GET /exceptionType/queryExceptionTypeByProjectIdAndType/{projectId}/{remarkSourceType}`、`/exceptionType/getDetail/{id}` | **接真实** |
| 异常体(exceptionConsortium) | ✅ `POST/PUT /exceptionConsortium`、`/page`、`/export`、`/getDetail/{id}` | **接真实** |
| 任务记录/可用任务 | ❌（`/model/task/page` 是反演任务，非三维分析任务） | mock |
### 异常新增请求体（web 实证 `datasetInfo/index.js:212`）
`POST /business/exception`：
```
{ exceptionName, exceptionTypeId, location:{...圈定坐标...},
projectId, remarkSourceId, remarkSourceType, remark }
```
- `remarkSourceId` / `remarkSourceType`：异常所附着的对象（本场景=切片数据集 id + 其类型）。
- `location`：圈定多边形坐标。截图：保存对话框含截图（行 393），上传方式参考 `exceptionInfos/modalNewException.vue`。
- 更新：`PUT /business/exception` `{ id, exceptionName, remark }`；删除：`DELETE /business/exception/{exceptionId}`；详情：`GET /business/exception/getDetail/{exceptionId}`。
---
## 4. 代码现状（落点）
- 维度归类：`LocalSample3dRepository::dimensionOf`（dd_voxel/Structual3D/Property3D/section/inversion → 3D；dd_slice → Analysis）。
- 体素：`core::IdwInterpolator`（IDW 现成）、`render::buildVoxel`/`VoxelActor`（体绘制）、`VoxelFromScatters`（散点→体）。
- 切片交互：`render::interact::SliceTool` + `InteractionManager`（已可在体素 image 上切，含上下/前后/左右/任意）。
- 仓储接口：`I3dSceneRepository` 已定义 `loadVolume / createSlice / saveSlice / deleteSlice / loadAnomalyTree / saveAnomaly / deleteAnomaly / deleteAnomalyGroup / loadTaskRecords / loadUsableTasks`。
- `LocalSample3dRepository`：以上多为**内存 mock**（slices_/anomalies_ map）。
- `Api3dRepository`：以上多为 **stub(`kNotReady`)** — 真实数据未接。
- UI：`Column3DAnalysis` 已定义信号（sliceRequested/colorScaleRequested/visibilityToggled/detailRequested/sliceSave|SaveAs|Export|Delete）；`main.cpp` **仅接了 sliceRequested + detailRequested**，其余未连。
---
## 5. 待产品确认（更新 2026-06-17）
1. **创建三维体在客户端还是平台？** → **已定：客户端**（§2.4）。
2. **后端三维体/切片/任务端点时间表？** → 暂未知。当前 web 源码**无**三维体网格、三维插值、切片、三维分析任务端点 → 这些**先 mock**（保持 `I3dSceneRepository` 接口不变，端点就绪后仅换实现）。
3. **异常写端点？** → **已找到**（§3）：`POST/PUT/DELETE /business/exception` + 类型/异常体一整套 → 异常**接真实**，不 mock。
剩余待确认（次要）：
- 异常保存对话框的**截图上传**方式/字段（参考 `exceptionInfos/modalNewException.vue`，落地时细化）。
- 三维体/切片本地 mock 的持久化形态（纯内存 vs 本地文件，影响重启后是否还在）。
---
## 6. 实现拆解（对应"剩余工作" #2–#6，缺端点先 mock）
按依赖与价值排序：
1. **三维体（mock 渲染）**：把当前勾选/源数据反演剖面散点 → `IdwInterpolator` → `VolumeGrid` → `VoxelActor`。`Api3dRepository::loadVolume` 由 stub 改为"取源数据散点 + IDW"（mock）。→ 解锁三维体显示 + 切片有可切对象。
2. **切片交互接通三维体**：体素就位后，三维体右键"切片▸"已能创建切片（现有 SliceTool）。补：选中切片滚轮推进、双击正视。
3. **切片保存/另存/导出/删除**：保存/删除 → Api3dRepository 改内存 mock（同 LocalSample）；导出图片(截图)/dat(写文件) → 客户端实现。VTK 视图切片右键菜单接线。
4. **异常**：切片右键"创建异常"→ 圈定工具 + 保存对话框（截图/坐标）。**全套接真实端点**：新增 `POST /business/exception`、更新 `PUT /business/exception`、删除 `DELETE /business/exception/{id}`、读 `queryException*`/`queryExceptionTree`、类型 `exceptionType/*`、异常体 `exceptionConsortium/*`。`remarkSourceId/Type` 填切片数据集。
5. **分析栏右键菜单接线**：色阶、显示/隐藏（纯客户端）、切片保存/另存/导出/删除（接 #3）。
6. **三维体/切片/异常详情**：数据详情栏展示源数据/插值参数/色阶/测量(点数·体积)/异常列表。
> 每步：客户端能做的先做、缺端点的内存 mock 留出可替换缝（保持 `I3dSceneRepository` 接口不变，仅换实现）。
---
## 7. 三维体持久化策略与存储结构（2026-06-17 定）
### 7.1 策略：参数为准 + 明细可选缓存 + 缺则惰性重算
- **保存**：
- **必存**：插值参数（源数据引用 + 插值模型/参数 + 色阶）+ **网格规格 `GridSpec`**(origin/spacing/dims)。
- **可选存**：网格明细值（体素标量，nx·ny·nz）。
- **加载**：
- **有明细** → 直接渲染明细。
- **无明细** → 按参数把值**重算填入已存的 `GridSpec`**（坐标系固定），再渲染。
- **理由**：参数小且可复现（详情面板要展示）；明细贵、但稳定一致；`GridSpec` 必存以**锚定切片/异常坐标**（它们定义在体网格坐标系上，重算必须落在同一规格里，否则错位）。
### 7.2 何时建议存明细
| 体的情形 | 建议 |
|---|---|
| 带切片/异常 | **存明细**（与源数据生命周期解耦，重算变形风险归零） |
| 网格大 / 插值慢 | **存明细**（避免每次加载实时重算的卡顿） |
| 纯展示、源数据稳定、网格小 | 可只存参数（省存储），加载时重算 |
### 7.3 重算路径的两个前提（UI/逻辑需兜住）
1. **源数据仍在且可取**：源数据集被删/改 → 重算失败或结果变 → 应回退提示 / 阻止。
2. **算法确定性**：同参数同输入 → 同结果（IDW 确定）；算法升级时旧体优先用已存明细，避免变形。
### 7.4 存储结构（字段定义，驱动实现）
**三维体元数据（必存，进数据集元数据）`VolumeBuildParams`**：
- `sourceDatasetIds[]`：源数据集 id 列表。
- `interpModel`：枚举 IDW / Kriging。
- `interpParams`：`{ cellXY, cellZ, power, maxDist, ... }`（按模型）。
- `colorScaleId` 或内联色阶。
- `gridSpec`：`{ ox, oy, oz, dx, dy, dz, nx, ny, nz }`（**必存**，锚定坐标）。
- `vmin, vmax`、`measure{ points, volume }`（派生，可缓存）。
**三维体明细（可选，进数据集数据文件）**：
- `values`：`ScalarVolume`（nx·ny·nz 标量，maxDist 外为 NaN=空）。
**与现有代码的关系**：
- 现 `data::VolumeGrid = { ScalarVolume vol; origin[3]; spacing[3]; vmin; vmax }` ≈ "明细 + 规格(部分)"。
- 落地改造：拆出 `VolumeBuildParams`（含 `GridSpec`）为必存元数据；`vol`（values）为可选。`I3dSceneRepository::loadVolume` 返回时：若有 values 直接给 `VolumeGrid`；若无，则用 `VolumeBuildParams` 现场 `IdwInterpolator` 重算出 `vol` 再给（坐标用存好的 `gridSpec`）。
- mock 阶段：客户端 IDW 同时产出 params(含 spec) 与 values，两者本地存；接口签名不变，后端就绪后元数据走数据集属性、values 走数据文件。

341
docs/superpowers/specs/2026-06-17-web-embed-subpage-mount-design.md Normal file
View File

@ -0,0 +1,341 @@
# 原版 Web 系统「子页面嵌入挂载」最小侵入改造设计
- 日期：2026-06-17
- 状态：**设计稿 v2（已经 opus 双评审 + 代码实测修订，可据以实现）**
- 涉及仓库：
- **Web 端（被改造方）**：`D:\Git\lanbingtech\commercial-admin`（Vue3 + Vite + Arco，hash 路由）
- **客户端（接入方）**：`D:\Git\lanbingtech\geopro`（Qt + `QWebEngineView`）
- 需求背景：客户端需把原版 web 系统的**单个子功能页**（如"系统管理"下的组织/用户/角色，以及项目空间下的数据视图等）**裸挂**进客户端窗口，不带原系统的"标题栏 + 左菜单 + 页签"外壳，复用既有页面与鉴权。
- 设计约束（用户已确认）：
1. **尽可能少改动原有代码**——既有函数保持行为零变化，优先"新增"而非"修改"。
2. token 注入：客户端用 `QWebEngineProfile` 预置 localStorage（首选）或 `loadStarted` 注入，token **不进 URL**。
3. 挂载范围：**同时支持租户空间页面（`space=2`）与项目空间页面（`space=3`，需 `projectId`）**。
> v2 修订摘要（详见 §10）：EmbedLayout 必须写成**懒加载函数**（否则被 `cloneDeep` 拷坏）；`generateEmbedRoutes` 必须定义在 **store 闭包内**；**独立 `QWebEngineProfile` 由建议升为强制**，并在生成路由前清理 pinia 持久化残留；token 注入首选 profile 预置。
---
## 0. 为什么不能直接挂 URL（约束根因，已对照代码）
| 阻碍 | 证据 | 含义 |
|---|---|---|
| 所有业务页面都是 `Layout` 子路由 | `stores/modules/route.js` `transformComponentView`：`'layout'→Layout`；`layout/index.vue` = Asider+Header+Tabs+Main | 任何路径渲染都带整套外壳 |
| 业务路由运行时才动态注册 | `router/guard.js` `beforeEach` → `generateRoutes()`/`generateSpaceRoutes()` → `router.addRoute` | 不跑守卫，目标路由不存在，直接访问 404 |
| 进入需登录态 + 空间上下文 | `getToken()` 读 `localStorage['token']`；`space==2/3`；项目空间依赖 `projectStore.projectId`（`computed(projectItem.id)`） | 必须先备好 token / projectId 再生成路由 |
> 结论：裸挂子页 = 必须同时解决 **①去外壳、②触发动态路由生成、③补登录态/projectId** 三件事。
---
## 1. 总体方案：新增「embed 引导入口 + EmbedLayout」，叠加而非改造
新增固定路由 `/embed` 作为引导页：读 URL 参数 → 备好上下文 → 调用**新增的** `generateEmbedRoutes`（用 `EmbedLayout` 包裹，无外壳）→ `router.replace` 到目标子页。正常登录链路**完全不经过**这些新增物。
### 1.1 嵌入 URL 规范（统一入口，参数驱动）
hash 路由下统一入口为 `/#/embed`，目标子页靠 query 指定：
```
http://<host>/#/embed?space=<2|3>&projectId=<pid>&target=<encodeURIComponent(叶子页路径)>
```
| 参数 | 必填 | 说明 |
|---|---|---|
| `space` | 是 | `2`=租户空间，`3`=项目空间 |
| `projectId` | 仅 `space=3` | 项目空间页面所属项目 id |
| `target` | 是 | 叶子菜单路由路径，经 `encodeURIComponent` 编码 |
示例：
- 系统管理·用户列表（租户）：`http://<host>/#/embed?space=2&target=%2ForganiMange%2FuserList`
- 项目空间·数据视图：`http://<host>/#/embed?space=3&projectId=123&target=%2FprojectSpace%2FdataView`
> token 不进 URL（由客户端 profile 预置注入，见 §4）。`target` 即 `/organiMange/userList` 这类原叶子菜单路径，`encodeURIComponent` 后 `/`→`%2F`。
### 1.2 改造性质：一次性框架级，非逐页改造
§2 列的 5 处改动全部是**框架级**（路由层 + 一个引导页 + 一个空壳布局），**与任何具体业务页无关**。改造完成后：
- **嵌入任意叶子菜单页 = 只改 URL 的 `target`/`space`/`projectId`**，业务页代码一行不动。
- 不存在"为某个页面单独做嵌入适配"的工作。
唯一两个"非纯 URL"例外且均已收敛、非逐页：
- **D 类**（极少数读 `currentSpace` 的页）：引导页对 `space=2` **统一**补 `getEnterpriseUserInfoFun`（§3.2），一处兜底覆盖，非逐页。
- **详情页带参**：属行点击详情、**不在叶子菜单范围**（§11）。
---
## 2. 改动分级（核心：既有逻辑零修改）
| 项 | 文件 | 性质 | 是否改既有逻辑 |
|---|---|---|---|
| ① 新增 `EmbedLayout.vue` | `commercial-admin/src/layout/EmbedLayout.vue` | 全新文件 | 否 |
| ② 新增引导页 `embed/index.vue` | `commercial-admin/src/views/embed/index.vue` | 全新文件 | 否 |
| ③ 注册 `/embed` 固定路由 | `commercial-admin/src/router/route.js` | 在 `constantRoutes` **插入一项（404 兜底之前）** | 否（不动既有项） |
| ④ 新增 `generateEmbedRoutes` | `commercial-admin/src/stores/modules/route.js` | **store 闭包内新增函数** + 给 `formatAsyncRoutes` 加 `export` | 既有函数体零修改 |
| ⑤ guard 顶部早返回 | `commercial-admin/src/router/guard.js` | **唯一的"修改"**：`beforeEach` 顶部加 `if(embed) return` | 既有分支原样保留 |
| ⑥ 客户端注入 token + 拼 URL + 独立 profile | `geopro` 客户端新增 `QWebEngineView` | 客户端侧新增 | 否 |
> 唯一动到既有执行路径的是 ⑤，做成"顶部早返回"。验收基线：**不带 `/embed`、且 `EMBED_MODE` 未点亮时，执行路径与改造前一致**。
---
## 3. Web 端详细设计
### 3.1 ① `EmbedLayout.vue`（新文件）
仅保留 `<a-config-provider>` + `<router-view>`，**不引入** Asider/Header/Tabs/DkFooter，**也不要 keep-alive**（`cacheList` 由 Tabs 组件填充，embed 无 Tabs 故恒为空，keep-alive 是死代码，去掉更简单——见 §10 M2）。
```vue
<template>
<a-config-provider :locale="arcoLocale">
<a-layout class="embed-main">
<router-view v-slot="{ Component, route }">
<component :is="Component" v-if="Component" :key="route.path" />
</router-view>
</a-layout>
</a-config-provider>
</template>
<script setup>
import { useI18n } from 'vue-i18n'
import { arcoLocales } from '@/plugins/locales/i18n.js'
defineOptions({ name: 'EmbedLayout' })
const { locale } = useI18n()
const arcoLocale = computed(() => arcoLocales[locale.value])
</script>
<style scoped>.embed-main{width:100%;height:100%;overflow:hidden}</style>
```
> `useI18n`/`arcoLocales` 是全局插件，裸挂可用（评审已核实）。
### 3.2 ② 引导页 `views/embed/index.vue`（新文件）
无业务渲染（仅 loading/错误占位）。`onMounted` 内按序引导，**关键顺序**：先清理 pinia 持久化残留 → 写 `projectItem.id`（项目空间）→ 生成路由 → replace。
```js
onMounted(async () => {
try {
sessionStorage.setItem('EMBED_MODE', '1') // 点亮 embed 标志（仅本 profile/tab）
const { space, projectId, target } = route.query // token 已由客户端预置/注入 localStorage
const sp = Number(space)
// ① 清理持久化残留，防止跨会话/复用 profile 时脏读（见 §10 S3/M3）
routeStore.$reset()
projectStore.$reset()
// ② 设置空间标识（廉价、无害，避免子页/外壳读到错误值）
routeStore.isProjectSpace = (sp === 3)
await userStore.getInfo() // 复用既有；401 时 /auth/user/info 被拦截器排除→仅 reject
if (sp === 3) {
projectStore.projectItem.id = projectId // 先写！generateEmbedRoutes(3) 读 projectId=computed(id)
} else {
await appStore.getEnterpriseUserInfoFun() // space=2 默认补企业信息(写 currentSpace)，覆盖"企业空间"类叶子页
}
await routeStore.generateEmbedRoutes(sp) // 新增函数
router.replace(decodeURIComponent(target)) // 进入目标子页，EmbedLayout 生效
} catch (e) {
console.error('[embed] bootstrap failed:', e)
// 显示错误占位，不主动跳登录（embed 无登录交互）
errorMsg.value = '页面加载失败，请检查登录态或权限'
}
})
```
### 3.3 ③ 注册 `/embed`（`route.js`，插入 404 兜底之前）
`constantRoutes` 中 `/:pathMatch(.*)*` 是兜底项，`/embed` 必须**插在它之前**（精确路由优先，避免匹配歧义）：
```js
export const constantRoutes = [
{ path: '/redirect', /* ...既有不动... */ },
{
path: '/embed',
name: 'Embed',
component: () => import('@/views/embed/index.vue'),
meta: { hidden: false },
},
{ path: '/:pathMatch(.*)*', /* 404 兜底，保持在最后 */ },
{ path: '/403', /* ... */ },
]
```
### 3.4 ④ `generateEmbedRoutes`（`route.js` **store 闭包内**新增）
复用既有 `formatAsyncRoutes`/`flatMultiLevelRoutes`，**仅把顶层路由的 `component` 由 `Layout` 换成 `EmbedLayout`**（动态路由顶层节点恒为外壳包裹层；`flatMultiLevelRoutes` 只展平 children、不动顶层 component——评审已核实机制成立）。
**两处必须遵守（否则跑不起来，见 §10 S1/必错-1）：**
1. `EmbedLayout` 写成**懒加载函数**，与 `Layout` 一致。原因：`generateEmbedRoutes` 内沿用既有 `cloneDeep`，lodash 对**函数**按引用返回、对**组件 options 对象**会深拷贝并拷坏。静态 `import EmbedLayout` 是对象 → 必被拷坏。
2. 函数定义在 `storeSetup()` **闭包内**（与 `generateRoutes`/`generateSpaceRoutes` 并列），否则 `setRoutes`/`router`/`projectStore` 未定义（它们是闭包内符号）。
```js
// 模块顶层：给既有 formatAsyncRoutes 加 export（纯导出，零行为变化）
// 并新增懒加载的 EmbedLayout（不要静态 import！）
const EmbedLayout = () => import('@/layout/EmbedLayout.vue')
// —— 以下定义在 storeSetup() 内部，与 generateRoutes/generateSpaceRoutes 并列 ——
const generateEmbedRoutes = (space) => {
return new Promise((resolve, reject) => {
const p = space === 3
? getProjectRouteLimts({ projectId: projectStore.projectId })
: getUserRoute()
p.then((res) => {
try {
const tree = space === 3
? toArrayTree(res.data)
: searchTree(res.data, (i) => Number.parseInt(i.clientType) === 2)
const asyncRoutes = formatAsyncRoutes(tree) // 既有函数，零修改
asyncRoutes.forEach((r) => { r.component = EmbedLayout }) // ← 去外壳关键一步（顶层换壳）
setRoutes(asyncRoutes)
const flat = flatMultiLevelRoutes(cloneDeep(asyncRoutes)) // cloneDeep 对函数式组件按引用，安全
for (const route of flat) {
if (!isHttp(route.path) && !router.hasRoute(route.name)) router.addRoute(route)
}
resolve()
} catch (e) { reject(e) }
}).catch(reject)
})
}
// return { ...原有, generateEmbedRoutes }
```
> `generateRoutes`/`generateSpaceRoutes`/`transformComponentView` **函数体一行不动**，正常登录仍走它们（带 `Layout`）。
> `router.hasRoute(route.name)` 是对既有 `generateSpaceRoutes` 里 `hasRoute(route)`（误传对象）的修正用法，仅用于新增函数内部，不影响既有。
### 3.5 ⑤ guard 顶部早返回（`guard.js` 唯一修改）
`router.beforeEach` **最顶部**（`NProgress.start()` 之后）加：
```js
// —— embed 嵌入模式：放行，鉴权 + 路由生成由 /embed 引导页自管 ——
if (to.path === '/embed' || sessionStorage.getItem('EMBED_MODE') === '1') {
NProgress.done()
return next()
}
```
既有所有分支（登录判断/空间检测/白名单/版本检测）**整段保留**。
**注意（见 §10 S2）**：早返回是 embed 下唯一放行路径——`router.replace(target)` 的二次 `beforeEach` 靠 `EMBED_MODE==='1'` 兜住，跳过 `generateSpaceRoutes`（避免再生成 Layout 版路由覆盖 EmbedLayout 版）。因此 `EMBED_MODE` 的可靠性是硬约束，必须配合独立 profile（§4）与生成前 `$reset`（§3.2）。
---
## 4. 客户端 ↔ Web「嵌入契约」（geopro 侧）
**强制：每个 embed 视图使用独立 `QWebEngineProfile`**，与系统浏览器登录态、与正常登录链路隔离，避免 pinia 持久化（routeStore/projectStore/userStore 均 `persist` 到 localStorage）跨链路污染。
token 注入**首选 profile 预置**（彻底消除时序竞态），`loadStarted` 注入为备选：
```cpp
// 首选：独立 profile + 预置脚本，在文档创建早期写 localStorage
auto* profile = new QWebEngineProfile(QStringLiteral("geopro-embed"), parent); // 独立 profile
QWebEngineScript s;
s.setInjectionPoint(QWebEngineScript::DocumentCreation);
s.setWorldId(QWebEngineScript::MainWorld);
s.setSourceCode(QStringLiteral(
"localStorage.setItem('token','%1');"
"localStorage.setItem('refleshToken','%2');").arg(token, refleshToken));
profile->scripts()->insert(s);
auto* page = new QWebEnginePage(profile, parent);
auto* view = new QWebEngineView(parent);
view->setPage(page);
// 目标页/空间/项目id 走 query（非敏感）；hash 路由下 query 在 # 之后
// 租户(系统管理类): http://<host>/#/embed?space=2&target=%2ForganiMange%2FuserList
// 项目空间(数据视图): http://<host>/#/embed?space=3&projectId=<pid>&target=%2FprojectSpace%2FdataView
view->setUrl(QUrl(url));
```
约定：`target` 用 `encodeURIComponent` 编码（含 `/`），引导页 `decodeURIComponent` 还原。
---
## 5. 关键边界与风险（已对照代码确认）
1. **项目空间生成顺序**：`generateEmbedRoutes(3)` → `getProjectRouteLimts({projectId: projectStore.projectId})`，`projectId=computed(projectItem.id)`。**必须先 `projectItem.id=` 再生成**，否则拉空菜单 → `target` 404。`projectItem` 是 reactive，直接赋值即触发 computed（评审已背书）。
2. **target 须在该账号权限内**：后端按角色过滤菜单，无权限页生成后仍无该路由 → 仍 404。属权限问题。
3. **EMBED_MODE 隔离（安全关键）**：用 `sessionStorage`，**严禁持久化**；并**强制独立 profile**。否则普通访问可能误进 embed 分支、跳过鉴权（见 §3.5/§10 S3）。
4. **pinia 持久化残留**：`routeStore`/`projectStore`/`userStore` 均 `persist`(localStorage)。引导页生成前必须 `$reset`，否则复用 profile 时回灌旧 projectId / 旧路由表（§10 M3）。
5. **后端零改动**：复用 `getUserRoute`/`getProjectRouteLimts`，不碰接口。
6. **token 时序**：profile 预置脚本在 DocumentCreation 注入，早于 Vue 初始化与首个守卫，无竞态（优于 `loadStarted`，见 §10 可能-1）。
7. **token 失效行为**：`http.js:70` 仅对**非** `/auth/user/info` 的 401 弹"重新登录"并跳 `/login`。embed 下 token 失效会弹标准 401 框→无外壳的登录页；属可接受边界，由客户端决定是否重新引导。
8. **外壳态依赖**：`isProjectSpace`/`currentSpace` 仅外壳组件与"企业空间"专页消费（已 grep 确认）。普通业务子页裸挂安全；目标若为企业空间专页（`enterpriseManage/enterpriseSpace`、`setting/profile` 等），引导页需补 `appStore.getEnterpriseUserInfoFun()`。
---
## 6. 非目标（本轮 OUT）
- 不改造外壳组件本身；不为子页做独立 Vite 打包入口；不在 web 端做 token 刷新的嵌入式交互；不用"CSS 隐藏外壳"临时方案（外壳仍实例化、有副作用，已否决）。
---
## 7. 验收标准
1. **回归基线**：不带 `/embed` 且 `EMBED_MODE` 未点亮的所有访问行为与改造前一致；`generateRoutes`/`generateSpaceRoutes`/`transformComponentView`/`formatAsyncRoutes` 函数体未改（仅 `formatAsyncRoutes` 加 `export`）。
2. **租户空间挂载**：`#/embed?space=2&target=%2ForganiMange%2FuserList` 渲染用户列表且**无外壳**，数据正常。
3. **项目空间挂载**：`#/embed?space=3&projectId=<pid>&target=%2FprojectSpace%2FdataView` 正常渲染、projectId 正确。
4. **token 不外泄**：URL/历史/日志无 token；localStorage token 由 profile 预置成功。
5. **隔离**：普通浏览器新 tab 访问业务页，`EMBED_MODE` 不存在、守卫照常生效。
---
## 8. 回滚
新增物删除即回滚；guard 早返回分支删除即恢复。无数据/接口副作用。
---
## 9. 实现顺序
1. Web：EmbedLayout.vue → embed/index.vue → route.js 注册 + `generateEmbedRoutes`（闭包内、懒加载壳）→ guard 早返回。
2. 浏览器手验 `space=2`（console 预置 `localStorage.token` + `sessionStorage.EMBED_MODE=1` 后访问 `#/embed?...`）。
3. 验 `space=3`（有效 projectId）。
4. 客户端独立 profile + 预置脚本接入，端到端联调。
---
## 10. 评审修正记录（opus 双评审 + commercial-admin 代码实测）
**已采纳为硬性修正（不改跑不起来）：**
- **S1 / 必错-2（闭包作用域）**：`generateEmbedRoutes` 定义在 `storeSetup()` 内（`route.js:103-183` 区间），否则 `setRoutes`/`router`/`projectStore` ReferenceError。→ 已落到 §3.4。
- **必错-1（cloneDeep 拷坏组件）**：`EmbedLayout` 必须懒加载函数 `() => import()`。lodash `cloneDeep` 对作为对象属性的**函数按引用返回**（故原系统 `Layout=()=>import()` 正常），对**静态导入的组件 options 对象会深拷贝**并破坏 Vue 内部标识。→ 已落到 §3.4。
- **S3（持久化污染 + 隔离）**：`routeStore/projectStore/userStore` 均 `persist`(localStorage)。EmbedLayout 路由会被持久化，复用 profile 时污染正常链路/反之。→ 独立 profile 升为**强制**（§4），生成前 `$reset`（§3.2）。
- **M3（projectId 脏读）**：`dataView` setup 阶段快照式读 `projectId`（`views/projectSpace/dataView/index.vue:132`），叠加 persist 可能回灌旧值。→ `projectStore.$reset()` + 先赋值后生成（§3.2）。
- **token 时序（可能-1）**：`loadStarted` 的 `runJavaScript` 异步排队，不保证早于首个守卫。→ 改用 profile 预置脚本 DocumentCreation 注入为首选（§4/§5.6）。
- **/embed 插入位置（需确认-4）**：插在 `/:pathMatch(.*)*` 之前（§3.3）。
- **keep-alive（M2）**：EmbedLayout 去掉 keep-alive（cacheList 恒空）（§3.1）。
**已核实成立、予以背书（原 spec 正确）：**
- 顶层 `component` 换 EmbedLayout 去外壳机制成立（`formatAsyncRoutes` 顶层节点 component 即外壳，`flatMultiLevelRoutes` 不动顶层 component）。
- `projectStore.projectItem.id = projectId` 触发 computed，先赋值后生成"必要且充分"。
- `searchTree`/`toArrayTree` 用法与既有 `generateRoutes`/`generateSpaceRoutes` 一致。
- `useI18n`/`arcoLocales` 全局可用。
- 回归基线（仅 `formatAsyncRoutes` 加 `export` + guard 顶部分支）可验证。
**结论**：方向正确、工作量可控；上述硬性修正纳入 v2 后，**可据本 spec 进入实现**。"必错-1/必错-2"是两个不改连跑都跑不起来的点，实现时务必遵守 §3.4 两条约束。
**已核实安全（原列为"现场确认"，实为静态可查，已查清）：**
- 外壳 provide/inject 依赖：`grep` 确认 `src/layout` + `App.vue` **零 `provide()`**；外壳对事件总线**零 emit**。两个首批目标页 `organiMange/userList.vue`、`projectSpace/dataView/index.vue` 自身**既不 `inject()` 也不订阅任何 bus**。现存 `inject()` 仅在 `projectSpace/datasetInfo` 子树（colorLevel/contourLevel/GprHeader），是页面内部父子 provide，与外壳无关。`coustomEventBus`（`utils/event-bus.js`）定义后全仓无消费方。→ **裸挂这两页对外壳上下文依赖为 0，安全**。其他目标页若纳入，按同样三步静态核对（外壳 provide？页面 inject？总线发射方是否在外壳？）即可，无需等运行时。
**实现前必须用真实菜单接口数据核验（唯一未离线证实项）：**
- **顶层菜单 component 恒为 `'layout'`**（见 §11 E 类）：`generateEmbedRoutes` 换壳逻辑 `asyncRoutes.forEach(r => r.component = EmbedLayout)` 假设每个顶层路由都是外壳包裹层。需抓一次真实 `getUserRoute`（space=2）与 `getProjectRouteLimts`（space=3）响应，确认所有顶层节点 `component === 'layout'`（而非直接页面或 `ParentView`）。若存在非 layout 顶层，换壳会渲染空白 → 改为"仅替换 component 原为 'layout' 的顶层节点"。
**仍需留意：**
- embed 路由 name 与正常路由同名：独立 profile 下 embed SPA 不会生成 Layout 版路由，无冲突；若未来同一 SPA 既登录又 embed，需给 embed 路由 name 加前缀。
---
## 11. 覆盖范围：所有叶子菜单可导航页面（已代码实测）
**结论：本方案完整覆盖"所有叶子菜单可导航到的页面"。** 因为叶子菜单导航 = 只给路径，进入所需上下文仅 `path + space + projectId`，恰为 embed 契约所提供；且这些页路由与正常登录一致生成，仅顶层外壳由 `Layout` 换为 `EmbedLayout`。
### 为何成立（实测依据）
- **叶子菜单页不带行参数**：靠 `?id=` 进入的详情页（`projectMange/projectConfiguration/details`、`templateManage/details`、`datasetInfo` 等）是从列表页**行点击 `router.push` 带参**进入的（证据：`projectMange/configuration.vue:91`、`projectSpace/templateManage/index.vue:105`），**不属于叶子菜单**，不在本范围内。
- **项目空间叶子页自取数据**：`abnormalBody/List`、`dataMange`、`projectStructure` 等自调 `getGsTreeFun`/`queryProjectGsStruct`（证据：`grep` 命中 `src/views/projectSpace/*`），不依赖前序页面预加载的 store → 可独立裸挂。
- **页内向自身详情下钻仍可用**：叶子页里行点击 push 到详情页时，该详情路由**也已在同空间一次性生成（EmbedLayout 版）**，故详情同样无外壳渲染。
### 边界（非阻断，已收敛）
- **D 类（极少数读外壳态的叶子页）**：如"企业空间"读 `currentSpace`。引导页对 `space=2` 默认补 `appStore.getEnterpriseUserInfoFun()`（§3.2 已落），`isProjectSpace` 亦在引导页设置 → 覆盖。
- **C 类（仅当嵌入页内"跨空间/回首页"）**：单个叶子页本身不受影响；只有离开本页、跨租户↔项目空间或回工作台的跳转会脱离 embed 语境。属"离开该叶子页"的范畴，非"该叶子页能否嵌"。
- **E 类（唯一结构性前提）**：换壳假设顶层菜单 component 恒为 `'layout'`。本系统所有业务页现均带外壳，强烈暗示成立；但需用真实菜单接口数据核验（见 §10「实现前必须核验」）。
- **F 类（不适合/无意义）**：login/redirect/error；以及"导航中枢"类（工作台、项目列表，职责即切空间/进项目，单独嵌无意义）。这些通常也不是普通叶子功能菜单。

116
docs/superpowers/specs/2026-06-18-vtk-3d-volume-slice-detail-dialog-design.md Normal file
View File

@ -0,0 +1,116 @@
# 设计：三维体/切片 数据详情（只读属性对话框）
> 日期 2026-06-18。分支 `feat/vtk-3d-view`。收尾/打磨项 #6（见 `docs/superpowers/HANDOFF-vtk-3d.md` §4 末「下一步候选」）。
> 异常详情已用对话框做掉（`AnomalyPropertiesDialog`），本设计为**三维体 / 切片**补同类只读详情。
## 1. 目标与范围
三维分析栏右键「数据详情」时，弹出只读属性对话框展示该三维体 / 切片的元数据与统计。
- **形态**：只读 `QDialog`（仿 `AnomalyPropertiesDialog`），非停靠面板页签。
- 取舍理由：现成 `DatasetDetailController/Panel` 绑定 2D 的 `IAsyncDatasetRepository` + chartRegistry，而体/切片数据在 `Api3dRepository`（独立 3D 仓储），硬接需跨仓储桥接 + 新策略/视图，代价大、动共享设施风险高。对话框与刚落地的异常详情 UX 一致、零侵入 2D 管线。
- **内容范围**：参数/位姿随时可取；三维体统计（值域/测点数/范围）体被生成（loadVolume 缓存）后才显示，未生成显「—（生成/渲染后可见）」。
## 2. 架构与新增文件
仿 `src/app/AnomalyPropertiesDialog.{hpp,cpp}`，`QFormLayout` + `QLabel` 只读表：
| 文件 | 职责 |
|------|------|
| `src/app/VolumePropertiesDialog.{hpp,cpp}` | 三维体属性（参数 + 统计） |
| `src/app/SlicePropertiesDialog.{hpp,cpp}` | 切片属性（位姿 + 参数） |
两个对话框各自独立、构造即填充、`exec()` 模态，无网络、无加载态。
## 3. 数据获取
只改具体类 `src/data/api/Api3dRepository.{hpp,cpp}`；**接口 `I3dSceneRepository` 与 `LocalSample3dRepository` 不动**（`main.cpp` 持有具体 `scene3dRepo`，见 main.cpp:266，全程直接用）。
### 3.1 三维体 getter（新增）
```cpp
// Api3dRepository.hpp 内嵌结构 + 方法
struct VolumeInfo {
VolumeBuildParams params;
std::string name;
bool loaded = false; // cachedGrid 是否已就绪（= loadVolume 跑过）
// 以下仅 loaded 时有效：
double vmin = 0.0, vmax = 0.0; // 来自 cachedGrid
int nx = 0, ny = 0, nz = 0; // 网格维度
double dx = 0, dy = 0, dz = 0; // 单元间距（来自 cachedGrid.spacing）
std::size_t pointCount = 0; // 聚合后参与插值的散点数
};
bool volumeInfo(const std::string& dsId, VolumeInfo& out) const; // 非体返回 false
```
- `loaded` 取 `StoredVolume::cachedGrid.has_value()`；统计字段从 `cachedGrid`（vmin/vmax、`vol.nx()/ny()/nz()`、`spacing`）填。
- **测点数持久化**：`StoredVolume` 增 `std::optional<std::size_t> pointCount`，在 `finalizeVolume`（散点聚合完成处）写入 `pts.v.size()`。`volumeInfo` 透出。
### 3.2 切片数据
复用已有 `bool sliceSpec(const std::string& dsId, SliceSpec& out) const`（main.cpp 已在用）取位姿；名称用 `detailRequested` 信号已携带的 `name`，不新增 getter。
## 4. 触发与接线（`main.cpp`）
`detailRequested` 仅来自三维分析栏（`Column3DAnalysis`，项非体即切片；右键菜单「数据详情」已接，无需改 Column3DAnalysis），现连接 `detailCtrl.openDataset`（对 3D dsId 会降级失败）。改为按 ddCode 分派：
```cpp
QObject::connect(ca, &Column3DAnalysis::detailRequested, &window,
[&window, scene3dRepo](const QString& dsId, const QString& ddCode, const QString& name) {
if (ddCode == QStringLiteral("dd_slice")) {
I3dSceneRepository::SliceSpec sp;
if (scene3dRepo->sliceSpec(dsId.toStdString(), sp)) {
SlicePropertiesDialog dlg(name, sp, &window); dlg.exec();
}
} else { // dd_voxel
Api3dRepository::VolumeInfo info;
if (scene3dRepo->volumeInfo(dsId.toStdString(), info)) {
VolumePropertiesDialog dlg(name, info, &window); dlg.exec();
}
}
});
```
`src/app/CMakeLists.txt` 加两个新 `.cpp`。
## 5. 内容字段
### 三维体（`VolumePropertiesDialog`）
- 名称
- 源数据集（`sourceDatasetIds`，逗号连接）
- 插值模型（IDW / Kriging）+ 幂指数（IDW 时显 `power`）
- 网格间距（`XY=cellXY m Z=cellZ m`）
- 超距（`maxDist m`）
- 色阶来源（`colorScaleId`，空显「首个源数据集」）
- **统计**（loaded 才有，否则全显「—（生成/渲染后可见）」）：
- 值域（`vmin ~ vmax`）
- 网格（`nx × ny × nz`）
- 测点数（`pointCount`）
- 范围（`nx·dx × ny·dy × nz·dz` 米）
### 切片（`SlicePropertiesDialog`）
- 名称
- 所属三维体（`volumeDsId`）
- 轴向（0 上下 / 1 前后 / 2 左右 / 3 任意）
- 平面三点 Origin / Point1 / Point2（各 `(x, y, z)` 米，2 位小数）
- 色阶来源（`colorScaleId`，空显「首个源数据集」）
> 切片**不含统计项**：采样分辨率/值域来自渲染时的切面网格，仓储层不持久化（`StoredSlice` 仅存 `spec`+`name`）。回写渲染产物属额外 plumbing，守 YAGNI 不做。位姿/参数已完整。
## 6. 错误处理
- `volumeInfo` / `sliceSpec` 取不到（非体/非切片）→ 返回 false，不弹空对话框（理论不发生，触发来自该行）。
- 统计未就绪 → 占位「—（生成/渲染后可见）」，不报错。
## 7. 测试
- 新增 gtest（`tests/` 内 Api3dRepository 测套，若无则新建）覆盖 `volumeInfo`：
- `createVolume` 后、`loadVolume` 前：`volumeInfo` 返回 true、`params`/`name` 正确、`loaded=false`、`pointCount=0`。
- `loadVolume` 成功后：`loaded=true`、`vmin<vmax`、`nx/ny/nz>0`、`pointCount>0`。
- 非体 dsId：返回 false。
- 对话框为纯只读 UI（无逻辑分支），不做单测，靠 GUI 实测（Claude 无法 GUI 验证，交用户）。
## 8. 影响面 / 不变量
- 接口 `I3dSceneRepository` 与 `LocalSample3dRepository` 零改动 → 真实后端就绪后切换不受影响。
- `finalizeVolume` 仅多写一个 `pointCount`，不改插值/渲染行为。
- 不与 VTK 三维视图交互（详情只读查阅，职责清晰）。

111
docs/superpowers/specs/2026-06-19-vtk-3d-color-scale-editor-design.md Normal file
View File

@ -0,0 +1,111 @@
# 三维体/切片 色阶编辑器（复刻原版 web「色阶配置」）— 设计
> 关联交接：`docs/superpowers/HANDOFF-vtk-3d.md` §「真实色阶编辑」候选项。
> 原版参考：`commercial-admin/src/views/projectSpace/datasetInfo/components/comm/`
> （`colorLevel.vue` 外层 + `colorEditor.vue` 内层 + `contourLevel.vue`/`contourLine.vue` 子弹框 + `colorUtils.js` 算法）。
## 0. 目标与边界
把右键「色阶」占位（main.cpp `colorScaleRequested` → "色阶设置开发中"）替换为可用的色阶编辑对话框，
1:1 复刻原版 web 数据集详情页「色阶配置」对话框（`colorLevel.vue`）的核心交互，应用后驱动
体素 / 切片 / 帘面 重新着色。
后端 3D 色阶保存接口未就绪 → 持久化先走**会话级 mock**（控制器 `volumeScaleCache_`，再勾选命中缓存）。
## 1. 分期（P1 本期）
| 期 | 范围 | 验收 |
|----|------|------|
| **P1 ✅** | 主表编辑器：表格（层级/颜色）+ 新增/删除 + 双击改值/改色 + 确定应用 | 编辑后体/切片即时变色 |
| **P2 ✅（层级⚙）** | 层级⚙（分层方式 normal/log/equalArea + 间隔↔层数联动 + 校验）→ 重算层级分布并按旧色阶插值取色 | 改分层后色带分布变化 |
| **P2 ✅（线形⚙ + 共享）** | 线形⚙（线型/线显/线色/标注显/标注色，复刻 contourLine.vue）；编辑器做成 **2D 数据集视图 + 3D 共用**，输出 `{colorScale, lineConfig, labelConfig}` | 2D 数据集视图改线色/线型/标注色即时生效 |
| **P3 ✅（颜色⚙）** | 连续渐变画布（自绘 `GradientEditWidget` 替 fabric+d3）+ 预设方案 + 反向 + 整体透明度 → 按各层级位置采样回填颜色 | 改渐变/透明度后体素/切片/2D 变色（透明度影响 3D 体素观感） |
| **P4 ✅（文件 IO）** | 主表 `.lvl` 导入/导出 + 颜色⚙ `.clr` 导入/导出（纯函数 `ColorScaleIO`，与原系统互通，4 单测） | 导出再导入 1:1 还原 |
| P4 模板库 | 后端 `.lvl/.clr` 模板「另存/打开」需后端接口，本地无后端 → 暂以文件导入导出替代 | — |
## P2（层级⚙）落地说明
- **子对话框** `ContourLevelDialog`（复刻 `contourLevel.vue`）：分层方式下拉、最大/最小等值线、normal
「间隔数↔层数」双向联动（`isAutoUpdating` 防递归）、对数「次要等值线数」、等积「层数+区间面积(自动)」、
恢复默认、确定校验（max>min、间隔>0、层数≤50、对数 max>0/min≥0、等积 count>0）。
- **纯算法** `ContourLevels.{hpp,cpp}`（无 Qt/VTK）：`generateContourLevels(params, samples)` 复刻
`colorLevel.vue` case 'level' 的层级重算——normal 等距、log 10 的幂区间细分、equalArea 样本分位
（样本不足退化等距线性，复刻原版失败兜底）。6 个单测覆盖。
- **取色**：`ColorScaleConfigDialog::interpColor` 复刻 `colorUtils.js` mapColors，在旧断点上连续线性
RGBA 插值给新层级上色；主表「层级⚙」按钮打开子对话框 → 重算 → 重填表，最终「确定」走 P1 应用链路。
- **等积样本**：main.cpp 从当前体素 `vtkImageData` 标量抽取传入；无则等积退化线性。
## P2（线形⚙ + 共享）落地说明
> 修正：编辑器是**与数据集视图（2D）共用**的组件。2D `ContourPlotItem` 真画等值线，故 线形⚙ 有渲染
> 落点（先前"3D 无落点"仅对 3D 成立）。
- **子对话框** `ContourLineDialog`（复刻 `contourLine.vue`）：线型(实线/虚线)、线显、线色、标注显、标注色。
- **共享输出**：`ContourLineConfig {lineShow, lineColor, dashed, labelShow, labelColor}`；
`ColorScaleConfigDialog` 加「线形⚙」按钮 + `lineConfig()` getter，构造增 `lineInit` 入参。
- **2D 接入**：`GridDataChartView`「色阶配置」按钮 → 打开共享编辑器（传 grid 色阶 + `grid.values()`
样本 + 当前 `lineCfg_`）→ 确定后更新色阶/线形配置 + 重建 `ContourPlotItem`。
`ContourPlotItem` 新增 `setLineColor/setLineDashed/setLabelColor`，`draw()` 等值线 pen 取色/虚实、
标注 pen 取色（默认黑实线，未编辑前行为不变）。
- **3D 接入**：右键「色阶」打开同一编辑器，仅消费 `colorScale()`，线形/标注忽略（3D 帘面 banded
contour 不画独立线、体素/切片无线）。
- **未接**：`RawDataChartView`（原始散点视图，无等值线网格）「色阶配置」仍占位；待真有需求再接。
## P3（颜色⚙）落地说明
- **自绘渐变控件** `GradientEditWidget`（替代原版 fabric.js+d3 画布）：横向渐变条 + 棋盘透明底 +
可拖拽三角手柄；单击条加点(色=该处采样)、拖拽移位、双击改色、选中后 Delete/右键删除(≥2)。
- **`ColorGradientDialog`（颜色⚙）**：渐变控件 + 预设方案(含原版 17 段 GMT + 彩虹/蓝白红/灰度) +
反向(pos→1-pos) + 整体透明度(0–1 滑块) + `.clr` 导入/导出。
- **回填**：主表「颜色⚙」按钮 → 用当前断点归一化位置(lo..hi→0..1)作渐变初值 → 编辑确定后在新渐变上
按各层级位置连续采样回填颜色(复刻 `mapColors`)，整体透明度<1 时覆盖 alpha(复刻 `addAlphaToColor`)。
透明度直接影响 3D 体素/切片观感(alpha 进 LUT/转移函数)。
## P4（文件 IO）落地说明
- **纯函数** `ColorScaleIO.{hpp,cpp}`（无 Qt）：`parseLvl/generateLvl`(复刻 colorUtils.js `.lvl` LVL3
格式，行内扫 `R G B A` 令牌定位线色/填充色，免疫 `LStyle` 含空格的列错位) +
`parseClr/generateClr`(复刻 colorEditor.vue `.clr` `ColorMap n 0 6 2` 格式)。4 单测覆盖往返。
- **接入**：主表「导入/导出」按钮 = `.lvl`；颜色⚙「导入/导出」按钮 = `.clr`。文件级互通替代后端模板库
（原版「另存模板/打开模板库」走后端 `saveLvlTemplate/queryClrColorLevel`，本地无后端故省）。
- **校正**：原版 `.clr` 导入读透明度取了行首 token（恒为 100）实为 bug，这里取真实透明度 token。
## 2. P1 数据模型映射
原版表格行 `{level, lineType, color}` ←→ 本工程 `core::ColorScale` 的 `(value, Rgba)` 升序断点。
- 原版 `generateColorScale(origincolors, dataMin, dataMax)` 把绝对 level 归一化为 pos；本工程
`core::ColorScale` 直接存**绝对值**断点，无需归一化 → 表格「层级」= 绝对数据值，确定时逐行
`addStop(value, rgba)`。
- alpha：`Rgba.a`（0–255）；颜色选择用 `QColorDialog`（启用 alpha 通道）保真。
- 表格按层级**降序**显示（高值在上，对齐竖直色阶条直觉）；内部仍升序 addStop。
## 3. P1 UI（`ColorScaleConfigDialog`，新增 `src/app/`）
- 标题「色阶配置」，模态。
- `QTableWidget` 两列：**层级**（数值，右对齐）｜**颜色**（色块单元，整格填充该色）。
- 双击「层级」格 → `QInputDialog::getDouble` 改该断点值；改后重排序并刷新色块插值。
- 双击「颜色」格 → `QColorDialog`（`ShowAlphaChannel`）改该断点色。
- 按钮：**新增**（在选中行上方插入，值取选中行与上一行中点、色取两端线性插值）、**删除**
（选中行；保留 ≥2 个断点）、**确定** / **取消**。
- `colorScale()` getter：从表格行装配并返回新的 `core::ColorScale`。
## 4. P1 应用链路
`Column3DAnalysis::colorScaleRequested(dsId)` → main.cpp 处理：
1. 校验 dsId 为当前已渲染三维体（`sceneView->currentVolumeDsId()==dsId && hasVolume()`），否则提示
「请先勾选该三维体使其渲染后再编辑色阶」。
2. 用 `sceneView->currentColorScale()` + `currentVmin()/currentVmax()` 打开对话框。
3. 确定 → `sceneCtrl->setVolumeColorScale(dsId, dlg.colorScale())`。
新增 `VtkSceneController::setVolumeColorScale(dsId, cs)`：
- 更新 `volumeScaleCache_[dsId] = cs`（会话级 mock 持久）。
- 若该体已渲染（isChecked + volumeCache 命中）：`view_.removeDataset(dsId)` → `view_.addVolume(dsId,
grid, cs)`。`addVolume` 内部置 `currentColorScale_` 并触发 `onVolumeChanged` → InteractionManager
以新色阶重建已勾选**切片**；末尾 `renderIncremental()`。
- 帘面（源剖面）为独立数据集、各自源色阶，P1 不联动（仅体+切片，对齐 InteractionManager 单元）。
## 5. 不做（YAGNI / 边界）
- 不动 2D `GridDataChartView`/`RawDataChartView` 的「色阶配置」按钮（共享同对话框，留 P 后续接线）。
- 不接后端保存（mock）；不做线形/标注、连续画布、模板 IO（P2–P4）。

138
docs/superpowers/specs/2026-06-22-2d-dataset-vtk-view-design.md Normal file
View File

@ -0,0 +1,138 @@
# 二维数据集视图（VTK 2D 渲染）设计 — 调研与取舍
> 日期 2026-06-22。分支 `feat/vtk-3d-view`。
> 起因：需求"二维数据集视图 = 筛选勾选对象中、ds 类型显示属性为 2D 的数据集，勾选后显示在 VTK 的 2D 视图"。
> **此面板是客户端独有功能，原版 web 无对应面板**（无可照抄的实现）。
---
## 1. 需求原文
```
筛选对象列表中所勾选的对象中、ds 类型的显示属性为 2D 的数据集
勾选一个或者多个数据集，可显示在 VTK 的 2D 视图
```
经与用户确认：「VTK 的 2D 视图」= **2D 数据平铺进当前 3D 地图**（不另开正交视口），由二维数据集栏的 `view2DMode`（关闭 / Z=0 / 顶部 / 底部 / 自定义）+ `customZ` 控制摆放高度，叠在底图（天地图/Google）之上，多选可叠多张。共享同一 `GeoLocalFrame` 配准。
---
## 2. 关键调研结论：后端无「显示属性」字段（实测 API 确认）
用真实 token 拉了 `项目列表 → 项目结构 → 数据集列表` 三级接口（`http://tenant.geomative.cn/pop-api`）：
- 数据集列表 `POST /business/dsObject/data/page`（**classifyType=3** 为数据，非 2）返回的每条 ds：
```
ddCode(如 dd_inversion_data)、dsTypeCode("ERT platform inversion data")、
dsTypeId、name(类型名)、dsName、dsClassifyType=3、
properties[](confFieldId→value：采集时间/CRS/点数/日期…)、parentId/source*…
```
**没有任何 2D/3D、dimension、display、显示 字段。**
- dataView 用的 `POST /business/projectWorkbench/queryProjectStruct` 只返回树节点（type 1/2/3），同样无维度。
- `properties` 里的 confField 是采集元数据（时间/坐标系/点数），不是显示属性。
**结论**：「ds 类型的显示属性为 2D」**不是后端字段**，只能是**客户端按 `ddCode` 自定义的分类**。桌面端其实已有这张表 —— `Api3dRepository::dimensionOf` / `LocalSample3dRepository::dimensionOf`（标了 TODO），它**就是**「显示属性」的实现，只是当前不完整（仅 `dd_trajectory_data`→2D，其余 3D/Other）。
> 即：要做这个需求，等于**客户端定义/补全 ddCode→显示维度 映射**，后端给不了真值。
---
## 3. ddCode 形态台账（取自原版 datasetInfo 的 ddCode→详情组件映射 + 行业语义）
| ddCode | 详情组件 / 含义 | 空间形态 |
|---|---|---|
| dd_trajectory_data | ElectrodeCom 电极/测线 | **线**（lat/lon 序列）|
| //dd_transient_electromagnetic_trajectory_data | BatteryComMapLineCom 瞬变电磁测线 | **线** |
| //dd_radar_channel_trajectory / dd_radar_rtk_trajectory | 雷达通道/RTK 轨迹 | **线** |
| dd_inversion_data | ContourCom 等值面 | **剖面** |
| dd_ert_measurement_data | ScattersCom 散点 | **原始数据**（电极对 × 视深，散点） |
| //dd_ert_measurement_gr_data | GroundResistanceCom 接地电阻 | 沿线序列 |
| //dd_gpr_channel_image / dd_radar / //dd_gpr_channel_detail | 雷达图像/成果，//重新分析 | **竖直 B-scan**（沿轨迹 × 时深）|
| dd_grid | DdGridCom 网格，//扩展支持接地电阻 | 网格（**面 or 剖面，依数据而定，存疑**）|
| dd_voxel / （dd_Structual3D） / //dd_Property3D | 体素 / （结构） / //属性 3D | **三维体** |
| //dd_3d_show | ThreeModelCom 3D 模型 | **三维模型** |
| dd_slice | 切片 | 三维分析 |
| ??dd_time_sensor | TimingSensor 时序传感器（折线图+数据表）| 时序曲线（非空间）**待确认** |
| ??dd_current_method_indicator | DdElectricDetectionCom 电流法指标（指标表+散点状态图）| 指标/状态（非空间）**待确认** |
> `??` 标记：原版 datasetInfo 有此详情组件，但初版台账漏列，详情视图是否纳入客户端范围**待确认**（2026-06-22 补）。雷达/GPR 家族（`//` 标记）因客户端将重构、客户需求未定，整体搁置。
---
## 4. 专业 + 用户视角：哪些值得作为「2D 渲染到 VTK」（业务价值导向，不凑功能）
中央 VTK 视图是**地理配准的 3D 地图**（地形 + 底图 + 共享 frame）。"2D 渲染进去"= 把数据**摆到地图上**。按数据的空间本质分三类：
### 4.1 地理足迹型（线 / 点 / 面）—— 有真业务价值 ✅
- **测线 / 轨迹**（dd_trajectory_data、各类 *_trajectory）：本就是地面上一串 lat/lon = 物理测线/电极布设/雷达轨迹。
- **电极 / 传感器点位**：地理点。
- **真·面状栅格**（若存在：lat×lon 的面值网格，如地表某物性面）。
**价值**：回答"survey 做在**哪**、多条线/对象**空间怎么排布**、覆盖范围、异常相对地图/地形在**哪**"。对**没有三维体表示的纯 2D 数据（轨迹、点）**，地图平铺是它**唯一**的空间表达。daily 工程价值高。
### 4.2 竖直剖面型（反演剖面 / 雷达 B-scan / 拟剖面）—— 平铺进地图**没有业务价值** ❌
- 这类数据是"距离 × **深度**"。把它**平铺**到水平地图上，等于让"深度"当地图的水平轴 —— **地理上无意义、且误导**。
- 它们的正确表达是：
- **3D 视图**里沿测线**立成帘面**（地理竖直切片，已实现）；
- **2D 详情面板**（`GridDataChartView` / Qwt）里**正视读图**（距离 × 深度，地球物理师标准看图方式，已实现）。
- 再把剖面图平铺到地图 = **凑功能**，无增量价值。
### 4.3 三维体型（voxel / 结构 / 属性 / 3D 模型）—— 不属于 2D
走 3D 渲染（体素/模型），不在本面板范围。
### 4.4 用户视角佐证
- **野外/项目工程师**：要"我测在哪、线怎么排、异常落在地图哪个位置" → **足迹型**每天用。
- **解释员**：剖面要么正视读（详情面板）、要么看帘面（3D），**绝不**会想看一张平铺在地图上的剖面。
---
## 5. 建议（结论）
**二维数据集视图的真实业务价值 = 地图上的「平面/足迹层」**：把**本质是平面/线、且没有有意义三维体表示**的数据集，按地理位置摆到 3D 地图上，提供空间上下文与覆盖总览。
- **纳入 2D 渲染（足迹）**：测线/轨迹类（线）、电极/传感器点位（点）、真·面状栅格（面，若有）。
- **不纳入**：反演剖面、雷达 B-scan、拟剖面等**竖直剖面**——它们已有"3D 帘面 + 2D 详情正视图"两条更对的表达，平铺地图无价值且误导。
- **dd_grid 存疑**：需确认其数据到底是"面状栅格"（→ 纳入）还是"剖面网格"（→ 不纳入）。
> 即 `dimensionOf` 的 2D 集合应当是**足迹型**，而非把所有非三维体都塞进来。
### 待产品确认
1. 2D 集合是否就取"足迹型"（测线/轨迹 + 点位 + 面状栅格）？
2. `dd_inversion_data` 是否**坚持不进** 2D 面板（按 §4.2，建议不进；它进 3D 栏渲帘面 + 详情面板正视）？
3. `dd_grid` 的真实数据形态（面 / 剖面）？
---
## 5.1 关键数据路径发现（影响实现规模）
`VtkSceneController` 持**两个仓储**：
- `dsRepo_` = **`LocalSampleRepository`（样本数据）**：`grid(dsId)=dsRepo_.loadGrid` 只有内置样本网格（grid1 等）。**现有 Map2D 的 `addSurveyLine(grid(dsId))` 用的就是样本数据，不是真实后端**，且 Map2D 模式从不激活。
- `sceneRepo_` = **`Api3dRepository`（真实后端，async）**：帘面 `loadSection` / 体 `loadVolume` 走真实 ERT 端点。
**结论**：渲染**真实** 2D 足迹**不能复用样本测线路径**，需在 `Api3dRepository` 加**真实异步足迹加载器**。轨迹线端点已存在：`GET /business/dd/ert/trajectory/line?dsObjectId={id}&frontCrsCode={crs}`（返回经纬度，`ApiDatasetRepository::makeTrajectoryMap` 已在用）。
**首切片范围（可交付、可测）**：先做**轨迹线**足迹（`dd_trajectory_data` 等轨迹类）——端点确定、数据形态确定（线）。点位/面状栅格待其端点与数据形态确认后续做。
## 6. 实现路径（确认 2D 集合后）
1. **分类**：补全 `dimensionOf`（ddCode→维度），2D 集合 = 足迹型。DsRow 无需新字段（后端无此字段）。
2. **渲染**：
- 线（测线/轨迹）→ 复用 `buildSurveyLine` / `addSurveyLine`（已存在），在**当前 3D 场景**画（不切 Map2D 模式）。
- 点（电极/传感器）→ 复用 `ElectrodeActor` / 点 actor。
- 面状栅格（若纳入）→ 收尾 `GridContourActor` 成水平等值面，着色复用帘面刚修正的「banded + 上界 stop 取色 + 满 RGB」共享函数。
3. **Z 摆放**：`view2DModeChanged`（关闭/Z=0/顶部/底部/自定义）+ `customZChanged` → 控制 2D 层世界 Z。
4. **接线**（main.cpp）：`col2D()->checkedDatasetsChanged` → 新增 `setChecked2DDatasets`；Z 模式信号接入。底图已就绪。
5. **配准**：共享 `GeoLocalFrame`，与帘面/测线同系。
---
## 7. 参考 / 实证
- 真实端点（base `http://tenant.geomative.cn/pop-api`，header `geomativeauthorization: Geomative <token>`）：
- 项目 `POST /business/my/profile/project/page`
- 结构 `GET /business/projectStruct/queryProjectStruct/{projectId}`
- 数据集 `POST /business/dsObject/data/page`（body 含 projectId/structParentId/structParentConfType/`classifyTypeList:[3]`/pageNo/pageSize）
- dataView 结构 `POST /business/projectWorkbench/queryProjectStruct`
- 桌面端：`Api3dRepository::dimensionOf`（待补全）、`VtkSceneController`（Map2D/View3D + addSurveyLine）、`Column2DDataset`（信号 checkedDatasetsChanged / view2DModeChanged / customZChanged 已定义、main.cpp 仅接 basemap）。
</content>
</invoke>

174
docs/superpowers/specs/2026-06-22-dataset-detail-interaction-replica-ledger.md Normal file
View File

@ -0,0 +1,174 @@
# 数据集详情视图 · 交互 100% 复刻台账
> 目标：详情视图（datasetInfo）逐交互 1:1 复刻原版 web（`D:\Git\lanbingtech\commercial-admin`）。
> 原则：对照原版源码找全差距；凡已实现的视图，其后端接口均已具备（客户端只需新增对应调用）。
> 范围：仅**已实现的 5 个 ddCode 视图**。雷达/GPR/电磁/3D 模型家族（客户端将重构、需求未定）整体搁置。
> 日期：2026-06-22 立账。
## 0. 总览结论
| 视图 (ddCode) | 客户端类 | 复刻完成度 | 差距集中点 |
|---|---|---|---|
| 电极轨迹 dd_trajectory_data | TrajectoryStrategy / TrajectoryMapView 等 | ✅ **无差距** | 地图/列表/高程齐全；原版「导出」按钮原版自身亦未实现 |
| 接地电阻 dd_ert_measurement_gr_data | GrMeasurementStrategy / BarChartView | ✅ **无差距** | 柱状图/列表齐全；原版地面信息/模型/脚本/导出按钮原版自身亦未实现 |
| ERT 原始数据 dd_ert_measurement_data | MeasurementStrategy / RawDataChartView | ✅ **基本接通** | 工具条 1:1，写操作全接；仅 M14 框选后置（重型，已登记） |
| 反演等值面 dd_inversion_data | ErtInversionStrategy / RawDataChartView(原数据) + GridDataChartView(网格) | ✅ **基本接通** | 网格/白化/滤波/异常CRUD/自动标注/另存为/色阶均接；仅 I9 图上绘制、I14 富文本、I3 tmObjectId 透传后置 |
| 网格白化 dd_grid | GridStrategy / DataTableView | ✅ **已通** | 分页列表 + 「反演」功能按钮(载荷 functionList 驱动，复用 InversionFormDialog) |
**架构事实**：客户端 `ApiDatasetRepository` 当前只有 load（读）操作，无写操作。所有反演/保存/过滤/白化/滤波/异常写接口需新增客户端调用，沿用 `ApiClient(get/postJsonAsync) → ApiBatch → ApiDetailLoad` 模式（或为写操作引入独立的 command 调用路径）。
> ⚠️ 实现前务必直接读原版 `src/apis/datasetInfo/index.js` 与对应 `.vue` 复核请求体字段名（本台账 API 字段来自探查 agent 摘录，端点/方法可信，个别字段名以源码为准）。
---
## 1. 共享基础设施（先建，多视图复用）
这些组件被多个交互复用，应优先抽象，避免各视图各写一份。
### 1.1 反演动态表单对话框（InversionForm）
- **复用于**：measurement「反演运算」「生成视电阻率」、grid「反演」。
- **流程**：① 查模型列表 → ② 选模型 → ③ 按 typeId 拉动态表单字段 → ④ 填参 → ⑤ 提交。
- **API**：
- 模型列表 `GET /business/outerInversion/query/script?dsObjectId=`（measurement/grid 通用）
- 动态表单 `POST /business/project/getDynamicForm` body `{projectId, type:6, typeId}`
- 提交反演 `POST /business/outerInversion/submitInversionTask` body `{dsId, properties, ...}`
- 生成视电阻率 `POST /business/dd/ert/measurement/createVisualResistivityData` body `{dsObjectId, scriptId, scriptParamListJsonStr}`
- **客户端现状**：无。需建 `InversionFormDialog`（动态字段渲染：分组卡片 + Select 为主）。
### 1.2 色阶配置编辑器（已存在，复用）
- **已有**：`ColorScaleConfigDialog`（被 GridDataChartView 使用，且与三维体右键色阶共用）。
- **复用目标**：measurement 散点「色阶配置」、inversion 原数据散点「色阶配置」。
- **API**：查 `POST /business/lvl/colorGradation/getDetail`，存 `POST /business/lvl/colorGradation`。
- **注意**：measurement 走 `businessCode=R0, type=3`；inversion 原数据 `type=1`、网格 `type=2`。散点上色用 `colorSvc_`，编辑后需重建并重绘散点。
### 1.3 另存为对话框（SaveAs）
- **复用于**：measurement 另存为、inversion 另存为。
- **measurement**：`POST /business/dd/ert/measurement/saveRawData` `{dsId, operationType(1新增/0覆盖), name?}`（含新增/覆盖单选）
- **inversion**：`POST /business/dd/ert/inversion/saveAsData` `{dsObjectId, name}`（仅名称）
---
## 2. ERT 原始数据（measurement / RawDataChartView）
客户端 measurement 工具条已 1:1 建出（`buildMeasurementToolbar`）。逐控件差距：
| # | 控件 | 原版行为 | 原版 API | 客户端现状 | 实现要点 |
|---|---|---|---|---|---|
| M1 | 显示/隐藏 | popconfirm→改全部点可见性（持久化） | `POST /business/dd/ert/measurement/saveDisplayStatus` `{dsObjectId, ids[], status}` | ✅ **已通**（onShowHide：确认→调接口→本地切换） | — |
| M2 | 表格行可见性 switch | 行级 popconfirm→改单点 | 同 M1（ids=[record.id]，status 取反） | 🔸 **后置**（DataTableView 行级开关列交互重，源 saveDisplayStatus 已具备） | 见 §6 |
| M3 | 数据过滤 | 弹窗(直方图+min/max)→生成过滤后数据集 | 查 `GET /business/scatterPlotDataFilter/getDataFilterConfig?dsObjectId&vFieldCode`；应用 `POST /business/scatterPlotDataFilter` `{sourceDsObjectId, sourceVFieldCode, min, max}` | ✅ **已通**（ScatterFilterDialog：范围 min/max + 应用）；直方图绘制后置 | 直方图见 §6 |
| M4 | X 轴下拉(平距/斜距) | 本地换列重绘 | 无 | ✅ 已通(replotForAxis) | — |
| M5 | Y 轴下拉(伪深度/+高程/层数) | 本地换列重绘 | 无 | ✅ 已通 | 层数为 no-op（原版亦无数据） |
| M6 | V 值下拉 | 重新请求散点+色阶 | `GET .../scatter/graph?vFieldCode=` + `POST .../getDetail{businessCode=新V}` | ✅ **已通**（reloadForVValue 带 vFieldCode 重载） | — |
| M7 | 值类型下拉(线性/倒数/对数) | 本地换显示 | 无 | ✅ **已通**（applyValueType 本地变换重上色） | — |
| M8 | 色阶配置 | 弹窗编辑+保存 | getDetail/colorGradation（见 1.2） | ✅ **已通**（复用 ColorScaleConfigDialog；properties 含 colorBar+lineConfig+labelConfig） | — |
| M9 | 生成视电阻率 | 反演弹窗（模型锁定视电阻率脚本） | createVisualResistivityData（见 1.1） | ✅ **已通**（InversionFormDialog::ApparentResistivity：下拉 disabled+锁 `script_visual_resistivity_data`，对齐原版） | — |
| M10 | 反演运算 | 反演弹窗 | submitInversionTask（见 1.1） | ✅ **已通**（InversionFormDialog::Inversion） | — |
| M11 | 另存为 | 新增/覆盖弹窗 | saveRawData（见 1.3） | ✅ **已通**（SaveAsDialog::RawData） | — |
| M12 | 导出 DAT | 下载 base64 | `GET /business/dd/ert/measurement/rs2d/export?dsId&electrodePosition=2&ipDataMark=0&typeMeasurement=0` | ✅ **已通**（exportDat，参数对齐原版） | — |
| M13 | [i] 信息 | 点选看 A/B/M/N/Pseu/Row | 无（本地） | ✅ **已通**（toggleInfoMode：信息模式点选散点看属性） | — |
| M14 | 框选/点选模式 | enter/exitSelectMode | 无（本地） | 🔸 **后置**（Qwt 橡皮筋框选+选区联动隐藏成本高，保留占位提示） | 见 §6 |
---
## 3. 反演等值面（inversion）
### 3.1 网格视图（GridDataChartView）
| # | 控件 | 原版行为 | 原版 API | 客户端现状 | 实现要点 |
|---|---|---|---|---|---|
| I1 | 网格(化) | 2步向导(选算法+参数)→网格化 | `GET .../queryAlgorithmModel/{ds}`；`GET .../getRawData/{ds}`；`POST /business/dd/ert/inversion/grid`(actionCode,x/y min/max,**xsize/ysize=点数**,xSpacing/ySpacing=间距,vmin/vmax,saveDataValueType) | ✅ **已通**（GridWizardDialog 2步；xsize=点数 xPoints/ySize=yPoints，间距走 xSpacing/ySpacing，对齐原版 toGridTheData） | — |
| I2 | 色阶配置 | 弹窗 | getDetail/colorGradation | ✅ **已通**（本地生效；网格视图色阶不持久化到后端，与原版网格路径一致） | — |
| I3 | 白化 | 弹窗(3种方式) | `POST /business/dd/ert/inversion/whitenedData`；文件列表 `POST /business/dsObject/queryWhitenedDataList` | ✅ **已通**（白化弹窗+提交）；`tmObjectId` 暂兜底空串 | tmObjectId 透传见 §6 |
| I4 | 滤波处理 | 弹窗(滤波器树+矩阵) | 列表 `GET /business/filter/queryFilter`；增 `POST /business/filter`；删 `DELETE /business/filter/delete/{id}`；应用 `POST /business/dd/ert/inversion/filterData` | ✅ **已通**（滤波弹窗含滤波器 CRUD+应用） | — |
| I5 | 显示异常 | 本地显隐 | 无 | ✅ 已通 | — |
| I6 | 显示等值线标注 | 本地显隐 | 无 | ✅ 已通 | — |
| I7 | 显示等值线提示 tooltip | 本地显隐 | 无 | ✅ **已通**（chkContourTip 接 hover tooltip 显隐） | — |
| I8 | 简化容差滑块 | 防抖本地重算等值线(0~2,步0.1) | 无 | ✅ **已通**（防抖 applySimplify→setSimplifyTolerance 真生效） | — |
| I9 | 异常 创建 | 弹窗(类型/名称/备注)+图上绘形 | 类型 `GET .../queryExceptionTypeByProjectIdAndType/{pid}/{type}`；名建议 `POST /business/exception/getExceptionName`；新增 `POST /business/exception` | ✅ **表单已通**（ExceptionDialog：类型/名建议/备注+提交）；🔸 **图上绘形后置** | 图上绘制见 §6 |
| I10 | 异常 删除 | 表格行删 | `DELETE /business/exception/{id}` | ✅ **已通**（AnomalyTablePanel deleteRequested） | — |
| I11 | 异常 详情/编辑 | 抽屉(名称/备注/样式) | `PUT /business/exception` | ✅ **已通**（ExceptionDetailDialog；只发 `{id, exceptionName, remark}`，对齐原版局部更新） | — |
| I12 | 异常 定位 | 本地高亮+缩放(防抖) | 无 | ✅ **已通**（AnomalyTablePanel locateRequested→图上定位） | — |
| I13 | 自动标注 | 弹窗(规则+预览) | 预演 `POST /business/exception/exception-mark/execute`；批量存 `POST /business/exception/batch/create` | ✅ **已通**（openAutoAnnotation 自动标注弹窗） | — |
| I14 | 富文本描述保存 | Quill→保存 | 存 `PUT /business/dsObject/updateDsObject/`；取 `GET /business/dsObject/getDetail/{ds}` | ✅ **保存链路已通**（DescriptionPanel saveRequested→saveDescription，取/存均通）；🔸 **富文本降级为纯文本** | Quill 富文本见 §6 |
| I15 | 另存为 | 弹窗(名称) | `POST /business/dd/ert/inversion/saveAsData` | ✅ **已通**（SaveAsDialog） | — |
### 3.2 原数据散点视图（RawDataChartView 默认工具条）
| # | 控件 | 原版行为 | 客户端现状 | 实现要点 |
|---|---|---|---|---|
| O1 | 网格 | 同 I1 网格化向导 | ✅ **已通**（复用 GridWizardDialog） | — |
| O2 | 色阶配置 | 散点色阶(type1，businessCode 空) | ✅ **已通**（openInversionColorScale；properties 含 colorBar+lineConfig+labelConfig） | — |
| O3 | 另存为 | 同 I15 | ✅ **已通**（SaveAsDialog::Inversion） | — |
| O4 | 图形格式下拉 | 散点↔2D直方图等值线（原版 disabled） | ✅ 不做（原版自身禁用） | — |
---
## 4. 网格白化数据（grid / DataTableView）
| # | 控件 | 原版行为 | 原版 API | 客户端现状 | 实现要点 |
|---|---|---|---|---|---|
| G1 | 反演 | 反演弹窗 | submitInversionTask（见 1.1） | ✅ 已接 | DataTableView 顶部功能按钮行(载荷 functionList 驱动，仅 dd_grid 非空)，点 inversion → 复用 InversionFormDialog(Mode::Inversion) |
| G2 | 分页 | 服务端分页 | grid/rows pageNo/pageSize | ✅ 已通 | — |
---
## 5. 建议执行顺序（分阶段）
1. **阶段 A · 共享基础设施**
- InversionFormDialog（模型列表+动态表单+提交）→ 一次解锁 M9/M10/G1。
- SaveAs 弹窗（measurement + inversion 两形态）。
- 色阶配置接入散点（复用 ColorScaleConfigDialog）→ M8/O2。
2. **阶段 B · measurement 主交互**
- M1/M2 可见性持久化、M11 另存为、M12 导出、M6 V值重载、M7 值类型、M3 数据过滤。
- M13/M14 信息/框选（交互重，最后）。
3. **阶段 C · inversion 写操作**
- I1/O1 网格化向导、I15/O3 另存为。
- I9~I13 异常 CRUD + 自动标注。
- I3 白化、I4 滤波。
- I7 tooltip、I8 简化容差真生效、I14 描述保存复核。
4. **阶段 D · grid**
- G1 反演按钮（阶段 A 完成后顺带）。
> 每个交互按 TDD：先对 repository 写方法/解析写测试（mock ApiClient），再接 UI；UI 视觉对照原版。
---
## 6. 复刻收尾状态（2026-06-22）
三份审查后的修正项已落地，build 通过 + 测试全过（285/285）。
### 6.1 已 100% 接通项
- **measurement（M1~M13）**：显隐持久化、数据过滤（范围）、X/Y/V/值类型下拉、色阶配置、生成视电阻率（下拉锁 `script_visual_resistivity_data`）、反演运算、另存为、导出 DAT、[i] 信息点选——全部接通并对齐原版。
- **inversion 网格（I1~I8、I10~I13、I15）**：网格化向导（xsize/ysize=点数，对齐 toGridTheData）、色阶、白化、滤波（含滤波器 CRUD）、显示异常/标注/tooltip、简化容差真生效、异常删除/详情编辑/定位、自动标注、另存为——全部接通。
- **inversion 原数据散点（O1~O3）**：网格化、色阶（type1）、另存为——全部接通；O4 原版自身禁用，不做。
- **grid 白化（G1/G2）**：反演按钮（functionList 驱动）、分页——已通。
### 6.2 审查修正项（本轮）
- **重复 connect（M13/M14）**：删除 `btnInfo`/`btnMarquee` 残留的 `clicked→showNotImplemented`，消除信息按钮多弹「暂未实现」、框选按钮单击弹两次；btnInfo 保留 checkable+toggled（信息模式），btnMarquee 保留单条占位提示。
- **异常详情更新字段（I11）**：原版 `contourPage.vue onOk` 走 `PUT /business/exception` 局部更新，**仅发 `{id, exceptionName, remark}`**（线样式是另一条独立 PUT，且抽屉样式控件 disabled）。客户端 `ExceptionDetailDialog::onConfirm` 已对齐：不再附带/覆盖 `legend`。
- **色阶 properties 补齐（M8/O2）**：原版散点路径 `newLvlColorLevel` 的 `properties` 含 `colorBar` + `lineConfig{showLines,color,lineType}` + `labelConfig{showLabels,color}`（battery/scatters 仅这三块，不含等值面专属的 lvlSchemeType/logLinesCount/equalAreaLayerCount）。客户端两处散点保存已补齐这三块（新增 `buildColorScaleProperties` 复用 `dlg.lineConfig()`）。`templateId` 原版非必需，客户端按原版处理。
### 6.3 self-check 结论（无需改）
- **#4 视电阻率模型锁定**：`InversionFormDialog::ApparentResistivity` 已 `modelCombo_->setEnabled(false)` 且锁定 `code==script_visual_resistivity_data` 的项——与原版 `InversionDialog.vue`（静态 `disabled` + 锁脚本）一致。
- **#5 网格 xsize/ysize 绑点数**：`GridWizardDialog` 的 `xSize_/ySize_` 是「X/Y点数」（1~300，默认 100），`buildGridToBody` 映射 `xsize←xSize`、间距走独立 `xSpacing←xSpacing_`——与原版 `GridDialog.vue toGridTheData`（`xsize:xPoints`、`xSpacing:xInterval`）一致。
### 6.4 收尾 6 项 —— 已全部接通（2026-06-23，commit ec4a7e8）
§6.4 原列的 6 项后置/降级项已全部实现，build app + test 全绿（318/318）。
| 项 | 状态 | 实现 / 残留边界 |
|---|---|---|
| **M2 行级可见性 switch** | ✅ | DataTableView 载荷驱动可交互开关列（`toggleInteractive`+`rowIds`，仅 measurement 置位），行级 popconfirm → `saveDisplayStatus` |
| **M3 过滤直方图** | ✅ | 新增自绘 `ScatterHistogramView`（20 箱，选区高亮 + min/max 输入联动）；拖拽刷选未做（原版用输入/滑块，非画布 brush） |
| **M14 框选/点选模式** | ✅ | `ScatterMarqueePicker` 橡皮筋矩形 → `ScatterPlotItem` 选中红边高亮；显示/隐藏对选中子集操作（无选区回退全部）。复刻 box-select 变体；原版单击逐点选未做 |
| **I9 异常图上绘形** | ✅ | `ContourDrawTool` 在等值面交互绘制 点/线/面/文字（先弹窗填类型/名称→图上绘制→`newException`）；坐标表保留为兜底。文字类型无原版独立富文本样式编辑器 |
| **I14 Quill 富文本** | ✅（降级可用） | `DescriptionPanel` 升级富文本（粗体/斜体/下划线/字色/字号/标题/列表）+ `QuillDelta` 与 Quill Delta 常见格式往返。**Qt 无 Quill，不可字节级 1:1**：未知 attributes/嵌入对象容错降级（保文本、丢样式、不崩） |
| **I3 白化 tmObjectId** | ✅（待联调验证） | `openWhitening` 经 `getDsObjectDetail(dsId)` 取 `structParentId` 作 tmObjectId。**存疑**：未实证 getDetail 响应含 structParentId，若不含需转方案 B（经 openDataset 链路透传） |
### 6.5 命名冲突修复
`ScatterHistogram` 名冲突（M3 widget 类 vs ScatterDataOps 分箱 struct）导致 desktop 目标曾无法链接（`build.bat test` 只建测试目标未暴露）→ widget 改名 `ScatterHistogramView`。**教训**：详情视图改动须 `build.bat all` 验证 app 链接，不能只 `build.bat test`。

99
docs/superpowers/specs/2026-06-23-gpr-volume-A-whole-texture-no-pyramid.md Normal file
View File

@ -0,0 +1,99 @@
# GPR 三维体 · 方案 A：整卷上纹理，不用金字塔（复用现有管线，最简基线）
- 日期：2026-06-23
- 范围：把 GPR（探地雷达）阵列数据插值成三维体并在 VTK 中渲染/切片，**直接复用现有剖面三维体管线**，整卷一次性进显存，不做分块/金字塔/核外。
- 定位：三选一中的**最小改动基线**。用于评估"现有架构原样接雷达，能做到什么、卡在哪"。
- **⚠ 评审结论（2026-06-23，opus）：A 不应作为独立交付步，建议并入 B。** 唯一值得从 A 单独先做的是"三方案共有的地基"（§2）。`double`+400³+暴力 IDW 三条硬约束使 A 产出的 GPR 体既无业务分辨率（沿线被强制粗化到 5.5m vs 物理 5cm）、又无法落盘秒开。详见 §5/§6。
- 测试数据（明星路）：450MHz 阵列 GPR，14 通道，每道 821 采样，单线 ~45306 道，20 线，int16，合计 13.6GB；路长 2223m，测幅 1.37m，深 ~8m。
---
## 1. 设计意图
不引入任何新渲染/存储机制。把雷达数据**喂进现有体素管线**，让它走和反演剖面三维体完全一样的路：
```
.iprb/.iprh → PointSet → core::IdwInterpolator → ScalarVolume(double)
→ data::VolumeGrid → render::buildVoxel → vtkSmartVolumeMapper（整卷进显存）
切片：render::interact::SliceTool（vtkImagePlaneWidget / vtkImageReslice，CPU 重采样）
持久化：VolumeBuildParams（参数必存）+ 可选明细缓存（现内存 mock）
```
现有落点（实证）：
- `core::ScalarVolume` = `std::vector<double>`，行优先（`src/core/model/Field.hpp:8-26`）。
- `render::buildVoxel` → `vtkImageData`+`vtkDoubleArray`+`vtkSmartVolumeMapper`，整卷上传（`src/render/actors/VoxelActor.cpp:41-79`）。
- 体素维度上限 `kMaxVolumeDim = 400`（`src/core/algo/VolumeBuilder.hpp:8`）。
- 切片 CPU 重采样（`src/render/interact/SliceTool.cpp:24-39`）。
- 插值 `IdwInterpolator`，单线程三重循环，且**无空间索引——每体素全点集线性扫描，O(体素数×点数) 暴力**（`src/core/algo/IdwInterpolator.cpp:15-33`，评审实证）。雷达级点集下即便 400³ 也是分钟级甚至卡死，不只是"偏慢"。
- 持久化 `Api3dRepository::StoredVolume`，纯内存（`src/data/api/Api3dRepository.hpp:112-119`），重算逻辑已就绪（`Api3dRepository.cpp:212-225`）。
- **注意（评审）**：现有 `loadVolume` 的散点来源硬绑 `loadSection`/`appendGridPoints`（ERT 反演帘面，`Api3dRepository.cpp:146-171`），**雷达没有现成喂入路径**。"复用现有管线"实际仍须新写 GPR→`buildVolume` 接入（§2 已含），§1 流程图的"原样复用"措辞偏乐观。
---
## 2. 新增工作（雷达接入，三方案共有的地基）
A/B/C 都绕不开这块，A 用最朴素实现：
1. **`.iprb`/`.iprh` 解析器**（新）：`.iprh` 文本头取 `SAMPLES/LAST TRACE/CHANNELS/TIMEWINDOW/SOIL VELOCITY/DISTANCE INTERVAL`；`.iprb` 读 int16 B-scan（`samples × traces`，校验 `samples×traces×2 == 文件大小`）。
2. **地理配准**：`.ord` 取 14 通道横向偏移；`.gps`/`.cor` 取每道经纬度/RTK；深度 = `time × soilVelocity / 2`。
3. **GPR→PointSet 适配器**：把"14 通道 × N 道 × 821 采样"摊成 `PointSet{x,y,z,v}`（局部坐标）。**注意横向只有 14 个真实样本**，是稀疏维。
4. **数据集接入**：新增 ddCode（如 `dd_gpr_volume`），在维度分类（`Api3dRepository.cpp:30-45`、`LocalSample3dRepository.cpp:43-58`）归 3D；DTO 解析器放 `src/data/dto/`。
---
## 3. 关键约束与后果（A 的硬边界）
现有管线是 **double + 400³ 上限**。这两条直接决定 A 能做什么：
| 约束 | 数值 | 后果 |
|---|---|---|
| 标量 dtype | `double`（8 字节/体素） | 同样体素数，内存是 int16 的 **4 倍** |
| 维度上限 | 400³ | 整卷 ≤ 400³×8 ≈ **512MB**；放不下全路段 |
| 整卷进显存 | 一次性 | 体大小受限于显存 |
| IDW | 单线程 + 无空间索引暴力 | 大点集插值分钟级/卡死（明星路单线 ~5亿采样点级） |
> **`fitAxis` 行为（评审实证 `VolumeBuilder.cpp:16-26`）**：格数超 400 时**不裁剪范围**，而是 `outCell=ext/(400-1)` 把 400 格摊满整个包络。所以 A 不是"丢掉远端"，而是"强制粗化"——沿线细节被低分辨率抹平。
**全路段在 A 下做不到原始分辨率。** 明星路需 ~22000(沿线)×270(横)×400(深)，远超 400³。在 A 下只能：
- **重度降采样到 ≤400³**：沿线 2223m/400 ≈ 5.5m 网格 → 沿线细节全毁；或
- **按单条测线/短段分别建小体**（单线降到 400³ 仍偏粗），多体并排显示（类似现有 2D 足迹平铺）。**但**（评审）：20 体 × 400³ × double ≈ 10GB 整卷同驻显存，比单大体更易爆显存；且各体独立 `GridSpec`/origin，**跨体的全路段连续切片做不到**（用户想沿全路一刀切无法实现）。
---
## 4. 持久化（沿用 2026-06-17 §7 策略）
- **必存**：`VolumeBuildParams`（源数据引用 + 插值模型/参数 + 色阶）+ `GridSpec`（origin/spacing/dims，锚定切片/异常坐标）。
- **可选明细**：`ScalarVolume`(double)。A 阶段仍是内存 mock（`StoredVolume.cachedGrid`），**未真实落盘**——这是 A 与用户"保存插值后体"诉求的**主要差距**。
- 用户要的两种保存：①参数 ②插值后明细 —— A 的 ②目前只有内存缓存，需补一段最朴素的 double 体落盘（raw + sidecar）才算满足；但 double 全路段落盘巨大，不实用。
---
## 5. 评估
**优点**
- 改动最小：渲染/切片/异常/详情**全部现成**，只加雷达解析与适配。
- 路径已验证，风险低，可最快出"雷达能进三维场景"的可见效果。
**缺点/限制**
- `double` + 400³ → **撑不起全路段原始分辨率**，只能粗览或分段小体。
- 明细落盘不实用（double 体积过大），用户"算一次秒开"诉求难真正成立。
- 单线程 IDW 在雷达量级偏慢。
- 把结构化的雷达数据（沿线/深度本就规则）当无结构散点做 3D IDW，**算力浪费**（见方案 B 的结构化插值优化）。
**适用**
- 单条短测线 / 粗分辨率概览 / 快速打通链路的第一步。
- **不适合**作为全路段完整体验的最终方案。
---
## 6. 工作量与落地顺序
1. `.iprb`/`.iprh` 解析 + 地理配准 + GPR→PointSet（地基，~中）。
2. 雷达 ddCode 接入维度分类 + DTO（~小）。
3. 直接复用 `IdwInterpolator`/`buildVoxel`/`SliceTool`，按 ≤400³ 降采样建体（~小）。
4. （可选）double 明细落盘最朴素实现（~小，但不推荐用于全路段）。
**结论（修订，评审定）**：**no-go（作为独立交付步），并入 B。** A 没有任何 B 不需要的独立资产，渲染/切片/异常/持久化骨架 A、B 共享，地基（§2）也共享。`double`+400³+暴力 IDW 三条硬约束使 A 的 GPR 产物既无业务分辨率、又无法落盘秒开，连"最小基线该兑现的可用产物"都达不到。
- **唯一抽出先做的独立里程碑 = §2 共有地基**（`.iprb`/`.iprh` 解析 + 14 通道配准 + GPR→PointSet + ddCode 接入），A/B/C 都要。
- "复用 double+400³ 管线建退化体"这一步**不单独交付**，直接在 B 的 int16+结构化建体上落地，避免做一遍注定被 B 推翻的降级体。
- **全路段完整体验走 B。**

120
docs/superpowers/specs/2026-06-23-gpr-volume-B-fullroad-int16-whole-gpu.md Normal file
View File

@ -0,0 +1,120 @@
# GPR 三维体 · 方案 B：全路段 int16 整卷上 GPU（升级现有管线，推荐）
- 日期：2026-06-23
- 范围：把全路段 GPR 按**物理分辨率（5~10cm）**插值成**单个 int16 体（~5~10GB）**，整卷传成 GPU 3D 纹理，切片/体绘制都丝滑。**不做金字塔/核外**，靠"右尺寸 + int16"让单体进显存。
- 定位（2026-06-23 用户定）：**与 C 对等的两条已承诺路线之一，两者都做、用户运行时按需切换**。B 走"整卷进显存"路线（在现有管线上有针对性升级），适合能装进显存的体；超显存的体走 C。经同一 `IVolumeRenderSource` 接口切换。
- **✅ 评审结论（2026-06-23，opus）：Go（条件式）。** 体积测算、int16+结构化插值、渲染/切片复用均成立。**开工前必改 3 项**：①落盘方案（VTKHDF Writer 写不了 ImageData，必须改裸分块，见 §3）；②量化贯穿传递函数/色阶/反量化（见 §3.5）；③一个 vtkShortArray→GPU 体绘制的小验证 spike。
- 测试数据（明星路）：同方案 A。物理分辨率依据：450MHz、土速 0.1m/ns → 波长 λ≈0.22m、垂向分辨率 ≈5cm；网格细过 ~5cm 即过采样。
---
## 1. 设计意图
A 的瓶颈是 `double` + 400³ 上限，撑不起全路段。B 针对性拆掉这两条，**保持"整卷进显存"这一最省力的渲染架构不变**：
```
.iprb/.iprh → 结构化建体（仅横向插值）→ ScalarVolumeI16（int16）
→ vtkImageData + vtkShortArray → vtkSmartVolumeMapper（整卷进显存）
切片：复用 SliceTool（reslice 对 int16 image 同样工作）
持久化：VolumeBuildParams + int16 明细【真实落盘 + 分块压缩】
```
体积测算（明星路全路段，依据真实头文件）：
| 网格 (横×纵×深) | 体素数 | int16 体积 | 进显存? |
|---|---|---|---|
| 10cm×10cm×2cm | 22230×270×400 ≈ 2.4G | **4.8GB** | 12GB+ 显卡可 |
| 10cm×10cm×原生821 | ≈ 4.9G | **9.8GB** | 16~24GB 显卡可 |
| 5cm×5cm×5cm | 44460×540×160 ≈ 3.8G | **7.7GB** | 16GB+ 显卡可 |
**关键：5~10GB 全部在单显卡可承载区间——不需要金字塔/核外。** 那个 39TB 是 cm 级横向过采样的产物，物理无意义。
---
## 2. 三处核心升级（相对 A）
### 2.1 dtype：引入 int16 体（4× 内存削减）
- 现 `ScalarVolume` 全仓库是 `double`（`Field.hpp:8-26`），直接改全局风险大。**方案**：新增并行的 `ScalarVolumeI16`（`std::vector<int16_t>` + 同样行优先布局 + 量化标定 `scale/offset` 把物理值映射到 int16），雷达走 int16 路径，反演剖面仍走 double。
- 渲染：`buildVoxel` 增加 int16 重载 → `vtkImageData` + `vtkShortArray`。**评审已证实** GPU 体绘制原生支持 short（`vtkSmartVolumeMapper`→`vtkOpenGLGPUVolumeRayCastMapper`→`vtkVolumeTexture` 走 GL 16-bit 整型纹理）。NaN/空值改用 int16 哨兵（如 `INT16_MIN`）+ 不透明度传递函数透明（与现 `VoxelActor.cpp:23-24,68-72` 同构）。
- 收益：同体素数内存/显存/磁盘 = double 的 1/4，是"让全路段进显存"的关键杠杆。雷达原始本就是 int16，**无精度损失**。
- **适配面比"加个重载"大（评审 HIGH）**：`ScalarVolume`(double) 被 `VolumeGrid`/`buildVoxel`/`finalizeVolume`/`Api3dRepository`(`StoredVolume.cachedGrid`、`loadVolume` 回调签名、`VolumeInfo` 统计) 一路引用。int16 体需让这些**要么模板化、要么并行一套带量化 meta 的变体**。隔离方向（雷达 int16 / 反演剖面仍 double）对，但工作量按"中"算偏乐观，§6 已上调。
### 2.2 维度上限：由物理分辨率决定，拆掉 400³ 死值
- 移除/放宽 `kMaxVolumeDim=400`（`VolumeBuilder.hpp:8`），改为按 `cellXY/cellZ` 与场景范围算出 dims，并加**显存预算守卫**（建体前估算 `nx·ny·nz·2B`，**并留余量**：实际还要叠加传递函数纹理 + 颜色/深度 FBO，按裸标量算偏紧——评审 MEDIUM）。
- **显存探测无可靠跨厂商 API（评审 MEDIUM）**：OpenGL 无统一"可用显存"查询。实践只能 try-upload-on-fail 或留保守阈值。
- **免费兜底（评审发现，spec 原漏报）**：`vtkSmartVolumeMapper` 自带 `MaxMemoryInBytes` + `LowResResample`（`vtkSmartVolumeMapper.h:194-211,373-379`），体超显存时**自动降采样重采样到可容纳**——等于"概览体"免费实现。目标机显存小时优先用它 + 按区域细化，**仍在 B 框架内，不必转 C**。
- 默认网格由雷达物理分辨率给（横 5~10cm、深 2~5cm），不让用户填出过采样网格。
### 2.3 插值：结构化建体，不做 3D 散点 IDW
- **重要架构洞察**：雷达数据沿测线(X)、深度(Z)**本就是规则密采样**，只有横向(Y)的 14 通道是稀疏的。所以"插值成体"≠ 3D 无结构散点插值，而是：
- X、Z 方向按道距/采样直接落格（重采样/最近邻，廉价）；
- **只在 Y 方向对 14 通道做 1D 插值**填充横向空隙。
- 这比 A 复用的全 3D IDW **快一两个数量级**，且单线程可接受；若仍慢，Y 向插值天然可并行（QtConcurrent/std::thread，按 X 切片并行）。
- 保留 `IInterpolator` 抽象，新增 `GprStructuredBuilder` 实现,与 IDW 并列。
---
## 3. 持久化（真正满足"算一次、之后秒开"）
用户要两种保存，B 把第二种做实：
- **方式一（参数档）**：`VolumeBuildParams`（源 .iprb 引用 + 建体参数 + 色阶 + 量化 scale/offset）+ `GridSpec`。小、可复算、详情面板展示。
- **方式二（明细缓存，升级为真实落盘）**：int16 体 **分块写盘 + 逐块压缩**：
- **⚠ 不能用 `vtkHDFWriter`（评审 CRITICAL，两个评审独立证实）**：VTK 9.6 的 `vtkHDFWriter` **写不了 `vtkImageData`/规则体**——它只支持 PolyData/UnstructuredGrid/Partitioned/MultiBlock（`vtkHDFWriter.h:6-9,232-235`，无 ImageData 写重载）。`vtkHDFReader` 能**读** ImageData，但 Writer 不能**写**，读写不对称。"补个 IOHdf 组件就能 VTKHDF 原生落盘体"的说法**错误**。
- **首选（改正后）**：**自定义 raw int16 分块 + sidecar(GridSpec/量化 scale·offset/vmin·vmax/分块索引) + 逐块 zlib（VTK 自带 `vtkzlib`，无需新依赖）**。分块布局从一开始就设计好，C 的"切片核外"可几乎免费复用同一格式。
- 备选：直接用底层 `vtkhdf5` C API 自写 chunked dataset（绕过 `vtkHDFWriter`），获得 HDF5 生态兼容；成本高于 raw 分块。
- 不引入独立 zstd/blosc（vcpkg 未含；如需更高压缩比再加）。
- **加载**：有明细 → 读盘(可 mmap)→ 整卷上显存；无明细 → 按参数后台线程重算落缓存（复用现有重算逻辑 `Api3dRepository.cpp:212-225`，从 mock 升级为真实落盘）。
- **后台重算不阻塞 UI（评审 MEDIUM）**：现 `loadVolume` 回调**在主线程**（mock 同步）。改为工作线程建体/重算后，回调要**跨线程编组**回 UI（Qt 信号 / `QMetaObject::invokeMethod`），这是线程模型改动，需显式设计。
- **加载耗时别承诺"秒开"（评审 LOW）**：5~10GB 上传 GPU(约 1~5s) + 压缩明细解压，实际**约 10s 量级**。明星路单体压缩后约 2~6GB，读盘+解压秒~十秒级——比每次重算快得多，用户"算一次之后快读"诉求成立。
### 3.5 量化贯穿（评审 HIGH，正确性问题，必做）
int16 渲染标量是量化域 `q = round((v_phys - offset)/scale)`，不是物理值。必须把量化贯穿全链，否则色阶/读数全错：
- **传递函数 / 不透明度**：现 `VoxelActor.cpp:62-72` 用物理 `vmin/vmax` 加控制点 → int16 路径必须改成在**量化域 `qmin/qmax`** 采样。
- **切片色阶 LUT**：`buildLut(cs,vmin,vmax)`（`SliceTool.cpp:37`）同理喂量化域。
- **反量化显示**：取值光标 / 异常详情 / 数据详情面板展示给用户的值必须 `v_phys = q*scale + offset` 反量化回物理量。
- `scale/offset` 存入 `VolumeBuildParams` 并随 `VolumeInfo` 传递。
---
## 4. 渲染与交互（基本复用，验证为主）
- 整卷 `vtkSmartVolumeMapper`（现有），int16 image 直接喂；确认 9.6 的 GPU ray cast 对 short 标量正常。
- 切片 `SliceTool`（`vtkImagePlaneWidget`/`vtkImageReslice`）对 int16 image 同样工作（CPU reslice 与 dtype 无关）；丝滑度由"整卷已在显存"保证。
- 异常/详情/色阶：复用现有 3D 分析栏链路。
---
## 5. 评估
**优点**
- **全路段完整连续体 + 最好体验**，切片/体绘制丝滑，且**不必上金字塔/核外**。
- 复用现有渲染/切片/异常/详情，主要新增 = int16 路径 + 结构化建体 + 真实落盘。
- int16 + 结构化插值同时解决"内存/显存/磁盘大"和"插值慢"。
- 明细真实落盘，"算一次秒开"成立。
**缺点/风险（评审分级）**
- **CRITICAL（已在 §3 修正）**：`vtkHDFWriter` 写不了 ImageData → 落盘改裸 int16 分块+zlib。有现成退路，非方案推翻，但落盘是"自写格式"的中等工程，非"补组件"。
- **HIGH**：量化未贯穿传递函数/色阶/反量化会导致颜色与读数错（§3.5 已补设计）。
- **HIGH**：int16 适配面被低估（`VolumeGrid`/`loadVolume` 回调/`StoredVolume`/`VolumeInfo` 均需带量化 meta），非单点重载。
- **MEDIUM**：后台重算从主线程改工作线程，跨线程回调编组需设计；显存无可靠查询、预算按裸标量偏紧；结构化落格假设道近似等距，GPS 抖动需沿弧长重采样。
- **LOW**：5~10GB 加载约 10s 级，UX 别承诺"秒开"。
- 单巨体无部分加载：打开即载全量。
- int16 路径是对核心类型的扩展，需谨慎不污染 double 主路径（用并行类型隔离）。
**适用**
- 当前明星路这一档（及绝大多数单路段工程）。**这是默认推荐。**
---
## 6. 工作量与落地顺序
0. **【开工前】验证 spike（~半天）**：`vtkShortArray` 填小 `vtkImageData` → `vtkSmartVolumeMapper` 跑通 GPU ray cast + 量化域传递函数，确认 GPU 路径与颜色正确。
1. 地基（同 A §2）：`.iprb`/`.iprh` 解析 + 配准 + 接入（~中）。
2. `ScalarVolumeI16` + `buildVoxel` int16 重载 + 哨兵透明 + **量化贯穿传递函数/LUT/反量化（§3.5）**（~中大，评审上调：适配面比单点重载大）。
3. `GprStructuredBuilder`（X/Z 落格 + Y 向插值，可并行；GPS 抖动需沿弧长重采样）替代全 3D IDW（~中）。
4. 显存预算守卫（留 FBO/传函余量）+ `LowResResample` 概览兜底 + 物理分辨率默认网格（~小）。
5. 明细真实落盘（**raw int16 分块 + sidecar + zlib，不用 vtkHDFWriter**）+ 后台重算（**含跨线程回调编组**）（~中大，评审上调：自写分块格式 + 线程模型）。
6. 渲染/切片对 int16 的验证（~小）。
**结论（评审：Go 条件式 / 用户定：与 C 都做）**：B 用"右尺寸 + int16 + 结构化插值"在现有架构上拿到全路段完整体验。**前置条件**：§3 落盘章节已从 VTKHDF 改为裸分块、§3.5 量化设计已补、第 0 步 spike 通过——满足后即可进入实现。B 与 C 经同一 `IVolumeRenderSource` 并存，用户按数据规模在两者间切换（能进显存走 B、超显存走 C），落盘格式两者共用（B 的裸分块是 C 分块/金字塔的基座）。

108
docs/superpowers/specs/2026-06-23-gpr-volume-C-chunk-pyramid-outofcore.md Normal file
View File

@ -0,0 +1,108 @@
# GPR 三维体 · 方案 C：分块 + 金字塔 + 核外（应对超大数据量）
- 日期：2026-06-23
- 范围：当单个三维体在**合理分辨率下仍超显存/内存**时（几十公里测线、多工区合并、或必须超精网格），采用业界处理 TB 级体的标准架构：**分块(bricking) + 多分辨率金字塔(LOD) + 逐块压缩 + 核外按需加载(out-of-core)**。
- 定位（2026-06-23 用户定）：**与 B 对等的两条已承诺路线之一，两者都做、用户运行时按需切换**（不是 B 的兜底/预案）。对标地震(OpenVDS/ZGY)、数字病理/显微(OME-Zarr)。B 适合能整卷进显存的体、C 适合超显存/超大范围的体，由用户按数据选择，经同一 `IVolumeRenderSource` 接口切换。
- POC（用户定）：C 的 POC **含"最小但真实的核外分页器"**，正面验证最高风险点（分页器在 VTK 上可行性、块边接缝、LOD 闪烁、热路径解压），"POC 过 ⇒ 可落地"。
- 前置：地基(`.iprb` 解析/配准/接入) 与 int16 + 结构化建体 与方案 B 共用。
- **⚠ 评审结论（2026-06-23，opus）+ 用户决策**：**Go——C 是已承诺路线，与 B 都做。** 架构对标业界无误。开工注意：①`vtkHDFWriter` 写不了规则体（与 B 同源 CRITICAL，§2.2 已改正为裸 HDF5/分块）；②整卷核外分页器无 VTK 开箱基础（CRITICAL，月级，**POC 即用最小真实分页器正面验证**）；③`vtkSmartVolumeMapper` 自带 `LowResResample` 仅作 C 内的降质兜底手段，不替代 C。落地顺序：裸分块格式 → 切片核外 → 整卷核外分页器。
---
## 1. C 的适用场景（用户在 B/C 间按需选择的依据，非"门槛"）
C 与 B 并存，用户对某个体选 C 而非 B，典型是：
- 合理分辨率(5~10cm)下单体 int16 体积 **超过本机显存**；
- 测线长一个数量级（几十 km）或多工区拼接成连续大体；
- 需要在内存/显存恒定下浏览任意大的体。
B 与 C 同为成品、经同一 `IVolumeRenderSource` 切换；小体走 B（整卷最省力）、大体走 C（核外不爆内存），**由用户按数据选**。
---
## 2. 架构
```
建体(int16) → 分块(brick 64³/128³) → 逐块压缩 + 每块 min/max
→ 多分辨率金字塔(全分辨率 / 1/2 / 1/4 / 1/8 …)
→ 写入分块格式文件（离线/后台一次）
渲染 → 核外分页器：按相机视野 + LOD 选块 → 解压载入显存 → 相机移动换入换出
内存/显存只驻留当前所需块（数 GB），与总体积无关
切片 → 只读切面相交的块（最便宜的子集）；等值面靠每块 min/max 剔除
交互 → 拖动用粗 LOD，停下加载全分辨率；沿拖动方向预取
```
### 2.1 存储格式（分块 + 金字塔 + 压缩）
- **⚠ 不能依赖 `vtkHDFWriter`（评审 CRITICAL，与 B 同源）**：VTK 9.6 的 `vtkHDFWriter` **写不了 `vtkImageData`/规则体**（`vtkHDFWriter.h:6-9,232-235`，仅 PolyData/UnstructuredGrid/composite）；且**无规则体的多分辨率 overview**（头文件唯一多级机制是 AMR 层级 `vtkHDFReader.h:203-209`，非金字塔）。所以"补 IOHdf 组件即可 VTKHDF 落盘 + overview"**不成立**——原 spec 的"待验证"实为"基本不支持"。
- **首选（改正后）**：**裸 `vtkhdf5` C API 自写 chunked dataset**（HDF5 原生 chunking + zlib 逐块压缩 + 随机访问），金字塔层作为多个 HDF5 dataset **自行组织**；或自定义 brick 文件（裸分块 + 索引），每块 zlib + 头存 min/max + LOD 偏移表。**与 B 的落盘层统一**（B 本就要改成裸分块，正好一并设计成可分块/可多级）。
- 不引入独立 zstd/blosc（vcpkg 未含）；如压缩比不足再评估加入。
### 2.2 渲染端核外分页（C 的真正难点）
- **VTK 不开箱提供大体的 out-of-core GPU 体绘制（评审证实）。** 注意两个相关但不够用的开箱件：
- `vtkMultiBlockVolumeMapper` **存在但不是分页器**（`vtkMultiBlockVolumeMapper.h:14-21`：试图"同时加载所有块"，仅 GPU 分配失败才退化逐块重载）——它给的是"多块同时渲染 + 抖动抗块边接缝"，**没有按视野换入换出/LOD 选块/预取**。要复用它做渲染层，须在喂数据前自己完成"只放视野块"的筛选。
- `vtkSmartVolumeMapper` 的 `LowResResample`（见 B §2.2）是"自动降质看全貌"，**不是核外**——它是 C 之前的免费兜底，不是 C 的实现。
- 整卷核外分页器须**从零自建**（选块/LOD/LRU/解压/换入换出/预取）。三条路：
1. **切片优先（推荐先做）**：切片只需读相交的块，复用 `vtkImageReslice` 对"当前块集合"重采样。**这条最易落地**，能先拿到"超大体看切片"的能力，不碰整卷核外。
2. **自建 LOD + brick 分页**：在 `vtkSmartVolumeMapper` 之上，把视野内块按 LOD 作为多个 `vtkImageData`/`vtkMultiBlockDataSet` 动态加载/淘汰。整卷透明体绘制走这条，**工作量最大**。
3. **集成 OpenVDS**（地震库）：能力最全但**重依赖**（vcpkg 未含，需自带 + 适配 VTK），适配成本高。
- 建议：**先做 1（切片核外），整卷体绘制核外(2)列为后续**。
### 2.3 建体/金字塔流水线
- 复用方案 B 的 int16 + 结构化建体产出全分辨率体 → 分块 → 逐级降采样建金字塔 → 逐块压缩落盘。
- **离线/后台执行一次**，结果即持久化产物（C 的"保存插值后体"天然就是这个分块金字塔文件）。
---
## 3. 持久化
- C 的存储格式**本身就是方式二（明细缓存）**：分块 + 金字塔 + 压缩，是"算一次、之后秒开"的载体，且读取只碰视野块、内存可控。
- 方式一（参数档 `VolumeBuildParams`+`GridSpec`）仍保留，用于复算/详情/校验。
- 切片/异常坐标仍锚定 `GridSpec`（与 A/B 一致），保证跨 LOD 一致。
---
## 4. 评估
**优点**
- **不设规模上限**：任意大小（几十 GB ~ TB）皆可，内存/显存恒定在数 GB。
- 切片只读相交块、等值面块级剔除、拖动 LOD 降级 —— 大体交互可做到流畅。
- 与业界(地震/医学)成熟路径同构，可借鉴现成设计。
**缺点/风险（评审分级）**
- **CRITICAL**：`vtkHDFWriter` 写不了规则体 → 落盘须自写裸 HDF5/分块（§2.1 已改），是中大件，非"补组件"。
- **CRITICAL**：整卷核外分页器**无 VTK 开箱基础**，从零自建（选块/LOD/LRU/预取），月级且风险集中；或集成重依赖 OpenVDS。
- **HIGH**：VTKHDF 无规则体多分辨率 overview，金字塔须全自管。
- **HIGH**：压缩块解压在**交互热路径**（拖动每帧换块解压），CPU 可能成瓶颈——不止 IO 放大。
- **MEDIUM**：LOD 降采样的半像素偏移 → 异常拾取**跨层落点漂移**（"GridSpec 锚定保证一致"未覆盖此情形）。
- **MEDIUM**：块边接缝（MultiBlock 抖动可部分缓解）/ LOD 切换闪烁（需 morphing/淡入自解决）。
- 复杂度高 → 维护成本与缺陷面大。
- **依赖断点（评审）**：C 声称"复用 B 的落盘"，而 B 那层须先从 VTKHDF 改成裸分块 HDF5——C 的"地基已就绪"前提依赖 B 先这么做。
**适用**
- 仅当数据真正超出方案 B 的单显卡承载。**当前明星路用不到。**
---
## 5. 工作量与落地顺序（仅在需要时启动）
1. 地基 + int16 + 结构化建体（与 B 共用，若已做则复用）。
2. 分块格式 + 逐块压缩 + 每块 min/max（VTKHDF 或自定义）（~中大）。
3. 多分辨率金字塔生成流水线（后台一次）（~中）。
4. **切片核外**：按切面读相交块重采样（~中）—— 先交付这条。
5. 整卷体绘制核外分页器 + LOD 拖动降级 + 预取（~大，后续）。
6. 显存/内存缓存与淘汰策略（~中）。
---
## 6. 与 A/B 的关系
- 能力：A ⊂ B ⊂ C；成本同序递增。
- A、B 共享渲染/切片现有架构；**C 是不同的存储+渲染架构**（分块+核外），是 B 撞到显存天花板后的演进，不是平行替代。
- **推荐策略**：现在做 B 满足明星路与多数工程；把 C 的"分块格式 + 切片核外"作为**预案**，待出现真正超大数据再启动；整卷体绘制核外列为最后一档。
> **切片核外"最易落地"有隐藏前提（评审）**：它要求分块格式**已做完**才能"读相交块"。所以"先交付切片核外"≠ 可跳过分块——§5 顺序（先分块格式再切片核外）正确，别误读为切片核外是独立小工程。
**结论（用户定：Go，C 与 B 都做）**：C 的总体架构成立、对标 OpenVDS/ZGY/OME-Zarr 无误，是与 B 对等的已承诺成品；工程最重、渲染端整卷核外非开箱、落盘须裸 HDF5（已改）。
- **落盘与 B 统一**：裸分块格式（不依赖 vtkHDFWriter），B 落盘本就改裸分块，C 的分块/切片核外在同一格式上增量获得。
- **整卷核外分页器**是 C 的最高风险件（两个 CRITICAL + 热路径解压 HIGH，月级），**POC 即以"最小真实分页器"正面验证**，确保"过了能落地"。
- **B/C 切换**：经 `IVolumeRenderSource` 运行时切换，用户按数据选；`LowResResample` 是 C 内的降质手段，不替代 C 也不替代用户选择。

202
docs/superpowers/specs/2026-06-24-vtk-category-view-refactor-design.md Normal file
View File

@ -0,0 +1,202 @@
# VTK 三维分析视图重构设计（按数据类型分组 + 对象树联动）
> 日期 2026-06-24 · 分支 `feat/vtk-3d-view` · 状态：设计待评审
> 配套后端契约见 [`HANDOFF-vtk-3d-backend-api.md`](../HANDOFF-vtk-3d-backend-api.md)；持久化定论见记忆 `vtk-3d-persistence-structure`。
## 1. 背景与目标
现状 VTK 视图左侧 `ColumnDrawer` 是三个固定 tab（三维数据集 / 二维数据集 / 三维分析），`splitByDimension` 仅按 `ddCode` 把数据集分到 3 个维度桶。
新需求：把「三维数据集」并入「三维分析」，改成**按数据类型大类分组**的视图（电阻率 / 视电阻率 / 瞬变电磁 / 三维体 / 切片），每类有各自的筛选条与操作；对象树勾选与 VTK 列表联动，且支持 GS / 项目层级直挂的数据集；全局视图控制移到 VTK 画布工具条。
**目标**：在保持现有渲染/交互能力的前提下，完成上述信息架构与交互重构，分类与筛选数据全部走已查实的真实字段，不引入臆测。
## 2. 范围
**含**：
- 「三维数据集 + 三维分析」合并为按大类分组的「三维分析」tab。
- 分类层由 `ddCode`（3 维）改为 `dsTypeCode`（大类）映射表驱动。
- 对象树联动改造：非根 GS 三态复选框 + 右键 ds/tm；项目根直挂数据固定显示；按 `structParentConfType` 分流拉取。
- 装置类型 / 采集时间筛选落地（客户端可做，不依赖后端补字段）。
- 全局视图控制（坐标轴 / 比例 / 快捷视图 / 缩放）移到中央 VTK 画布工具条。
- 三维体/切片生成（`createVolume/createSlice`）按契约 DTO 组装出**真实 `VoxelGenerateRequest`/`SliceGenerateRequest` 请求体结构**（仍走 mock 存储、假 id），供后端联调、并为将来切真实端点铺序列化路径。
**不含**：
- 「二维分析」tab（现 `Column2DDataset`）本次不改。
- 三维体 / 切片 / 异常的持久化切真实（仍走 `Api3dRepository` mock，后端就绪后另行切换，见配套 handoff）。
- 后端接口改动（装置类型值→中文字典源待坐实，见 §11）。
## 3. 实测依据（关键事实，已通过真实接口核实）
后端基址 `http://tenant.geomative.cn/pop-api`，样本项目「演示项目（高密度+瞬变）」`1438889436225536`。
1. **大类必须按 `dsTypeCode` 分**，不能按 `ddCode`——电阻率 / 视电阻率 / 瞬变电磁反演剖面**三者 `ddCode` 同为 `dd_inversion_data`**，仅 `dsTypeCode`/`name` 不同：
| 大类 | ds 行 `name` | `dsTypeCode` |
|---|---|---|
| 电阻率数据 | 电阻率数据 | `ERT platform inversion data` |
| 视电阻率数据 | 视电阻率数据 | `visual resistivity data` |
| 瞬变电磁数据 | 瞬变电磁反演剖面 | `DD TRANSIENT ELECTROMAGNETIC INVERSION` |
2. **装置类型与采集时间是 ds 的结构化属性**：`dsObject/dynamicForm/{id}` 的 `formList` 定义字段 `arrayType`(装置类型,下拉)、`collectTime`(采集时间)；ds 行 `properties` 按 confFieldId 携带其值。装置类型只 ERT 类（电阻率/视电阻率）有，瞬变电磁没有。
3. **装置类型枚举**：`GET /business/script/arrayTypeList` → `[{itemValue,name}]`（温纳排列(α)…施伦贝谢尔…共 15 项）。
4. **层级拉取**：`dsObject/data/page` 按 `structParentId` + `structParentConfType`（1=GS/项目，2=TM）查；客户端 `loadRowsAsync` 第 3 参即 `parentConfType`，现状写死 2。
5. **遗留**：`arrayType` 值是 id（如 `1429468249448449`），实测**不在**该字段 `optionsObject`（另一套 id 体系）里，value→中文字典源待坐实（§11）。
## 4. 整体架构
`ColumnDrawer` 改为两 tab：「三维分析」「二维分析」。二维分析不动。
**「三维分析」tab = `QScrollArea` 纵向堆叠 5 个类型段：**
```
┌─ 三维分析 ──────────── 二维分析 ─┐
│ ▼ 电阻率数据 [日期▾][装置类型▾]│ 段头:类型级筛选
│ ▸ 演示项目(根·直挂ds固定·无复选框) │
│ ▾ ☑ ERT1 (GS·三态) [右键:生成体]│
│ ☑ ERT1-WN (数据行·勾选=渲染)│
│ ☑ ERT1-WS │
│ ▾ ☐ ERT2 (GS) [右键:生成体]│
│ ▼ 视电阻率数据 [日期▾][装置类型▾]│
│ ▼ 瞬变电磁数据 [日期▾] │ 无装置类型筛选
│ ▼ 三维体 [日期▾] │ 体→[切片们 + 直接挂体的异常]三级树
│ ▾ 体A │
│ ▾ 切片S1(挂体A) │
│ 异常a1(挂S1) │
│ 异常a2(挂体A,临时切片上画) │
│ ▼ 切片 [日期▾] │ 已保存切片(挂父体下,与三维体段切片同源)
└──────────────────────────────────────┘
```
**全局视图控制移到中央 VTK 画布竖排工具条：** 设置(⚙→坐标轴设置对话框) / 快捷视图(前后上下左右) / 放大·缩小·复位(=现"适配")。
## 5. 数据模型与分类层
**`DsRow` 扩展**（`RepoTypes.hpp`）：现解析 `id/dsName/typeName(=name)/ddCode/createTime/parentId/file*`，新增：
- `dsTypeCode` —— 大类分类主键。
- `arrayType` —— 装置类型值（从 ds 行 `properties[]` 按 confFieldId 取）。
- `collectTime` —— 采集时间（同上）。
`NavDto::parseDsRows` 补这三个字段的解析。**两接口 `properties` 形态不同（实测）**：`dsObject/data/page` 的 ds 行 `properties` 是 **`[{confFieldId,value}]` 数组**（按 confFieldId 取值）；`dsObject/dynamicForm/{id}` 的 `properties` 是 **`{fieldCode:value}` map**（现 `parseDynamicForm` 用 fieldCode 取值，正确、不冲突）。DsRow 解析的是前者，故需配合 §10 的 confFieldId↔fieldCode 映射定位 arrayType / collectTime。
**分类配置表 `CategoryConfig`**（新文件，集中一处，开闭原则）——每段一条，带元数据：
| 段序 | 段名 | 识别键 | 可生成三维体 | 装置类型筛选 |
|---|---|---|:--:|:--:|
| 1 | 电阻率数据 | `dsTypeCode = ERT platform inversion data` | ✓ | ✓ |
| 2 | 视电阻率数据 | `dsTypeCode = visual resistivity data` | ✓ | ✓ |
| 3 | 瞬变电磁数据 | `dsTypeCode = DD TRANSIENT ELECTROMAGNETIC INVERSION` | ✓ | ✗ |
| 4 | 三维体 | `ddCode = dd_voxel` | — | ✗ |
| 5 | 切片 | `ddCode = dd_slice` | — | ✗ |
**`splitByCategory(rows) -> CategoryBuckets`**：替代 `splitByDimension`，按配置表把 `DsRow` 分入有序大类桶；不在表内的 dsTypeCode（接地电阻/原始数据/白化/坐标等）丢弃。
## 6. 对象树联动（`ObjectTreePanel` 改造）
**节点交互模型：**
| 节点 | 复选框 | 右键新增项 |
|---|---|---|
| 项目根 | 无（不可勾，直挂 ds 固定显示） | —（生成三维体改在段头，见 §7） |
| 非根 GS | 三态 | 选择 ▸ ds / tm（带对号） |
| TM 叶子 | 普通二态 | — |
**GS 三态语义**（标准 tristate 聚合）：GS 复选框 = `[GS 自身 ds]` + `[所有子 TM 勾选]` 的聚合；都有=Checked，都无=Unchecked，部分=PartiallyChecked。
- 右键「选择 ▸ ds」= 切换「GS 自身 ds」开关（GS 自身 ds 在树中无独立复选框载体，故必须由此控制）。
- 右键「选择 ▸ tm」= 一键全选/全不选所有子 TM（子 TM 仍可单独勾，此项是批量便捷）。
- 点 GS 复选框：任一开 → 全关；全关 → 全开。
- 菜单项按有无动态禁用（无直挂 ds 禁 ds 项，无 TM 禁 tm 项）。
- **实现约束（必须）**：**停用现有 `Qt::ItemIsAutoTristate`**（`ObjectTreePanel.cpp:123`）——它只聚合子项 checkState、看不到「GS 自身 ds 开关」这第二维度，直接套用会产出错误聚合态。改为：用一个 `UserRole` 在 GS 节点存「自身 ds 开关」布尔，`itemChanged` 里手动按「ds 开关 ∨ 子 TM 勾选」计算父三态并 `setCheckState`（复用现有 0ms 合并防重入 pattern，避免级联多次触发）。
**信号扩展**：`checkedTmsChanged(QStringList)` → `checkedSourcesChanged(QList<DataSource>)`，每个 `DataSource = {id, confType}`：
- 勾选 TM → `{tmId, 2}`；GS 自身 ds 开关开 → `{gsId, 1}`；项目根直挂（固定）→ `{rootId, 1}`。
- 集合为**按 `{id,confType}` 去重的并集**：一条 TM 既被 GS 聚合又被单独勾时只算一次；`confType=1`(GS/项目)拉该节点**直挂 ds**、`confType=2`(TM)拉 TM 下 ds，二者物理数据不重叠，不会重复进桶。
**数据流**（`main.cpp` 接线）：
```
checkedSourcesChanged
→ 对每源 loadRowsAsync(projId, src.id, src.confType, classify=3, …) // 第3参按源传(1/2)
→ 汇总 DsRow[] → splitByCategory → 各 CategorySection.setDatasets
```
## 7. 类型段组件 `CategorySection`
一个可参数化的类型段（单一职责，高内聚），由 `CategoryConfig` 一条配置驱动：
- **段头**：标题 + 折叠开关 + 日期范围筛选 + 装置类型下拉（仅 `装置类型筛选=✓` 的段显示）。
- **段体**：项目根 / GS / TM 树 + 数据行，复用 `DatasetListPanel::populateDatasetList`（按 parentId 建树）与卡片委托；数据行可勾选 = 渲染。
- **渲染勾选链承接（必须）**：CategorySection 暴露 `checkedDatasetsChanged`，**接管退役的 `Column3DDataset` 原有「剖面勾选→帘面渲染」主链**——main.cpp 把 5 段（电阻率/视电阻率/瞬变=帘面，三维体/切片=体素/切片）的勾选并集后下发 `pushChecked`（沿用现有 `checkedProfiles`/`checkedAnalysis` 并集模型），否则帘面渲染整体失联。
- **生成三维体入口**：仅 `可生成三维体=✓` 的段（电阻率/视电阻率/瞬变电磁）**段头**有「+新增三维体」按钮。**源数据集 = 三维分析中当前勾选的同类型 ds**（本段类型，天然按段隔离、可跨 GS）。点击 → `VolumeParamsDialog`（页面中心弹窗）：**左侧·数据列表** 树状（按 GS 分组）展示这些已勾选源，每项可勾选/取消供**确认或二次修改**；**右侧·插值参数**：名称、**生成位置**（下拉）、插值模型、水平/竖向间距、IDW 幂次、最大影响距离。**生成位置（归属）规则**：默认 = 源同属单 GS→该 GS、源跨 GS→项目根；用户可改为**项目内任意 GS / TM**（故归属 `structParentConfType` 可为 1 或 2，与源数据解耦）。提交 → 组装 `VoxelGenerateRequest` → `createVolume`。
- **筛选**：复用并扩展 `applyDatasetFilter`，日期比较字段由 `createTime` 改为 `collectTime`（§10）。
「三维分析」tab 容器（替代原 Column3DDataset/Column3DAnalysis 在 tab 中的位置）：`QScrollArea` + 垂直布局，按配置表实例化 5 个 `CategorySection`。
## 8. 三维体 / 切片 / 异常段
复用现有 `Api3dRepository`（mock）与 `refreshAnalysis` 合并注入机制，仅重新组织到段：
> 三维体归属由「生成位置」选择决定：默认单 GS→该 GS、跨 GS→项目根，用户可改为项目内任意 **GS / TM**（`structParentConfType` 可 1 或 2）。后端契约 `docs/api/vtk-3d-openapi.json` 已同步至 v0.6-draft（`structParentConfType` 放开 1/2 + 默认规则）；客户端 `createVolume` 接真实端点时需补 `structParentId/structParentConfType`，并新增按归属实体 id 查异常的 `queryException/{remarkSourceId}` 调用。
**三维体段是「体 → 切片 / 异常」三级树**（**取消独立异常区**——异常不再单列，而是作为叶子挂在它归属的实体节点下）：
- **三维体段**：列已生成的体（客户端 mock + 后端 `dd_voxel`），按归属（项目/GS/TM）分组。（**「正在生成…」状态**：现 `createVolume` 同步登记、首次 `loadVolume` 惰性插值，本期**不引入异步生成态机**、体即时出行。）体节点下挂：① 基于该体生成的**切片**子节点；② **直接挂体的异常**（见归属规则）。多体可同时勾选渲染（`dsProps_` 按 dsId 各存 actor），切片/异常操作针对「当前激活体」`volumeOwnerDs_`（=切片源体 `currentVolumeImage_`）。
- **异常归属（核心规则）**：异常**必基于切片**（在某切片平面上画），切片**必基于体**（`SliceSpec.volumeDsId`）。查找链 `异常 → 所在切片 → 切片所属体`。挂载目标按**该切片是否已保存成 `dd_slice`** 决定：
- 切片**已保存**（是 `dd_slice` 实体）→ 异常挂**该切片**（`remarkSourceId=切片dsId`）。
- 切片**未保存**（临时圈定平面）→ 异常挂**切片所属体**（`remarkSourceId=体dsId=volumeOwnerDs_`）。
- 数据模型：`Anomaly` 的 `volumeDsId` 改名为 `remarkSourceId`（= 挂载实体 dsId，体 or 切片；对齐后端 `remarkSourceId=dsObjectId`）。挂体/挂切片由 `remarkSourceId` 指向的实体类型区分（查 `isVolumeDataset`/`isSliceDataset`），展示树按 `parentId=remarkSourceId` 自动挂到对应节点——**不引入新 type 字段**。⚠️ 后端 `remarkSourceType` 已是**标注几何形态**(1点/2线/3面/4文字 = `Anomaly.markType`)，勿与"挂体/挂切片"混淆。仍 mock 存储。
- **切片段**：列已保存切片（`dd_slice`），按父体分组（`parentId` = 所属体）。与三维体段内的切片子节点同源（同一批 `sliceRows`）。
体素 / 切片 / 异常的渲染、生成、保存路径不变（`VtkSceneController` / `InteractionManager` / `Api3dRepository`），只改列表的承载位置。
**请求体组装（本次新增）**：`createVolume` 扩参为 `(projectId, structParentId, structParentConfType, params, name)`——归属来自对话框「生成位置」选择（GS/项目根/TM，默认单GS→该GS、跨GS→项目根）；`createSlice` 补 `projectId`。两者内部按新增客户端 DTO `VoxelGenerateRequest`/`SliceGenerateRequest`（对齐 `docs/api/vtk-3d-openapi.json` schema）组装出**完整请求体**并提供 `toJson` 序列化；mock 路径存内存 +（debug）打印请求体，将来切真实端点只把「存」改「发」、组装逻辑原样复用。如此重构一落地即可从 UI 真实产出请求体（值为 mock、结构与字段为真）。`createSlice` 补 `projectId` 会波及 main.cpp 切片保存调用点（切片右键/列表保存路径），须一并传 `nav.currentProjectId()`。
## 9. VTK 画布工具条 `VtkViewToolbar`
从 `Column3DDataset` 抽出全局视图控制，做成中央 VTK 画布上的竖排工具条（新组件）：
- **设置（⚙）** → 弹「坐标轴设置」对话框 `AxesSettingsDialog`：X 轴 / Y 轴 / 深度(m) 各带「显示」开关 + 最小值 / 最大值，取消 / 应用。
- **快捷视图**：前、后、上、下、左、右（按钮文字即此六字，沿用现有 `ViewDir` 与功能）。
- **缩放**：放大 / 缩小 / 复位（复位 = 现「适配」）。
信号沿用现有 `Column3DDataset` 已接的控制器槽（`axesModeChanged`/`verticalExaggerationChanged`/`viewRequested`/`zoom*`/`fitRequested` 等），仅迁移承载控件。水平/垂直比例的承载位置随工具条一并迁移（或并入坐标轴设置对话框，实现时取最贴合者）；`setVerticalExaggeration` 默认值回灌（main.cpp:902）也要迁到新工具条，避免默认夸张值不同步。
## 10. 装置类型 / 采集时间筛选落地
**字段映射服务 `DatasetFieldDictionary`**（新组件，按 dsType 缓存）——**为何必要**：ds 列表行 `properties` 只给 `[{confFieldId,value}]`（数字 confFieldId、无字段名），要判定哪个 confFieldId 是 arrayType/collectTime，必须从 `dynamicForm` 的 `formList`（含 confFieldId↔fieldCode 对应）取映射。
- 对每个 dsType 拉一次 `dsObject/dynamicForm`，缓存：① `arrayType` / `collectTime` 字段的 `confFieldId`（用于从 ds 行 `properties` 取值）；② 装置类型选项字典（value→中文）。
- 列表行装置类型 = ds 行 `properties` 中 `confFieldId == arrayType 的 confFieldId` 那项的 value，经字典翻中文展示与分组。
- 段头装置类型下拉 = 该段当前数据出现过的装置类型集合；选中按值过滤。
**采集时间**：日期筛选按 `collectTime`；三维体 / 切片段无此字段 → 回退 `createTime`。
## 11. 待坐实 / 风险
- **装置类型 value→中文字典源**：实测 `arrayType` 值不在该字段 `optionsObject` 里（另一套 id），`parseDynamicForm` 也不翻译；但客户端属性面板据称显中文。需在实现前坐实正确字典源（候选：`fieldConfigJsonObject.fieldDataRadius` 指向的全局字典 / `script/arrayTypeList`）——**请提供客户端数据集属性面板截图**以最快定位现有翻译路径。不阻塞其余设计。
- **三维体 / 切片 / 异常仍 mock**：后端就绪后切真实（接口 `I3dSceneRepository` 留缝），见配套 handoff。
- **跨 GS 生成体**：本次以「单容器（项目根/GS）范围」为主；跨多 GS 拼大体暂不做。
## 12. 组件 / 文件边界
| 类别 | 组件 | 说明 |
|---|---|---|
| 新增 | `CategoryConfig` | dsTypeCode/ddCode→大类映射表 + 段元数据 |
| 新增 | `splitByCategory` | 替代 `splitByDimension` |
| 新增 | `CategorySection` | 单个类型段（段头筛选/操作 + 段体树） |
| 新增 | 三维分析 tab 容器 | QScrollArea 堆叠 5 段 |
| 新增 | `VtkViewToolbar` + `AxesSettingsDialog` | VTK 画布工具条 + 坐标轴设置 |
| 新增 | `DatasetFieldDictionary` | 按 dsType 缓存 arrayType/collectTime 映射 + 装置字典 |
| 改造 | `ObjectTreePanel` | GS 三态 + 右键 ds/tm + 信号扩展为带 confType 源集合 |
| 改造 | `DsRow` + `NavDto::parseDsRows` | 补 dsTypeCode/arrayType/collectTime |
| 改造 | `ColumnDrawer` | 三 tab → 两 tab |
| 改造 | `main.cpp` | 数据流按 confType 分流拉取 + 段接线 + 生成入口传容器归属 |
| 新增 | `VoxelGenerateRequest`/`SliceGenerateRequest` DTO + `toJson` | 对齐 openapi schema 的客户端请求体结构 + 序列化 |
| 改造 | `Api3dRepository::createVolume/createSlice` | 扩参带归属/projectId，内部组装请求体 DTO（mock 存 / 将来发） |
| 复用 | `DatasetListPanel` | populateDatasetList / 卡片委托 / applyDatasetFilter |
| 复用 | `Api3dRepository` / `refreshAnalysis` | 三维体/切片/异常 mock 与合并注入 |
| 复用 | `Column2DDataset` | 二维分析 tab，不动 |
| 退役 | `Column3DDataset` / `Column3DAnalysis` | 功能拆分到 CategorySection / VtkViewToolbar / 三维体段 |
## 13. 非目标
- 不改二维分析。
- 不改后端接口、不新增后端字段（装置类型走客户端已有数据）。
- 不切换三维体/切片/异常持久化为真实后端。
- 不做跨 GS 拼体、不做装置类型以外的新筛选维度。

101
docs/superpowers/specs/2026-06-26-2d-analysis-topdown-elevation.md Normal file
View File

@ -0,0 +1,101 @@
# 二维分析：锁定俯视相机 + 内容显隐 + 高程拖动 — Spec（2026-06-26）
## 0. 一句话目标
把「二维分析」从"另一套平面地图"改为**同一个 3D 地形场景的一个锁定近俯视视角**：切 tab 只切相机+翻另一方数据集的可见标志（不清空），二维内容（轨迹/栅格）落在带高程的地形上，且可选中后沿高程上下拖动分离。
---
## 1. 背景与现状
- 三维分析栏（`CategoryAnalysisTab`）与二维分析栏（`Column2DDataset` / `col2D`）**共用同一个 `VtkSceneView` / `InteractionManager` / `renderWindow`**。现状：两栏勾选的 actor 叠在同一场景，切 tab 不切相机、不区分内容。
- 二维内容现状：`col2D` 勾选 → `loadMapLine`（`dd/ert/trajectory/line`）→ `MapLineActor`（lat/lon 折线）；有 `view2DModeChanged` 信号已接到 `sceneCtrl`（2D 视图模式钩子，本 spec 在其上扩展）。
- 地形 + 底图：场景已有地形（`buildTerrain`，带高程）+ 天地图底图（`TileBasemap`，按经纬贴）。
- 维度分类：`DatasetDimension::dimOf` + `Api3dRepository/LocalSample3dRepository::dimensionOf`，已对齐数据字典 DD0623（2D = `dd_trajectory_data`，commit c1a824e）。
**用户确认的认知**：二维分析"只是 3D 的固定视角"，底图不是平面图、是**带高程的地形图**；内容沿用不清空。
---
## 2. 核心设计：一个场景 + 两种相机
- **不分两个场景**，只有一个 3D 地形场景（地形 + 底图 + 全部已勾选数据），两栏区别仅在**相机**与**哪类数据集可见**。
| | 三维分析 | 二维分析 |
|---|---|---|
| 相机 | 自由透视（可旋转/倾斜/平移/缩放） | **锁定近俯视**（不可旋转，仅平移+缩放）|
| 可见数据集 | 3D 数据集（体/切片/剖面…）可见；2D 数据集隐藏 | 2D 数据集（轨迹/栅格）可见；3D 数据集隐藏 |
| 地形 + 底图 | 常驻可见 | 常驻可见（同一地形，俯视看即"地形图"）|
---
## 3. 二维分析的相机：锁定近俯视
- 切到二维分析 → 相机切到**近俯视固定角（约 75–80°，非绝对正俯视）**：理由——绝对正俯视在正交/小透视下高程变化不可见，留一点倾斜以便看出高低（§5 拖动反馈需要）。
- 锁定：**禁用旋转**（interactor style 不响应旋转/倾斜），仅保留**平移 + 缩放**。
- 切回三维分析 → 恢复自由透视相机（恢复切走前的视角或合理默认）。
- 实现锚点：扩展 `view2DModeChanged` 钩子 → `VtkSceneController` 切相机模式 + 切 interactor style（或在 style 内按模式禁旋转）。
---
## 4. 内容显隐：切 tab 翻可见标志（**不清空**）
- 切 tab 时，对"另一方"的数据集 actor 用 `SetVisibility(false)`，切回 `SetVisibility(true)`。**不移除 actor、不重建**。
- 性能：VTK 渲染跳过不可见 actor → 隐藏内容**不参与绘制、不耗 FPS**；切换瞬时（无重插值/重传 GPU）；唯一代价是内存/显存驻留（数据本已加载，无新增加载）。
- **禁止用清空**：重体素（GPR/ERT）每次切回要重插值+重传 GPU，必卡。
- 地形 + 底图两边都不隐藏。
- 实现锚点：`VtkSceneView` 按数据集维度（`dimensionOf`/记录每 actor 的维度）批量翻可见标志；切 tab 时调用。
---
## 5. 高程拖动（C1）：选中 2D 内容沿 Z 上下移
- 二维分析里，**拾取选中已渲染的 2D 内容**（轨迹/栅格），支持**单选 / 多选**。
- 选中后**竖向拖动 → 仅改其高程 Z（离地高度）**，**锁死 X/Y**（不动地理位置）。用于把叠在一起的 2D 层分离、看清。
- 拖动时**实时显示当前高程数值**（屏幕浮层读数）。
- 近俯视固定角（§3）使高低可见。
- 实现锚点：新增/复用一个 2D 拾取-拖动交互（类似切片 widget 但只允许 Z 平移 + 多选）；actor 的 Z 偏移持久（切走再回保留）。
- 待定：高程是否需要随数据保存（暂定仅会话内 actor 变换，不落库；接真实端点再议）。
---
## 6. dd_raster：二维栅格过滤 + 渲染（本期新增）
- 数据字典 DD0623：`dd_raster`（栅格/遥感影像，**本次新增**，展示模式 2D，形态=栅格）。
- 纳入 2D 过滤：`dimOf`/`dimensionOf` 增 `dd_raster` → `Dim2D`；但 col2D 勾选渲染须**按 ddCode 分派**——轨迹走 `loadMapLine`，栅格走**栅格加载**（不可让栅格走轨迹端点）。
- 渲染：取栅格的**地理范围（四至/仿射）+ 像素**，作为**地理配准的纹理平面贴到地形上**（带高程，可被 §5 高程拖动），类似底图瓦片按经纬度定位。
- 依赖：dd_raster 的**数据端点**（返回像素 + 四至/投影）——**待确认**，未明确前 §6 不落地（先做 §3–§5）。
---
## 7. 维度过滤口径（对齐数据字典 DD0623，已部分落地）
- 2D（足迹/栅格）：`dd_trajectory_data`（统一通用轨迹，"保留"，已并入 dd_radar_rtk_trajectory）+ `dd_raster`（本期新增，随 §6）。
- 已删除、不再单列：`dd_radar_rtk_trajectory` / `dd_transient_electromagnetic_trajectory_data` / `dd_radar_channel_trajectory`（字典均"删除"）。已清理：commit c1a824e。
- `dd_radar_2d` / `dd_radar_3d`：字典为 `展示模式=3D`（通道剖面 / 三维插值模型）→ **属三维分析，不进 2D 过滤**。
---
## 8. 与雷达客户反馈的边界（本 spec **不含**）
- 雷达 TM 模型（单/双/多频，每频一个 `dd_radar_2d`/`dd_radar_3d`，共用一个 `dd_trajectory_data` 轨迹）→ 数据模型，与本 spec 无冲突。
- 雷达**数据在 3D 视图的渲染**（二维雷达=线/curtain、三维雷达=切面，按 trace 坐标，带打标 hover tip）→ **三维分析的另立任务**。
- 详情页用 trace 坐标校准异常 + 剖面打标 → 详情页另立任务。
- **2D 视图只显示轨迹线、打标暂不在 2D 展示**（客户 #6 修正）→ 与本 spec 的"2D 显示轨迹足迹"一致，无新增 2D 工作。
- 雷达轨迹就是 `dd_trajectory_data`，本 spec 的 2D 分析按统一轨迹处理，无需特判。
---
## 9. 实现分期
- **A. 一场景两相机**：切 tab → 锁定近俯视/恢复自由相机 + 翻另一方数据集可见标志（§3、§4）。基础，先做。
- **B. 高程拖动**：2D 拾取单/多选 + 仅 Z 拖动 + 锁 XY + 实时读数（§5）。
- **C. dd_raster**：过滤纳入 + 按 ddCode 分派渲染 + 栅格地理配准贴地形（§6）。依赖栅格数据端点确认。
---
## 10. 风险 / 待定
- 近俯视角度（75–80°）需实机调；用户若坚持绝对正俯视，则 §5 高程反馈改为纯数值（不直观）。
- §4 翻可见标志需可靠区分每个 actor 的维度归属（按数据集 ddCode 记录维度 → actor）。
- §5 高程是否持久化/落库待定（暂会话内）。
- §6 dd_raster 数据端点（像素 + 四至/投影）未确认 → C 期阻塞点。
- 切相机/可见标志切换需与现有 `view2DModeChanged`、底图、地形 VE（垂直夸张）逻辑兼容，勿互相打架。
---
## 11. 验收
- 切到二维分析：相机变近俯视、**不能旋转**，只能平移+缩放；3D 数据集（体/切片/剖面）不可见，轨迹+地形+底图可见。
- 切回三维分析：恢复自由相机；3D 数据集重新可见，2D 轨迹隐藏。切换**瞬时无卡顿**（无重建）。
- 二维分析里选中一条/多条轨迹，竖向拖动→只改高程、地理位置不动、实时显示高程；叠在一起的层能被拉开。
- （C 期）勾选 dd_raster → 栅格按地理范围贴在地形上、可被高程拖动；轨迹与栅格各走各的加载路径、互不串。
- 维度过滤与数据字典 DD0623 一致（2D=trajectory_data+raster；radar_2d/3d 归 3D）。

210
docs/superpowers/specs/2026-06-26-gpr-3d-render-perf-ANALYSIS-for-review.md Normal file
View File

@ -0,0 +1,210 @@
# GPR 多通道三维体渲染性能问题 — 分析文档（供外部专家评审）
> 自包含技术文档。读者无需了解本代码库内部，只需具备 GPU 体绘制 / VTK 基础。
> 目的：把"探地雷达(GPR)多通道阵列数据渲成可交互三维体"遇到的性能问题、已试方案、实测数据、
> 待定关键点完整呈现，供外部专家判断方向。
---
## 1. 背景与系统
- 桌面端 C++ 应用（Qt6 + **VTK 9.6.2**），渲染探地雷达(GPR)采集的地下三维数据，要求**可交互**（旋转/缩放）。
- 渲染用 VTK 的 `vtkGPUVolumeRayCastMapper`（OpenGL GPU 光线投射体绘制）。
- 当前测试机 GPU：32 个着色器纹理单元（典型独显/中端）。
## 2. 数据特征（关键，决定一切）
多通道阵列 GPR，一次采集一条"测线(line)"：
- **道(trace)**：一个位置一根天线的垂直回波，深度方向 **821 采样**。
- **通道(channel)**：阵列横向并排的多对天线，本数据 **14 通道**；**相邻通道横向间距 ≈ 10.5cm**（来自 `.ord` 文件真实偏移 -0.686…+0.686m，跨度 1.37m）。
- **沿测线道间距 ≈ 4.9cm**（比横向通道间距细 ~2 倍）。
- 一条测线：沿路 **~45305 道**，覆盖 **~2.2km**（一条南北向道路）。
- **共 20 条测线 = 同一条路来回扫 20 趟**（车载，每趟阵列覆盖约 1.4m 宽，多趟铺横向）。
**单条线 = 一个三维体**：X=沿测线(~45305)、Y=通道(14)、Z=深度(821)。
**关键业务约束（来自现场专家）**：
- 通道太稀（10.5cm）→ 需**线内通道间插值**加密（相邻真实天线之间插，物理成立）；
- **绝不做"测线之间"的插值**（车与车之间是真实物理空隙，插出来"信号全是假的"，工程上不可接受）；
- 多条测线"分开各自插值，渲染可以合到一起"。
GPR 数据的统计特征（实测，见 §6）：**~91% 体素近零（反射层之间是空的），但反射层横贯整个深度分布**（不是集中一坨）。
## 3. 已建成并验证可用的功能（不是问题所在）
1. **线内通道插值**：读 `.ord` 真实横向偏移，规则化到 2.5cm 网格、相邻通道线性插值（不跨线）。
实测 Y 由 14 加密到 **56**。有单元测试。
2. **多体单遍合成**：20 条独立体（各自插值）作为一个 `vtkGPUVolumeRayCastMapper` 的多个端口注册进
`vtkMultiVolume`，**单遍 ray-cast 合成**（而非每条体一遍）。已验证。
3. **纹理单元上限自动退避**：单个 multi-volume 同时挂的体数受 GPU 每着色器纹理单元上限制约
（每体约吃 4 个单元 → 32 单元机上**一个包最多 7 体**，第 8 体报错并丢体）。已实现"渲一帧→报错则
每包减 1 重建重渲"的自动退避（强制 K=12 → 自动退避到 7，无丢体）。
4. **运行时换贴图边界**（确定性测试结论）：给某端口**就地换贴图**——若**保持包围盒不变**（同范围、
只改 Y 密度）则 multi-volume 算得对；若**改包围盒**（任意子区域、origin/范围/spacing 变）则破坏
其缓存 `TexToBBox` → 体断开/消失。
5. 通道维 LOD、统一传函、色标图例等。
## 4. 核心问题：性能
- **20 条密体（Y=56）总览，交互极卡**：静止 ~1.7 fps，旋转/缩放掉到 < 1 fps（GPU 100%）。
- 渲染**视觉正确**（雷达剖面纹理清晰、横向连续、合成无误），纯属性能。
- 现有提速手段都是**"交互时降质"**方向（降屏幕分辨率、加粗采样步长）——**损可见质量**，治标。
用户明确要求："有没有不损可见质量的根本性提速（业界最佳实践）？"
## 5. 已分析/已试的所有方案（含理由与状态）
| # | 方案 | 理由 | 状态 / 结论 |
|---|---|---|---|
| A | multi-volume 单遍合成 | 把"N 体=N 遍 ray-cast"降到分包遍数 | ✅ 已实现。但单遍内每步仍要在重叠体里逐个采样 |
| B | 纹理单元自动退避分包 | 绕开 GPU 纹理单元上限、不丢体 | ✅ 已实现（K=7/包，20 条=3 包）。代价：**跨包重叠合成不正确（接缝）** |
| C | 交互降屏幕采样(ImageSampleDistance) | VTK AutoAdjust 标准手段 | ✅ 已做。**损质量**；且 AutoAdjust 只降屏幕、不降沿光线步长 |
| D | 交互手动加粗沿光线步长(SampleDistance) | 通道插值后 Y 密→自动步长极细→巨卡；这才是大头 | ✅ 已实现（`--sampleDist`/`--dragSampleMul`）。**损质量；且用户尚未实测**（见 §7 待定） |
| E | 通道维 LOD（远疏近密换 Y 平面子集）| 保包围盒换贴图（#4 验证安全） | ✅ 已实现。但**只减纹理内存、不减每步重叠体采样次数 → 对此瓶颈几乎无效** |
| F | **装箱单体(binning)**：各线先逐线插值，再把**真实道**摆进一个总览网格体（空隙透明、不跨线插值）| 一个体一遍、每步采 1 次 → ~20×；真实数据无假信号 | ⚠️ 技术可行、合规，但**用户否决**：装箱合并后**总览里分不出各线**，而用户要"一起渲染时仍能逐线区分/查看"→ 合并即失去意义 |
| G | **空体素跳过 ESS（换 OSPRay/ANARI 后端）**：跳过透明背景块 | 业界对稀疏体的头号提速、不损质量 | ❌ **实测对本数据收益有限**（见 §6）：保质量阈值下仅 ~2×，且**ESS 跳的是空区、不解决"重叠"**。VTK 库存 mapper 无自动 ESS；OSPRay 本环境未编、vcpkg 无包 |
| H | 减少同屏体数（只渲选中 ≤7 条）| 真实工作流本就是选几条，1 包 1 遍 | ✅ 免费、永远有效（使用方式，非技术） |
## 6. 关键实测数据
### 6.1 ESS（空体素跳过）潜力——零依赖实测，决定要不要上 OSPRay
对一条真实测线密体（5702×56×789），按块算 min/max，统计"整块落在近零透明带"的占比（=ESS 可跳块）：
| 透明带半宽(相对半值域) | 8³ 块可跳占比 | 理论提速上限 1/(1−占比) | 说明 |
|---|---|---|---|
| 5% | 8% | 1.1× | 极保守 |
| **10%（保质量，不丢弱反射）** | **52%** | **~2.1×** | — |
| 20% | 80% | ~4.9× | 开始把弱反射当背景丢 |
| 30%（激进）| 90% | ~10× | 明显损质量 |
- 体素层面 **91% 近零**，但块层面（ESS 实际粒度）保质量阈值下**只能跳 ~52% → 理论 ~2×**。
- 原因：**反射层横贯整个深度分布**，多数块里总混着信号、跳不掉。要 10× 须用激进阈值（损质量）。
- **更关键**：ESS 跳"空区"，**不减少"重叠"**——在有信号的块里仍要逐个采样所有重叠体。
### 6.2 其它实测
- multi-volume 纹理单元上限：本机 7 体/包（32 单元），第 8 体报 "Hardware does not support the number of textures"。
- 体维度示例：coarse 4 → ~11000×56×793/线；coarse 32 → ~1400×56×780/线。
- 全 20 条 dense（coarse 32）：底图 level 0、Y=56、分 3 包，**渲染正确**；交互 ~1.7fps（**未加 D 方案的旧构建**）。
## 7. 关键点——已实测，结论修正（原假设两条都被推翻）
### 7.1 "重叠几层"——实测：**平均 ~8.7 层、最大 15 层（不是 ~2–3，也不是 20）**
纯几何测（各线世界 AABB 投到 X-Y 俯视 footprint、细网格统计每格覆盖层数，`--overlapStat`）：
- footprint：横向 X≈37m、沿路 Y≈2.2km；
- **有体覆盖处平均重叠 8.74 层，最大 15 层**；穿 12–14 个体的格子占 ~42%。
- **结论修正**：原"~2–3 层"假设**错**（开发团队和外部专家都猜偏了）；**重叠是真实的大瓶颈**。
- **且这 9 层是冗余**：20 趟是同一条路反复扫，同一地下点被测了 ~9 次 → 这 9 个重叠体在该处**都非空**
（同一地下结构）→ **ESS 在重叠区一个都跳不掉**（再次印证 ESS 不解决重叠）。
### 7.2 "采样 vs 重叠谁是大头"——实测：**采样瓶颈，fps 线性正比于步长**
20 条密体、静止近景、离屏（步长越大越快越糙）：
| sampleDist | fps | 相对 |
|---|---|---|
| 0.2（≈自动细）| 1.3 | 1× |
| 0.5 | 3.2 | 2.5× |
| 1.0 | 5.9 | 4.5× |
| 2.0 | 11.3 | 8.7× |
| 4.0 | 20.9 | 16× |
- **步长翻倍→fps 翻倍 → GPU 是采样瓶颈**。总开销 ≈ 光线数 × (光线长/步长) × ~9 个重叠体。
- D 方案（手动步长）**确实直接、强力提速**；但**保质量的步长（≈ Nyquist，0.5×体素）下仍只 ~2 fps**
——因为 **9× 冗余重叠**把它乘了回去。要到交互级(10+fps) 得把步长粗到 ~2.0（欠采样、损 Z 薄层）。
### 7.3 合并诊断（两测合起来）
**慢 = 采样密度 × ~9 倍冗余重叠，两者都真实。**
- D 方案(粗化采样)：提速强，但保质量步长下被 9× 重叠压回 ~2fps；要交互须损质量。
- **唯一"保质量又快"的，是去掉那 9× 冗余重叠**（同路重扫的同一地下点）：合并/装箱（取真实道、不跨线
插值）→ 一个体一遍 → ~9× 提速、且 Nyquist 步长下也能交互、**零质量损失**（冗余测量本就该合并降噪）。
- **但这与用户"保持 20 条可区分"直接冲突**——而这 9 层在物理上是**冗余测量**（同一地下结构扫了 9 遍），
保持它们"可区分"的工程价值存疑。
### 7.4 CPU OSPRay vs GPU（仍未测）
ESS 对本数据 ~2× 且不解决 9× 重叠；OSPRay 主要 CPU、对手是 GPU 数千核。**很可能换 OSPRay 比现状还慢**，
且为 ~2× 重编整个 VTK 投入产出极差。不建议在去掉冗余重叠之前考虑。
### 7.5 "多线为何卡"的根因确诊（passcost，决定架构）——结论：**不是固定开销，是没用 LOD**
> 背景：最初 P11/P12 是"各线独立 mapper + 视野 LOD"，实测仍 0.5fps。需确诊卡在三个嫌疑哪个：
> ①LOD 选区没削小 ②N 遍固定开销 ③重叠没摊掉。`passcost` 命令：N 个独立 GPU mapper 各渲一个 64³ 小体
> （模拟 LOD 削过的小区），分"铺开/不重叠"与"叠在一起/重叠"，测离屏稳态 fps vs N。
| N | 铺开(不重叠) fps | 叠加(重叠) fps |
|---|---|---|
| 1 | 177 | 204 |
| 5 | 162 | 43 |
| 10 | 144 | 22 |
| **20** | **78** | **11** |
**判读（决定性）：**
- **嫌疑 ②（N 遍固定开销）排除**：20 个独立 mapper 铺开仍 **78fps**（177→78，远非线性）。
→ **各线独立 mapper 架构上完全可行，固定开销温和。"multi-volume 单遍 ⊥ 视野 LOD"这个不可兼得不致命**——
放弃单遍、回独立 mapper 并不慢。
- **嫌疑 ③（重叠）真实但小体下可控**：叠加随 N ~1/N（每条光线乘 N），但 **20 层 64³ 叠加仍 11fps**（可用），
再叠屏幕降采样更快。
- **嫌疑 ①（选区没削小）= 真凶**：passcost 小体 20 层叠加=11fps，而真实 view-all 只 1.7fps——差距全在
**贴图大小**：当前渲的是**整卷底图**（~11000×56×200 ≈ 上亿体素/条），**根本没用视野 LOD 把它削成小区**。
这是**最好结局：可修，不动地基，只需真正用上 LOD**。
**对架构的直接含义**：本会话引入的 **multi-volume 单遍是错误取舍**——为"单遍"关掉了 LOD、改固定整卷贴图，
导致大贴图 × 9 层重叠 = 1.7fps。而 passcost 证明独立 mapper 够快，**根本不必为单遍牺牲 LOD**。
## 8. 部署约束（硬件不确定，跨厂商）
客户机配置未知（可能无独显，或 N卡/A卡/Intel）。**没有任何单一渲染器能在 N 卡和 A 卡上都做"GPU+ESS"**——
GPU 体光追渲染器全厂商锁定（N 卡→NVIDIA VisRTX/OptiX/IndeX；Intel→OSPRay-GPU；A 卡→基本无成熟方案）。
跨厂商唯一通用的是 **OSPRay-CPU（免显卡、任意 x86）** 或 **OpenGL（任意 GPU、但无 ESS=现状）**。
若上多后端，需"OSPRay-CPU 保底 + 探测到 N卡/Intel独显时升对应 GPU 后端 + OpenGL 终极兜底"。
## 9. 关键问题——大多已被实测回答
1. ~~有没有不损质量的根本性提速法~~ **有，且是通用解：LOD（视野自适应多分辨率）**——让 GPU 单帧实际
ray-cast 的体素量**与数据总量解耦、只与"屏幕能看清的量"挂钩**（Task 12c 单体已验证 752/380fps）。
§7.5 passcost 证明它**对多线也成立**（独立 mapper 开销温和，20 条铺开 78fps）。
2. ~~"卡"的主因~~ **已确诊（§7.5）：不是 N 遍固定开销（排除），是【当前根本没用 LOD、渲整卷大贴图】（嫌疑①）。**
本会话引入的 multi-volume 单遍为"单遍"关掉了 LOD → 大贴图 × 9 层重叠 → 1.7fps。
3. **9 层重叠的正确定位**（外部专家纠偏 + passcost 印证）：它只是**这批数据（同路重扫 20 趟）的特例倍数**，
**不是渲染本质问题**。本质是"单帧采样量 > GPU 吞吐"，通用解是 LOD（扛任意大数据：无重叠但更大也能扛）。
9 层重叠在 LOD 之上降级为"一个被摊薄的常数因子"（passcost：20 层小体叠加仍 11fps）。
**不要让渲染架构围绕这个特例设计。**
4. ESS/OSPRay/多后端：**继续埋掉**——ESS 对本数据 ~2× 且不解决重叠、CPU 对手是 GPU，且**它解决的是 LOD
已经解决的通用问题**，投入产出差。
## 10. 最终结论（passcost 确诊后，架构清晰）
- **渲染架构 = LOD 中心（视野自适应、单帧量与总量解耦）。** 这是扛"任意大数据"的通用根本解，
Task 12c 单体已验证、§7.5 passcost 多线也成立。
- **本会话的 multi-volume 单遍是错误取舍**：为"单遍合成"牺牲了 LOD、改固定整卷大贴图，正是当前 1.7fps 的
直接原因。passcost 证明独立 mapper 开销温和（20 条 78fps）→ **根本不必为单遍弃 LOD**。
- **正解 = 各线独立 mapper + 视野 LOD（逐线用 Task 12c 引擎）+ 停手才重建**（不每帧重建，避免 P11/P12
那种"20 条每帧重建上传"的 thrash——那才是 0.5fps 的另一半原因，与稳态 ray-cast 无关，已被 P13 思路解决）。
让每条线只渲视野内小区 → 即使 9 层叠加也可用。
- **9 层重叠 = LOD 之上的可选应用层优化**（对同路重扫冗余可"合并/降噪"，顺带省 9×），**不进渲染地基**。
用户要逐条区分就不合并（靠 LOD 摊薄），要纯总览就合并。
- **采样步长（D 方案）= LOD 框架内的质量旋钮**，非独立根本解。
- **ESS/OSPRay/多后端：不做**（不解决 LOD 已解决的通用问题，对本数据收益差）。
→ **下一步（确诊已完成，可开工）**：把多线总览从"multi-volume 单遍固定整卷"改回"各线独立 mapper +
视野 LOD + 停手重建"，让单帧渲染量随视野走、与 20 条总量解耦；实测多线总览是否达交互级。
这是顺着通用 LOD 框架、被 passcost 数据支撑的明确方向——不再围着 9 层重叠这个特例转。
---
### 附：相关已落地代码 / 诊断工具（如专家要复现）
- 通道插值：`src/io/gpr/GprGeometry.cpp::planChannelInterpolation` + `Gpr3dvVolumeBridge.cpp`
- 多体合成/退避/质量控制/通道 LOD：`tools/gpr_poc/main.cpp::cmdViewAll`
- **诊断命令**（`tools/gpr_poc/main.cpp`，可直接跑复现 §6/§7 的数）：
- `gpr_poc ess-stat <dir> <line>`：ESS 空块潜力（§6.1）
- `gpr_poc view-all <dir> <gps> --overlapStat`：实测重叠层数（§7.1）
- `gpr_poc view-all <dir> <gps> --sampleDist D`：步长↔fps（§7.2）
- `gpr_poc passcost --size 64 --overlap 0|1`：N 遍开销 vs 重叠 隔离测（§7.5）
- 数据/插值口径 spec：`docs/superpowers/specs/2026-06-25-gpr-line-channel-interpolation-and-multivolume.md`
- 多后端 ESS 架构 spec（**结论：不做，见本文 §10**）：`docs/superpowers/specs/2026-06-26-gpr-multibackend-ess-rendering.md`
---
## 摘要（一页结论，供决策）
1. **现象**：20 条通道插值密体总览，~1.7fps、交互更卡。视觉正确，纯性能。
2. **确诊**（passcost 隔离测）：**不是 N 遍固定开销**（20 独立 mapper 铺开 78fps，排除）；
是**当前根本没用视野 LOD、在渲整卷大贴图**（× 9 层重叠）。本会话的 multi-volume 单遍为"单遍"
牺牲了 LOD，是直接原因。
3. **通用根本解 = LOD**（单帧渲染量与数据总量解耦），扛任意大数据；Task 12c 单体 752fps、passcost 多线
也成立。9 层重叠只是**本批数据的特例倍数**，是 LOD 之上一个可摊薄/可选合并的因子，**不是架构核心**。
4. **正解**：各线独立 mapper + 视野 LOD + 停手才重建（弃 multi-volume 单遍）。
5. **明确否定**：ESS/OSPRay/多后端（对本数据 ~2×、不解决重叠、解决的是 LOD 已解决的通用问题）。

132
docs/superpowers/specs/2026-06-26-gpr-multibackend-ess-rendering.md Normal file
View File

@ -0,0 +1,132 @@
# ⚠️ 本 spec 已被实测推翻，勿照此实现
> **结论（见 `2026-06-26-gpr-3d-render-perf-ANALYSIS-for-review.md` §10）：ESS/OSPRay/多后端【不做】。**
> 实测：ESS 对本数据 ~2× 且不解决重叠；passcost 确诊"多线卡"的真因是【没用视野 LOD、渲整卷大贴图】，
> 不是固定开销。**正解 = LOD 中心（各线独立 mapper + 视野 LOD + 停手重建），见下方实现计划。**
> 本文余下"多后端/ESS"内容仅作历史记录。
---
## 实现计划（LOD 中心多线总览 — 已确诊、可执行）
**目标**：把 `cmdViewAll` 从"multi-volume 单遍 + 固定整卷大贴图"改为"各线独立 mapper + 视野 LOD +
停手才重建"，使单帧渲染量随视野走、与 20 条总量解耦。
**改动步骤（`tools/gpr_poc/main.cpp::cmdViewAll`）**：
1. `PlacedSource` 加回**每线自己的 `vtkSmartVolumeMapper`**（GPU 模式）；删 multi-volume 用法
（multiMapper/multiVol/port 不再需要，但可暂留不碍）。
2. **装配**：删 `buildBundles` + 退避（无 multi-volume 即无纹理单元上限）；改为逐线
`mapper->SetInputData(baseImage)` → `volume->SetMapper(mapper)` → `ren->AddVolume(volume)`，
各线 mapper 收进 `mappers` 向量（供质量控制）。
3. **开 LOD**：`gViewAllBaseOnly = false`（启用引擎选区换图）；引擎换的是"改包围盒的子区域"，
各线独立 mapper 下**安全**（无 multi-volume 可破坏）。
4. **关 channel LOD**：`gChanLod = false`——引擎金字塔已逐级降 Y，无需单独抽 Y 平面。
5. `viewAllPickOneLine`：`ps.mapper->SetInputData(ps.currentImg); ps.mapper->Update();`（非 multiMapper 端口）。
6. **停手才重建（已有，确认接线）**：拖动中(`viewAllOnInteracting`)只降质+重置裁剪、**不提交引擎目标**；
松手(`viewAllOnInteract`)/定时器 idle 才 `viewAllSubmitTargets`（提交 LOD 目标）+ `viewAllPickOneLine`
（拉就绪区域换上）。避免 P11/P12"每帧 20 条重建上传"thrash。
7. **质量旋钮保留**：`--sampleDist`/`--maxImgSample`/`--dragSampleMul` 作 LOD 框架内的交互降质兜底。
8. **总览级别**：引擎 `selectLod` 按屏幕像素选层——拉远时全路映射到少量像素 → 自动选粗层（小贴图）→
20 条小贴图即可用；拉近 → 小区域细层。**确认 selectLod 多线下确实选到粗层**（若没有，调
selectLod 的屏幕像素阈值——这是 §7.5 嫌疑①的修复点）。
**验收**：离屏看各线底图 level 随相机距离变（远→粗/小、近→细/小区）；真窗口测 20 条总览交互级 fps、
拖动跟手、松手清晰、过档位无明显卡顿（外部专家提示重点盯"停手重建过渡手感"）。
---
# GPR 三维体渲染：多后端 + 空体素跳过(ESS) 加速架构 — Spec（2026-06-26，已废）
> 解决"20 个重叠密体在 VTK 库存 OpenGL mapper 上又卡又只能降质"的根本性方案。
> 关联：`docs/superpowers/specs/2026-06-25-gpr-line-channel-interpolation-and-multivolume.md`（数据/插值口径）。
---
## 0. 一句话目标
用**空体素跳过(ESS)** 这一不损可见质量的业界技术，把"逐线分开的多个密体合并渲染"做到**不卡**；
并以**多渲染后端 + 自动适配**覆盖客户侧未知/多厂商硬件（含无显卡）。
---
## 1. 问题与根因
- 现状渲染 = VTK `vtkGPUVolumeRayCastMapper`（OpenGL）。**任意 GPU 可跑（最通用），但无 ESS**。
- 20 个重叠半透明密体：每条光线每步在 20 体各采一次、光线又长 → 几十亿次纹理查找/帧 → 1.7fps、交互更卡。
- 通道插值后 Y 加密到 2.5cm，使自动沿光线步长更细 → 更卡。
- **已尝试的"交互降质"（屏幕降采样 + 沿光线步长加粗）是治标**，损可见质量。
## 2. 根本方案：ESS（不损质量）
GPR 体 ~90% 是近零背景（反射层之间空）。ESS 用 min/max 加速结构**跳过"在传函里全透明"的块**，
对稀疏数据常 5–50× 提速、**零质量损失**。但 **VTK 库存 GPU mapper 不做自动 ESS**（仅有受限的
`UseDepthPass` 等高线跳过）。→ 真 ESS 必须**换专业体渲染后端**（其底层自带 ESS + 正确合成多重叠体）。
## 3. 关键事实：跨厂商 GPU 加速不存在单一方案
GPU 体光追渲染器全是**厂商锁定**：
| 后端 | 硬件 | ESS | 跨厂商 | 角色 |
|---|---|---|---|---|
| OpenGL（vtkGPUVolumeRayCastMapper，现状）| 任意 GPU(N/A/Intel) | ❌ | ✅ | **终极兜底** |
| OSPRay（CPU，Embree/ISPC）| 任意 x86 CPU（免显卡）| ✅ | ✅ | **通用基线** |
| OSPRay-GPU（SYCL/oneAPI）| 仅 Intel Arc/数据中心卡 | ✅ | ❌ | Intel 独显 |
| ANARI + VisRTX（OptiX）| 仅 NVIDIA | ✅ | ❌ | N 卡 |
| AMD GPU 体渲染+ESS | — | — | ❌ 无成熟方案 | — |
**结论**：没有"同时 N/A 卡的 GPU-ESS"。**面向未知客户机，OSPRay-CPU 是最稳通用选择**（免显卡、ESS、质量不降）。
## 4. 渲染后端架构（多后端 + 自动适配 + 手动覆盖 + 兼容灰掉）
### 4.1 用户可见选项（按硬件/结果命名，不暴露库名）
| 用户看到 | 背后实现 | 适配硬件 |
|---|---|---|
| **自动（推荐）** | 探测后选下面之一 | — |
| GPU 加速（N卡）| ANARI + VisRTX | NVIDIA 独显 |
| GPU 加速（Intel）| OSPRay-GPU | Intel Arc 独显 |
| CPU（通用，免显卡）| OSPRay-CPU | 任意 CPU |
| 通用 GPU（兼容）| OpenGL（现状 mapper）| 任意 GPU（兜底）|
### 4.2 自动探测逻辑
```
if NVIDIA 独显: → VisRTX(GPU)
elif Intel Arc 独显: → OSPRay-GPU
elif AMD(独显/核显) 或 Intel 核显 或 无显卡 或 探测失败:
→ OSPRay-CPU（默认） // 核显一律走 CPU：弱+共享内存+多不被GPU后端支持
// 强力 A 卡可手动选"通用 OpenGL"用其 GPU(无 ESS)，但不作默认
```
- **手动覆盖**：用户可自选，但**只列出与当前硬件兼容的项**（不兼容灰掉，如 A 卡上禁 VisRTX）。
- **集显建议**：一律 OSPRay-CPU（CPU+ESS 比让弱核显硬渲更稳更快）。
### 4.3 部署策略（一句话）
**OSPRay-CPU 保底通用；探测到 N卡/Intel Arc 时升对应 GPU 后端；A 卡/核显吃 CPU 基线；OpenGL 终极兜底。**
## 5. 上 ESS 后端后，废弃哪些
- ❌ **装箱单体(binning)**：当初为绕 OpenGL 无 ESS 才提（代价=丢"逐线分开"）。ESS 后端让**逐线分开
的多体也快** → 不需要装箱。**逐线分开 + 不造假 + 不卡，三者兼得。**
- ❌ **交互降质权宜**（屏幕/沿光线步长加粗）：ESS 后端有自带的自适应/渐进式细化，基本不用；保留作任何后端的兜底。
- ❌ 自写 ESS shader / 预积分 / UseDepthPass：后端自带，无需自行实现。
- ✅ **保留**："选几条 ds(≤7)" 是使用方式（非技术），永远有效。
## 6. 实现要点（工程）
- VTK 需**重编**带：`RenderingRayTracing`(OSPRay)、`RenderingAnari`(ANARI/VisRTX) 模块 + 依赖
（OSPRay/Embree/ISPC/OpenVKL；ANARI-SDK/VisRTX）。用户已确认工程量无所谓。
- 渲染层抽象一个 `IVolumeRenderBackend`，运行时按 §4 选具体 mapper：
`vtkGPUVolumeRayCastMapper`(OpenGL) / `vtkOSPRayPass`+volume / `vtkAnariPass`+volume。
- **数据不变**：逐线密体（含通道插值，spec 前一份）原样喂各后端；多体合成由后端负责（无 K=7 分包）。
- 硬件探测：GL_VENDOR / 平台 API（DXGI 枚举适配器）判 N/A/Intel + 独显/核显。
## 7. POC 计划（先验"CPU+ESS 够不够快"——最通用、风险最低）
1. **POC-1（先做）**：最小程序，用 **OSPRay-CPU** 渲一个 GPR 密体（tmp/lines_all_dense 里一条/几条），
**实测普通 CPU 上对多体/密体的 fps + ESS 提速比**，对照现状 OpenGL。先确认 OSPRay 在本环境
可编可跑、CPU+ESS 实际够快——这是整套方案值不值得上的关键闸门。
2. **POC-2**：若有 N 卡，ANARI+VisRTX 渲同一体，对照 GPU 提速。
3. POC 通过 → 才动手重编 VTK + 接后端抽象层。
## 8. 风险 / 待定
- OSPRay-GPU（Intel）较新、不如 CPU 路成熟；ANARI/VisRTX 需 NVIDIA 驱动 + VisRTX 库。
- 各后端传函/外观与 OpenGL 有差异，需重新调一致。
- 本环境能否编出带光追/ANARI 的 VTK（vcpkg/手动依赖）待 POC-1 验证。
- CPU+ESS 在低核机上的实际帧率待实测。
## 9. 验收
1. 客户机无论有无显卡/何种显卡，自动选到可跑的后端并出图（OSPRay-CPU 永远兜底）。
2. 20 条密体总览：逐线分开、不造假、**ESS 后端下不卡**（目标交互 ≥ 可用帧率，质量不降）。
3. 手动选项只列兼容项；集显默认 CPU。
4. 数据层（通道插值密体）零改动复用。

58
external/gpr3dviewer/CMakeLists.txt vendored Normal file
View File

@ -0,0 +1,58 @@
# =====================================================================
# geopro_gpr3dv —— vendored 3DGPRViewer 数据生成链（原样拷贝，算法零改动）
#
# 链路：多通道 _Axx.iprh/.iprb
# → IprhParser::loadImpulseMultiChannel → GPRDataModel（traces）
# → GPRDataModel::buildVolumeData → volumeData[ch][trace][sample]
# → RadarProcessor::runPipeline → 处理后 GPRDataModel
#
# 版权属用户（lanbingtech 自有），可拷入本仓库 vendored 隔离。
# 仅链 Qt6::Core（QVector/QString/QFile/QVector3D/QJson）+ OpenMP + kissfft。
# 不含 UI/Sql/Network（这些在原版属 GPRWidget/mainwindow，未拷）。
# =====================================================================
# 根工程仅 enable CXX；kissfft 是 C 源（kiss_fft.c/kiss_fftr.c），需显式启用 C 语言，
# 否则 .c 文件被 CMake 忽略，导致 kiss_fftr/kiss_fftr_alloc 链接缺失。
enable_language(C)
find_package(OpenMP)
add_library(geopro_gpr3dv STATIC
IprhParser.cpp
ImpulseMultiChannelConverter.cpp
Rd3Parser.cpp
RadarProcessor.cpp
PerformanceLogger.cpp
# P8 测绘级精确坐标：原样拷自 3DGPRViewer（算法零改动，diff 逐字节一致）。
# CoordinateTransform —— CGCS2000 高斯-克吕格 3°带正反算（零 Qt）。
# TrajectoryCalculator —— RTK GPS + 天线几何 → 每通道每道 CGCS 世界坐标。
# CScanGridder —— 世界坐标逐深度 IDW 网格化 C-scan（堆成世界对齐体）。
# PosParser —— .pos / center.ccc GPS 解析。
CoordinateTransform.cpp
TrajectoryCalculator.cpp
CScanGridder.cpp
PosParser.cpp
third_party/kissfft/kiss_fft.c
third_party/kissfft/kiss_fftr.c
)
# 头文件目录：本目录（GPRDataModel.h 等）+ kissfft（RadarProcessor.cpp 内 #include "kiss_fftr.h"）。
target_include_directories(geopro_gpr3dv PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}
${CMAKE_CURRENT_SOURCE_DIR}/third_party/kissfft
)
# Qt6::Gui 为 QVector3D（GPRDataModel.h 的道三维位置）所需；Core 提供 QVector/QString/QFile/QJson。
target_link_libraries(geopro_gpr3dv PUBLIC Qt6::Core Qt6::Gui)
if(OpenMP_CXX_FOUND)
target_link_libraries(geopro_gpr3dv PUBLIC OpenMP::OpenMP_CXX)
endif()
target_compile_features(geopro_gpr3dv PRIVATE cxx_std_17)
# vendored 第三方代码：关 Qt 自动工具（无 QObject/moc 需求），并放宽告警（不改算法、不为告警动代码）。
set_target_properties(geopro_gpr3dv PROPERTIES AUTOMOC OFF AUTOUIC OFF AUTORCC OFF)
if(MSVC)
target_compile_options(geopro_gpr3dv PRIVATE /W0)
endif()

336
external/gpr3dviewer/CScanGridder.cpp vendored Normal file
View File

@ -0,0 +1,336 @@
#include "CScanGridder.h"
#include <QHash>
#include <QPair>
#include <QtGlobal>
#include <algorithm>
#include <cmath>
#include <limits>
namespace {
struct CScanSamplePoint {
double x = 0.0;
double y = 0.0;
float amplitude = 0.0f;
int line = -1;
int channel = -1;
int trace = -1;
};
struct BinKey {
int x = 0;
int y = 0;
bool operator==(const BinKey &other) const
{
return x == other.x && y == other.y;
}
};
uint qHash(const BinKey &key, uint seed = 0)
{
return ::qHash(key.x, seed) ^ (::qHash(key.y, seed + 0x9e3779b9U) << 1);
}
static double distanceSquared(double ax, double ay, double bx, double by)
{
const double dx = ax - bx;
const double dy = ay - by;
return dx * dx + dy * dy;
}
static int gridIndex(int x, int y, int width)
{
return y * width + x;
}
static QVector<float> gaussianKernel(double sigma)
{
sigma = std::max(0.1, sigma);
const int radius = std::max(1, static_cast<int>(std::ceil(sigma * 3.0)));
QVector<float> kernel(radius * 2 + 1);
double sum = 0.0;
for (int i = -radius; i <= radius; ++i) {
const double v = std::exp(-(i * i) / (2.0 * sigma * sigma));
kernel[i + radius] = static_cast<float>(v);
sum += v;
}
if (sum > 0.0) {
for (float &v : kernel) v = static_cast<float>(v / sum);
}
return kernel;
}
static void smoothMasked(CScanGridResult &grid, double sigma)
{
if (!grid.valid || grid.width <= 0 || grid.height <= 0) return;
const QVector<float> kernel = gaussianKernel(sigma);
const int radius = kernel.size() / 2;
const int count = grid.width * grid.height;
QVector<float> tmpValues(count, 0.0f);
QVector<float> tmpWeights(count, 0.0f);
for (int y = 0; y < grid.height; ++y) {
for (int x = 0; x < grid.width; ++x) {
double sum = 0.0;
double weight = 0.0;
for (int k = -radius; k <= radius; ++k) {
const int sx = x + k;
if (sx < 0 || sx >= grid.width) continue;
const int idx = gridIndex(sx, y, grid.width);
if (!grid.validMask[idx]) continue;
const double w = kernel[k + radius];
sum += grid.values[idx] * w;
weight += w;
}
const int outIdx = gridIndex(x, y, grid.width);
if (weight > 1e-6) {
tmpValues[outIdx] = static_cast<float>(sum / weight);
tmpWeights[outIdx] = static_cast<float>(weight);
}
}
}
QVector<float> outValues(count, 0.0f);
QVector<unsigned char> outMask(count, 0);
for (int y = 0; y < grid.height; ++y) {
for (int x = 0; x < grid.width; ++x) {
double sum = 0.0;
double weight = 0.0;
for (int k = -radius; k <= radius; ++k) {
const int sy = y + k;
if (sy < 0 || sy >= grid.height) continue;
const int idx = gridIndex(x, sy, grid.width);
if (tmpWeights[idx] <= 1e-6f) continue;
const double w = kernel[k + radius] * tmpWeights[idx];
sum += tmpValues[idx] * w;
weight += w;
}
const int outIdx = gridIndex(x, y, grid.width);
if (weight > 1e-4) {
outValues[outIdx] = static_cast<float>(sum / weight);
outMask[outIdx] = 1;
}
}
}
grid.values = std::move(outValues);
grid.validMask = std::move(outMask);
}
static float percentile(QVector<float> values, double percent)
{
if (values.isEmpty()) return 0.0f;
std::sort(values.begin(), values.end());
percent = std::clamp(percent, 0.0, 100.0);
const double pos = percent / 100.0 * (values.size() - 1);
const int lo = static_cast<int>(std::floor(pos));
const int hi = static_cast<int>(std::ceil(pos));
if (lo == hi) return values[lo];
const double t = pos - lo;
return static_cast<float>(values[lo] * (1.0 - t) + values[hi] * t);
}
static void updateDisplayRange(CScanGridResult &grid, double lowPercent, double highPercent)
{
QVector<float> validValues;
validValues.reserve(grid.values.size());
for (int i = 0; i < grid.values.size(); ++i) {
if (i < grid.validMask.size() && grid.validMask[i]) {
validValues.append(grid.values[i]);
}
}
if (validValues.isEmpty()) {
grid.displayMin = 0.0f;
grid.displayMax = 1.0f;
return;
}
grid.displayMin = percentile(validValues, lowPercent);
grid.displayMax = percentile(validValues, highPercent);
if (std::abs(grid.displayMax - grid.displayMin) < 1e-6f) {
grid.displayMax = grid.displayMin + 1.0f;
}
}
} // namespace
CScanGridResult CScanGridder::build(const QVector<SurveyLine> &surveyLines, CScanGridOptions options)
{
CScanGridResult result;
options.cellSizeM = std::max(0.005, options.cellSizeM);
options.searchRadiusM = std::max(options.cellSizeM, options.searchRadiusM);
options.idwPower = std::max(0.1, options.idwPower);
options.smoothingSigmaCells = std::clamp(options.smoothingSigmaCells, 0.1, 5.0);
if (options.clipLowPercent >= options.clipHighPercent) {
options.clipLowPercent = 2.0;
options.clipHighPercent = 98.0;
}
options.maxGridWidth = std::max(64, options.maxGridWidth);
options.maxGridHeight = std::max(64, options.maxGridHeight);
options.maxGridCells = std::max(4096, options.maxGridCells);
QVector<CScanSamplePoint> samples;
double minX = std::numeric_limits<double>::max();
double minY = std::numeric_limits<double>::max();
double maxX = std::numeric_limits<double>::lowest();
double maxY = std::numeric_limits<double>::lowest();
for (int li = 0; li < surveyLines.size(); ++li) {
const SurveyLine &line = surveyLines[li];
if (!line.hasValidTrajectories()) continue;
const GPRDataModel &data = line.data;
const int channelCount = std::min(static_cast<int>(line.channelTrajectories.size()), data.getChannelCount());
const int traceCount = data.getTraceCountPerChannel();
const int sampleCount = data.getSampleCount();
if (channelCount <= 0 || traceCount <= 0 || sampleCount <= 0) continue;
const int sampleIndex = qBound(0, options.sampleIndex, sampleCount - 1);
for (int c = 0; c < channelCount; ++c) {
const QVector<QVector3D> &traj = line.channelTrajectories[c];
const int n = std::min(traceCount, static_cast<int>(traj.size()));
for (int t = 0; t < n; ++t) {
const RadarTrace *trace = data.getTrace(c, t);
if (!trace || sampleIndex >= trace->amplitudes.size()) continue;
const QVector3D &pos = traj[t];
const float amp = static_cast<float>(trace->amplitudes[sampleIndex]);
// Grid X uses CGCS easting (Y), grid Y uses CGCS northing (X),
// so the generated C-scan image aligns with map screen axes.
samples.append({pos.y(), pos.x(), amp, li, c, t});
minX = std::min(minX, static_cast<double>(pos.y()));
minY = std::min(minY, static_cast<double>(pos.x()));
maxX = std::max(maxX, static_cast<double>(pos.y()));
maxY = std::max(maxY, static_cast<double>(pos.x()));
}
}
}
if (samples.isEmpty() || maxX <= minX || maxY <= minY) {
return result;
}
result.dataMinX = minX;
result.dataMinY = minY;
result.dataMaxX = maxX;
result.dataMaxY = maxY;
minX -= options.searchRadiusM;
minY -= options.searchRadiusM;
maxX += options.searchRadiusM;
maxY += options.searchRadiusM;
double cellSize = options.cellSizeM;
int width = static_cast<int>(std::ceil((maxX - minX) / cellSize)) + 1;
int height = static_cast<int>(std::ceil((maxY - minY) / cellSize)) + 1;
while ((width > options.maxGridWidth || height > options.maxGridHeight
|| static_cast<qint64>(width) * height > options.maxGridCells) && cellSize < 10.0) {
cellSize *= 1.5;
width = static_cast<int>(std::ceil((maxX - minX) / cellSize)) + 1;
height = static_cast<int>(std::ceil((maxY - minY) / cellSize)) + 1;
}
if (width <= 0 || height <= 0 || width > options.maxGridWidth || height > options.maxGridHeight
|| static_cast<qint64>(width) * height > options.maxGridCells) {
return result;
}
result.valid = true;
result.originX = minX;
result.originY = minY;
result.cellSizeM = cellSize;
result.width = width;
result.height = height;
const int cellCount = width * height;
result.values.fill(0.0f, cellCount);
result.validMask.fill(0, cellCount);
result.nearestLine.fill(-1, cellCount);
result.nearestChannel.fill(-1, cellCount);
result.nearestTrace.fill(-1, cellCount);
const double binSize = options.searchRadiusM;
QHash<BinKey, QVector<int>> bins;
bins.reserve(samples.size());
for (int i = 0; i < samples.size(); ++i) {
const CScanSamplePoint &p = samples[i];
const BinKey key{static_cast<int>(std::floor((p.x - minX) / binSize)),
static_cast<int>(std::floor((p.y - minY) / binSize))};
bins[key].append(i);
}
const double radiusSq = options.searchRadiusM * options.searchRadiusM;
const int searchBins = std::max(1, static_cast<int>(std::ceil(options.searchRadiusM / binSize)));
for (int y = 0; y < height; ++y) {
const double cy = minY + y * cellSize;
const int by = static_cast<int>(std::floor((cy - minY) / binSize));
for (int x = 0; x < width; ++x) {
const double cx = minX + x * cellSize;
const int bx = static_cast<int>(std::floor((cx - minX) / binSize));
double sum = 0.0;
double weightSum = 0.0;
double bestDistSq = std::numeric_limits<double>::max();
int bestIndex = -1;
bool exact = false;
float exactValue = 0.0f;
for (int oy = -searchBins; oy <= searchBins; ++oy) {
for (int ox = -searchBins; ox <= searchBins; ++ox) {
const BinKey key{bx + ox, by + oy};
auto it = bins.constFind(key);
if (it == bins.constEnd()) continue;
for (int sampleIdx : it.value()) {
const CScanSamplePoint &p = samples[sampleIdx];
const double d2 = distanceSquared(cx, cy, p.x, p.y);
if (d2 > radiusSq) continue;
if (d2 < bestDistSq) {
bestDistSq = d2;
bestIndex = sampleIdx;
}
if (d2 < 1e-8) {
exact = true;
exactValue = p.amplitude;
bestIndex = sampleIdx;
break;
}
const double w = 1.0 / std::pow(std::sqrt(d2), options.idwPower);
sum += p.amplitude * w;
weightSum += w;
}
if (exact) break;
}
if (exact) break;
}
const int idx = gridIndex(x, y, width);
if (exact || weightSum > 0.0) {
result.values[idx] = exact ? exactValue : static_cast<float>(sum / weightSum);
result.validMask[idx] = 1;
if (bestIndex >= 0) {
const CScanSamplePoint &p = samples[bestIndex];
result.nearestLine[idx] = p.line;
result.nearestChannel[idx] = p.channel;
result.nearestTrace[idx] = p.trace;
}
}
}
}
if (options.smoothingEnabled) {
smoothMasked(result, options.smoothingSigmaCells);
}
updateDisplayRange(result, options.clipLowPercent, options.clipHighPercent);
return result;
}

48
external/gpr3dviewer/CScanGridder.h vendored Normal file
View File

@ -0,0 +1,48 @@
#ifndef CSCANGRIDDER_H
#define CSCANGRIDDER_H
#include "GPRDataModel.h"
#include <QVector>
struct CScanGridOptions {
int sampleIndex = 0;
double cellSizeM = 0.05;
double searchRadiusM = 0.50;
double idwPower = 2.0;
bool smoothingEnabled = true;
double smoothingSigmaCells = 0.9;
int maxGridWidth = 2048;
int maxGridHeight = 2048;
int maxGridCells = 250000;
double clipLowPercent = 2.0;
double clipHighPercent = 98.0;
};
struct CScanGridResult {
bool valid = false;
double originX = 0.0;
double originY = 0.0;
double dataMinX = 0.0;
double dataMinY = 0.0;
double dataMaxX = 0.0;
double dataMaxY = 0.0;
double cellSizeM = 0.05;
int width = 0;
int height = 0;
QVector<float> values;
QVector<unsigned char> validMask;
QVector<int> nearestLine;
QVector<int> nearestChannel;
QVector<int> nearestTrace;
float displayMin = 0.0f;
float displayMax = 1.0f;
};
class CScanGridder
{
public:
static CScanGridResult build(const QVector<SurveyLine> &surveyLines, CScanGridOptions options);
};
#endif // CSCANGRIDDER_H

219
external/gpr3dviewer/CoordinateTransform.cpp vendored Normal file
View File

@ -0,0 +1,219 @@
#include "CoordinateTransform.h"
#include <cmath>
// 静态辅助：预计算的子午线弧长系数
static inline double computeA0(double e2) {
return 1.0 + 3.0/4.0 * e2 + 45.0/64.0 * e2*e2 + 175.0/256.0 * e2*e2*e2
+ 11025.0/16384.0 * e2*e2*e2*e2;
}
static inline double computeA2(double e2) {
return 3.0/4.0 * e2 + 15.0/16.0 * e2*e2 + 525.0/512.0 * e2*e2*e2
+ 2205.0/2048.0 * e2*e2*e2*e2;
}
static inline double computeA4(double e2) {
return 15.0/64.0 * e2*e2 + 105.0/256.0 * e2*e2*e2
+ 2205.0/4096.0 * e2*e2*e2*e2;
}
static inline double computeA6(double e2) {
return 35.0/512.0 * e2*e2*e2 + 315.0/2048.0 * e2*e2*e2*e2;
}
static inline double computeA8(double e2) {
return 315.0/16384.0 * e2*e2*e2*e2;
}
int CoordinateTransform::detectZoneFromCgcsY(double cgcsY)
{
// 中国范围内 CGCS2000 坐标 Y 通常为正值且包含带号
// 格式：zone * 1,000,000 + 500,000 + easting
double absY = std::abs(cgcsY);
if (absY > 1e6) {
int zone = static_cast<int>(std::floor(absY / 1e6));
if (zone >= 1 && zone <= 60)
return zone;
}
// 如果无法推断，返回 0（表示需要手动指定）
return 0;
}
double CoordinateTransform::centralMeridianFromZone(int zone)
{
// 3度带：中央经线 = 带号 * 3°
return zone * 3.0;
}
double CoordinateTransform::meridianArc(double latRad)
{
const double e2 = E2;
const double a = A;
const double A0 = computeA0(e2);
const double A2 = computeA2(e2);
const double A4 = computeA4(e2);
const double A6 = computeA6(e2);
const double A8 = computeA8(e2);
double s2 = std::sin(2.0 * latRad);
double s4 = std::sin(4.0 * latRad);
double s6 = std::sin(6.0 * latRad);
double s8 = std::sin(8.0 * latRad);
return a * (1.0 - e2) * (A0 * latRad - A2/2.0 * s2 + A4/4.0 * s4
- A6/6.0 * s6 + A8/8.0 * s8);
}
double CoordinateTransform::meridianArcInverse(double x)
{
const double e2 = E2;
const double a = A;
const double A0 = computeA0(e2);
const double A2 = computeA2(e2);
const double A4 = computeA4(e2);
const double A6 = computeA6(e2);
const double A8 = computeA8(e2);
const double c0 = a * (1.0 - e2) * A0;
double bf = x / c0;
for (int i = 0; i < 8; ++i) {
double s2 = std::sin(2.0 * bf);
double s4 = std::sin(4.0 * bf);
double s6 = std::sin(6.0 * bf);
double s8 = std::sin(8.0 * bf);
double fx = a * (1.0 - e2) * (A0 * bf - A2/2.0 * s2 + A4/4.0 * s4
- A6/6.0 * s6 + A8/8.0 * s8) - x;
double fpx = a * (1.0 - e2) * (A0 - A2 * std::cos(2.0 * bf)
+ A4 * std::cos(4.0 * bf)
- A6 * std::cos(6.0 * bf)
+ A8 * std::cos(8.0 * bf));
double delta = fx / fpx;
bf -= delta;
if (std::abs(delta) < 1e-12)
break;
}
return bf;
}
void CoordinateTransform::cgcs2000ToWgs84(double cgcsX, double cgcsY, int zone,
double &latRad, double &lonRad)
{
const double a = A;
const double e2 = E2;
const double e12 = E12;
// 提取东偏移（去掉带号和 500km 常数）
double easting = cgcsY;
if (zone > 0) {
easting = cgcsY - zone * 1e6 - FALSE_EASTING;
} else {
easting = cgcsY - FALSE_EASTING;
}
double northing = cgcsX;
double l0 = centralMeridianFromZone(zone) * DEG2RAD;
// 底点纬度
double bf = meridianArcInverse(northing);
double sinBf = std::sin(bf);
double cosBf = std::cos(bf);
double tanBf = std::tan(bf);
double Nf = a / std::sqrt(1.0 - e2 * sinBf * sinBf);
double etaf2 = e12 * cosBf * cosBf;
double tf = tanBf;
double Vf2 = 1.0 + etaf2;
double y = easting;
double y2 = y * y;
double y4 = y2 * y2;
double y6 = y4 * y2;
double Nf2 = Nf * Nf;
double Nf4 = Nf2 * Nf2;
double Nf6 = Nf4 * Nf2;
// 纬度修正
double dB = tf / Vf2 * (
y2 / (2.0 * Nf2) * (1.0 + etaf2)
- y4 / (24.0 * Nf4) * (5.0 + 3.0 * tf*tf + 6.0 * etaf2
- 6.0 * tf*tf * etaf2
- 3.0 * etaf2*etaf2
- 9.0 * tf*tf * etaf2*etaf2)
+ y6 / (720.0 * Nf6) * (61.0 + 90.0 * tf*tf + 45.0 * tf*tf*tf*tf)
);
latRad = bf - dB;
// 经差
double dl = y / (Nf * cosBf) * (
1.0
- y2 / (6.0 * Nf2) * (1.0 + 2.0 * tf*tf + etaf2)
+ y4 / (120.0 * Nf4) * (5.0 + 28.0 * tf*tf + 24.0 * tf*tf*tf*tf
+ 6.0 * etaf2 + 8.0 * tf*tf * etaf2)
- y6 / (5040.0 * Nf6) * (61.0 + 662.0 * tf*tf + 1320.0 * tf*tf*tf*tf
+ 720.0 * tf*tf*tf*tf*tf*tf)
);
lonRad = l0 + dl;
}
void CoordinateTransform::wgs84ToCgcs2000(double latRad, double lonRad, int zone,
double &cgcsX, double &cgcsY)
{
const double a = A;
const double e2 = E2;
const double e12 = E12;
double l0 = centralMeridianFromZone(zone) * DEG2RAD;
double l = lonRad - l0;
double sinB = std::sin(latRad);
double cosB = std::cos(latRad);
double tanB = std::tan(latRad);
double N = a / std::sqrt(1.0 - e2 * sinB * sinB);
double t2 = tanB * tanB;
double t4 = t2 * t2;
double eta2 = e12 * cosB * cosB;
double eta4 = eta2 * eta2;
double l2 = l * l;
double l4 = l2 * l2;
double l6 = l4 * l2;
// 子午线弧长
double X = meridianArc(latRad);
// 北坐标
cgcsX = X + N / 2.0 * sinB * cosB * l2 * (
1.0 + l2 / 12.0 * (5.0 - t2 + 9.0 * eta2 + 4.0 * eta4)
+ l4 / 360.0 * (61.0 - 58.0 * t2 + t4)
);
// 东坐标（自然值，不含带号和 500km）
double yNatural = N * cosB * l * (
1.0 + l2 / 6.0 * (1.0 - t2 + eta2)
+ l4 / 120.0 * (5.0 - 18.0 * t2 + t4 + 14.0 * eta2 - 58.0 * t2 * eta2)
);
// 加上带号和 500km 常数
if (zone > 0) {
cgcsY = zone * 1e6 + FALSE_EASTING + yNatural;
} else {
cgcsY = FALSE_EASTING + yNatural;
}
}
void CoordinateTransform::wgs84ToWebMercator(double latRad, double lonRad, double &mx, double &my)
{
mx = EARTH_RADIUS * lonRad;
my = EARTH_RADIUS * std::log(std::tan(PI / 4.0 + latRad / 2.0));
}
void CoordinateTransform::webMercatorToWgs84(double mx, double my, double &latRad, double &lonRad)
{
lonRad = mx / EARTH_RADIUS;
latRad = 2.0 * std::atan(std::exp(my / EARTH_RADIUS)) - PI / 2.0;
}

48
external/gpr3dviewer/CoordinateTransform.h vendored Normal file
View File

@ -0,0 +1,48 @@
#ifndef COORDINATETRANSFORM_H
#define COORDINATETRANSFORM_H
#include <cmath>
class CoordinateTransform {
public:
// CGCS2000 椭球参数
static constexpr double A = 6378137.0; // 长半轴 (m)
static constexpr double F = 1.0 / 298.257222101; // 扁率
static constexpr double E2 = 2.0 * F - F * F; // 第一偏心率平方
static constexpr double E12 = E2 / (1.0 - E2); // 第二偏心率平方
static constexpr double FALSE_EASTING = 500000.0; // 东偏移 (m)
static constexpr double EARTH_RADIUS = 6378137.0; // Web Mercator 地球半径
static constexpr double PI = 3.14159265358979323846;
static constexpr double DEG2RAD = PI / 180.0;
static constexpr double RAD2DEG = 180.0 / PI;
// 从 CGCS2000 东向坐标(Y)自动推断 3° 带带号
// 假设 Y 格式为：zone*1e6 + 500000 + easting，或纯自然值
static int detectZoneFromCgcsY(double cgcsY);
// 带号 → 中央经线（度）
static double centralMeridianFromZone(int zone);
// CGCS2000 平面坐标 → WGS84 经纬度（弧度）
// cgcsX: 北向坐标(m), cgcsY: 东向坐标(m, 可含带号)
static void cgcs2000ToWgs84(double cgcsX, double cgcsY, int zone,
double &latRad, double &lonRad);
// WGS84 经纬度（弧度） → CGCS2000 平面坐标
static void wgs84ToCgcs2000(double latRad, double lonRad, int zone,
double &cgcsX, double &cgcsY);
// WGS84 经纬度（弧度） ↔ Web Mercator 平面坐标（米）
static void wgs84ToWebMercator(double latRad, double lonRad, double &mx, double &my);
static void webMercatorToWgs84(double mx, double my, double &latRad, double &lonRad);
private:
// 子午线弧长（从赤道到纬度 B 的弧长）
static double meridianArc(double latRad);
// 子午线弧长反解：已知弧长 X，求底点纬度 Bf
static double meridianArcInverse(double x);
};
#endif // COORDINATETRANSFORM_H

297
external/gpr3dviewer/GPRDataModel.h vendored Normal file
View File

@ -0,0 +1,297 @@
#ifndef GPRDATAMODEL_H
#define GPRDATAMODEL_H
#include <QVector>
#include <QString>
#include <QMap>
#include <QVector3D>
#include <QMetaType>
#include <utility>
#include "SurveyGeometry.h"
struct RadarTrace {
QVector<short> amplitudes; // 【重要】改为 short (16-bit)，之前是 float
double startTime = 0.0;
double timeStep = 0.0;
// 三维位置信息
QVector3D position; // 该道的三维空间位置
int channelNumber = 0; // 通道号
RadarTrace() = default;
RadarTrace(const RadarTrace& other)
: amplitudes(QVector<short>(other.amplitudes.cbegin(), other.amplitudes.cend()))
, startTime(other.startTime)
, timeStep(other.timeStep)
, position(other.position)
, channelNumber(other.channelNumber)
{}
RadarTrace& operator=(const RadarTrace& other) {
if (this != &other) {
amplitudes = QVector<short>(other.amplitudes.cbegin(), other.amplitudes.cend());
startTime = other.startTime;
timeStep = other.timeStep;
position = other.position;
channelNumber = other.channelNumber;
}
return *this;
}
RadarTrace(RadarTrace&& other) noexcept
: amplitudes(std::move(other.amplitudes))
, startTime(other.startTime)
, timeStep(other.timeStep)
, position(other.position)
, channelNumber(other.channelNumber)
{}
RadarTrace& operator=(RadarTrace&& other) noexcept {
if (this != &other) {
amplitudes = std::move(other.amplitudes);
startTime = other.startTime;
timeStep = other.timeStep;
position = other.position;
channelNumber = other.channelNumber;
}
return *this;
}
};
class GPRDataModel {
public:
struct Header {
int numTraces = 0; // LAST TRACE
int samplesPerTrace = 0; // SAMPLES
double timeWindowNs = 0.0; // TIMEWINDOW (ns)
double distanceInc = 0.0; // DISTANCE INTERVAL (m)
double antennaFreq = 0.0; // FREQUENCY (MHz)
QString antennaType; // ANTENNAS
QString date; // DATE
QString timeStr; // TIME
// 三维相关参数
int numberOfChannels = 1; // NUMBER_OF_CH
QVector<float> chXOffsets; // CH_X_OFFSETS
QVector<float> chYOffsets; // CH_Y_OFFSETS
QString units; // UNITS
double startPosition = 0.0; // START POSITION
double stopPosition = 0.0; // STOP POSITION
double waveVelocity = 0.1; // 波速，用于深度计算
double timeIntervalNs = 0.0; // TIME INTERVAL (ns)，用于计算时窗
// 原始映射，用于调试或扩展
QMap<QString, QString> rawParams;
};
Header header;
QVector<RadarTrace> traces;
// 三维数据相关属性
int tracesPerChannel = 0; // 每个通道的道数
int channels = 0; // 实际通道数
double totalDistance = 0.0; // 总距离
// 三维数据体 - 存储为[channel][trace][sample]格式
QVector<QVector<QVector<short>>> volumeData; // [channel][trace][sample]
bool isEmpty() const { return traces.isEmpty(); }
void clear() {
traces.clear();
header = Header{};
tracesPerChannel = 0;
channels = 0;
totalDistance = 0.0;
volumeData.clear();
}
// 获取指定通道的道数
int getTracesPerChannel() const {
if (header.numTraces <= 0) {
return 0;
}
if (header.numberOfChannels > 0) {
return header.numTraces / header.numberOfChannels;
}
return header.numTraces;
}
int getTraceIndex(int channel, int traceInChannel) const {
const int nChannels = header.numberOfChannels > 0 ? header.numberOfChannels : 1;
if (channel < 0 || channel >= nChannels ||
traceInChannel < 0 || traceInChannel >= getTracesPerChannel()) {
return -1;
}
return traceInChannel * nChannels + channel;
}
// 获取指定通道和道号的数据
const RadarTrace* getTrace(int channel, int traceInChannel) const {
const int index = getTraceIndex(channel, traceInChannel);
if (index >= 0 && index < traces.size()) {
return &traces[index];
}
return nullptr;
}
// 计算深度（米）
double calculateDepth(int sampleIndex) const {
if (header.samplesPerTrace > 0) {
// 使用默认波速0.1m/ns，除以2是因为往返时间
double timePerSample = header.timeWindowNs / header.samplesPerTrace;
double timeNs = sampleIndex * timePerSample;
return timeNs * header.waveVelocity / 2.0; // 深度 = 时间 * 波速 / 2
}
return 0.0;
}
// 计算距离（米）
double calculateDistance(int traceIndex) const {
if (header.distanceInc > 0) {
return traceIndex * header.distanceInc;
}
return 0.0;
}
// 构建三维数据体
void buildVolumeData() {
if (traces.isEmpty()) return;
int nChannels = header.numberOfChannels > 0 ? header.numberOfChannels : 1;
int nTracesPerChannel = getTracesPerChannel();
int nSamples = header.samplesPerTrace;
volumeData.resize(nChannels);
for (int c = 0; c < nChannels; ++c) {
volumeData[c].resize(nTracesPerChannel);
for (int t = 0; t < nTracesPerChannel; ++t) {
volumeData[c][t].resize(nSamples);
}
}
// 填充数据
for (int i = 0; i < traces.size(); ++i) {
int channel = i % nChannels;
int traceInChannel = i / nChannels;
if (channel < volumeData.size() && traceInChannel < volumeData[channel].size()) {
for (int s = 0; s < traces[i].amplitudes.size() && s < nSamples; ++s) {
volumeData[channel][traceInChannel][s] = traces[i].amplitudes[s];
}
}
}
}
// 获取三维数据点
short getVolumeValue(int channel, int trace, int sample) const {
if (channel < 0 || channel >= volumeData.size() ||
trace < 0 || trace >= volumeData[channel].size() ||
sample < 0 || sample >= volumeData[channel][trace].size()) {
return 0;
}
return volumeData[channel][trace][sample];
}
// 获取全局最小最大值
void getGlobalMinMax(short& minVal, short& maxVal) const {
if (volumeData.isEmpty()) {
minVal = 0;
maxVal = 0;
return;
}
minVal = 32767;
maxVal = -32768;
for (const auto& channelData : volumeData) {
for (const auto& traceData : channelData) {
for (short val : traceData) {
if (val < minVal) minVal = val;
if (val > maxVal) maxVal = val;
}
}
}
}
// 获取通道数
int getChannelCount() const {
if (!volumeData.isEmpty()) return volumeData.size();
return qMax(1, header.numberOfChannels);
}
// 获取每通道的迹数
int getTraceCountPerChannel() const {
if (!volumeData.isEmpty() && !volumeData[0].isEmpty()) return volumeData[0].size();
int nCh = qMax(1, header.numberOfChannels);
return header.numTraces / nCh;
}
// 获取每迹的样本数
int getSampleCount() const {
if (!volumeData.isEmpty() && !volumeData[0].isEmpty()) return volumeData[0][0].size();
return header.samplesPerTrace;
}
GPRDataModel() = default;
GPRDataModel(const GPRDataModel&) = default;
GPRDataModel& operator=(const GPRDataModel&) = default;
GPRDataModel(GPRDataModel&&) = default;
GPRDataModel& operator=(GPRDataModel&&) = default;
};
struct TrajectoryEditPoint {
QVector3D rawPosition;
QVector3D editedPosition;
bool enabled = true;
bool manuallyEdited = false;
bool distanceOutlier = false;
bool speedOutlier = false;
bool angleOutlier = false;
};
struct TrajectoryEditSettings {
bool distanceFilterEnabled = true;
double maxSegmentDistanceM = 1.0;
bool speedFilterEnabled = false;
double maxSpeedMps = 5.0;
double traceIntervalSec = 0.05;
bool angleFilterEnabled = true;
double maxTurnAngleDeg = 60.0;
int interpolationMode = 0; // 0 linear, 1 spline
bool preserveManualEdits = true;
};
// 单条测线结构（含GPS）
struct SurveyLine {
QString name; // 测线编号，如 "_000", "_001"
QString displayName; // 显示名称，如 "碧新路_000"
QString radFilePath; // .rad 文件完整路径
GPRDataModel data; // 雷达数据
QVector<QVector3D> gpsPositions; // 每个trace的GPS坐标 (X,Y,Z)
QVector<TrajectoryEditPoint> trajectoryEditPoints; // 可编辑中心线轨迹点
TrajectoryEditSettings trajectoryEditSettings;
// 三维轨迹相关（新增）
SurveyGeometry geometry; // 天线几何参数
QVector<QVector<QVector3D>> channelTrajectories; // [channel][trace] 绝对坐标
bool hasGps() const { return !gpsPositions.isEmpty(); }
bool hasValidTrajectories() const { return !channelTrajectories.isEmpty() && !channelTrajectories[0].isEmpty(); }
bool isEmpty() const { return data.isEmpty(); }
void clear() {
name.clear();
displayName.clear();
radFilePath.clear();
data.clear();
gpsPositions.clear();
trajectoryEditPoints.clear();
trajectoryEditSettings = TrajectoryEditSettings{};
geometry = SurveyGeometry{};
channelTrajectories.clear();
}
SurveyLine() = default;
SurveyLine(const SurveyLine&) = default;
SurveyLine& operator=(const SurveyLine&) = default;
SurveyLine(SurveyLine&&) = default;
SurveyLine& operator=(SurveyLine&&) = default;
};
Q_DECLARE_METATYPE(SurveyLine)
#endif // GPRDATAMODEL_H

406
external/gpr3dviewer/ImpulseMultiChannelConverter.cpp vendored Normal file
View File

@ -0,0 +1,406 @@
#include "ImpulseMultiChannelConverter.h"
#include "IprhParser.h"
#include <QDebug>
#include <QDir>
#include <QFile>
#include <QFileInfo>
#include <QLocale>
#include <QMap>
#include <QRegularExpression>
#include <QSharedPointer>
#include <QStringList>
#include <QTextStream>
#include <algorithm>
#include <limits>
bool ImpulseMultiChannelConverter::isMultiChannelImpulseHeader(const QString &headerPath,
QString *dirPath,
QString *baseName)
{
QFileInfo fi(headerPath);
QRegularExpression reMultiChannel(QStringLiteral("^(.*)_A(\\d+)$"),
QRegularExpression::CaseInsensitiveOption);
QRegularExpressionMatch match = reMultiChannel.match(fi.completeBaseName());
if (!match.hasMatch())
return false;
const QString surveyBase = match.captured(1);
QDir dir(fi.absolutePath());
const QStringList channels = dir.entryList(QStringList() << surveyBase + QStringLiteral("_A*.iprh"),
QDir::Files);
if (channels.size() <= 1)
return false;
if (dirPath)
*dirPath = fi.absolutePath();
if (baseName)
*baseName = surveyBase;
return true;
}
bool ImpulseMultiChannelConverter::buildPlan(const QString &dirPath,
const QString &baseName,
ConversionPlan &plan,
QString *errorMessage)
{
plan = ConversionPlan{};
plan.dirPath = dirPath;
plan.baseName = baseName;
QDir dir(dirPath);
dir.setFilter(QDir::Files | QDir::NoDotAndDotDot);
QRegularExpression reChannel(QStringLiteral("^%1_A(\\d+)\\.iprh$").arg(QRegularExpression::escape(baseName)),
QRegularExpression::CaseInsensitiveOption);
QMap<int, QString> channelHeaders;
for (const QFileInfo &fi : dir.entryInfoList()) {
QRegularExpressionMatch match = reChannel.match(fi.fileName());
if (!match.hasMatch())
continue;
const int chNum = match.captured(1).toInt();
const QString iprhPath = fi.absoluteFilePath();
QString iprbPath = iprhPath;
iprbPath.replace(QStringLiteral(".iprh"), QStringLiteral(".iprb"), Qt::CaseInsensitive);
if (QFile::exists(iprbPath)) {
channelHeaders.insert(chNum, iprhPath);
} else {
qDebug() << "Missing .iprb for" << iprhPath;
}
}
if (channelHeaders.isEmpty()) {
if (errorMessage)
*errorMessage = QStringLiteral("未找到 Impulse 多通道文件：%1").arg(baseName);
return false;
}
GPRDataModel::Header masterHeader;
if (!IprhParser::parseHeaderOnly(channelHeaders.first(), masterHeader)) {
if (errorMessage)
*errorMessage = QStringLiteral("无法解析主通道头文件：%1").arg(channelHeaders.first());
return false;
}
QVector<float> xOffsets;
QVector<float> yOffsets;
xOffsets.reserve(channelHeaders.size());
yOffsets.reserve(channelHeaders.size());
qint64 minTraceCount = std::numeric_limits<qint64>::max();
double antennaSeparation = 0.0;
for (auto it = channelHeaders.begin(); it != channelHeaders.end(); ++it) {
ChannelInfo info;
info.channelNumber = it.key();
info.iprhPath = it.value();
info.iprbPath = info.iprhPath;
info.iprbPath.replace(QStringLiteral(".iprh"), QStringLiteral(".iprb"), Qt::CaseInsensitive);
if (!IprhParser::parseHeaderOnly(info.iprhPath, info.header)) {
if (errorMessage)
*errorMessage = QStringLiteral("无法解析通道头文件：%1").arg(info.iprhPath);
return false;
}
if (info.header.samplesPerTrace != masterHeader.samplesPerTrace) {
if (errorMessage)
*errorMessage = QStringLiteral("多通道 SAMPLES 不一致：%1").arg(info.iprhPath);
return false;
}
if (!qFuzzyCompare(info.header.timeIntervalNs, masterHeader.timeIntervalNs) &&
info.header.timeIntervalNs > 0 && masterHeader.timeIntervalNs > 0) {
qDebug() << "Warning: Inconsistent TIME INTERVAL across channels" << info.iprhPath;
}
if (!qFuzzyCompare(info.header.distanceInc, masterHeader.distanceInc) &&
info.header.distanceInc > 0 && masterHeader.distanceInc > 0) {
qDebug() << "Warning: Inconsistent DISTANCE INTERVAL across channels" << info.iprhPath;
}
if (info.header.rawParams.contains(QStringLiteral("CH_X_OFFSET"))) {
info.xOffset = info.header.rawParams.value(QStringLiteral("CH_X_OFFSET")).toFloat();
} else if (info.header.rawParams.contains(QStringLiteral("CH_OFFSET_X"))) {
info.xOffset = info.header.rawParams.value(QStringLiteral("CH_OFFSET_X")).toFloat();
} else if (!info.header.chXOffsets.isEmpty()) {
info.xOffset = info.header.chXOffsets.first();
}
if (info.header.rawParams.contains(QStringLiteral("CH_Y_OFFSET"))) {
info.yOffset = info.header.rawParams.value(QStringLiteral("CH_Y_OFFSET")).toFloat();
} else if (info.header.rawParams.contains(QStringLiteral("CH_OFFSET_Y"))) {
info.yOffset = info.header.rawParams.value(QStringLiteral("CH_OFFSET_Y")).toFloat();
} else if (!info.header.chYOffsets.isEmpty()) {
info.yOffset = info.header.chYOffsets.first();
}
xOffsets.append(info.xOffset);
yOffsets.append(info.yOffset);
if (info.header.rawParams.contains(QStringLiteral("ANTENNA SEPARATION"))) {
antennaSeparation = info.header.rawParams.value(QStringLiteral("ANTENNA SEPARATION")).toDouble();
}
const qint64 traceBytes = static_cast<qint64>(info.header.samplesPerTrace) * sizeof(qint16);
if (traceBytes <= 0) {
if (errorMessage)
*errorMessage = QStringLiteral("通道采样数无效：%1").arg(info.iprhPath);
return false;
}
info.traceCount = QFileInfo(info.iprbPath).size() / traceBytes;
if (info.traceCount <= 0) {
if (errorMessage)
*errorMessage = QStringLiteral("通道无有效数据：%1").arg(info.iprbPath);
return false;
}
minTraceCount = std::min(minTraceCount, info.traceCount);
plan.channels.append(info);
}
if (plan.channels.isEmpty() || minTraceCount <= 0 || minTraceCount == std::numeric_limits<qint64>::max()) {
if (errorMessage)
*errorMessage = QStringLiteral("Impulse 多通道没有有效 trace：%1").arg(baseName);
return false;
}
for (const ChannelInfo &info : plan.channels) {
if (info.traceCount != minTraceCount) {
qDebug() << "Warning: Inconsistent trace count across channels. Using minimum:"
<< minTraceCount << "channel has:" << info.traceCount << info.iprhPath;
}
}
bool allZeroOffsets = true;
for (float value : xOffsets) {
if (!qFuzzyIsNull(value)) {
allZeroOffsets = false;
break;
}
}
if (allZeroOffsets && antennaSeparation > 1e-6 && plan.channels.size() > 1) {
const double totalWidth = (plan.channels.size() - 1) * antennaSeparation;
const double startX = -totalWidth / 2.0;
for (int i = 0; i < xOffsets.size(); ++i) {
xOffsets[i] = static_cast<float>(startX + i * antennaSeparation);
plan.channels[i].xOffset = xOffsets[i];
}
qDebug() << "Computed symmetric X offsets from antenna separation:" << antennaSeparation;
}
plan.channelCount = plan.channels.size();
plan.tracesPerChannel = static_cast<int>(minTraceCount);
plan.samplesPerTrace = masterHeader.samplesPerTrace;
plan.traceByteSize = plan.samplesPerTrace * static_cast<qint64>(sizeof(qint16));
plan.totalOutputTraces = static_cast<qint64>(plan.tracesPerChannel) * plan.channelCount;
plan.outputHeader = masterHeader;
plan.outputHeader.numberOfChannels = plan.channelCount;
plan.outputHeader.numTraces = static_cast<int>(plan.totalOutputTraces);
plan.outputHeader.chXOffsets = xOffsets;
plan.outputHeader.chYOffsets = yOffsets;
if (plan.outputHeader.timeWindowNs <= 0.0 && plan.outputHeader.timeIntervalNs > 0.0) {
plan.outputHeader.timeWindowNs = plan.outputHeader.samplesPerTrace * plan.outputHeader.timeIntervalNs;
}
const QString basePath = dir.absoluteFilePath(baseName + QStringLiteral("_mala_converted"));
plan.outputRadPath = basePath + QStringLiteral(".rad");
plan.outputRd3Path = basePath + QStringLiteral(".rd3");
return true;
}
bool ImpulseMultiChannelConverter::convertStreaming(const ConversionPlan &plan,
const Options &options,
QString *radFilePath,
QString *errorMessage,
CancelFn cancel,
ProgressFn progress)
{
if (plan.channelCount <= 0 || plan.tracesPerChannel <= 0 || plan.traceByteSize <= 0) {
if (errorMessage)
*errorMessage = QStringLiteral("Impulse 转换计划无效");
return false;
}
if (options.reuseExistingIfValid && convertedFilesAreValid(plan)) {
if (radFilePath)
*radFilePath = plan.outputRadPath;
return true;
}
if (!options.overwriteExisting && (QFile::exists(plan.outputRadPath) || QFile::exists(plan.outputRd3Path))) {
if (errorMessage)
*errorMessage = QStringLiteral("转换输出文件已存在：%1").arg(plan.outputRadPath);
return false;
}
const QString tmpRd3Path = plan.outputRd3Path + QStringLiteral(".tmp");
const QString tmpRadPath = plan.outputRadPath + QStringLiteral(".tmp");
QFile::remove(tmpRd3Path);
QFile::remove(tmpRadPath);
QVector<QSharedPointer<QFile>> inputFiles;
inputFiles.reserve(plan.channels.size());
for (const ChannelInfo &channel : plan.channels) {
auto file = QSharedPointer<QFile>::create(channel.iprbPath);
if (!file->open(QIODevice::ReadOnly)) {
if (errorMessage)
*errorMessage = QStringLiteral("无法读取 Impulse 通道数据：%1").arg(channel.iprbPath);
return false;
}
inputFiles.append(file);
}
QFile rd3File(tmpRd3Path);
if (!rd3File.open(QIODevice::WriteOnly | QIODevice::Truncate)) {
if (errorMessage)
*errorMessage = QStringLiteral("无法写入转换后的 RD3 文件：%1").arg(tmpRd3Path);
return false;
}
const qint64 bytesPerTracePosition = plan.traceByteSize * plan.channelCount;
const qint64 chunkBudget = qMax<qint64>(bytesPerTracePosition, options.maxChunkBytes);
const int chunkTraces = qMax<qint64>(1, chunkBudget / bytesPerTracePosition);
QVector<QByteArray> channelBuffers(plan.channelCount);
qint64 tracesDone = 0;
while (tracesDone < plan.tracesPerChannel) {
if (cancel && cancel()) {
rd3File.close();
QFile::remove(tmpRd3Path);
QFile::remove(tmpRadPath);
if (errorMessage)
*errorMessage = QStringLiteral("Impulse 多通道转换已取消");
return false;
}
const int currentChunk = qMin<qint64>(chunkTraces, plan.tracesPerChannel - tracesDone);
const qint64 expectedChannelBytes = currentChunk * plan.traceByteSize;
for (int ch = 0; ch < plan.channelCount; ++ch) {
channelBuffers[ch] = inputFiles[ch]->read(expectedChannelBytes);
if (channelBuffers[ch].size() != expectedChannelBytes) {
rd3File.close();
QFile::remove(tmpRd3Path);
if (errorMessage) {
*errorMessage = QStringLiteral("读取通道数据不完整：%1").arg(plan.channels[ch].iprbPath);
}
return false;
}
}
for (int localTrace = 0; localTrace < currentChunk; ++localTrace) {
const qint64 offset = localTrace * plan.traceByteSize;
for (int ch = 0; ch < plan.channelCount; ++ch) {
const qint64 written = rd3File.write(channelBuffers[ch].constData() + offset, plan.traceByteSize);
if (written != plan.traceByteSize) {
rd3File.close();
QFile::remove(tmpRd3Path);
if (errorMessage)
*errorMessage = QStringLiteral("写入转换后的 RD3 文件失败：%1").arg(tmpRd3Path);
return false;
}
}
}
tracesDone += currentChunk;
if (progress) {
progress(Progress{tracesDone, plan.tracesPerChannel,
QStringLiteral("正在转换 Impulse 多通道 %1/%2")
.arg(tracesDone)
.arg(plan.tracesPerChannel)});
}
}
rd3File.close();
if (rd3File.error() != QFile::NoError) {
QFile::remove(tmpRd3Path);
if (errorMessage)
*errorMessage = QStringLiteral("保存转换后的 RD3 文件失败：%1").arg(rd3File.errorString());
return false;
}
ConversionPlan tmpPlan = plan;
tmpPlan.outputRadPath = tmpRadPath;
if (!writeRadHeader(tmpRadPath, tmpPlan, errorMessage)) {
QFile::remove(tmpRd3Path);
QFile::remove(tmpRadPath);
return false;
}
QFile::remove(plan.outputRd3Path);
QFile::remove(plan.outputRadPath);
if (!QFile::rename(tmpRd3Path, plan.outputRd3Path)) {
QFile::remove(tmpRd3Path);
QFile::remove(tmpRadPath);
if (errorMessage)
*errorMessage = QStringLiteral("无法替换转换后的 RD3 文件：%1").arg(plan.outputRd3Path);
return false;
}
if (!QFile::rename(tmpRadPath, plan.outputRadPath)) {
QFile::remove(plan.outputRd3Path);
QFile::remove(tmpRadPath);
if (errorMessage)
*errorMessage = QStringLiteral("无法替换转换后的 RAD 文件：%1").arg(plan.outputRadPath);
return false;
}
if (radFilePath)
*radFilePath = plan.outputRadPath;
qDebug() << "Impulse multi-channel streaming conversion OK:" << plan.outputRadPath << plan.outputRd3Path;
return true;
}
bool ImpulseMultiChannelConverter::writeRadHeader(const QString &radFilePath,
const ConversionPlan &plan,
QString *errorMessage)
{
QFile radFile(radFilePath);
if (!radFile.open(QIODevice::WriteOnly | QIODevice::Text | QIODevice::Truncate)) {
if (errorMessage)
*errorMessage = QStringLiteral("无法写入转换后的 RAD 文件：%1").arg(radFilePath);
return false;
}
QTextStream rad(&radFile);
const auto &header = plan.outputHeader;
rad << "# Converted from Impulse multi-channel survey: " << plan.baseName << '\n';
rad << "SAMPLES: " << header.samplesPerTrace << '\n';
rad << "LAST TRACE: " << plan.totalOutputTraces << '\n';
rad << "TIMEWINDOW: " << QLocale::c().toString(header.timeWindowNs, 'g', 12) << '\n';
rad << "TIME INTERVAL: " << QLocale::c().toString(header.timeIntervalNs, 'g', 12) << '\n';
rad << "DISTANCE INTERVAL: " << QLocale::c().toString(header.distanceInc, 'g', 12) << '\n';
rad << "ANTENNAS: " << QLocale::c().toString(header.antennaFreq, 'g', 12) << '\n';
if (!header.antennaType.isEmpty()) rad << "ANTENNA: " << header.antennaType << '\n';
if (!header.date.isEmpty()) rad << "DATE: " << header.date << '\n';
if (!header.timeStr.isEmpty()) rad << "TIME: " << header.timeStr << '\n';
rad << "NUMBER_OF_CH: " << qMax(1, header.numberOfChannels) << '\n';
rad << "CH_X_OFFSETS: " << formatFloatList(header.chXOffsets) << '\n';
rad << "CH_Y_OFFSETS: " << formatFloatList(header.chYOffsets) << '\n';
if (!header.units.isEmpty()) rad << "UNITS: " << header.units << '\n';
rad << "START POSITION: " << QLocale::c().toString(header.startPosition, 'g', 12) << '\n';
const double stopPosition = header.stopPosition > header.startPosition
? header.stopPosition
: header.startPosition + plan.tracesPerChannel * header.distanceInc;
rad << "STOP POSITION: " << QLocale::c().toString(stopPosition, 'g', 12) << '\n';
radFile.close();
return true;
}
bool ImpulseMultiChannelConverter::convertedFilesAreValid(const ConversionPlan &plan)
{
QFileInfo radInfo(plan.outputRadPath);
QFileInfo rd3Info(plan.outputRd3Path);
if (!radInfo.exists() || !rd3Info.exists())
return false;
const qint64 expectedBytes = plan.totalOutputTraces * plan.traceByteSize;
return rd3Info.size() == expectedBytes;
}
QString ImpulseMultiChannelConverter::formatFloatList(const QVector<float> &values)
{
QStringList parts;
parts.reserve(values.size());
for (float value : values) {
parts.append(QLocale::c().toString(value, 'g', 10));
}
return parts.join(' ');
}

75
external/gpr3dviewer/ImpulseMultiChannelConverter.h vendored Normal file
View File

@ -0,0 +1,75 @@
#ifndef IMPULSEMULTICHANNELCONVERTER_H
#define IMPULSEMULTICHANNELCONVERTER_H
#include "GPRDataModel.h"
#include <QVector>
#include <QString>
#include <functional>
class ImpulseMultiChannelConverter {
public:
struct ChannelInfo {
int channelNumber = 0;
QString iprhPath;
QString iprbPath;
GPRDataModel::Header header;
qint64 traceCount = 0;
float xOffset = 0.0f;
float yOffset = 0.0f;
};
struct ConversionPlan {
QString dirPath;
QString baseName;
QVector<ChannelInfo> channels;
GPRDataModel::Header outputHeader;
int channelCount = 0;
int tracesPerChannel = 0;
qint64 totalOutputTraces = 0;
qint64 samplesPerTrace = 0;
qint64 traceByteSize = 0;
QString outputRadPath;
QString outputRd3Path;
};
struct Options {
qint64 maxChunkBytes = 32 * 1024 * 1024;
bool overwriteExisting = true;
bool reuseExistingIfValid = false;
};
struct Progress {
qint64 tracesDone = 0;
qint64 tracesTotal = 0;
QString message;
};
using CancelFn = std::function<bool()>;
using ProgressFn = std::function<void(const Progress&)>;
static bool isMultiChannelImpulseHeader(const QString &headerPath,
QString *dirPath = nullptr,
QString *baseName = nullptr);
static bool buildPlan(const QString &dirPath,
const QString &baseName,
ConversionPlan &plan,
QString *errorMessage = nullptr);
static bool convertStreaming(const ConversionPlan &plan,
const Options &options,
QString *radFilePath = nullptr,
QString *errorMessage = nullptr,
CancelFn cancel = {},
ProgressFn progress = {});
private:
static bool writeRadHeader(const QString &radFilePath,
const ConversionPlan &plan,
QString *errorMessage);
static bool convertedFilesAreValid(const ConversionPlan &plan);
static QString formatFloatList(const QVector<float> &values);
};
#endif // IMPULSEMULTICHANNELCONVERTER_H

625
external/gpr3dviewer/IprhParser.cpp vendored Normal file
View File

@ -0,0 +1,625 @@
#include "IprhParser.h"
#include "PerformanceLogger.h"
#include "ImpulseMultiChannelConverter.h"
#include <QFile>
#include <QTextStream>
#include <QDataStream>
#include <QDebug>
#include <QDir>
#include <QFileInfo>
#include <QRegularExpression>
#include <QStringList>
#include <QVector3D>
#include <QLocale>
#include <algorithm>
#include <cstring>
/**
* @brief 加载 Impulse 系列雷达 IPRH 数据（iprh头文件 + iprb纯二进制波形）
* @param iprhFilePath .iprh 文本配置头文件路径
* @param model 输出 GPR 全局数据模型
* @return true 加载解析成功；false 失败
* @note 存储结构：.iprh 存储全部仪器/测线参数；.iprb 无文件头，从头到尾全是 short16 振幅采样
*/
bool IprhParser::loadFromIprh(const QString &iprhFilePath, GPRDataModel &model) {
SCOPED_PERF_TIMER("Parser", "IprhParser::loadFromIprh");
model.clear();
model.header = GPRDataModel::Header{};
// 第一步：解析 iprh 文本头
if (!parseIprhHeader(iprhFilePath, model.header)) {
qDebug() << "Error: Failed to parse .iprh header file:" << iprhFilePath;
return false;
}
// 自动匹配同目录同名二进制数据文件 .iprb
QFileInfo iprhInfo(iprhFilePath);
QString iprbPath = iprhInfo.absolutePath() + "/" + iprhInfo.completeBaseName() + ".iprb";
if (!QFile::exists(iprbPath)) {
qDebug() << "Error: Matching .iprb binary file not found at:" << iprbPath;
return false;
}
// 如果头文件没有 LAST TRACE，从二进制文件大小推算
if (model.header.numTraces <= 0) {
QFile binaryFile(iprbPath);
if (binaryFile.open(QIODevice::ReadOnly)) {
qint64 fileSize = binaryFile.size();
qint64 traceBytes = static_cast<qint64>(model.header.samplesPerTrace) * sizeof(short);
if (traceBytes > 0) {
model.header.numTraces = static_cast<int>(fileSize / traceBytes);
qDebug() << "Inferred numTraces from binary size:" << model.header.numTraces;
}
binaryFile.close();
}
}
if (model.header.timeWindowNs <= 0.0 && model.header.timeIntervalNs > 0.0) {
model.header.timeWindowNs = model.header.samplesPerTrace * model.header.timeIntervalNs;
qDebug() << "Inferred timeWindowNs from samples * timeInterval:" << model.header.timeWindowNs;
}
if (model.header.numTraces <= 0) {
qDebug() << "Error: Unable to determine numTraces from header or binary file";
return false;
}
// 第二步：读取纯二进制波形
return loadIprbBinary(iprbPath, model);
}
/**
* @brief 解析 IPRH 文本头文件，提取雷达采集关键参数
* @param iprhFilePath iprh 文本文件路径
* @param header 待填充头部参数结构体
* @return 解析成功返回 true
*/
bool IprhParser::parseHeaderOnly(const QString &iprhFilePath, GPRDataModel::Header &header)
{
return parseIprhHeader(iprhFilePath, header);
}
bool IprhParser::parseIprhHeader(const QString &iprhFilePath, GPRDataModel::Header &header) {
SCOPED_PERF_TIMER("Parser", "IprhParser::parseIprhHeader");
QFile file(iprhFilePath);
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
qDebug() << "Error: Cannot open iprh file for read";
return false;
}
QTextStream in(&file);
while (!in.atEnd()) {
QString line = in.readLine().trimmed();
if (line.isEmpty()) continue;
int sepPos = line.indexOf(':');
if (sepPos == -1) continue;
QString key = line.left(sepPos).trimmed();
QString value = line.mid(sepPos + 1).trimmed();
header.rawParams[key] = value;
if (key == "SAMPLES") {
header.samplesPerTrace = extractInt(value);
} else if (key == "LAST TRACE") {
header.numTraces = extractInt(value);
} else if (key == "TIMEWINDOW") {
header.timeWindowNs = extractDouble(value);
} else if (key == "DISTANCE INTERVAL") {
header.distanceInc = extractDouble(value);
} else if (key == "TIME INTERVAL") {
header.timeIntervalNs = extractDouble(value);
} else if (key == "ANTENNAS") {
header.antennaFreq = extractDouble(value);
} else if (key == "ANTENNA") {
header.antennaType = value;
} else if (key == "DATE") {
header.date = value;
} else if (key == "START TIME" || key == "TIME") {
header.timeStr = value;
} else if (key == "CHANNELS" || key == "NUMBER_OF_CH") {
header.numberOfChannels = extractInt(value);
} else if (key == "CH_X_OFFSET" || key == "CH_OFFSET_X") {
// 单通道偏移量（Impulse 单通道文件）
if (!value.isEmpty()) {
header.chXOffsets.append(value.toFloat());
}
} else if (key == "CH_Y_OFFSET" || key == "CH_OFFSET_Y") {
if (!value.isEmpty()) {
header.chYOffsets.append(value.toFloat());
}
} else if (key == "CH_X_OFFSETS") {
// 兼容 Mala Mira 风格多值空格分隔
QStringList offsets = value.split(' ', Qt::SkipEmptyParts);
for (const QString &offset : offsets) {
header.chXOffsets.append(offset.toFloat());
}
} else if (key == "CH_Y_OFFSETS") {
QStringList offsets = value.split(' ', Qt::SkipEmptyParts);
for (const QString &offset : offsets) {
header.chYOffsets.append(offset.toFloat());
}
} else if (key == "UNITS") {
header.units = value;
} else if (key == "START POSITION") {
header.startPosition = extractDouble(value);
} else if (key == "STOP POSITION") {
header.stopPosition = extractDouble(value);
}
}
file.close();
if (header.samplesPerTrace <= 0) {
qDebug() << "Error: Invalid SAMPLES value in iprh file";
return false;
}
header.waveVelocity = 0.1;
qDebug() << "==== IPRH Header Parse Complete ===="
<< "\nSamples per trace:" << header.samplesPerTrace
<< "\nTotal traces:" << header.numTraces
<< "\nTime window(ns):" << header.timeWindowNs
<< "\nChannel count:" << header.numberOfChannels
<< "\nX offset array size:" << header.chXOffsets.size()
<< "\nY offset array size:" << header.chYOffsets.size();
return true;
}
/**
* @brief 读取纯 IPRB 二进制数据（无任何文件头，全连续 short16 振幅）
* @param iprbFilePath iprb 波形文件路径
* @param model 绑定头部参数，填充完整 traces 波形数组
* @return 读取成功 true
*/
bool IprhParser::loadIprbBinary(const QString &iprbFilePath, GPRDataModel &model) {
SCOPED_PERF_TIMER("Parser", "IprhParser::loadIprbBinary");
QFile file(iprbFilePath);
if (!file.open(QIODevice::ReadOnly)) {
qDebug() << "Error: Open iprb binary failed:" << iprbFilePath;
return false;
}
const int samplesPerTrace = model.header.samplesPerTrace;
const int totalTraceCount = model.header.numTraces;
const qint64 dataStartOffset = 0;
file.seek(dataStartOffset);
const qint64 singleTraceByteSize = samplesPerTrace * sizeof(short);
const qint64 fullExpectedBytes = totalTraceCount * singleTraceByteSize;
const qint64 realFileBytes = file.size();
if (realFileBytes < fullExpectedBytes) {
qDebug() << "Warning: IPRB file size smaller than theoretical data size!"
<< "Expected:" << fullExpectedBytes << "Actual:" << realFileBytes;
}
model.traces.reserve(totalTraceCount);
QByteArray traceBuffer;
traceBuffer.resize(singleTraceByteSize);
const int channelCnt = model.header.numberOfChannels > 0 ? model.header.numberOfChannels : 1;
model.channels = channelCnt;
model.tracesPerChannel = totalTraceCount / channelCnt;
if (model.header.distanceInc > 1e-6) {
model.totalDistance = static_cast<float>(model.tracesPerChannel * model.header.distanceInc);
} else {
model.totalDistance = static_cast<float>(model.header.stopPosition - model.header.startPosition);
}
for (int traceGlobalIdx = 0; traceGlobalIdx < totalTraceCount; ++traceGlobalIdx) {
if (file.atEnd()) {
qDebug() << "Warning: File ended early at global trace index" << traceGlobalIdx;
break;
}
qint64 readBytes = file.read(traceBuffer.data(), traceBuffer.size());
if (readBytes != traceBuffer.size()) {
qDebug() << "Warning: Trace" << traceGlobalIdx << "incomplete byte read";
break;
}
RadarTrace oneTrace;
oneTrace.amplitudes.resize(samplesPerTrace);
const short* rawShortBuf = reinterpret_cast<const short*>(traceBuffer.constData());
for (int s = 0; s < samplesPerTrace; s++) {
oneTrace.amplitudes[s] = rawShortBuf[s];
}
int chNo = traceGlobalIdx % channelCnt;
int traceInChIdx = traceGlobalIdx / channelCnt;
oneTrace.channelNumber = chNo;
float xOff = 0.0f;
float yOff = 0.0f;
if (chNo < model.header.chXOffsets.size()) xOff = model.header.chXOffsets[chNo];
if (chNo < model.header.chYOffsets.size()) yOff = model.header.chYOffsets[chNo];
float lineDist = static_cast<float>(model.header.startPosition + traceInChIdx * model.header.distanceInc);
oneTrace.position = QVector3D(xOff, lineDist - yOff, 0.0f);
model.traces.append(std::move(oneTrace));
}
file.close();
if (model.traces.isEmpty()) {
qDebug() << "Error: No valid traces loaded from iprb";
return false;
}
qDebug() << "IPRB Binary Load OK, total valid traces:" << model.traces.size();
return true;
}
/**
* @brief 加载 Impulse 多通道数据（每个通道一个 .iprh + .iprb）
* @param dirPath 数据所在目录
* @param baseName 测线基础名（如 "明星路_001"）
* @param model 输出合并后的 GPR 数据模型
* @return true 加载合并成功
*
* 文件命名约定：baseName_A01.iprh / .iprb ... baseName_A14.iprh / .iprb
* 合并后 traces 按 Mala Mira 格式交错：trace0=ch0_pos0, trace1=ch1_pos0, ...
*/
bool IprhParser::convertImpulseMultiChannelToMala(const QString &dirPath,
const QString &baseName,
QString *radFilePath,
QString *errorMessage)
{
ImpulseMultiChannelConverter::ConversionPlan plan;
if (!ImpulseMultiChannelConverter::buildPlan(dirPath, baseName, plan, errorMessage)) {
if (errorMessage && errorMessage->isEmpty()) {
*errorMessage = QStringLiteral("多通道 Impulse 数据合并失败：%1").arg(baseName);
}
return false;
}
ImpulseMultiChannelConverter::Options options;
options.overwriteExisting = true;
options.reuseExistingIfValid = false;
if (!ImpulseMultiChannelConverter::convertStreaming(plan, options, radFilePath, errorMessage)) {
return false;
}
qDebug() << "Impulse multi-channel converted to Mala Mira files:" << plan.outputRadPath << plan.outputRd3Path;
return true;
}
/**
* @brief 加载 Impulse 多通道数据（每个通道一个 .iprh + .iprb）
* @param dirPath 数据所在目录
* @param baseName 测线基础名（如 "明星路_001"）
* @param model 输出合并后的 GPR 数据模型
* @return true 加载合并成功
*
* 文件命名约定：baseName_A01.iprh / .iprb ... baseName_A14.iprh / .iprb
* 合并后 traces 按 Mala Mira 格式交错：trace0=ch0_pos0, trace1=ch1_pos0, ...
*/
bool IprhParser::loadImpulseMultiChannel(const QString &dirPath,
const QString &baseName,
GPRDataModel &model)
{
SCOPED_PERF_TIMER("Parser", "IprhParser::loadImpulseMultiChannel");
model.clear();
model.header = GPRDataModel::Header{};
// 1. 发现所有通道文件并排序
QDir dir(dirPath);
dir.setFilter(QDir::Files | QDir::NoDotAndDotDot);
QRegularExpression reChannel(QStringLiteral("^%1_A(\\d+)\\.iprh$").arg(QRegularExpression::escape(baseName)));
QMap<int, QString> channelHeaders; // channelNum -> iprh path
for (const QFileInfo &fi : dir.entryInfoList()) {
QRegularExpressionMatch match = reChannel.match(fi.fileName());
if (match.hasMatch()) {
int chNum = match.captured(1).toInt();
QString iprhPath = fi.absoluteFilePath();
QString iprbPath = iprhPath;
iprbPath.replace(".iprh", ".iprb");
if (QFile::exists(iprbPath)) {
channelHeaders.insert(chNum, iprhPath);
} else {
qDebug() << "Missing .iprb for" << iprhPath;
}
}
}
if (channelHeaders.isEmpty()) {
qDebug() << "No multi-channel .iprh/.iprb found for baseName:" << baseName;
return false;
}
const int channelCount = channelHeaders.size();
qDebug() << "Impulse multi-channel: found" << channelCount << "channels for" << baseName;
// 2. 解析第一个通道的头文件作为 master
auto it = channelHeaders.begin();
GPRDataModel::Header masterHeader;
if (!parseIprhHeader(it.value(), masterHeader)) {
qDebug() << "Failed to parse master header:" << it.value();
return false;
}
QVector<float> xOffsets;
QVector<float> yOffsets;
xOffsets.reserve(channelCount);
yOffsets.reserve(channelCount);
// 3. 验证各通道一致性并收集偏移量
QVector<int> channelTracesPerChannel;
channelTracesPerChannel.reserve(channelCount);
double antennaSeparation = 0.0;
for (auto cit = channelHeaders.begin(); cit != channelHeaders.end(); ++cit) {
int chNum = cit.key();
QString iprhPath = cit.value();
GPRDataModel::Header chHeader;
if (!parseIprhHeader(iprhPath, chHeader)) {
qDebug() << "Failed to parse channel header:" << iprhPath;
return false;
}
// 验证关键参数一致性
if (chHeader.samplesPerTrace != masterHeader.samplesPerTrace) {
qDebug() << "Inconsistent SAMPLES across channels";
return false;
}
if (qFuzzyCompare(chHeader.timeIntervalNs, masterHeader.timeIntervalNs) == false &&
chHeader.timeIntervalNs > 0 && masterHeader.timeIntervalNs > 0) {
qDebug() << "Warning: Inconsistent TIME INTERVAL across channels";
}
if (qFuzzyCompare(chHeader.distanceInc, masterHeader.distanceInc) == false &&
chHeader.distanceInc > 0 && masterHeader.distanceInc > 0) {
qDebug() << "Warning: Inconsistent DISTANCE INTERVAL across channels";
}
// 收集单通道偏移量
float xOff = 0.0f, yOff = 0.0f;
if (chHeader.rawParams.contains("CH_X_OFFSET")) {
xOff = chHeader.rawParams.value("CH_X_OFFSET").toFloat();
} else if (chHeader.rawParams.contains("CH_OFFSET_X")) {
xOff = chHeader.rawParams.value("CH_OFFSET_X").toFloat();
} else if (!chHeader.chXOffsets.isEmpty()) {
xOff = chHeader.chXOffsets.first();
}
if (chHeader.rawParams.contains("CH_Y_OFFSET")) {
yOff = chHeader.rawParams.value("CH_Y_OFFSET").toFloat();
} else if (chHeader.rawParams.contains("CH_OFFSET_Y")) {
yOff = chHeader.rawParams.value("CH_OFFSET_Y").toFloat();
} else if (!chHeader.chYOffsets.isEmpty()) {
yOff = chHeader.chYOffsets.first();
}
xOffsets.append(xOff);
yOffsets.append(yOff);
if (chHeader.rawParams.contains("ANTENNA SEPARATION")) {
antennaSeparation = chHeader.rawParams.value("ANTENNA SEPARATION").toDouble();
}
// 从 .iprb 大小计算该通道的道数
QString iprbPath = iprhPath;
iprbPath.replace(".iprh", ".iprb");
QFile iprbFile(iprbPath);
int tracesInThisChannel = 0;
if (iprbFile.open(QIODevice::ReadOnly)) {
qint64 fileSize = iprbFile.size();
qint64 traceBytes = static_cast<qint64>(chHeader.samplesPerTrace) * sizeof(short);
if (traceBytes > 0) {
tracesInThisChannel = static_cast<int>(fileSize / traceBytes);
}
iprbFile.close();
}
channelTracesPerChannel.append(tracesInThisChannel);
}
// 4. 以最小道数为准截断读取，容忍各通道微小差异
int tracesPerChannel = channelTracesPerChannel.isEmpty() ? 0 : *std::min_element(channelTracesPerChannel.begin(), channelTracesPerChannel.end());
for (int tc : channelTracesPerChannel) {
if (tc != tracesPerChannel) {
qDebug() << "Warning: Inconsistent trace count across channels. Using minimum:" << tracesPerChannel << "channel has:" << tc;
}
}
if (tracesPerChannel <= 0) {
qDebug() << "Error: No valid traces in any channel";
return false;
}
// 5. 如果偏移量全部为零，基于 ANTENNA SEPARATION 计算对称分布
bool allZeroOffsets = true;
for (float v : xOffsets) { if (qFuzzyIsNull(v) == false) { allZeroOffsets = false; break; } }
if (allZeroOffsets && antennaSeparation > 1e-6 && channelCount > 1) {
double totalWidth = (channelCount - 1) * antennaSeparation;
double startX = -totalWidth / 2.0;
for (int i = 0; i < channelCount; ++i) {
xOffsets[i] = static_cast<float>(startX + i * antennaSeparation);
}
qDebug() << "Computed symmetric X offsets from antenna separation:" << antennaSeparation;
}
// 6. 组装合并后的 Header
model.header = masterHeader;
model.header.numberOfChannels = channelCount;
model.header.numTraces = tracesPerChannel * channelCount;
model.header.chXOffsets = xOffsets;
model.header.chYOffsets = yOffsets;
if (model.header.timeWindowNs <= 0.0 && model.header.timeIntervalNs > 0.0) {
model.header.timeWindowNs = model.header.samplesPerTrace * model.header.timeIntervalNs;
}
// 7. 预分配 traces
model.traces.reserve(model.header.numTraces);
// 8. 读取每个通道的 .iprb 到临时数组
QVector<QVector<RadarTrace>> channelTraceArrays;
channelTraceArrays.resize(channelCount);
int chIdx = 0;
for (auto cit = channelHeaders.begin(); cit != channelHeaders.end(); ++cit, ++chIdx) {
QString iprhPath = cit.value();
QString iprbPath = iprhPath;
iprbPath.replace(".iprh", ".iprb");
QFile file(iprbPath);
if (!file.open(QIODevice::ReadOnly)) {
qDebug() << "Error: Cannot open" << iprbPath;
return false;
}
const int samplesPerTrace = model.header.samplesPerTrace;
const qint64 singleTraceByteSize = samplesPerTrace * sizeof(short);
QByteArray traceBuffer;
traceBuffer.resize(singleTraceByteSize);
channelTraceArrays[chIdx].reserve(tracesPerChannel);
for (int t = 0; t < tracesPerChannel; ++t) {
if (file.atEnd()) break;
qint64 readBytes = file.read(traceBuffer.data(), traceBuffer.size());
if (readBytes != traceBuffer.size()) break;
RadarTrace oneTrace;
oneTrace.amplitudes.resize(samplesPerTrace);
const short* rawShortBuf = reinterpret_cast<const short*>(traceBuffer.constData());
for (int s = 0; s < samplesPerTrace; s++) {
oneTrace.amplitudes[s] = rawShortBuf[s];
}
channelTraceArrays[chIdx].append(std::move(oneTrace));
}
file.close();
if (channelTraceArrays[chIdx].size() != tracesPerChannel) {
qDebug() << "Warning: Channel" << cit.key() << "has fewer traces than expected";
}
}
// 9. 按 Mala Mira 格式交错合并
model.channels = channelCount;
model.tracesPerChannel = tracesPerChannel;
for (int pos = 0; pos < tracesPerChannel; ++pos) {
for (int ch = 0; ch < channelCount; ++ch) {
if (pos < channelTraceArrays[ch].size()) {
RadarTrace trace = std::move(channelTraceArrays[ch][pos]);
trace.channelNumber = ch;
float xOff = (ch < xOffsets.size()) ? xOffsets[ch] : 0.0f;
float yOff = (ch < yOffsets.size()) ? yOffsets[ch] : 0.0f;
float lineDist = static_cast<float>(model.header.startPosition + pos * model.header.distanceInc);
trace.position = QVector3D(xOff, lineDist - yOff, 0.0f);
model.traces.append(std::move(trace));
}
}
}
if (model.header.distanceInc > 1e-6) {
model.totalDistance = static_cast<float>(model.tracesPerChannel * model.header.distanceInc);
} else {
model.totalDistance = static_cast<float>(model.header.stopPosition - model.header.startPosition);
}
qDebug() << "Impulse multi-channel load OK. Total traces:" << model.traces.size()
<< "Channels:" << channelCount << "Traces/Channel:" << tracesPerChannel;
return !model.traces.isEmpty();
}
bool IprhParser::writeMalaFiles(const QString &radFilePath,
const QString &rd3FilePath,
const GPRDataModel &model,
const QString &sourceBaseName,
QString *errorMessage)
{
QFile rd3File(rd3FilePath);
if (!rd3File.open(QIODevice::WriteOnly | QIODevice::Truncate)) {
if (errorMessage) {
*errorMessage = QStringLiteral("无法写入转换后的 RD3 文件：%1").arg(rd3FilePath);
}
return false;
}
QDataStream out(&rd3File);
out.setByteOrder(QDataStream::LittleEndian);
const int samplesPerTrace = model.header.samplesPerTrace;
for (const RadarTrace &trace : model.traces) {
for (int s = 0; s < samplesPerTrace; ++s) {
const qint16 sample = static_cast<qint16>(s < trace.amplitudes.size() ? trace.amplitudes[s] : 0);
out << sample;
}
}
rd3File.close();
QFile radFile(radFilePath);
if (!radFile.open(QIODevice::WriteOnly | QIODevice::Text | QIODevice::Truncate)) {
if (errorMessage) {
*errorMessage = QStringLiteral("无法写入转换后的 RAD 文件：%1").arg(radFilePath);
}
QFile::remove(rd3FilePath);
return false;
}
QTextStream rad(&radFile);
rad << "# Converted from Impulse multi-channel survey: " << sourceBaseName << '\n';
rad << "SAMPLES: " << model.header.samplesPerTrace << '\n';
rad << "LAST TRACE: " << model.traces.size() << '\n';
rad << "TIMEWINDOW: " << QLocale::c().toString(model.header.timeWindowNs, 'g', 12) << '\n';
rad << "TIME INTERVAL: " << QLocale::c().toString(model.header.timeIntervalNs, 'g', 12) << '\n';
rad << "DISTANCE INTERVAL: " << QLocale::c().toString(model.header.distanceInc, 'g', 12) << '\n';
rad << "ANTENNAS: " << QLocale::c().toString(model.header.antennaFreq, 'g', 12) << '\n';
if (!model.header.antennaType.isEmpty()) rad << "ANTENNA: " << model.header.antennaType << '\n';
if (!model.header.date.isEmpty()) rad << "DATE: " << model.header.date << '\n';
if (!model.header.timeStr.isEmpty()) rad << "TIME: " << model.header.timeStr << '\n';
rad << "NUMBER_OF_CH: " << qMax(1, model.header.numberOfChannels) << '\n';
rad << "CH_X_OFFSETS: " << formatFloatList(model.header.chXOffsets) << '\n';
rad << "CH_Y_OFFSETS: " << formatFloatList(model.header.chYOffsets) << '\n';
if (!model.header.units.isEmpty()) rad << "UNITS: " << model.header.units << '\n';
rad << "START POSITION: " << QLocale::c().toString(model.header.startPosition, 'g', 12) << '\n';
const double stopPosition = model.header.stopPosition > model.header.startPosition
? model.header.stopPosition
: model.header.startPosition + model.tracesPerChannel * model.header.distanceInc;
rad << "STOP POSITION: " << QLocale::c().toString(stopPosition, 'g', 12) << '\n';
radFile.close();
return true;
}
QString IprhParser::formatFloatList(const QVector<float> &values)
{
QStringList parts;
parts.reserve(values.size());
for (float value : values) {
parts.append(QLocale::c().toString(value, 'g', 10));
}
return parts.join(' ');
}
QString IprhParser::uniqueConvertedBasePath(const QString &dirPath, const QString &baseName)
{
return QDir(dirPath).absoluteFilePath(baseName + QStringLiteral("_mala_converted"));
}
double IprhParser::extractDouble(const QString &value) {
bool ok = false;
double res = value.toDouble(&ok);
return ok ? res : 0.0;
}
int IprhParser::extractInt(const QString &value) {
bool ok = false;
int res = value.toInt(&ok);
return ok ? res : 0;
}

41
external/gpr3dviewer/IprhParser.h vendored Normal file
View File

@ -0,0 +1,41 @@
#ifndef IPRHPARSER_H
#define IPRHPARSER_H
#include "GPRDataModel.h"
#include <QString>
#include <QStringList>
class IprhParser {
public:
// 主入口：传入 .iprh 文件路径，自动寻找同名的 .iprb 文件
static bool loadFromIprh(const QString &iprhFilePath, GPRDataModel &model);
// 多通道 Impulse 数据合并入口：一个文件夹下有多个 _A01.iprh/.iprb ... _A14.iprh/.iprb
static bool loadImpulseMultiChannel(const QString &dirPath,
const QString &baseName,
GPRDataModel &model);
// 将多通道 Impulse 数据转换为本地 Mala Mira 风格 .rad/.rd3，再走现有 Mala Mira 解析流程
static bool convertImpulseMultiChannelToMala(const QString &dirPath,
const QString &baseName,
QString *radFilePath,
QString *errorMessage = nullptr);
static bool parseHeaderOnly(const QString &iprhFilePath, GPRDataModel::Header &header);
private:
static bool parseIprhHeader(const QString &iprhFilePath, GPRDataModel::Header &header);
static bool loadIprbBinary(const QString &iprbFilePath, GPRDataModel &model);
static bool writeMalaFiles(const QString &radFilePath,
const QString &rd3FilePath,
const GPRDataModel &model,
const QString &sourceBaseName,
QString *errorMessage);
static QString formatFloatList(const QVector<float> &values);
static QString uniqueConvertedBasePath(const QString &dirPath, const QString &baseName);
static double extractDouble(const QString &value);
static int extractInt(const QString &value);
};
#endif // IPRHPARSER_H

122
external/gpr3dviewer/PerformanceLogger.cpp vendored Normal file
View File

@ -0,0 +1,122 @@
#include "PerformanceLogger.h"
PerformanceLogger &PerformanceLogger::instance()
{
static PerformanceLogger logger;
return logger;
}
void PerformanceLogger::beginSession(const QString &sessionName)
{
QMutexLocker locker(&m_mutex);
m_sessionName = sessionName;
m_sessionActive = true;
}
void PerformanceLogger::endSession()
{
QMutexLocker locker(&m_mutex);
m_sessionActive = false;
}
void PerformanceLogger::log(const QString &category, const QString &name, qint64 elapsedMs)
{
QMutexLocker locker(&m_mutex);
Record rec;
rec.category = category;
rec.name = name;
rec.elapsedMs = elapsedMs;
rec.timestamp = QDateTime::currentDateTime();
m_records.append(rec);
}
QVector<PerformanceLogger::Record> PerformanceLogger::records() const
{
QMutexLocker locker(&m_mutex);
return m_records;
}
void PerformanceLogger::clear()
{
QMutexLocker locker(&m_mutex);
m_records.clear();
}
QString PerformanceLogger::reportString() const
{
QMutexLocker locker(&m_mutex);
QString report;
QTextStream ts(&report);
ts << "==================================================\n";
ts << "Performance Report";
if (!m_sessionName.isEmpty())
ts << " - " << m_sessionName;
ts << "\n";
ts << "Generated: " << QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss") << "\n";
ts << "==================================================\n";
if (m_records.isEmpty()) {
ts << "No records.\n";
return report;
}
// Group by category
QString currentCategory;
qint64 categoryTotal = 0;
for (const auto &rec : m_records) {
if (rec.category != currentCategory) {
if (!currentCategory.isEmpty()) {
ts << " [Category Total: " << categoryTotal << " ms]\n\n";
}
currentCategory = rec.category;
categoryTotal = 0;
ts << "[" << currentCategory << "]\n";
}
ts << " " << rec.name << ": " << rec.elapsedMs << " ms\n";
categoryTotal += rec.elapsedMs;
}
if (!currentCategory.isEmpty()) {
ts << " [Category Total: " << categoryTotal << " ms]\n";
}
ts << "\n==================================================\n";
ts << "Grand Total: ";
qint64 grandTotal = 0;
for (const auto &rec : m_records)
grandTotal += rec.elapsedMs;
ts << grandTotal << " ms\n";
ts << "==================================================\n";
return report;
}
void PerformanceLogger::printReport() const
{
const QString report = reportString();
qDebug().noquote() << report;
}
void PerformanceLogger::saveToFile(const QString &filePath) const
{
QFile file(filePath);
if (!file.open(QIODevice::WriteOnly | QIODevice::Text | QIODevice::Append)) {
qDebug() << "PerformanceLogger: failed to open" << filePath;
return;
}
QTextStream ts(&file);
ts << reportString();
file.close();
}
ScopedPerfTimer::ScopedPerfTimer(const QString &category, const QString &name)
: m_category(category), m_name(name)
{
m_timer.start();
}
ScopedPerfTimer::~ScopedPerfTimer()
{
const qint64 elapsed = m_timer.elapsed();
PerformanceLogger::instance().log(m_category, m_name, elapsed);
}

60
external/gpr3dviewer/PerformanceLogger.h vendored Normal file
View File

@ -0,0 +1,60 @@
#ifndef PERFORMANCELOGGER_H
#define PERFORMANCELOGGER_H
#include <QString>
#include <QElapsedTimer>
#include <QVector>
#include <QFile>
#include <QTextStream>
#include <QDateTime>
#include <QDebug>
#include <QMutex>
#include <memory>
class PerformanceLogger
{
public:
struct Record
{
QString category;
QString name;
qint64 elapsedMs = 0;
QDateTime timestamp;
};
static PerformanceLogger &instance();
void beginSession(const QString &sessionName = QString());
void endSession();
void log(const QString &category, const QString &name, qint64 elapsedMs);
void printReport() const;
void saveToFile(const QString &filePath) const;
QString reportString() const;
QVector<Record> records() const;
void clear();
private:
PerformanceLogger() = default;
mutable QMutex m_mutex;
QVector<Record> m_records;
QString m_sessionName;
bool m_sessionActive = false;
};
class ScopedPerfTimer
{
public:
ScopedPerfTimer(const QString &category, const QString &name);
~ScopedPerfTimer();
private:
QString m_category;
QString m_name;
QElapsedTimer m_timer;
};
#define SCOPED_PERF_TIMER(category, name) ScopedPerfTimer _perfTimer(category, name)
#endif // PERFORMANCELOGGER_H

73
external/gpr3dviewer/PosParser.cpp vendored Normal file
View File

@ -0,0 +1,73 @@
#include "PosParser.h"
#include <QFile>
#include <QTextStream>
#include <QDebug>
#include <QRegularExpression>
bool PosParser::loadPosFile(const QString &posFilePath, QVector<QVector3D> &outPositions) {
outPositions.clear();
QFile file(posFilePath);
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
qDebug() << "PosParser: Cannot open pos file:" << posFilePath;
return false;
}
QTextStream in(&file);
QRegularExpression reLineComment("^\\s*%");
while (!in.atEnd()) {
QString line = in.readLine().trimmed();
if (line.isEmpty()) continue;
if (reLineComment.match(line).hasMatch()) continue; // 跳过注释行
QStringList parts = line.split(QRegularExpression("\\s+"), Qt::SkipEmptyParts);
if (parts.size() < 4) continue;
bool okX = false, okY = false, okZ = false;
// 列顺序: 道号(忽略) X Y Z
double x = parts[1].toDouble(&okX);
double y = parts[2].toDouble(&okY);
double z = parts[3].toDouble(&okZ);
if (okX && okY && okZ) {
outPositions.append(QVector3D(static_cast<float>(x), static_cast<float>(y), static_cast<float>(z)));
}
}
file.close();
qDebug() << "PosParser: Loaded" << outPositions.size() << "GPS points from" << posFilePath;
return !outPositions.isEmpty();
}
bool PosParser::loadCenterCcc(const QString &cccFilePath, double &outLat, double &outLon) {
QFile file(cccFilePath);
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
qDebug() << "PosParser: Cannot open center.ccc:" << cccFilePath;
return false;
}
QTextStream in(&file);
QRegularExpression reLineComment("^\\s*%");
while (!in.atEnd()) {
QString line = in.readLine().trimmed();
if (line.isEmpty()) continue;
if (reLineComment.match(line).hasMatch()) continue;
QStringList parts = line.split(QRegularExpression("\\s+"), Qt::SkipEmptyParts);
if (parts.size() < 2) continue;
bool okLat = false, okLon = false;
outLat = parts[0].toDouble(&okLat);
outLon = parts[1].toDouble(&okLon);
if (okLat && okLon) {
file.close();
return true;
}
}
file.close();
return false;
}

17
external/gpr3dviewer/PosParser.h vendored Normal file
View File

@ -0,0 +1,17 @@
#ifndef POSPARSER_H
#define POSPARSER_H
#include <QString>
#include <QVector>
#include <QVector3D>
class PosParser {
public:
// 加载 .pos 文件（4列：道号 X Y Z）
static bool loadPosFile(const QString &posFilePath, QVector<QVector3D> &outPositions);
// 加载 center.ccc 项目中心坐标（2列：纬度 经度）
static bool loadCenterCcc(const QString &cccFilePath, double &outLat, double &outLon);
};
#endif // POSPARSER_H

1148
external/gpr3dviewer/RadarProcessor.cpp vendored Normal file
View File

File diff suppressed because it is too large Load Diff

346
external/gpr3dviewer/RadarProcessor.h vendored Normal file
View File

@ -0,0 +1,346 @@
/*
* RadarProcessor.h
* 探地雷达GPR数据预处理算法核心类头文件
* 功能：封装全套雷达道数据校正、滤波、增益、均衡、希尔伯特包络算法
* 架构：模块化单步骤参数结构体 + 流水线顺序调度执行
* 对接：MainWindow UI界面参数绑定、GPRDataModel三维道集数据模型
* 适配：RAD/RD3格式多通道、多测线原始雷达数据
*/
#ifndef RADARPROCESSOR_H
#define RADARPROCESSOR_H
#include "GPRDataModel.h"
#include <QVector>
#include <QString>
#include <functional>
class RadarProcessor
{
public:
/**
* @brief 所有可执行预处理步骤枚举标识
* 流水线严格按照枚举顺序业务逻辑排布
*/
enum class ProcStepType
{
StepTimeZeroCut, // 0：零时校正（切除直达波零点）
StepZeroDrift, // 1：道基线零漂消除
StepRemoveDC, // 2：简易整道直流偏移扣除
StepBackgroundRemove, // 3：剖面背景均值压制
StepSphericalTVG, // 4：球面扩散+介质吸收TVG深度增益
StepBandpassFilter, // 5：FIR带通滤波剔除高低频噪声
StepProfileSmooth, // 6：时空剖面平滑降噪
StepInnerAGC, // 7：单道内自适应振幅均衡AGC
StepTraceToTraceAGC, // 8：道与道之间整体振幅均衡
StepHilbertTransform, // 9：希尔伯特变换（包络/正交分量）
StepGlobalGain, // 10：全局统一倍率增益放大
StepMigration // 11：Kirchhoff偏移
};
//=========================================================================
// 1. 零时切除参数结构体 StepTimeZeroCut
// 作用：定位直达波起跳零点，裁掉零点前无效采样点，统一道起始位置
//=========================================================================
struct TimeZeroCutParams
{
bool autoDetect = true; // true=自动识别零点；false=手动固定裁掉前N个采样
int cutSamples = 30; // 手动模式裁切采样点数
int frontSearchWindow = 180; // 零点搜索窗口：只在道前180个采样内找起跳点
double noiseSigmaMultiple = 3.0; // 起跳判定阈值：噪声标准差倍数，大于判定为有效直达波
bool enable = false; // 流水线开关：是否启用本步骤
};
/**
* @brief 零漂消除模式枚举
*/
enum class ZeroDriftMode
{
DC, // 模式1：整道均值直流偏移一次性扣除（速度快）
Sliding // 模式2：滑动窗口逐段扣除基线（适合长时漂移严重数据）
};
struct ZeroDriftParams
{
ZeroDriftMode mode = ZeroDriftMode::Sliding;
int slidingWindowSamples = 100; // 滑动窗口采样点数，仅Sliding模式生效
bool enable = false;
};
//=========================================================================
// TVG球面深度增益 StepSphericalTVG
// 物理原理：电磁波随传播距离球面扩散衰减+介质吸收衰减
//=========================================================================
struct SphericalTvgParams {
bool enableSpherical = true; // 开启球面扩散补偿
bool enableAbsorption = true; // 开启介质吸收衰减补偿
double velocityMPerNs = 0.12; // 雷达波速(m/ns)，从GPRDataHeader自动读取
double referenceDepthM = 0.01; // 参考基准深度（增益归一化基准）
double exponent = 1.5; // 扩散指数：空气1.0、土体/混凝土常用1.0~2.0
double absorptionBeta = 1.0; // 吸收系数 β (dB/m)，干土小、湿土大
double maxGain = 30.0; // 最大增益上限，防止深层噪声过度放大
bool enable = false;
};
//=========================================================================
// 带通滤波 StepBandpassFilter
// 滤除天线主频外低频漂移、高频仪器白噪声
//=========================================================================
struct BandpassParams
{
bool autoFreq = true; // true自动根据天线主频计算通带；false手动填高低频
double lowFreqHz = 1000; // 通带下限(Hz)
double highFreqHz = 100; // 通带上限(Hz)
double antennaFreqMHz = 200.0; // 天线中心频率(MHz)，自动模式读取头文件
bool enable = false;
};
//=========================================================================
// 剖面二维平滑 StepProfileSmooth
// 垂直=深度方向平滑；水平=测线道方向平滑
//=========================================================================
struct ProfileSmoothParams
{
int smoothWindow = 2; // 半窗口大小，实际总窗口=2*window+1
bool verticalSmooth = true; // 深度方向平滑开关
bool horizontalSmooth = true; // 测线道方向平滑开关
bool enable = false;
};
//=========================================================================
// 背景去除 StepBackgroundRemove
// 压制整剖面静态杂波、地面耦合固定反射、钢筋/管线持续干扰
//=========================================================================
enum class BackgroundMode
{
MeanAverage, // 均值法：多道平均作为背景相减，通用稳定
SingularityFilter // 奇异值滤波：保留强异常，压制平缓背景（空洞/管线优选）
};
struct BackgroundParams
{
BackgroundMode mode = BackgroundMode::MeanAverage;
int averageTraceCount = 301; // 参与平均背景的同通道道数量
double singularityThreshold = 1.8; // 奇异判定阈值，越大越不容易抹掉小异常
bool enable = false;
};
//=========================================================================
// 道内AGC StepInnerAGC
// 同一道内深浅振幅均衡，消除天然深度衰减（TVG补充均衡）
//=========================================================================
struct TraceInnerAgcParams {
int windowSamples = 120; // 道内滑动RMS统计窗口
double targetRms = 0.0; // 目标RMS值；0=自适应均衡
double maxGain = 6.0; // 单窗口最大增益限制
double epsilon = 1.0; // 防除零极小值
bool enable = false;
};
//=========================================================================
// 道间AGC StepTraceToTraceAGC
// 整条测线所有道之间振幅拉平，消除收发耦合波动、行走速度不均
//=========================================================================
enum class TraceToTraceMode
{
Global, // 全局：全部道统一均衡基准
Local // 局部：滑动窗口相邻道均衡（起伏大路面优选）
};
struct TraceToTraceAgcParams {
TraceToTraceMode mode = TraceToTraceMode::Local;
int horizontalWindowTraces = 31; // 局部模式滑动道窗口
double targetRms = 0.0;
double maxGain = 4.0;
double epsilon = 1.0;
bool enable = false;
};
//=========================================================================
// 希尔伯特变换 StepHilbertTransform
// 输出振幅包络（成像常用）或正交虚部（相位分析）
//=========================================================================
struct HilbertParams
{
bool computeEnvelope = true; // true=振幅包络；false=正交相位分量
bool enable = false;
};
// 全局倍率增益
struct GlobalGainParams
{
double factor = 1.0; // 放大倍数，0.1~10区间常用
bool enable = false;
};
// 简易去直流（轻量零漂）
struct DcShiftParams
{
bool enable = false;
};
//=========================================================================
// Kirchhoff偏移参数
//=========================================================================
struct MigrationParams
{
int sumWidth = 64; // 两侧各求和的迹线数量
double velocityMPerNs = 0.12; // 雷达波速(m/ns)
bool enable = false;
};
//=========================================================================
// 流水线单步单元：存储步骤类型 + 全套独立参数
//=========================================================================
struct ProcStepUnit
{
ProcStepType type;
// 全部算法参数容器，运行时仅type对应的结构体生效
TimeZeroCutParams zeroCut;
SphericalTvgParams tvg;
BandpassParams band;
ProfileSmoothParams smooth;
BackgroundParams bg;
ZeroDriftParams zeroDrift;
TraceInnerAgcParams innerAgc;
TraceToTraceAgcParams traceAgc;
HilbertParams hilbert;
GlobalGainParams gain;
DcShiftParams dc;
MigrationParams migration;
};
//=========================================================================
// 完整预处理流水线：有序步骤队列 + 默认标准流程
//=========================================================================
struct ProcPipeline
{
QVector<ProcStepUnit> steps;
/**
* @brief 加载工业通用标准处理流水线（道路检测默认）
* 顺序：零时→零漂→背景→TVG增益→带通→平滑→内AGC→道间AGC→包络
*/
void setDefaultFlow()
{
steps.clear();
// 1. 零时校正
ProcStepUnit s0;
s0.type = ProcStepType::StepTimeZeroCut;
s0.zeroCut.autoDetect = true;
s0.zeroCut.cutSamples = 30;
s0.zeroCut.frontSearchWindow = 180;
s0.zeroCut.noiseSigmaMultiple = 3.0;
s0.zeroCut.enable = true;
steps.append(s0);
// 2. 零漂去除
ProcStepUnit s1;
s1.type = ProcStepType::StepZeroDrift;
s1.zeroDrift.mode = ZeroDriftMode::Sliding;
s1.zeroDrift.slidingWindowSamples = 100;
s1.zeroDrift.enable = true;
steps.append(s1);
// 3. 背景压制
ProcStepUnit s2;
s2.type = ProcStepType::StepBackgroundRemove;
s2.bg.mode = BackgroundMode::MeanAverage;
s2.bg.averageTraceCount = 301;
s2.bg.enable = true;
steps.append(s2);
// 4. TVG深度增益
ProcStepUnit s3;
s3.type = ProcStepType::StepSphericalTVG;
s3.tvg.enableSpherical = true;
s3.tvg.enableAbsorption = true;
s3.tvg.exponent = 1.0;
s3.tvg.maxGain = 20.0;
s3.tvg.absorptionBeta = 0.002;
s3.tvg.enable = true;
steps.append(s3);
// 5. 带通滤波
ProcStepUnit s4;
s4.type = ProcStepType::StepBandpassFilter;
s4.band.autoFreq = true;
s4.band.lowFreqHz = 100;
s4.band.highFreqHz = 1500;
s4.band.enable = true;
steps.append(s4);
// 6. 剖面平滑
ProcStepUnit s5;
s5.type = ProcStepType::StepProfileSmooth;
s5.smooth.smoothWindow = 2;
s5.smooth.verticalSmooth = true;
s5.smooth.horizontalSmooth = true;
s5.smooth.enable = true;
steps.append(s5);
// 7. 道内AGC
ProcStepUnit s6;
s6.type = ProcStepType::StepInnerAGC;
s6.innerAgc.windowSamples = 120;
s6.innerAgc.maxGain = 6.0;
s6.innerAgc.enable = true;
steps.append(s6);
// 8. 道间均衡AGC
ProcStepUnit s7;
s7.type = ProcStepType::StepTraceToTraceAGC;
s7.traceAgc.mode = TraceToTraceMode::Local;
s7.traceAgc.horizontalWindowTraces = 31;
s7.traceAgc.maxGain = 4.0;
s7.traceAgc.enable = true;
steps.append(s7);
}
};
public:
struct PipelineRuntimeContext {
std::function<bool()> isCanceled;
std::function<void(int stepIndex, int stepCount, const QString &stepName)> reportProgress;
};
RadarProcessor();
//==================== 单算法静态处理函数 ====================
/// 简易去除整道直流偏移
static GPRDataModel removeDCShift(const GPRDataModel &input, const DcShiftParams& param);
/// 零漂基线校正
static GPRDataModel removeZeroDrift(const GPRDataModel &input, const ZeroDriftParams& param);
/// 全局统一倍率增益
static GPRDataModel applyGain(const GPRDataModel &input, const GlobalGainParams& param);
/// TVG球面+吸收深度增益补偿
static GPRDataModel sphericalTvg(const GPRDataModel &input, const SphericalTvgParams &params);
/// 二维剖面均值平滑
static GPRDataModel profileSmooth(const GPRDataModel &input, const ProfileSmoothParams &params);
/// 道内滑动AGC均衡
static GPRDataModel traceInnerAgc(const GPRDataModel &input, const TraceInnerAgcParams &params);
/// 道与道之间振幅均衡
static GPRDataModel traceToTraceEqualization(const GPRDataModel &input, const TraceToTraceAgcParams &params);
/// 希尔伯特变换包络/相位
static GPRDataModel hilbertTransform(const GPRDataModel &input, const HilbertParams &params);
/// 零点自动/手动裁切算法实现
static GPRDataModel cutTimeZero(const GPRDataModel& input, const TimeZeroCutParams& param);
/// FIR带通滤波实现
static GPRDataModel bandpassFilter(const GPRDataModel &input, const BandpassParams &params);
/// 背景杂波去除实现（均值/奇异滤波双模式）
static GPRDataModel backgroundRemoval(const GPRDataModel &input, const BackgroundParams &params);
/// Kirchhoff偏移（x-t域双曲线求和）
static GPRDataModel kirchhoffMigration(const GPRDataModel &input, const MigrationParams &params);
/**
* @brief 流水线总执行入口
* @param rawData 原始未处理GPR三维道集数据
* @param pipeline 有序步骤流水线配置
* @return 逐步骤处理完成后的成品数据
*/
static GPRDataModel runPipeline(const GPRDataModel& rawData, const ProcPipeline& pipeline);
static GPRDataModel runPipeline(const GPRDataModel& rawData,
const ProcPipeline& pipeline,
const PipelineRuntimeContext *context);
};
#endif // RADARPROCESSOR_H

9
external/gpr3dviewer/RadarTypes.h vendored Normal file
View File

@ -0,0 +1,9 @@
#ifndef RADARTYPES_H
#define RADARTYPES_H
enum class RadarType {
Mala_Mira, // .rad + .rd3
Impulse // .iprh + .iprb
};
#endif // RADARTYPES_H

300
external/gpr3dviewer/Rd3Parser.cpp vendored Normal file
View File

@ -0,0 +1,300 @@
#include "Rd3Parser.h"
#include "PerformanceLogger.h"
#include <QFile>
#include <QTextStream>
#include <QDataStream>
#include <QDebug>
#include <QDir>
#include <QFileInfo>
#include <QRegularExpression>
#include <QStringList>
#include <QVector3D>
/**
* @brief 加载整套Mala Mira系列雷达RD3数据（rad头文件 + rd3纯二进制波形）
* @param radFilePath .rad文本配置头文件路径
* @param model 输出GPR全局数据模型
* @return true 加载解析成功；false 失败
* @note 存储结构：.rad存储全部仪器/测线参数；.rd3无文件头，从头到尾全是short16振幅采样
*/
bool Rd3Parser::loadFromRad(const QString &radFilePath, GPRDataModel &model) {
SCOPED_PERF_TIMER("Parser", "Rd3Parser::loadFromRad");
// 清空旧数据与头部信息
model.clear();
model.header = GPRDataModel::Header{};
// 第一步：解析rad文本头，填充全部采集参数
if (!parseRadHeader(radFilePath, model.header)) {
qDebug() << "Error: Failed to parse .rad header file:" << radFilePath;
return false;
}
// 自动匹配同目录同名二进制数据文件 .rd3
QFileInfo radInfo(radFilePath);
QString binaryPath = radInfo.absolutePath() + "/" + radInfo.completeBaseName() + ".rd3";
if (!QFile::exists(binaryPath)) {
qDebug() << "Error: Matching binary file not found at:" << binaryPath;
return false;
}
// 推算后仍无有效道数则失败
if (model.header.numTraces <= 0) {
qDebug() << "Error: Unable to determine numTraces from header";
return false;
}
// 第二步：读取无头部的纯二进制波形
return loadRd3Binary(binaryPath, model);
}
/**
* @brief 解析RAD文本头文件，提取雷达采集关键参数存入Header结构体
* @param radFilePath rad文本文件路径
* @param header 待填充头部参数结构体
* @return 解析成功返回true
*/
bool Rd3Parser::parseRadHeader(const QString &radFilePath, GPRDataModel::Header &header) {
SCOPED_PERF_TIMER("Parser", "Rd3Parser::parseRadHeader");
QFile file(radFilePath);
// 只读文本模式打开
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
qDebug() << "Error: Cannot open rad file for read";
return false;
}
QTextStream in(&file);
// 逐行读取键值对 KEY: VALUE 或 KEY=VALUE
while (!in.atEnd()) {
QString line = in.readLine().trimmed();
if (line.isEmpty()) continue;
int sepPos = line.indexOf(':');
if (sepPos == -1) sepPos = line.indexOf('=');
if (sepPos == -1) continue;
QString key = line.left(sepPos).trimmed();
QString value = line.mid(sepPos + 1).trimmed();
// 原始字符串参数全存入map备用
header.rawParams[key] = value;
// 识别核心业务参数并类型转换赋值
if (key == "SAMPLES") {
header.samplesPerTrace = extractInt(value);
} else if (key == "LAST TRACE") {
header.numTraces = extractInt(value);
} else if (key == "TIMEWINDOW") {
header.timeWindowNs = extractDouble(value);
} else if (key == "DISTANCE INTERVAL") {
header.distanceInc = extractDouble(value);
} else if (key == "ANTENNAS") {
header.antennaFreq = extractDouble(value);
} else if (key == "ANTENNAS") {
header.antennaType = value;
} else if (key == "DATE") {
header.date = value;
} else if (key == "TIME") {
header.timeStr = value;
} else if (key == "NUMBER_OF_CH") {
header.numberOfChannels = extractInt(value);
} else if (key == "CH_X_OFFSETS") {
// 多通道天线水平X偏移量
QStringList offsets = value.split(' ', Qt::SkipEmptyParts);
for (const QString &offset : offsets) {
header.chXOffsets.append(offset.toFloat());
}
} else if (key == "CH_Y_OFFSETS") {
// 多通道天线行进Y偏移量
QStringList offsets = value.split(' ', Qt::SkipEmptyParts);
for (const QString &offset : offsets) {
header.chYOffsets.append(offset.toFloat());
}
} else if (key == "UNITS") {
header.units = value;
} else if (key == "START POSITION") {
header.startPosition = extractDouble(value);
} else if (key == "STOP POSITION") {
header.stopPosition = extractDouble(value);
} else if (key == "TIME INTERVAL") {
header.timeIntervalNs = extractDouble(value);
}
}
file.close();
// 基础合法性校验：单道采样数必须大于0；总道数允许从二进制文件推算
if (header.samplesPerTrace <= 0) {
qDebug() << "Error: Invalid SAMPLES value in rad file";
return false;
}
// 设置地层电磁波默认速度 0.1 m/ns（空气近似值，后续界面可手动修改）
header.waveVelocity = 0.1;
qDebug() << "==== RAD Header Parse Complete ===="
<< "\nSamples per trace:" << header.samplesPerTrace
<< "\nTotal traces:" << header.numTraces
<< "\nTime window(ns):" << header.timeWindowNs
<< "\nChannel count:" << header.numberOfChannels
<< "\nX offset array size:" << header.chXOffsets.size()
<< "\nY offset array size:" << header.chYOffsets.size();
return true;
}
/**
* @brief 读取纯RD3二进制数据（无任何文件头，全连续short16振幅）
* @param rd3FilePath rd3波形文件路径
* @param model 绑定头部参数，填充完整traces波形数组
* @return 读取成功true
* @detail 存储格式：
* 道0采样0,道0采样1...道0采样N | 道1采样0...道1采样N | ...循环所有通道所有道
* 数据类型：小端序 short 16位有符号整型
*/
bool Rd3Parser::loadRd3Binary(const QString &rd3FilePath, GPRDataModel &model) {
SCOPED_PERF_TIMER("Parser", "Rd3Parser::loadRd3Binary");
QFile file(rd3FilePath);
if (!file.open(QIODevice::ReadOnly)) {
qDebug() << "Error: Open rd3 binary failed:" << rd3FilePath;
return false;
}
const int samplesPerTrace = model.header.samplesPerTrace;
const int totalTraceCount = model.header.numTraces;
// ========== 关键修正：rd3无头部偏移，直接从文件0位置开始读波形 ==========
const qint64 dataStartOffset = 0;
file.seek(dataStartOffset);
// 理论完整字节大小校验
const qint64 singleTraceByteSize = samplesPerTrace * sizeof(short);
const qint64 fullExpectedBytes = totalTraceCount * singleTraceByteSize;
const qint64 realFileBytes = file.size();
if (realFileBytes < fullExpectedBytes) {
qDebug() << "Warning: RD3 file size smaller than theoretical data size!"
<< "Expected:" << fullExpectedBytes << "Actual:" << realFileBytes;
}
// 预分配内存容器，减少动态扩容开销
model.traces.reserve(totalTraceCount);
// 单道读取缓冲区
QByteArray traceBuffer;
traceBuffer.resize(singleTraceByteSize);
// 通道数量兜底
const int channelCnt = model.header.numberOfChannels > 0 ? model.header.numberOfChannels : 1;
model.channels = channelCnt;
// 每通道独立道数量
model.tracesPerChannel = totalTraceCount / channelCnt;
// 计算整条测线总行进距离
if (model.header.distanceInc > 1e-6) {
model.totalDistance = static_cast<float>(model.tracesPerChannel * model.header.distanceInc);
} else {
model.totalDistance = static_cast<float>(model.header.stopPosition - model.header.startPosition);
}
// 循环逐道读取二进制波形
for (int traceGlobalIdx = 0; traceGlobalIdx < totalTraceCount; ++traceGlobalIdx) {
if (file.atEnd()) {
qDebug() << "Warning: File ended early at global trace index" << traceGlobalIdx;
break;
}
// 读取一整道所有采样字节
qint64 readBytes = file.read(traceBuffer.data(), traceBuffer.size());
if (readBytes != traceBuffer.size()) {
qDebug() << "Warning: Trace" << traceGlobalIdx << "incomplete byte read";
break;
}
RadarTrace oneTrace;
oneTrace.amplitudes.resize(samplesPerTrace);
// 二进制指针强转short（Windows平台原生小端序，雷达标准字节序）
const short* rawShortBuf = reinterpret_cast<const short*>(traceBuffer.constData());
// 填充单道振幅值
for (int s = 0; s < samplesPerTrace; s++) {
oneTrace.amplitudes[s] = rawShortBuf[s];
}
// 分配所属通道、通道内道序号
int chNo = traceGlobalIdx % channelCnt;
int traceInChIdx = traceGlobalIdx / channelCnt;
oneTrace.channelNumber = chNo;
// 计算空间三维坐标 X(天线横向偏移) Y(行进里程) Z=0地面平面
float xOff = 0.0f;
float yOff = 0.0f;
if (chNo < model.header.chXOffsets.size()) xOff = model.header.chXOffsets[chNo];
if (chNo < model.header.chYOffsets.size()) yOff = model.header.chYOffsets[chNo];
float lineDist = static_cast<float>(model.header.startPosition + traceInChIdx * model.header.distanceInc);
oneTrace.position = QVector3D(xOff, lineDist - yOff, 0.0f);
model.traces.append(std::move(oneTrace));
}
file.close();
if (model.traces.isEmpty()) {
qDebug() << "Error: No valid traces loaded from rd3";
return false;
}
qDebug() << "RD3 Binary Load OK, total valid traces:" << model.traces.size();
return true;
}
/**
* @brief 安全字符串转double数值，优先提取字符串开头的数字，转换失败返回0
* @param value 原始字符串（如：200 MHz shielded）
* @return 浮点结果
*/
double Rd3Parser::extractDouble(const QString& value) {
bool ok = false;
double res = 0.0;
// 1. 遍历字符串，截取开头连续的数字/小数点部分
int numLength = 0;
while (numLength < value.length()) {
QChar ch = value.at(numLength);
// 只保留 数字 和 小数点（支持小数，如 200.5 MHz）
if (ch.isDigit() || ch == '.') {
numLength++;
}
else {
// 遇到非数字/小数点，停止截取
break;
}
}
// 2. 截取有效数字字符串并转换
if (numLength > 0) {
QString numStr = value.left(numLength);
res = numStr.toDouble(&ok);
}
// 3. 转换成功返回数值，失败返回0.0
return ok ? res : 0.0;
}
/**
* @brief 安全字符串转int整型，转换失败返回0
* @param value 原始rad文件字符串数值
* @return 整型结果
*/
int Rd3Parser::extractInt(const QString &value) {
bool ok = false;
int res = value.toInt(&ok);
return ok ? res : 0;
}

21
external/gpr3dviewer/Rd3Parser.h vendored Normal file
View File

@ -0,0 +1,21 @@
#ifndef RD3PARSER_H
#define RD3PARSER_H
#include "GPRDataModel.h"
#include <QString>
class Rd3Parser {
public:
// 主入口：传入 .rad 文件路径，它会自动寻找同名的 .rd3 文件
static bool loadFromRad(const QString &radFilePath, GPRDataModel &model);
private:
static bool parseRadHeader(const QString &radFilePath, GPRDataModel::Header &header);
static bool loadRd3Binary(const QString &rd3FilePath, GPRDataModel &model);
// 辅助：从 .rad 的字符串中提取数值
static double extractDouble(const QString &value);
static int extractInt(const QString &value);
};
#endif // RD3PARSER_H

127
external/gpr3dviewer/SurveyGeometry.h vendored Normal file
View File

@ -0,0 +1,127 @@
#ifndef SURVEYGEOMETRY_H
#define SURVEYGEOMETRY_H
#include <QJsonArray>
#include <QJsonObject>
#include <QVector>
struct SurveyGeometry {
double rtkOffsetX = 0.0; // RTK相对天线中心的设备x轴偏移（m），头文件无对应字段，保留给用户输入
double rtkOffsetY = 0.0; // RTK相对天线中心的设备y轴偏移（m），来自CH_Y_OFFSETS
double ch1XRel = 0.0; // 第1通道相对天线中心的x坐标（m），由CH_X_OFFSETS首尾值推导
QVector<double> channelXRel; // 各通道相对天线中心的x坐标（m），来自CH_X_OFFSETS归一到天线中心
int channelCount = 1; // 通道总数，来自NUMBER_OF_CH
int cgcsZone = 0; // CGCS2000 3度带带号，0表示自动检测
double centralMeridianDeg = 0.0; // 中央经线（度），自动推导
bool operator==(const SurveyGeometry &other) const {
return rtkOffsetX == other.rtkOffsetX &&
rtkOffsetY == other.rtkOffsetY &&
ch1XRel == other.ch1XRel &&
channelXRel == other.channelXRel &&
channelCount == other.channelCount &&
cgcsZone == other.cgcsZone &&
centralMeridianDeg == other.centralMeridianDeg;
}
void applyHeaderOffsets(int numberOfChannels,
const QVector<float> &chXOffsets,
const QVector<float> &chYOffsets)
{
const int offsetChannelCount = qMax(chXOffsets.size(), chYOffsets.size());
channelCount = qMax(1, numberOfChannels > 0 ? numberOfChannels : offsetChannelCount);
rtkOffsetY = chYOffsets.isEmpty() ? 0.0 : static_cast<double>(chYOffsets.first());
channelXRel.clear();
channelXRel.reserve(channelCount);
if (chXOffsets.size() >= 2) {
const double centerX = (static_cast<double>(chXOffsets.first()) + chXOffsets.last()) / 2.0;
for (int i = 0; i < chXOffsets.size() && i < channelCount; ++i) {
channelXRel.append(static_cast<double>(chXOffsets[i]) - centerX);
}
ch1XRel = channelXRel.isEmpty() ? 0.0 : channelXRel.first();
} else {
ch1XRel = 0.0;
}
if (channelXRel.size() < channelCount) {
const int existing = channelXRel.size();
channelXRel.resize(channelCount);
if (existing == 0) {
for (int c = 0; c < channelCount; ++c) {
channelXRel[c] = 0.0;
}
} else if (channelCount > 1) {
const double lastXRel = -ch1XRel;
for (int c = existing; c < channelCount; ++c) {
channelXRel[c] = ch1XRel + (lastXRel - ch1XRel) * c / (channelCount - 1.0);
}
}
}
}
static SurveyGeometry fromHeaderOffsets(int numberOfChannels,
const QVector<float> &chXOffsets,
const QVector<float> &chYOffsets)
{
SurveyGeometry g;
g.applyHeaderOffsets(numberOfChannels, chXOffsets, chYOffsets);
return g;
}
QJsonObject toJson() const {
QJsonObject obj;
obj["rtkOffsetX"] = rtkOffsetX;
obj["rtkOffsetY"] = rtkOffsetY;
obj["ch1XRel"] = ch1XRel;
QJsonArray channelXRelArray;
for (double x : channelXRel) {
channelXRelArray.append(x);
}
obj["channelXRel"] = channelXRelArray;
obj["channelCount"] = channelCount;
obj["cgcsZone"] = cgcsZone;
obj["centralMeridianDeg"] = centralMeridianDeg;
return obj;
}
static SurveyGeometry fromJson(const QJsonObject &obj) {
SurveyGeometry g;
g.rtkOffsetX = obj.value("rtkOffsetX").toDouble(0.0);
g.rtkOffsetY = obj.value("rtkOffsetY").toDouble(0.0);
g.ch1XRel = obj.value("ch1XRel").toDouble(0.0);
g.channelCount = qMax(1, obj.value("channelCount").toInt(1));
g.cgcsZone = obj.value("cgcsZone").toInt(0);
g.centralMeridianDeg = obj.value("centralMeridianDeg").toDouble(0.0);
const QJsonArray channelXRelArray = obj.value("channelXRel").toArray();
for (const QJsonValue &value : channelXRelArray) {
g.channelXRel.append(value.toDouble(0.0));
}
if (g.channelXRel.isEmpty() && obj.contains("ch16XRel")) {
const double legacyLastXRel = obj.value("ch16XRel").toDouble(-g.ch1XRel);
g.channelXRel.resize(g.channelCount);
for (int c = 0; c < g.channelCount; ++c) {
g.channelXRel[c] = (g.channelCount > 1)
? g.ch1XRel + (legacyLastXRel - g.ch1XRel) * c / (g.channelCount - 1.0)
: g.ch1XRel;
}
} else if (g.channelXRel.isEmpty()) {
g.channelXRel.resize(g.channelCount);
const double lastXRel = -g.ch1XRel;
for (int c = 0; c < g.channelCount; ++c) {
g.channelXRel[c] = (g.channelCount > 1)
? g.ch1XRel + (lastXRel - g.ch1XRel) * c / (g.channelCount - 1.0)
: g.ch1XRel;
}
} else if (g.channelXRel.size() != g.channelCount) {
g.channelCount = qMax(1, g.channelXRel.size());
}
return g;
}
};
#endif // SURVEYGEOMETRY_H

242
external/gpr3dviewer/TrajectoryCalculator.cpp vendored Normal file
View File

@ -0,0 +1,242 @@
#include "TrajectoryCalculator.h"
#include <algorithm>
#include <cmath>
namespace {
double planarDistance(const QVector3D &a, const QVector3D &b)
{
const double dx = static_cast<double>(a.x()) - b.x();
const double dy = static_cast<double>(a.y()) - b.y();
return std::sqrt(dx * dx + dy * dy);
}
QVector3D lerpPoint(const QVector3D &a, const QVector3D &b, double t)
{
return a * static_cast<float>(1.0 - t) + b * static_cast<float>(t);
}
QVector3D catmullRom(const QVector3D &p0, const QVector3D &p1, const QVector3D &p2, const QVector3D &p3, double t)
{
const float tf = static_cast<float>(t);
const float t2 = tf * tf;
const float t3 = t2 * tf;
return 0.5f * ((2.0f * p1) + (-p0 + p2) * tf + (2.0f * p0 - 5.0f * p1 + 4.0f * p2 - p3) * t2 +
(-p0 + 3.0f * p1 - 3.0f * p2 + p3) * t3);
}
} // namespace
double TrajectoryCalculator::headingAt(int traceIdx, const QVector<QVector3D> &gpsPositions)
{
const int n = gpsPositions.size();
if (n <= 1) return 0.0;
if (traceIdx < n - 1) {
double deltaX = gpsPositions[traceIdx + 1].x() - gpsPositions[traceIdx].x(); // 北向变化
double deltaY = gpsPositions[traceIdx + 1].y() - gpsPositions[traceIdx].y(); // 东向变化
return std::atan2(deltaY, deltaX);
} else {
// 最后一点复用前一点方向
double deltaX = gpsPositions[traceIdx].x() - gpsPositions[traceIdx - 1].x();
double deltaY = gpsPositions[traceIdx].y() - gpsPositions[traceIdx - 1].y();
return std::atan2(deltaY, deltaX);
}
}
bool TrajectoryCalculator::computeTrajectories(SurveyLine &line, const SurveyGeometry &geom)
{
const QVector<QVector3D> &gps = line.gpsPositions;
const int nRtk = gps.size();
if (nRtk <= 0) return false;
const int chCount = geom.channelCount;
if (chCount <= 0) return false;
// 通道相对x偏移优先使用头文件CH_X_OFFSETS推导出的逐通道数组；旧工程无数组时按首通道对称补齐。
QVector<double> chXRel = geom.channelXRel;
if (chXRel.size() != chCount) {
chXRel.resize(chCount);
const double lastXRel = -geom.ch1XRel;
for (int c = 0; c < chCount; ++c) {
chXRel[c] = (chCount > 1)
? geom.ch1XRel + (lastXRel - geom.ch1XRel) * c / (chCount - 1.0)
: geom.ch1XRel;
}
}
// 预分配 channelTrajectories
line.channelTrajectories.resize(chCount);
for (int c = 0; c < chCount; ++c) {
line.channelTrajectories[c].resize(nRtk);
}
// 遍历每个 RTK 点
for (int i = 0; i < nRtk; ++i) {
double thetaY = headingAt(i, gps);
double thetaX = thetaY + M_PI / 2.0;
// 旋转矩阵 R = [cos(theta_x), cos(theta_y); sin(theta_x), sin(theta_y)]
// 作用：将设备相对坐标系（x=右, y=前）转换为绝对坐标系（X=北, Y=东）
double r11 = std::cos(thetaX);
double r12 = std::cos(thetaY);
double r21 = std::sin(thetaX);
double r22 = std::sin(thetaY);
// RTK 相对天线中心的偏移向量（设备坐标系）
double rtkLocalX = geom.rtkOffsetX; // 横向偏移
double rtkLocalY = geom.rtkOffsetY; // 纵向偏移（前方为正）
// 转换为绝对坐标系偏移
double rtkAbsOffsetX = r11 * rtkLocalX + r12 * rtkLocalY;
double rtkAbsOffsetY = r21 * rtkLocalX + r22 * rtkLocalY;
// 天线中心绝对坐标 = RTK - 偏移量
double antX = gps[i].x() - rtkAbsOffsetX;
double antY = gps[i].y() - rtkAbsOffsetY;
double antZ = gps[i].z();
// 遍历每个通道
for (int c = 0; c < chCount; ++c) {
// 通道相对坐标（设备坐标系）
double chLocalX = chXRel[c];
double chLocalY = 0.0; // MATLAB 中 ch_y_rel = zeros(...)
// 转换为绝对坐标系偏移
double chAbsOffsetX = r11 * chLocalX + r12 * chLocalY;
double chAbsOffsetY = r21 * chLocalX + r22 * chLocalY;
// 通道绝对坐标
double chX = antX + chAbsOffsetX;
double chY = antY + chAbsOffsetY;
double chZ = antZ;
line.channelTrajectories[c][i] = QVector3D(static_cast<float>(chX),
static_cast<float>(chY),
static_cast<float>(chZ));
}
}
// 同步更新 GPRDataModel 中 traces 的 position
// 数据存储顺序：trace0_ch0, trace0_ch1, ... trace0_chN, trace1_ch0, ...
// 即 globalIdx = traceInChannel * chCount + channel
const int tracesPerChannel = line.data.getTracesPerChannel();
for (int c = 0; c < chCount; ++c) {
for (int t = 0; t < tracesPerChannel && t < nRtk; ++t) {
int globalIdx = t * chCount + c;
if (globalIdx >= 0 && globalIdx < line.data.traces.size()) {
line.data.traces[globalIdx].position = line.channelTrajectories[c][t];
}
}
}
return true;
}
QVector<QVector3D> TrajectoryCalculator::resampleTrajectoryLinear(const QVector<QVector3D> &input, int targetCount)
{
QVector<QVector3D> output;
if (targetCount <= 0 || input.isEmpty()) return output;
if (input.size() == 1 || targetCount == 1) {
output.resize(targetCount);
std::fill(output.begin(), output.end(), input.first());
return output;
}
output.reserve(targetCount);
const double scale = static_cast<double>(input.size() - 1) / qMax(1, targetCount - 1);
for (int i = 0; i < targetCount; ++i) {
const double src = i * scale;
const int i0 = qBound(0, static_cast<int>(std::floor(src)), input.size() - 1);
const int i1 = qBound(0, i0 + 1, input.size() - 1);
output.append(lerpPoint(input[i0], input[i1], src - i0));
}
return output;
}
QVector<QVector3D> TrajectoryCalculator::resampleTrajectorySpline(const QVector<QVector3D> &input, int targetCount)
{
if (input.size() < 4) return resampleTrajectoryLinear(input, targetCount);
QVector<QVector3D> output;
if (targetCount <= 0) return output;
if (targetCount == 1) return QVector<QVector3D>{input.first()};
output.reserve(targetCount);
const double scale = static_cast<double>(input.size() - 1) / qMax(1, targetCount - 1);
for (int i = 0; i < targetCount; ++i) {
const double src = i * scale;
const int i1 = qBound(0, static_cast<int>(std::floor(src)), input.size() - 1);
const int i2 = qBound(0, i1 + 1, input.size() - 1);
const int i0 = qBound(0, i1 - 1, input.size() - 1);
const int i3 = qBound(0, i2 + 1, input.size() - 1);
output.append(catmullRom(input[i0], input[i1], input[i2], input[i3], src - i1));
}
return output;
}
TrajectoryFilterResult TrajectoryCalculator::filterAndInterpolateTrajectory(const QVector<QVector3D> &input,
const TrajectoryFilterOptions &options,
int targetCount)
{
TrajectoryFilterResult result;
const int n = input.size();
result.keepMask = QVector<bool>(n, true);
result.distanceOutlierMask = QVector<bool>(n, false);
result.speedOutlierMask = QVector<bool>(n, false);
result.angleOutlierMask = QVector<bool>(n, false);
if (n <= 0 || targetCount <= 0) return result;
for (int i = 1; i < n; ++i) {
const double dist = planarDistance(input[i - 1], input[i]);
if (options.distanceFilterEnabled && dist > options.maxSegmentDistanceM) {
result.distanceOutlierMask[i] = true;
result.keepMask[i] = false;
}
if (options.speedFilterEnabled && options.traceIntervalSec > 1e-9 && dist / options.traceIntervalSec > options.maxSpeedMps) {
result.speedOutlierMask[i] = true;
result.keepMask[i] = false;
}
}
if (options.angleFilterEnabled) {
const double thresholdRad = options.maxTurnAngleDeg * M_PI / 180.0;
for (int i = 1; i + 1 < n; ++i) {
const double d0 = planarDistance(input[i - 1], input[i]);
const double d1 = planarDistance(input[i], input[i + 1]);
if (d0 < 1e-6 || d1 < 1e-6) continue;
const double ax = input[i].x() - input[i - 1].x();
const double ay = input[i].y() - input[i - 1].y();
const double bx = input[i + 1].x() - input[i].x();
const double by = input[i + 1].y() - input[i].y();
const double cosv = std::clamp((ax * bx + ay * by) / (d0 * d1), -1.0, 1.0);
const double turn = std::acos(cosv);
if (turn > thresholdRad) {
result.angleOutlierMask[i] = true;
result.keepMask[i] = false;
}
}
}
if (options.preserveEndpoints && n > 0) {
result.keepMask[0] = true;
result.keepMask[n - 1] = true;
}
QVector<QVector3D> kept;
kept.reserve(n);
for (int i = 0; i < n; ++i) {
if (result.keepMask.value(i, true)) kept.append(input[i]);
}
if (kept.size() < 2) {
kept = input;
result.warnings.append(QStringLiteral("过滤后有效轨迹点过少，已使用原始轨迹插值。"));
}
if (options.interpolationMode == TrajectoryFilterOptions::InterpolationMode::Spline) {
if (kept.size() < 4) result.warnings.append(QStringLiteral("样条插值点数不足，已回退到线性插值。"));
result.outputPositions = resampleTrajectorySpline(kept, targetCount);
} else {
result.outputPositions = resampleTrajectoryLinear(kept, targetCount);
}
return result;
}

49
external/gpr3dviewer/TrajectoryCalculator.h vendored Normal file
View File

@ -0,0 +1,49 @@
#ifndef TRAJECTORYCALCULATOR_H
#define TRAJECTORYCALCULATOR_H
#include "GPRDataModel.h"
#include "SurveyGeometry.h"
#include <QVector3D>
#include <QStringList>
struct TrajectoryFilterOptions {
bool distanceFilterEnabled = true;
double maxSegmentDistanceM = 1.0;
bool speedFilterEnabled = false;
double maxSpeedMps = 60.0;
double traceIntervalSec = 0.05;
bool angleFilterEnabled = true;
double maxTurnAngleDeg = 60.0;
enum class InterpolationMode { Linear, Spline };
InterpolationMode interpolationMode = InterpolationMode::Linear;
bool preserveEndpoints = true;
bool preserveManualEdits = true;
};
struct TrajectoryFilterResult {
QVector<QVector3D> outputPositions;
QVector<bool> keepMask;
QVector<bool> distanceOutlierMask;
QVector<bool> speedOutlierMask;
QVector<bool> angleOutlierMask;
QStringList warnings;
};
class TrajectoryCalculator {
public:
// 计算第 traceIdx 个 RTK 点的行进方向角（弧度）
// 返回 theta_y = atan2(dY, dX)，其中 X=北向, Y=东向
static double headingAt(int traceIdx, const QVector<QVector3D> &gpsPositions);
// 根据 RTK 轨迹和天线几何参数，计算所有通道的绝对坐标
// 结果写入 line.channelTrajectories 和 line.data.traces[].position
static bool computeTrajectories(SurveyLine &line, const SurveyGeometry &geom);
static QVector<QVector3D> resampleTrajectoryLinear(const QVector<QVector3D> &input, int targetCount);
static QVector<QVector3D> resampleTrajectorySpline(const QVector<QVector3D> &input, int targetCount);
static TrajectoryFilterResult filterAndInterpolateTrajectory(const QVector<QVector3D> &input,
const TrajectoryFilterOptions &options,
int targetCount);
};
#endif // TRAJECTORYCALCULATOR_H

189
external/gpr3dviewer/third_party/kissfft/_kiss_fft_guts.h vendored Normal file
View File

@ -0,0 +1,189 @@
/*
* Copyright (c) 2003-2010, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
/* kiss_fft.h
defines kiss_fft_scalar as either short or a float type
and defines
typedef struct { kiss_fft_scalar r; kiss_fft_scalar i; }kiss_fft_cpx; */
#ifndef _kiss_fft_guts_h
#define _kiss_fft_guts_h
#include "kiss_fft.h"
#include "kiss_fft_log.h"
#include <limits.h>
#define MAXFACTORS 32
/* e.g. an fft of length 128 has 4 factors
as far as kissfft is concerned
4*4*4*2
*/
struct kiss_fft_state{
int nfft;
int inverse;
int factors[2*MAXFACTORS];
kiss_fft_cpx twiddles[1];
};
/*
Explanation of macros dealing with complex math:
C_MUL(m,a,b) : m = a*b
C_FIXDIV( c , div ) : if a fixed point impl., c /= div. noop otherwise
C_SUB( res, a,b) : res = a - b
C_SUBFROM( res , a) : res -= a
C_ADDTO( res , a) : res += a
* */
#ifdef FIXED_POINT
#include <stdint.h>
#if (FIXED_POINT==32)
# define FRACBITS 31
# define SAMPPROD int64_t
#define SAMP_MAX INT32_MAX
#define SAMP_MIN INT32_MIN
#else
# define FRACBITS 15
# define SAMPPROD int32_t
#define SAMP_MAX INT16_MAX
#define SAMP_MIN INT16_MIN
#endif
#if defined(CHECK_OVERFLOW)
# define CHECK_OVERFLOW_OP(a,op,b) \
if ( (SAMPPROD)(a) op (SAMPPROD)(b) > SAMP_MAX || (SAMPPROD)(a) op (SAMPPROD)(b) < SAMP_MIN ) { \
KISS_FFT_WARNING("overflow (%d " #op" %d) = %ld", (a),(b),(SAMPPROD)(a) op (SAMPPROD)(b)); }
#endif
# define smul(a,b) ( (SAMPPROD)(a)*(b) )
# define sround( x ) (kiss_fft_scalar)( ( (x) + (1<<(FRACBITS-1)) ) >> FRACBITS )
# define S_MUL(a,b) sround( smul(a,b) )
# define C_MUL(m,a,b) \
do{ (m).r = sround( smul((a).r,(b).r) - smul((a).i,(b).i) ); \
(m).i = sround( smul((a).r,(b).i) + smul((a).i,(b).r) ); }while(0)
# define DIVSCALAR(x,k) \
(x) = sround( smul( x, SAMP_MAX/k ) )
# define C_FIXDIV(c,div) \
do { DIVSCALAR( (c).r , div); \
DIVSCALAR( (c).i , div); }while (0)
# define C_MULBYSCALAR( c, s ) \
do{ (c).r = sround( smul( (c).r , s ) ) ;\
(c).i = sround( smul( (c).i , s ) ) ; }while(0)
#else /* not FIXED_POINT*/
# define S_MUL(a,b) ( (a)*(b) )
#define C_MUL(m,a,b) \
do{ (m).r = (a).r*(b).r - (a).i*(b).i;\
(m).i = (a).r*(b).i + (a).i*(b).r; }while(0)
# define C_FIXDIV(c,div) /* NOOP */
# define C_MULBYSCALAR( c, s ) \
do{ (c).r *= (s);\
(c).i *= (s); }while(0)
#endif
#ifndef CHECK_OVERFLOW_OP
# define CHECK_OVERFLOW_OP(a,op,b) /* noop */
#endif
#define C_ADD( res, a,b)\
do { \
CHECK_OVERFLOW_OP((a).r,+,(b).r)\
CHECK_OVERFLOW_OP((a).i,+,(b).i)\
(res).r=(a).r+(b).r; (res).i=(a).i+(b).i; \
}while(0)
#define C_SUB( res, a,b)\
do { \
CHECK_OVERFLOW_OP((a).r,-,(b).r)\
CHECK_OVERFLOW_OP((a).i,-,(b).i)\
(res).r=(a).r-(b).r; (res).i=(a).i-(b).i; \
}while(0)
#define C_ADDTO( res , a)\
do { \
CHECK_OVERFLOW_OP((res).r,+,(a).r)\
CHECK_OVERFLOW_OP((res).i,+,(a).i)\
(res).r += (a).r; (res).i += (a).i;\
}while(0)
#define C_SUBFROM( res , a)\
do {\
CHECK_OVERFLOW_OP((res).r,-,(a).r)\
CHECK_OVERFLOW_OP((res).i,-,(a).i)\
(res).r -= (a).r; (res).i -= (a).i; \
}while(0)
#ifdef FIXED_POINT
# define KISS_FFT_COS(phase) floor(.5+SAMP_MAX * cos (phase))
# define KISS_FFT_SIN(phase) floor(.5+SAMP_MAX * sin (phase))
# define HALF_OF(x) ((x)>>1)
#elif defined(USE_SIMD)
#if defined(HAVE_LASX)
#define KISS_FFT_COS(phase) ({ \
float __cos_val = cosf(phase); \
(__m256)(__lasx_xvldrepl_w(&__cos_val, 0)); \
})
#define KISS_FFT_SIN(phase) ({ \
float __sin_val = sinf(phase); \
(__m256)(__lasx_xvldrepl_w(&__sin_val, 0)); \
})
#define HALF_OF(x) ((x) * (__m256)(__lasx_xvreplgr2vr_w(0x3F000000))) // 0.5f
#elif defined(HAVE_LSX)
#define KISS_FFT_COS(phase) ({ \
float __cos_val = cosf(phase); \
(__m128)(__lsx_vldrepl_w(&__cos_val, 0)); \
})
#define KISS_FFT_SIN(phase) ({ \
float __sin_val = sinf(phase); \
(__m128)(__lsx_vldrepl_w(&__sin_val, 0)); \
})
#define HALF_OF(x) ((x) * (__m128)(__lsx_vreplgr2vr_w(0x3F000000))) // 0.5f
#else
# define KISS_FFT_COS(phase) _mm_set1_ps( cos(phase) )
# define KISS_FFT_SIN(phase) _mm_set1_ps( sin(phase) )
# define HALF_OF(x) ((x)*_mm_set1_ps(.5))
#endif
#else
# define KISS_FFT_COS(phase) (kiss_fft_scalar) cos(phase)
# define KISS_FFT_SIN(phase) (kiss_fft_scalar) sin(phase)
# define HALF_OF(x) ((x)*((kiss_fft_scalar).5))
#endif
#define kf_cexp(x,phase) \
do{ \
(x)->r = KISS_FFT_COS(phase);\
(x)->i = KISS_FFT_SIN(phase);\
}while(0)
/* a debugging function */
#define pcpx(c)\
KISS_FFT_DEBUG("%g + %gi\n",(double)((c)->r),(double)((c)->i))
#ifdef KISS_FFT_USE_ALLOCA
// define this to allow use of alloca instead of malloc for temporary buffers
// Temporary buffers are used in two case:
// 1. FFT sizes that have "bad" factors. i.e. not 2,3 and 5
// 2. "in-place" FFTs. Notice the quotes, since kissfft does not really do an in-place transform.
#include <alloca.h>
#define KISS_FFT_TMP_ALLOC(nbytes) alloca(nbytes)
#define KISS_FFT_TMP_FREE(ptr)
#else
#define KISS_FFT_TMP_ALLOC(nbytes) KISS_FFT_MALLOC(nbytes)
#define KISS_FFT_TMP_FREE(ptr) KISS_FFT_FREE(ptr)
#endif
#endif /* _kiss_fft_guts_h */

424
external/gpr3dviewer/third_party/kissfft/kiss_fft.c vendored Normal file
View File

@ -0,0 +1,424 @@
/*
* Copyright (c) 2003-2010, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
#include <stdint.h>
#include "_kiss_fft_guts.h"
/* The guts header contains all the multiplication and addition macros that are defined for
fixed or floating point complex numbers. It also delares the kf_ internal functions.
*/
static void kf_bfly2(
kiss_fft_cpx * Fout,
const size_t fstride,
const kiss_fft_cfg st,
int m
)
{
kiss_fft_cpx * Fout2;
kiss_fft_cpx * tw1 = st->twiddles;
kiss_fft_cpx t;
Fout2 = Fout + m;
do{
C_FIXDIV(*Fout,2); C_FIXDIV(*Fout2,2);
C_MUL (t, *Fout2 , *tw1);
tw1 += fstride;
C_SUB( *Fout2 , *Fout , t );
C_ADDTO( *Fout , t );
++Fout2;
++Fout;
}while (--m);
}
static void kf_bfly4(
kiss_fft_cpx * Fout,
const size_t fstride,
const kiss_fft_cfg st,
const size_t m
)
{
kiss_fft_cpx *tw1,*tw2,*tw3;
kiss_fft_cpx scratch[6];
size_t k=m;
const size_t m2=2*m;
const size_t m3=3*m;
tw3 = tw2 = tw1 = st->twiddles;
do {
C_FIXDIV(*Fout,4); C_FIXDIV(Fout[m],4); C_FIXDIV(Fout[m2],4); C_FIXDIV(Fout[m3],4);
C_MUL(scratch[0],Fout[m] , *tw1 );
C_MUL(scratch[1],Fout[m2] , *tw2 );
C_MUL(scratch[2],Fout[m3] , *tw3 );
C_SUB( scratch[5] , *Fout, scratch[1] );
C_ADDTO(*Fout, scratch[1]);
C_ADD( scratch[3] , scratch[0] , scratch[2] );
C_SUB( scratch[4] , scratch[0] , scratch[2] );
C_SUB( Fout[m2], *Fout, scratch[3] );
tw1 += fstride;
tw2 += fstride*2;
tw3 += fstride*3;
C_ADDTO( *Fout , scratch[3] );
if(st->inverse) {
Fout[m].r = scratch[5].r - scratch[4].i;
Fout[m].i = scratch[5].i + scratch[4].r;
Fout[m3].r = scratch[5].r + scratch[4].i;
Fout[m3].i = scratch[5].i - scratch[4].r;
}else{
Fout[m].r = scratch[5].r + scratch[4].i;
Fout[m].i = scratch[5].i - scratch[4].r;
Fout[m3].r = scratch[5].r - scratch[4].i;
Fout[m3].i = scratch[5].i + scratch[4].r;
}
++Fout;
}while(--k);
}
static void kf_bfly3(
kiss_fft_cpx * Fout,
const size_t fstride,
const kiss_fft_cfg st,
size_t m
)
{
size_t k=m;
const size_t m2 = 2*m;
kiss_fft_cpx *tw1,*tw2;
kiss_fft_cpx scratch[5];
kiss_fft_cpx epi3;
epi3 = st->twiddles[fstride*m];
tw1=tw2=st->twiddles;
do{
C_FIXDIV(*Fout,3); C_FIXDIV(Fout[m],3); C_FIXDIV(Fout[m2],3);
C_MUL(scratch[1],Fout[m] , *tw1);
C_MUL(scratch[2],Fout[m2] , *tw2);
C_ADD(scratch[3],scratch[1],scratch[2]);
C_SUB(scratch[0],scratch[1],scratch[2]);
tw1 += fstride;
tw2 += fstride*2;
Fout[m].r = Fout->r - HALF_OF(scratch[3].r);
Fout[m].i = Fout->i - HALF_OF(scratch[3].i);
C_MULBYSCALAR( scratch[0] , epi3.i );
C_ADDTO(*Fout,scratch[3]);
Fout[m2].r = Fout[m].r + scratch[0].i;
Fout[m2].i = Fout[m].i - scratch[0].r;
Fout[m].r -= scratch[0].i;
Fout[m].i += scratch[0].r;
++Fout;
}while(--k);
}
static void kf_bfly5(
kiss_fft_cpx * Fout,
const size_t fstride,
const kiss_fft_cfg st,
int m
)
{
kiss_fft_cpx *Fout0,*Fout1,*Fout2,*Fout3,*Fout4;
int u;
kiss_fft_cpx scratch[13];
kiss_fft_cpx * twiddles = st->twiddles;
kiss_fft_cpx *tw;
kiss_fft_cpx ya,yb;
ya = twiddles[fstride*m];
yb = twiddles[fstride*2*m];
Fout0=Fout;
Fout1=Fout0+m;
Fout2=Fout0+2*m;
Fout3=Fout0+3*m;
Fout4=Fout0+4*m;
tw=st->twiddles;
for ( u=0; u<m; ++u ) {
C_FIXDIV( *Fout0,5); C_FIXDIV( *Fout1,5); C_FIXDIV( *Fout2,5); C_FIXDIV( *Fout3,5); C_FIXDIV( *Fout4,5);
scratch[0] = *Fout0;
C_MUL(scratch[1] ,*Fout1, tw[u*fstride]);
C_MUL(scratch[2] ,*Fout2, tw[2*u*fstride]);
C_MUL(scratch[3] ,*Fout3, tw[3*u*fstride]);
C_MUL(scratch[4] ,*Fout4, tw[4*u*fstride]);
C_ADD( scratch[7],scratch[1],scratch[4]);
C_SUB( scratch[10],scratch[1],scratch[4]);
C_ADD( scratch[8],scratch[2],scratch[3]);
C_SUB( scratch[9],scratch[2],scratch[3]);
Fout0->r += scratch[7].r + scratch[8].r;
Fout0->i += scratch[7].i + scratch[8].i;
scratch[5].r = scratch[0].r + S_MUL(scratch[7].r,ya.r) + S_MUL(scratch[8].r,yb.r);
scratch[5].i = scratch[0].i + S_MUL(scratch[7].i,ya.r) + S_MUL(scratch[8].i,yb.r);
scratch[6].r = S_MUL(scratch[10].i,ya.i) + S_MUL(scratch[9].i,yb.i);
scratch[6].i = -S_MUL(scratch[10].r,ya.i) - S_MUL(scratch[9].r,yb.i);
C_SUB(*Fout1,scratch[5],scratch[6]);
C_ADD(*Fout4,scratch[5],scratch[6]);
scratch[11].r = scratch[0].r + S_MUL(scratch[7].r,yb.r) + S_MUL(scratch[8].r,ya.r);
scratch[11].i = scratch[0].i + S_MUL(scratch[7].i,yb.r) + S_MUL(scratch[8].i,ya.r);
scratch[12].r = - S_MUL(scratch[10].i,yb.i) + S_MUL(scratch[9].i,ya.i);
scratch[12].i = S_MUL(scratch[10].r,yb.i) - S_MUL(scratch[9].r,ya.i);
C_ADD(*Fout2,scratch[11],scratch[12]);
C_SUB(*Fout3,scratch[11],scratch[12]);
++Fout0;++Fout1;++Fout2;++Fout3;++Fout4;
}
}
/* perform the butterfly for one stage of a mixed radix FFT */
static void kf_bfly_generic(
kiss_fft_cpx * Fout,
const size_t fstride,
const kiss_fft_cfg st,
int m,
int p
)
{
int u,k,q1,q;
kiss_fft_cpx * twiddles = st->twiddles;
kiss_fft_cpx t;
int Norig = st->nfft;
kiss_fft_cpx * scratch = (kiss_fft_cpx*)KISS_FFT_TMP_ALLOC(sizeof(kiss_fft_cpx)*p);
if (scratch == NULL){
KISS_FFT_ERROR("Memory allocation failed.");
return;
}
for ( u=0; u<m; ++u ) {
k=u;
for ( q1=0 ; q1<p ; ++q1 ) {
scratch[q1] = Fout[ k ];
C_FIXDIV(scratch[q1],p);
k += m;
}
k=u;
for ( q1=0 ; q1<p ; ++q1 ) {
int twidx=0;
Fout[ k ] = scratch[0];
for (q=1;q<p;++q ) {
twidx += fstride * k;
if (twidx>=Norig) twidx-=Norig;
C_MUL(t,scratch[q] , twiddles[twidx] );
C_ADDTO( Fout[ k ] ,t);
}
k += m;
}
}
KISS_FFT_TMP_FREE(scratch);
}
static
void kf_work(
kiss_fft_cpx * Fout,
const kiss_fft_cpx * f,
const size_t fstride,
int in_stride,
int * factors,
const kiss_fft_cfg st
)
{
kiss_fft_cpx * Fout_beg=Fout;
const int p=*factors++; /* the radix */
const int m=*factors++; /* stage's fft length/p */
const kiss_fft_cpx * Fout_end = Fout + p*m;
#ifdef _OPENMP
// use openmp extensions at the
// top-level (not recursive)
if (fstride==1 && p<=5 && m!=1)
{
int k;
// execute the p different work units in different threads
# pragma omp parallel for
for (k=0;k<p;++k)
kf_work( Fout +k*m, f+ fstride*in_stride*k,fstride*p,in_stride,factors,st);
// all threads have joined by this point
switch (p) {
case 2: kf_bfly2(Fout,fstride,st,m); break;
case 3: kf_bfly3(Fout,fstride,st,m); break;
case 4: kf_bfly4(Fout,fstride,st,m); break;
case 5: kf_bfly5(Fout,fstride,st,m); break;
default: kf_bfly_generic(Fout,fstride,st,m,p); break;
}
return;
}
#endif
if (m==1) {
do{
*Fout = *f;
f += fstride*in_stride;
}while(++Fout != Fout_end );
}else{
do{
// recursive call:
// DFT of size m*p performed by doing
// p instances of smaller DFTs of size m,
// each one takes a decimated version of the input
kf_work( Fout , f, fstride*p, in_stride, factors,st);
f += fstride*in_stride;
}while( (Fout += m) != Fout_end );
}
Fout=Fout_beg;
// recombine the p smaller DFTs
switch (p) {
case 2: kf_bfly2(Fout,fstride,st,m); break;
case 3: kf_bfly3(Fout,fstride,st,m); break;
case 4: kf_bfly4(Fout,fstride,st,m); break;
case 5: kf_bfly5(Fout,fstride,st,m); break;
default: kf_bfly_generic(Fout,fstride,st,m,p); break;
}
}
/* facbuf is populated by p1,m1,p2,m2, ...
where
p[i] * m[i] = m[i-1]
m0 = n */
static
void kf_factor(int n,int * facbuf)
{
int p=4;
double floor_sqrt;
floor_sqrt = floor( sqrt((double)n) );
/*factor out powers of 4, powers of 2, then any remaining primes */
do {
while (n % p) {
switch (p) {
case 4: p = 2; break;
case 2: p = 3; break;
default: p += 2; break;
}
if (p > floor_sqrt)
p = n; /* no more factors, skip to end */
}
n /= p;
*facbuf++ = p;
*facbuf++ = n;
} while (n > 1);
}
/*
*
* User-callable function to allocate all necessary storage space for the fft.
*
* The return value is a contiguous block of memory, allocated with malloc. As such,
* It can be freed with free(), rather than a kiss_fft-specific function.
* */
kiss_fft_cfg kiss_fft_alloc(int nfft,int inverse_fft,void * mem,size_t * lenmem )
{
KISS_FFT_ALIGN_CHECK(mem)
kiss_fft_cfg st=NULL;
// check for overflow condition {memneeded > SIZE_MAX}.
if (nfft >= (SIZE_MAX - 2*sizeof(struct kiss_fft_state))/sizeof(kiss_fft_cpx))
return NULL;
size_t memneeded = KISS_FFT_ALIGN_SIZE_UP(sizeof(struct kiss_fft_state)
+ sizeof(kiss_fft_cpx)*(nfft-1)); /* twiddle factors*/
if ( lenmem==NULL ) {
st = ( kiss_fft_cfg)KISS_FFT_MALLOC( memneeded );
}else{
if (mem != NULL && *lenmem >= memneeded)
st = (kiss_fft_cfg)mem;
*lenmem = memneeded;
}
if (st) {
int i;
st->nfft=nfft;
st->inverse = inverse_fft;
for (i=0;i<nfft;++i) {
const double pi=3.141592653589793238462643383279502884197169399375105820974944;
double phase = -2*pi*i / nfft;
if (st->inverse)
phase *= -1;
kf_cexp(st->twiddles+i, phase );
}
kf_factor(nfft,st->factors);
}
return st;
}
void kiss_fft_stride(kiss_fft_cfg st,const kiss_fft_cpx *fin,kiss_fft_cpx *fout,int in_stride)
{
if (fin == fout) {
//NOTE: this is not really an in-place FFT algorithm.
//It just performs an out-of-place FFT into a temp buffer
if (fout == NULL){
KISS_FFT_ERROR("fout buffer NULL.");
return;
}
kiss_fft_cpx * tmpbuf = (kiss_fft_cpx*)KISS_FFT_TMP_ALLOC( sizeof(kiss_fft_cpx)*st->nfft);
if (tmpbuf == NULL){
KISS_FFT_ERROR("Memory allocation error.");
return;
}
kf_work(tmpbuf,fin,1,in_stride, st->factors,st);
memcpy(fout,tmpbuf,sizeof(kiss_fft_cpx)*st->nfft);
KISS_FFT_TMP_FREE(tmpbuf);
}else{
kf_work( fout, fin, 1,in_stride, st->factors,st );
}
}
void kiss_fft(kiss_fft_cfg cfg,const kiss_fft_cpx *fin,kiss_fft_cpx *fout)
{
kiss_fft_stride(cfg,fin,fout,1);
}
void kiss_fft_cleanup(void)
{
// nothing needed any more
}
int kiss_fft_next_fast_size(int n)
{
while(1) {
int m=n;
while ( (m%2) == 0 ) m/=2;
while ( (m%3) == 0 ) m/=3;
while ( (m%5) == 0 ) m/=5;
if (m<=1)
break; /* n is completely factorable by twos, threes, and fives */
n++;
}
return n;
}

184
external/gpr3dviewer/third_party/kissfft/kiss_fft.h vendored Normal file
View File

@ -0,0 +1,184 @@
/*
* Copyright (c) 2003-2010, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
#ifndef KISS_FFT_H
#define KISS_FFT_H
#include <stdlib.h>
#include <stdio.h>
#include <math.h>
#include <string.h>
// Define KISS_FFT_SHARED macro to properly export symbols
#ifdef KISS_FFT_SHARED
# ifdef _WIN32
# ifdef KISS_FFT_BUILD
# define KISS_FFT_API __declspec(dllexport)
# else
# define KISS_FFT_API __declspec(dllimport)
# endif
# else
# define KISS_FFT_API __attribute__ ((visibility ("default")))
# endif
#else
# define KISS_FFT_API
#endif
#ifdef __cplusplus
extern "C" {
#endif
/*
ATTENTION!
If you would like a :
-- a utility that will handle the caching of fft objects
-- real-only (no imaginary time component ) FFT
-- a multi-dimensional FFT
-- a command-line utility to perform ffts
-- a command-line utility to perform fast-convolution filtering
Then see kfc.h kiss_fftr.h kiss_fftnd.h fftutil.c kiss_fastfir.c
in the tools/ directory.
*/
/* User may override KISS_FFT_MALLOC and/or KISS_FFT_FREE. */
#ifdef USE_SIMD
#ifdef HAVE_LASX
# include <lasxintrin.h>
# define kiss_fft_scalar __m256
# ifndef KISS_FFT_MALLOC
# define KISS_FFT_MALLOC(nbytes) aligned_alloc(32, KISS_FFT_ALIGN_SIZE_UP(nbytes))
# define KISS_FFT_ALIGN_CHECK(ptr)
# define KISS_FFT_ALIGN_SIZE_UP(size) ((size + 31UL) & ~0x1FUL)
# endif
# ifndef KISS_FFT_FREE
# define KISS_FFT_FREE free
# endif
#elif defined(HAVE_LSX)
# include <lsxintrin.h>
# define kiss_fft_scalar __m128
# ifndef KISS_FFT_MALLOC
# define KISS_FFT_MALLOC(nbytes) aligned_alloc(16, KISS_FFT_ALIGN_SIZE_UP(nbytes))
# define KISS_FFT_ALIGN_CHECK(ptr)
# define KISS_FFT_ALIGN_SIZE_UP(size) ((size + 15UL) & ~0xFUL)
# endif
# ifndef KISS_FFT_FREE
# define KISS_FFT_FREE free
# endif
#else
# include <xmmintrin.h>
# define kiss_fft_scalar __m128
# ifndef KISS_FFT_MALLOC
# define KISS_FFT_MALLOC(nbytes) _mm_malloc(nbytes,16)
# define KISS_FFT_ALIGN_CHECK(ptr)
# define KISS_FFT_ALIGN_SIZE_UP(size) ((size + 15UL) & ~0xFUL)
# endif
# ifndef KISS_FFT_FREE
# define KISS_FFT_FREE _mm_free
# endif
#endif
#else
# define KISS_FFT_ALIGN_CHECK(ptr)
# define KISS_FFT_ALIGN_SIZE_UP(size) (size)
# ifndef KISS_FFT_MALLOC
# define KISS_FFT_MALLOC malloc
# endif
# ifndef KISS_FFT_FREE
# define KISS_FFT_FREE free
# endif
#endif
#ifdef FIXED_POINT
#include <stdint.h>
# if (FIXED_POINT == 32)
# define kiss_fft_scalar int32_t
# else
# define kiss_fft_scalar int16_t
# endif
#else
# ifndef kiss_fft_scalar
/* default is float */
# define kiss_fft_scalar float
# endif
#endif
typedef struct {
kiss_fft_scalar r;
kiss_fft_scalar i;
}kiss_fft_cpx;
typedef struct kiss_fft_state* kiss_fft_cfg;
/*
* kiss_fft_alloc
*
* Initialize a FFT (or IFFT) algorithm's cfg/state buffer.
*
* typical usage: kiss_fft_cfg mycfg=kiss_fft_alloc(1024,0,NULL,NULL);
*
* The return value from fft_alloc is a cfg buffer used internally
* by the fft routine or NULL.
*
* If lenmem is NULL, then kiss_fft_alloc will allocate a cfg buffer using malloc.
* The returned value should be free()d when done to avoid memory leaks.
*
* The state can be placed in a user supplied buffer 'mem':
* If lenmem is not NULL and mem is not NULL and *lenmem is large enough,
* then the function places the cfg in mem and the size used in *lenmem
* and returns mem.
*
* If lenmem is not NULL and ( mem is NULL or *lenmem is not large enough),
* then the function returns NULL and places the minimum cfg
* buffer size in *lenmem.
* */
kiss_fft_cfg KISS_FFT_API kiss_fft_alloc(int nfft,int inverse_fft,void * mem,size_t * lenmem);
/*
* kiss_fft(cfg,in_out_buf)
*
* Perform an FFT on a complex input buffer.
* for a forward FFT,
* fin should be f[0] , f[1] , ... ,f[nfft-1]
* fout will be F[0] , F[1] , ... ,F[nfft-1]
* Note that each element is complex and can be accessed like
f[k].r and f[k].i
* */
void KISS_FFT_API kiss_fft(kiss_fft_cfg cfg,const kiss_fft_cpx *fin,kiss_fft_cpx *fout);
/*
A more generic version of the above function. It reads its input from every Nth sample.
* */
void KISS_FFT_API kiss_fft_stride(kiss_fft_cfg cfg,const kiss_fft_cpx *fin,kiss_fft_cpx *fout,int fin_stride);
/* If kiss_fft_alloc allocated a buffer, it is one contiguous
buffer and can be simply free()d when no longer needed*/
#define kiss_fft_free KISS_FFT_FREE
/*
Cleans up some memory that gets managed internally. Not necessary to call, but it might clean up
your compiler output to call this before you exit.
*/
void KISS_FFT_API kiss_fft_cleanup(void);
/*
* Returns the smallest integer k, such that k>=n and k has only "fast" factors (2,3,5)
*/
int KISS_FFT_API kiss_fft_next_fast_size(int n);
/* for real ffts, we need an even size */
#define kiss_fftr_next_fast_size_real(n) \
(kiss_fft_next_fast_size( ((n)+1)>>1)<<1)
#ifdef __cplusplus
}
#endif
#endif

36
external/gpr3dviewer/third_party/kissfft/kiss_fft_log.h vendored Normal file
View File

@ -0,0 +1,36 @@
/*
* Copyright (c) 2003-2010, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
#ifndef kiss_fft_log_h
#define kiss_fft_log_h
#define ERROR 1
#define WARNING 2
#define INFO 3
#define DEBUG 4
#define STRINGIFY(x) #x
#define TOSTRING(x) STRINGIFY(x)
#if defined(NDEBUG)
# define KISS_FFT_LOG_MSG(severity, ...) ((void)0)
#else
# define KISS_FFT_LOG_MSG(severity, ...) \
fprintf(stderr, "[" #severity "] " __FILE__ ":" TOSTRING(__LINE__) " "); \
fprintf(stderr, __VA_ARGS__); \
fprintf(stderr, "\n")
#endif
#define KISS_FFT_ERROR(...) KISS_FFT_LOG_MSG(ERROR, __VA_ARGS__)
#define KISS_FFT_WARNING(...) KISS_FFT_LOG_MSG(WARNING, __VA_ARGS__)
#define KISS_FFT_INFO(...) KISS_FFT_LOG_MSG(INFO, __VA_ARGS__)
#define KISS_FFT_DEBUG(...) KISS_FFT_LOG_MSG(DEBUG, __VA_ARGS__)
#endif /* kiss_fft_log_h */

171
external/gpr3dviewer/third_party/kissfft/kiss_fftr.c vendored Normal file
View File

@ -0,0 +1,171 @@
/*
* Copyright (c) 2003-2004, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
#include "kiss_fftr.h"
#include "_kiss_fft_guts.h"
struct kiss_fftr_state{
kiss_fft_cfg substate;
kiss_fft_cpx * tmpbuf;
kiss_fft_cpx * super_twiddles;
#ifdef USE_SIMD
void * pad;
#endif
};
kiss_fftr_cfg kiss_fftr_alloc(int nfft,int inverse_fft,void * mem,size_t * lenmem)
{
KISS_FFT_ALIGN_CHECK(mem)
int i;
kiss_fftr_cfg st = NULL;
size_t subsize = 0, memneeded;
if (nfft & 1) {
KISS_FFT_ERROR("Real FFT optimization must be even.");
return NULL;
}
nfft >>= 1;
kiss_fft_alloc (nfft, inverse_fft, NULL, &subsize);
memneeded = sizeof(struct kiss_fftr_state) + subsize + sizeof(kiss_fft_cpx) * ( nfft * 3 / 2);
if (lenmem == NULL) {
st = (kiss_fftr_cfg) KISS_FFT_MALLOC (memneeded);
} else {
if (*lenmem >= memneeded)
st = (kiss_fftr_cfg) mem;
*lenmem = memneeded;
}
if (!st)
return NULL;
st->substate = (kiss_fft_cfg) (st + 1); /*just beyond kiss_fftr_state struct */
st->tmpbuf = (kiss_fft_cpx *) (((char *) st->substate) + subsize);
st->super_twiddles = st->tmpbuf + nfft;
kiss_fft_alloc(nfft, inverse_fft, st->substate, &subsize);
for (i = 0; i < nfft/2; ++i) {
double phase =
-3.14159265358979323846264338327 * ((double) (i+1) / nfft + .5);
if (inverse_fft)
phase *= -1;
kf_cexp (st->super_twiddles+i,phase);
}
return st;
}
void kiss_fftr(kiss_fftr_cfg st,const kiss_fft_scalar *timedata,kiss_fft_cpx *freqdata)
{
/* input buffer timedata is stored row-wise */
int k,ncfft;
kiss_fft_cpx fpnk,fpk,f1k,f2k,tw,tdc;
if ( st->substate->inverse) {
KISS_FFT_ERROR("kiss fft usage error: improper alloc");
return;/* The caller did not call the correct function */
}
ncfft = st->substate->nfft;
/*perform the parallel fft of two real signals packed in real,imag*/
kiss_fft( st->substate , (const kiss_fft_cpx*)timedata, st->tmpbuf );
/* The real part of the DC element of the frequency spectrum in st->tmpbuf
* contains the sum of the even-numbered elements of the input time sequence
* The imag part is the sum of the odd-numbered elements
*
* The sum of tdc.r and tdc.i is the sum of the input time sequence.
* yielding DC of input time sequence
* The difference of tdc.r - tdc.i is the sum of the input (dot product) [1,-1,1,-1...
* yielding Nyquist bin of input time sequence
*/
tdc.r = st->tmpbuf[0].r;
tdc.i = st->tmpbuf[0].i;
C_FIXDIV(tdc,2);
CHECK_OVERFLOW_OP(tdc.r ,+, tdc.i);
CHECK_OVERFLOW_OP(tdc.r ,-, tdc.i);
freqdata[0].r = tdc.r + tdc.i;
freqdata[ncfft].r = tdc.r - tdc.i;
#ifdef USE_SIMD
#ifdef HAVE_LASX
freqdata[0].i = (__m256)(__lasx_xvreplgr2vr_w(0));
freqdata[ncfft].i = freqdata[0].i;
#elif defined(HAVE_LSX)
freqdata[0].i = (__m128)(__lsx_vreplgr2vr_w(0));
freqdata[ncfft].i = freqdata[0].i;
#else
freqdata[ncfft].i = freqdata[0].i = _mm_set1_ps(0);
#endif
#else
freqdata[ncfft].i = freqdata[0].i = 0;
#endif
for ( k=1;k <= ncfft/2 ; ++k ) {
fpk = st->tmpbuf[k];
fpnk.r = st->tmpbuf[ncfft-k].r;
fpnk.i = - st->tmpbuf[ncfft-k].i;
C_FIXDIV(fpk,2);
C_FIXDIV(fpnk,2);
C_ADD( f1k, fpk , fpnk );
C_SUB( f2k, fpk , fpnk );
C_MUL( tw , f2k , st->super_twiddles[k-1]);
freqdata[k].r = HALF_OF(f1k.r + tw.r);
freqdata[k].i = HALF_OF(f1k.i + tw.i);
freqdata[ncfft-k].r = HALF_OF(f1k.r - tw.r);
freqdata[ncfft-k].i = HALF_OF(tw.i - f1k.i);
}
}
void kiss_fftri(kiss_fftr_cfg st,const kiss_fft_cpx *freqdata,kiss_fft_scalar *timedata)
{
/* input buffer timedata is stored row-wise */
int k, ncfft;
if (st->substate->inverse == 0) {
KISS_FFT_ERROR("kiss fft usage error: improper alloc");
return;/* The caller did not call the correct function */
}
ncfft = st->substate->nfft;
st->tmpbuf[0].r = freqdata[0].r + freqdata[ncfft].r;
st->tmpbuf[0].i = freqdata[0].r - freqdata[ncfft].r;
C_FIXDIV(st->tmpbuf[0],2);
for (k = 1; k <= ncfft / 2; ++k) {
kiss_fft_cpx fk, fnkc, fek, fok, tmp;
fk = freqdata[k];
fnkc.r = freqdata[ncfft - k].r;
fnkc.i = -freqdata[ncfft - k].i;
C_FIXDIV( fk , 2 );
C_FIXDIV( fnkc , 2 );
C_ADD (fek, fk, fnkc);
C_SUB (tmp, fk, fnkc);
C_MUL (fok, tmp, st->super_twiddles[k-1]);
C_ADD (st->tmpbuf[k], fek, fok);
C_SUB (st->tmpbuf[ncfft - k], fek, fok);
#ifdef USE_SIMD
#ifdef HAVE_LASX
__m256 neg_one = (__m256)__lasx_xvreplgr2vr_w(0xBF800000); // -1.0f
st->tmpbuf[ncfft - k].i = __lasx_xvfmul_s(st->tmpbuf[ncfft - k].i, neg_one);
#elif defined(HAVE_LSX)
__m128 neg_one = (__m128)__lsx_vreplgr2vr_w(0xBF800000); // -1.0f
st->tmpbuf[ncfft - k].i = __lsx_vfmul_s(st->tmpbuf[ncfft - k].i, neg_one);
#else
st->tmpbuf[ncfft - k].i *= _mm_set1_ps(-1.0);
#endif
#else
st->tmpbuf[ncfft - k].i *= -1;
#endif
}
kiss_fft (st->substate, st->tmpbuf, (kiss_fft_cpx *) timedata);
}

54
external/gpr3dviewer/third_party/kissfft/kiss_fftr.h vendored Normal file
View File

@ -0,0 +1,54 @@
/*
* Copyright (c) 2003-2004, Mark Borgerding. All rights reserved.
* This file is part of KISS FFT - https://github.com/mborgerding/kissfft
*
* SPDX-License-Identifier: BSD-3-Clause
* See COPYING file for more information.
*/
#ifndef KISS_FTR_H
#define KISS_FTR_H
#include "kiss_fft.h"
#ifdef __cplusplus
extern "C" {
#endif
/*
Real optimized version can save about 45% cpu time vs. complex fft of a real seq.
*/
typedef struct kiss_fftr_state *kiss_fftr_cfg;
kiss_fftr_cfg KISS_FFT_API kiss_fftr_alloc(int nfft,int inverse_fft,void * mem, size_t * lenmem);
/*
nfft must be even
If you don't care to allocate space, use mem = lenmem = NULL
*/
void KISS_FFT_API kiss_fftr(kiss_fftr_cfg cfg,const kiss_fft_scalar *timedata,kiss_fft_cpx *freqdata);
/*
input timedata has nfft scalar points
output freqdata has nfft/2+1 complex points
*/
void KISS_FFT_API kiss_fftri(kiss_fftr_cfg cfg,const kiss_fft_cpx *freqdata,kiss_fft_scalar *timedata);
/*
input freqdata has nfft/2+1 complex points
output timedata has nfft scalar points
*/
#define kiss_fftr_free KISS_FFT_FREE
#ifdef __cplusplus
}
#endif
#endif

66
installer/README.md Normal file
View File

@ -0,0 +1,66 @@
# Geopro Windows 安装包
把已构建的 `geopro_desktop` 打包成单个 Inno Setup 安装程序（带安装向导、开始菜单/桌面快捷方式、卸载程序，并自动安装 VC++ 运行时）。
## 一键打包
```powershell
# 1) 先构建 Release（若尚未构建）
build.bat app
# 2) 打包（默认版本 3.0.0，文件名带当天日期）
powershell -ExecutionPolicy Bypass -File installer\build_installer.ps1
```
产物：`installer\dist\Geopro_Setup_<版本>-<yyyyMMdd>.exe`
### 常用参数
| 参数 | 说明 |
|------|------|
| `-Version 3.1.0` | 指定版本号（最终文件名 `Geopro_Setup_3.1.0-<日期>.exe`） |
| `-Rebuild` | 打包前先 `build.bat rebuild` 干净重编 |
| `-QtPrefix D:/Qt/6.11.1/msvc2022_64` | 指定 Qt 路径（默认从 `CMakePresets.json` 解析） |
| `-SkipDeploy` | 跳过 windeployqt（不推荐，仅 staging 已补齐时用） |
## 打包流程（build_installer.ps1 做了什么）
1. **stage** — 把 `build/release/src/app` 复制到 `installer/staging`，剔除构建产物
（`CMakeFiles/`、`*_autogen/`、`*.pdb`、`*.log`、`*.cmake`）。
2. **windeployqt** — 在 staging 上补齐 Qt 运行时缺件：`D3Dcompiler_47.dll`、`opengl32sw.dll`
（软件 OpenGL 回退）、WebEngine QML、各类插件。
> 自动绕过已知坑：`qt6advanceddocking.dll` 名字带 `qt6` 前缀会被 windeployqt 误判为 Qt 模块、
> 去 `Qt\bin` 找它而报错中止——脚本临时把它拷进 `Qt\bin`，跑完即删。
3. **redist** — 确保 `vc_redist.x64.exe` 就位（缺则从本机 Visual Studio 复制）。
4. **ISCC** — 调用 Inno Setup 编译 `geopro.iss`，LZMA2/max 固实压缩，输出到 `dist/`。
## 安装包行为
- 默认装入 `C:\Program Files\Geopro`（需管理员权限）。
- 仅在系统**未安装** VC++ 2015-2022 x64 运行时时，静默安装 `vc_redist.x64.exe`。
- 创建开始菜单项；桌面快捷方式为可选项（默认不勾）。
- 程序日志/配置写入 `%LOCALAPPDATA%\Geomative\Geopro3`，与安装目录解耦。
- 向导支持简体中文 / 英文。
## 前置依赖（打包机）
| 工具 | 获取方式 |
|------|----------|
| Inno Setup 6 | `winget install --id JRSoftware.InnoSetup -e` |
| Qt 6.11.1 (msvc2022_64) | 含 `windeployqt.exe`，已是构建依赖 |
| Visual Studio 2022/2026 (C++) | 提供 `vc_redist.x64.exe`，已是构建依赖 |
## 仓库内/生成物
入库（打包工具本体）：
- `geopro.iss` — Inno Setup 脚本
- `build_installer.ps1` — 一键打包工具
- `lang/ChineseSimplified.isl` — 向导简体中文语言包
- `README.md`
不入库（每次生成，见 `.gitignore`）：
- `staging/` — 临时部署副本
- `redist/` — 复制来的 `vc_redist.x64.exe`
- `dist/` — 最终安装包

183
installer/build_installer.ps1 Normal file
View File

@ -0,0 +1,183 @@
<#
.SYNOPSIS
Geopro Windows 安装包一键打包工具。
.DESCRIPTION
把已构建的 geopro_desktop 部署目录打包成单个 Inno Setup 安装程序：
1) stage —— 将 build/release/src/app 复制到 installer\staging，剔除构建产物
（CMakeFiles / *_autogen / *.pdb / *.log / *.cmake）
2) deploy —— 在 staging 上跑 windeployqt 补齐 Qt 运行时缺件
（D3Dcompiler_47 / opengl32sw / WebEngine QML / 各插件）。
自动绕过 ADS 卡死问题（qt6advanceddocking.dll 被误判为 Qt 模块）。
3) redist —— 确保 VC++ 运行时安装器 vc_redist.x64.exe 就位（缺则从 VS 复制）
4) compile —— 调用 ISCC 编译 geopro.iss，输出到 installer\dist\
工具链（Qt / ISCC / VS 的 vc_redist）全部自动定位，便于换机复用。
.PARAMETER Version
产品版本号（默认 3.0.0）。最终文件名为 Geopro_Setup_<Version>-<yyyyMMdd>.exe。
.PARAMETER Rebuild
先执行 build.bat rebuild 做一次干净重编，再打包。默认使用现有构建产物。
.PARAMETER SkipDeploy
跳过 windeployqt 步骤（仅当确认 staging 已补齐时使用，不推荐）。
.PARAMETER QtPrefix
Qt 安装前缀。默认从 CMakePresets.json 的 CMAKE_PREFIX_PATH 解析。
.EXAMPLE
powershell -ExecutionPolicy Bypass -File installer\build_installer.ps1
.EXAMPLE
powershell -ExecutionPolicy Bypass -File installer\build_installer.ps1 -Version 3.1.0 -Rebuild
#>
[CmdletBinding()]
param(
[string]$Version = '3.0.0',
[switch]$Rebuild,
[switch]$SkipDeploy,
[string]$QtPrefix
)
$ErrorActionPreference = 'Stop'
$InstallerDir = $PSScriptRoot
$RepoRoot = Split-Path $InstallerDir -Parent
$BuildAppDir = Join-Path $RepoRoot 'build\release\src\app'
$StageDir = Join-Path $InstallerDir 'staging'
$RedistDir = Join-Path $InstallerDir 'redist'
$DistDir = Join-Path $InstallerDir 'dist'
$IssFile = Join-Path $InstallerDir 'geopro.iss'
$ExeName = 'geopro_desktop.exe'
$BuildDate = Get-Date -Format 'yyyyMMdd'
function Info($m){ Write-Host "[pack] $m" -ForegroundColor Cyan }
function Warn($m){ Write-Host "[pack] $m" -ForegroundColor Yellow }
function Die($m){ Write-Host "[pack] ERROR: $m" -ForegroundColor Red; exit 1 }
# --- 0. 可选：干净重编 -------------------------------------------------------
if ($Rebuild) {
Info '执行 build.bat rebuild（干净重编）...'
& (Join-Path $RepoRoot 'build.bat') rebuild
if ($LASTEXITCODE -ne 0) { Die "build.bat rebuild 失败 (exit $LASTEXITCODE)" }
}
# --- 1. 定位 Qt / windeployqt ----------------------------------------------
if (-not $QtPrefix) {
$presets = Join-Path $RepoRoot 'CMakePresets.json'
if (Test-Path $presets) {
try {
$j = Get-Content $presets -Raw | ConvertFrom-Json
foreach ($p in $j.configurePresets) {
if ($p.cacheVariables.CMAKE_PREFIX_PATH) {
$QtPrefix = $p.cacheVariables.CMAKE_PREFIX_PATH; break
}
}
} catch { }
}
}
if (-not $QtPrefix) { $QtPrefix = 'D:/Qt/6.11.1/msvc2022_64' }
$QtBin = Join-Path ($QtPrefix -replace '/','\') 'bin'
$WinDeploy = Join-Path $QtBin 'windeployqt.exe'
# --- 2. 定位 ISCC -----------------------------------------------------------
$IsccCandidates = @(
"$env:LOCALAPPDATA\Programs\Inno Setup 6\ISCC.exe",
"${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe",
"$env:ProgramFiles\Inno Setup 6\ISCC.exe"
)
$Iscc = $IsccCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if (-not $Iscc) { $Iscc = (Get-Command ISCC.exe -ErrorAction SilentlyContinue).Source }
if (-not $Iscc) {
Die '未找到 Inno Setup (ISCC.exe)。请先安装：winget install --id JRSoftware.InnoSetup -e'
}
# --- 3. 校验构建产物 --------------------------------------------------------
$BuiltExe = Join-Path $BuildAppDir $ExeName
if (-not (Test-Path $BuiltExe)) {
Die "未找到构建产物 $BuiltExe`n请先构建：build.bat app（或加 -Rebuild 参数）"
}
Info "构建产物: $BuiltExe ($([math]::Round((Get-Item $BuiltExe).Length/1MB,2)) MB, 修改于 $((Get-Item $BuiltExe).LastWriteTime))"
# --- 4. stage：复制部署目录、剔除构建产物 -----------------------------------
Info 'stage 部署副本（剔除 CMakeFiles / *_autogen / *.pdb / *.log / *.cmake）...'
if (Test-Path $StageDir) { Remove-Item $StageDir -Recurse -Force }
New-Item -ItemType Directory -Force $StageDir | Out-Null
robocopy $BuildAppDir $StageDir /E `
/XD CMakeFiles geopro_desktop_autogen `
/XF *.pdb *.log cmake_install.cmake *.ilk *.exp `
/NFL /NDL /NJH /NJS /MT:8 | Out-Null
if ($LASTEXITCODE -ge 8) { Die "robocopy 失败 (exit $LASTEXITCODE)" }
# --- 5. windeployqt 补齐 Qt 运行时（绕过 ADS 卡死） -------------------------
if (-not $SkipDeploy) {
if (-not (Test-Path $WinDeploy)) { Die "未找到 windeployqt: $WinDeploy（用 -QtPrefix 指定 Qt 路径）" }
Info 'windeployqt 补齐 Qt 运行时缺件...'
# qt6advanceddocking.dll 名字带 qt6 前缀，windeployqt 会误当 Qt 模块去 Qt\bin 找它并报错中止。
# 临时把它拷进 Qt\bin 让 windeployqt 能读其依赖（实为 Qt6Core/Gui/Widgets），跑完即删。
$adsName = 'qt6advanceddocking.dll'
$adsTmp = Join-Path $QtBin $adsName
$adsPreexisted = Test-Path $adsTmp
if (-not $adsPreexisted) { Copy-Item (Join-Path $StageDir $adsName) $adsTmp -Force }
try {
& $WinDeploy --release --no-translations --compiler-runtime (Join-Path $StageDir $ExeName) | Out-Null
if ($LASTEXITCODE -ne 0) { Die "windeployqt 失败 (exit $LASTEXITCODE)" }
} finally {
if (-not $adsPreexisted) { Remove-Item $adsTmp -Force -ErrorAction SilentlyContinue }
}
# 中文化：windeployqt --no-translations 不带翻译，单独拷 Qt 自带 zh_CN（QMessageBox/QFileDialog
# 等标准按钮中文化；app 启动按 exe 旁 translations\ 加载）。
$qtZh = Join-Path $QtBin '..\translations\qtbase_zh_CN.qm'
if (Test-Path $qtZh) {
$stageTr = Join-Path $StageDir 'translations'
New-Item -ItemType Directory -Force $stageTr | Out-Null
Copy-Item $qtZh $stageTr -Force
} else {
Warn "未找到 qtbase_zh_CN.qm（$qtZh）—部署版标准按钮可能仍为英文"
}
}
# --- 5.5 随包数据：本地样本演示数据 + PROJ 数据（exe 旁布局，运行时相对定位）-------
# 客户端启动会同步加载本地样本数据构建工作台；PROJ 数据供 3D 体素 CRS 配准。
# 二者缺失会导致登录后无界面/3D 退化，故随包到 exe 旁（sampledata\ 与 proj\）。
Info '随包数据：复制样本演示数据 + PROJ 数据到 staging...'
# 用目录内 ASCII 标志文件 dem.tif 定位样本目录，避免在脚本里写中文路径（编码风险）。
$sampleSrc = Get-ChildItem (Join-Path $RepoRoot 'docs') -Directory -ErrorAction SilentlyContinue |
Where-Object { Test-Path (Join-Path $_.FullName 'dem.tif') } | Select-Object -First 1
if (-not $sampleSrc) { Die '未找到本地样本数据目录（docs 下含 dem.tif 的目录）' }
robocopy $sampleSrc.FullName (Join-Path $StageDir 'sampledata') /E /NFL /NDL /NJH /NJS /MT:8 | Out-Null
if ($LASTEXITCODE -ge 8) { Die "robocopy 样本数据失败 (exit $LASTEXITCODE)" }
$projSrc = Join-Path $RepoRoot 'build\release\vcpkg_installed\x64-windows\share\proj'
if (-not (Test-Path (Join-Path $projSrc 'proj.db'))) { Die "未找到 PROJ 数据: $projSrc\proj.db" }
robocopy $projSrc (Join-Path $StageDir 'proj') /E /NFL /NDL /NJH /NJS /MT:8 | Out-Null
if ($LASTEXITCODE -ge 8) { Die "robocopy PROJ 数据失败 (exit $LASTEXITCODE)" }
# --- 6. VC++ 运行时安装器就位 -----------------------------------------------
New-Item -ItemType Directory -Force $RedistDir | Out-Null
$VcRedist = Join-Path $RedistDir 'vc_redist.x64.exe'
if (-not (Test-Path $VcRedist)) {
Info 'vc_redist.x64.exe 缺失，从 Visual Studio 复制...'
$vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
$vsPath = & $vswhere -all -prerelease -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath | Select-Object -Last 1
$found = Get-ChildItem (Join-Path $vsPath 'VC\Redist') -Filter 'vc_redist.x64.exe' -Recurse -ErrorAction SilentlyContinue |
Sort-Object FullName -Descending | Select-Object -First 1
if (-not $found) { Die '未找到 vc_redist.x64.exe，请手动放入 installer\redist\' }
Copy-Item $found.FullName $VcRedist -Force
}
# --- 7. ISCC 编译 -----------------------------------------------------------
New-Item -ItemType Directory -Force $DistDir | Out-Null
$stageMB = [math]::Round((Get-ChildItem $StageDir -Recurse -File | Measure-Object Length -Sum).Sum/1MB,1)
Info "staging 载荷 $stageMB MB，开始用 Inno Setup 编译安装包..."
& $Iscc "/DAppVersion=$Version" "/DBuildDate=$BuildDate" $IssFile
if ($LASTEXITCODE -ne 0) { Die "ISCC 编译失败 (exit $LASTEXITCODE)" }
# --- 8. 收尾报告 ------------------------------------------------------------
$out = Join-Path $DistDir "Geopro_Setup_$Version-$BuildDate.exe"
if (Test-Path $out) {
Info '打包完成 ✓'
Write-Host " 安装包: $out"
Write-Host " 大小 : $([math]::Round((Get-Item $out).Length/1MB,1)) MB"
} else {
Warn "ISCC 返回成功，但未找到预期产物 $out（检查 installer\dist\）"
}

88
installer/geopro.iss Normal file
View File

@ -0,0 +1,88 @@
; ============================================================================
; Geopro — Windows 安装包脚本 (Inno Setup 6)
;
; 本脚本不直接手动编译，而是由 build_installer.ps1 调用：
; - 该脚本会先把 build/release/src/app 部署副本 stage 到 installer\staging，
; 跑 windeployqt 补齐 Qt 运行时缺件（D3Dcompiler / opengl32sw / WebEngine 等），
; 再用 /D 命令行宏把版本号与构建日期传进来。
; 也可手动编译（用 staging 现有内容、默认版本号）：
; "%LOCALAPPDATA%\Programs\Inno Setup 6\ISCC.exe" geopro.iss
;
; 产物：installer\dist\Geopro_Setup_<版本>-<日期>.exe
; ============================================================================
; ---- 版本/日期：默认值，可被 build_installer.ps1 的 /D 宏覆盖 ----
#ifndef AppVersion
#define AppVersion "3.0.0"
#endif
#ifndef BuildDate
#define BuildDate "dev"
#endif
#define AppName "Geopro"
#define AppPublisher "Geomative"
#define AppExeName "geopro_desktop.exe"
[Setup]
; AppId 必须保持稳定，升级/卸载据此识别同一程序——切勿修改此 GUID。
AppId={{B1C23792-2FFC-4326-89DA-B592D50DDF16}
AppName={#AppName}
AppVersion={#AppVersion}
AppVerName={#AppName} {#AppVersion} ({#BuildDate})
AppPublisher={#AppPublisher}
DefaultDirName={autopf}\{#AppName}
DefaultGroupName={#AppName}
DisableProgramGroupPage=yes
UninstallDisplayName={#AppName} {#AppVersion}
UninstallDisplayIcon={app}\{#AppExeName}
OutputDir={#SourcePath}\dist
OutputBaseFilename=Geopro_Setup_{#AppVersion}-{#BuildDate}
Compression=lzma2/max
SolidCompression=yes
WizardStyle=modern
; 仅 64 位（Qt/VTK 均为 x64 构建）
ArchitecturesAllowed=x64compatible
ArchitecturesInstallIn64BitMode=x64compatible
; 装入 Program Files 并需安装 VC++ 运行时——要求管理员权限
PrivilegesRequired=admin
; 失败时在 %TEMP% 留安装日志，便于排障
SetupLogging=yes
[Languages]
Name: "zh"; MessagesFile: "{#SourcePath}\lang\ChineseSimplified.isl"
Name: "en"; MessagesFile: "compiler:Default.isl"
[Tasks]
Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked
[Files]
; 主载荷：staging 全量（exe + 全部 DLL + 插件目录 + WebEngine 资源），递归打包
Source: "{#SourcePath}\staging\*"; DestDir: "{app}"; Flags: recursesubdirs createallsubdirs ignoreversion
; VC++ 运行时安装器：临时落地、装完即删
Source: "{#SourcePath}\redist\vc_redist.x64.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall
[Icons]
Name: "{group}\{#AppName}"; Filename: "{app}\{#AppExeName}"; WorkingDir: "{app}"
Name: "{group}\{cm:UninstallProgram,{#AppName}}"; Filename: "{uninstallexe}"
Name: "{autodesktop}\{#AppName}"; Filename: "{app}\{#AppExeName}"; WorkingDir: "{app}"; Tasks: desktopicon
[Run]
; 安装 Microsoft Visual C++ 运行时（仅在系统未安装时执行；退出码被 Inno 忽略，已装则静默跳过）
Filename: "{tmp}\vc_redist.x64.exe"; Parameters: "/install /quiet /norestart"; \
StatusMsg: "正在安装 Microsoft Visual C++ 运行时..."; Check: VCRedistNeeded
; 安装结束可选立即启动
Filename: "{app}\{#AppExeName}"; Description: "{cm:LaunchProgram,{#AppName}}"; \
WorkingDir: "{app}"; Flags: nowait postinstall skipifsilent
[Code]
// 检测 VC++ 2015-2022 x64 运行时是否已安装（64 位 + WOW6432Node 两个视图都查）
function VCRedistNeeded: Boolean;
var
installed: Cardinal;
begin
Result := True;
if RegQueryDWordValue(HKLM, 'SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64', 'Installed', installed) and (installed = 1) then
Result := False
else if RegQueryDWordValue(HKLM, 'SOFTWARE\WOW6432Node\Microsoft\VisualStudio\14.0\VC\Runtimes\x64', 'Installed', installed) and (installed = 1) then
Result := False;
end;

418
installer/lang/ChineseSimplified.isl Normal file
View File

@ -0,0 +1,418 @@
; *** Inno Setup version 6.5.0+ Chinese Simplified messages ***
;
; To download user-contributed translations of this file, go to:
; https://jrsoftware.org/files/istrans/
;
; Note: When translating this text, do not add periods (.) to the end of
; messages that didn't have them already, because on those messages Inno
; Setup adds the periods automatically (appending a period would result in
; two periods being displayed).
;
; Maintained by Zhenghan Yang
; Email: 847320916@QQ.com
; Translation based on network resource
; The latest Translation is on https://github.com/kira-96/Inno-Setup-Chinese-Simplified-Translation
;
[LangOptions]
; The following three entries are very important. Be sure to read and
; understand the '[LangOptions] section' topic in the help file.
LanguageName=简体中文
; If Language Name display incorrect, uncomment next line
; LanguageName=<7B80><4F53><4E2D><6587>
; About LanguageID, to reference link:
; https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c
LanguageID=$0804
; About CodePage, to reference link:
; https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers
LanguageCodePage=936
; If the language you are translating to requires special font faces or
; sizes, uncomment any of the following entries and change them accordingly.
;DialogFontName=
;DialogFontSize=9
;DialogFontBaseScaleWidth=7
;DialogFontBaseScaleHeight=15
;WelcomeFontName=Segoe UI
;WelcomeFontSize=14
[Messages]
; *** 应用程序标题
SetupAppTitle=安装
SetupWindowTitle=安装 - %1
UninstallAppTitle=卸载
UninstallAppFullTitle=%1 卸载
; *** Misc. common
InformationTitle=信息
ConfirmTitle=确认
ErrorTitle=错误
; *** SetupLdr messages
SetupLdrStartupMessage=现在将安装 %1。您想要继续吗？
LdrCannotCreateTemp=无法创建临时文件。安装程序已中止
LdrCannotExecTemp=无法执行临时目录中的文件。安装程序已中止
HelpTextNote=
; *** 启动错误消息
LastErrorMessage=%1。%n%n错误 %2: %3
SetupFileMissing=安装目录中缺少文件 %1。请修正这个问题或者获取程序的新副本。
SetupFileCorrupt=安装文件已损坏。请获取程序的新副本。
SetupFileCorruptOrWrongVer=安装文件已损坏，或是与这个安装程序的版本不兼容。请修正这个问题或获取新的程序副本。
InvalidParameter=无效的命令行参数：%n%n%1
SetupAlreadyRunning=安装程序正在运行。
WindowsVersionNotSupported=此程序不支持当前计算机运行的 Windows 版本。
WindowsServicePackRequired=此程序需要 %1 服务包 %2 或更高版本。
NotOnThisPlatform=此程序不能在 %1 上运行。
OnlyOnThisPlatform=此程序只能在 %1 上运行。
OnlyOnTheseArchitectures=此程序只能安装到为下列处理器架构设计的 Windows 版本中：%n%n%1
WinVersionTooLowError=此程序需要 %1 版本 %2 或更高。
WinVersionTooHighError=此程序不能安装于 %1 版本 %2 或更高。
AdminPrivilegesRequired=在安装此程序时您必须以管理员身份登录。
PowerUserPrivilegesRequired=在安装此程序时您必须以管理员身份或有权限的用户组身份登录。
SetupAppRunningError=安装程序发现 %1 当前正在运行。%n%n请先关闭正在运行的程序，然后点击“确定”继续，或点击“取消”退出。
UninstallAppRunningError=卸载程序发现 %1 当前正在运行。%n%n请先关闭正在运行的程序，然后点击“确定”继续，或点击“取消”退出。
; *** 启动问题
PrivilegesRequiredOverrideTitle=选择安装程序模式
PrivilegesRequiredOverrideInstruction=选择安装模式
PrivilegesRequiredOverrideText1=%1 可以为所有用户安装(需要管理员权限)，或仅为您安装。
PrivilegesRequiredOverrideText2=%1 可以仅为您安装，或为所有用户安装(需要管理员权限)。
PrivilegesRequiredOverrideAllUsers=为所有用户安装(&A)
PrivilegesRequiredOverrideAllUsersRecommended=为所有用户安装(&A) (建议选项)
PrivilegesRequiredOverrideCurrentUser=仅为我安装(&M)
PrivilegesRequiredOverrideCurrentUserRecommended=仅为我安装(&M) (建议选项)
; *** 其他错误
ErrorCreatingDir=安装程序无法创建目录“%1”
ErrorTooManyFilesInDir=无法在目录“%1”中创建文件，因为里面包含太多文件
; *** 安装程序公共消息
ExitSetupTitle=退出安装程序
ExitSetupMessage=安装程序尚未完成。如果现在退出，将不会安装该程序。%n%n您之后可以再次运行安装程序完成安装。%n%n现在退出安装程序吗？
AboutSetupMenuItem=关于安装程序(&A)...
AboutSetupTitle=关于安装程序
AboutSetupMessage=%1 版本 %2%n%3%n%n%1 主页：%n%4
AboutSetupNote=
TranslatorNote=简体中文翻译由Kira(847320916@qq.com)维护。项目地址：https://github.com/kira-96/Inno-Setup-Chinese-Simplified-Translation
; *** 按钮
ButtonBack=< 上一步(&B)
ButtonNext=下一步(&N) >
ButtonInstall=安装(&I)
ButtonOK=确定
ButtonCancel=取消
ButtonYes=是(&Y)
ButtonYesToAll=全是(&A)
ButtonNo=否(&N)
ButtonNoToAll=全否(&O)
ButtonFinish=完成(&F)
ButtonBrowse=浏览(&B)...
ButtonWizardBrowse=浏览(&R)...
ButtonNewFolder=新建文件夹(&M)
; *** “选择语言”对话框消息
SelectLanguageTitle=选择安装语言
SelectLanguageLabel=选择安装时使用的语言。
; *** 公共向导文字
ClickNext=点击“下一步”继续，或点击“取消”退出安装程序。
BeveledLabel=
BrowseDialogTitle=浏览文件夹
BrowseDialogLabel=在下面的列表中选择一个文件夹，然后点击“确定”。
NewFolderName=新建文件夹
; *** “欢迎”向导页
WelcomeLabel1=欢迎使用 [name] 安装向导
WelcomeLabel2=现在将安装 [name/ver] 到您的电脑中。%n%n建议您在继续安装前关闭所有其他应用程序。
; *** “密码”向导页
WizardPassword=密码
PasswordLabel1=这个安装程序有密码保护。
PasswordLabel3=请输入密码，然后点击“下一步”继续。密码区分大小写。
PasswordEditLabel=密码(&P)：
IncorrectPassword=您输入的密码不正确，请重新输入。
; *** “许可协议”向导页
WizardLicense=许可协议
LicenseLabel=请在继续安装前阅读以下重要信息。
LicenseLabel3=请仔细阅读下列许可协议。在继续安装前您必须同意这些协议条款。
LicenseAccepted=我同意此协议(&A)
LicenseNotAccepted=我不同意此协议(&D)
; *** “信息”向导页
WizardInfoBefore=信息
InfoBeforeLabel=请在继续安装前阅读以下重要信息。
InfoBeforeClickLabel=准备好继续安装后，点击“下一步”。
WizardInfoAfter=信息
InfoAfterLabel=请在继续安装前阅读以下重要信息。
InfoAfterClickLabel=准备好继续安装后，点击“下一步”。
; *** “用户信息”向导页
WizardUserInfo=用户信息
UserInfoDesc=请输入您的信息。
UserInfoName=用户名(&U)：
UserInfoOrg=组织(&O)：
UserInfoSerial=序列号(&S)：
UserInfoNameRequired=您必须输入用户名。
; *** “选择目标目录”向导页
WizardSelectDir=选择目标位置
SelectDirDesc=您想将 [name] 安装在哪里？
SelectDirLabel3=安装程序将安装 [name] 到下面的文件夹中。
SelectDirBrowseLabel=点击“下一步”继续。如果您想选择其他文件夹，点击“浏览”。
DiskSpaceGBLabel=至少需要有 [gb] GB 的可用磁盘空间。
DiskSpaceMBLabel=至少需要有 [mb] MB 的可用磁盘空间。
CannotInstallToNetworkDrive=安装程序无法安装到一个网络驱动器。
CannotInstallToUNCPath=安装程序无法安装到一个 UNC 路径。
InvalidPath=您必须输入一个带驱动器卷标的完整路径，例如：%n%nC:\APP%n%n或UNC路径：%n%n\\server\share
InvalidDrive=您选定的驱动器或 UNC 共享不存在或不能访问。请选择其他位置。
DiskSpaceWarningTitle=磁盘空间不足
DiskSpaceWarning=安装程序至少需要 %1 KB 的可用空间才能安装，但选定驱动器只有 %2 KB 的可用空间。%n%n您一定要继续吗？
DirNameTooLong=文件夹名称或路径太长。
InvalidDirName=文件夹名称无效。
BadDirName32=文件夹名称不能包含下列任何字符：%n%n%1
DirExistsTitle=文件夹已存在
DirExists=文件夹：%n%n%1%n%n已经存在。您一定要安装到这个文件夹中吗？
DirDoesntExistTitle=文件夹不存在
DirDoesntExist=文件夹：%n%n%1%n%n不存在。您想要创建此文件夹吗？
; *** “选择组件”向导页
WizardSelectComponents=选择组件
SelectComponentsDesc=您想安装哪些程序组件？
SelectComponentsLabel2=选中您想安装的组件；取消您不想安装的组件。然后点击“下一步”继续。
FullInstallation=完全安装
; if possible don't translate 'Compact' as 'Minimal' (I mean 'Minimal' in your language)
CompactInstallation=简洁安装
CustomInstallation=自定义安装
NoUninstallWarningTitle=组件已存在
NoUninstallWarning=安装程序检测到下列组件已安装在您的电脑中：%n%n%1%n%n取消选中这些组件不会卸载它们。%n%n确定要继续吗？
ComponentSize1=%1 KB
ComponentSize2=%1 MB
ComponentsDiskSpaceGBLabel=当前选择的组件需要至少 [gb] GB 的磁盘空间。
ComponentsDiskSpaceMBLabel=当前选择的组件需要至少 [mb] MB 的磁盘空间。
; *** “选择附加任务”向导页
WizardSelectTasks=选择附加任务
SelectTasksDesc=您想要安装程序执行哪些附加任务？
SelectTasksLabel2=选择您想要安装程序在安装 [name] 时执行的附加任务，然后点击“下一步”。
; *** “选择开始菜单文件夹”向导页
WizardSelectProgramGroup=选择开始菜单文件夹
SelectStartMenuFolderDesc=安装程序应该在哪里放置程序的快捷方式？
SelectStartMenuFolderLabel3=安装程序将在下列“开始”菜单文件夹中创建程序的快捷方式。
SelectStartMenuFolderBrowseLabel=点击“下一步”继续。如果您想选择其他文件夹，点击“浏览”。
MustEnterGroupName=您必须输入一个文件夹名。
GroupNameTooLong=文件夹名或路径太长。
InvalidGroupName=无效的文件夹名字。
BadGroupName=文件夹名不能包含下列任何字符：%n%n%1
NoProgramGroupCheck2=不创建开始菜单文件夹(&D)
; *** “准备安装”向导页
WizardReady=准备安装
ReadyLabel1=安装程序准备就绪，现在可以开始安装 [name] 到您的电脑。
ReadyLabel2a=点击“安装”继续此安装程序。如果您想重新考虑或修改任何设置，点击“上一步”。
ReadyLabel2b=点击“安装”继续此安装程序。
ReadyMemoUserInfo=用户信息：
ReadyMemoDir=目标位置：
ReadyMemoType=安装类型：
ReadyMemoComponents=已选择组件：
ReadyMemoGroup=开始菜单文件夹：
ReadyMemoTasks=附加任务：
; *** TExtractionWizardPage 向导页面与 ExtractArchive
ExtractingLabel=正在解压文件...
ButtonStopExtraction=停止解压(&S)
StopExtraction=您确定要停止解压吗？
ErrorExtractionAborted=解压已中止
ErrorExtractionFailed=解压失败：%1
; *** 压缩文件解压失败详情
ArchiveIncorrectPassword=压缩文件密码不正确
ArchiveIsCorrupted=压缩文件已损坏
ArchiveUnsupportedFormat=不支持的压缩文件格式
; *** TDownloadWizardPage 向导页面和 DownloadTemporaryFile
DownloadingLabel2=正在下载文件...
ButtonStopDownload=停止下载(&S)
StopDownload=您确定要停止下载吗？
ErrorDownloadAborted=下载已中止
ErrorDownloadFailed=下载失败：%1 %2
ErrorDownloadSizeFailed=获取下载大小失败：%1 %2
ErrorProgress=无效的进度：%1 / %2
ErrorFileSize=文件大小错误：预期 %1，实际 %2
; *** “正在准备安装”向导页
WizardPreparing=正在准备安装
PreparingDesc=安装程序正在准备安装 [name] 到您的电脑。
PreviousInstallNotCompleted=先前的程序安装或卸载未完成，您需要重启您的电脑以完成。%n%n在重启电脑后，再次运行安装程序以完成 [name] 的安装。
CannotContinue=安装程序不能继续。请点击“取消”退出。
ApplicationsFound=以下应用程序正在使用将由安装程序更新的文件。建议您允许安装程序自动关闭这些应用程序。
ApplicationsFound2=以下应用程序正在使用将由安装程序更新的文件。建议您允许安装程序自动关闭这些应用程序。安装完成后，安装程序将尝试重新启动这些应用程序。
CloseApplications=自动关闭应用程序(&A)
DontCloseApplications=不要关闭应用程序(&D)
ErrorCloseApplications=安装程序无法自动关闭所有应用程序。建议您在继续之前，关闭所有在使用需要由安装程序更新的文件的应用程序。
PrepareToInstallNeedsRestart=安装程序必须重启您的计算机。计算机重启后，请再次运行安装程序以完成 [name] 的安装。%n%n是否立即重新启动？
; *** “正在安装”向导页
WizardInstalling=正在安装
InstallingLabel=安装程序正在安装 [name] 到您的电脑，请稍候。
; *** “安装完成”向导页
FinishedHeadingLabel=[name] 安装完成
FinishedLabelNoIcons=安装程序已在您的电脑中安装了 [name]。
FinishedLabel=安装程序已在您的电脑中安装了 [name]。您可以通过已安装的快捷方式运行此应用程序。
ClickFinish=点击“完成”退出安装程序。
FinishedRestartLabel=为完成 [name] 的安装，安装程序必须重新启动您的电脑。要立即重启吗？
FinishedRestartMessage=为完成 [name] 的安装，安装程序必须重新启动您的电脑。%n%n要立即重启吗？
ShowReadmeCheck=是，我想查阅自述文件
YesRadio=是，立即重启电脑(&Y)
NoRadio=否，稍后重启电脑(&N)
; used for example as 'Run MyProg.exe'
RunEntryExec=运行 %1
; used for example as 'View Readme.txt'
RunEntryShellExec=查阅 %1
; *** “安装程序需要下一张磁盘”提示
ChangeDiskTitle=安装程序需要下一张磁盘
SelectDiskLabel2=请插入磁盘 %1 并点击“确定”。%n%n如果这个磁盘中的文件可以在下列文件夹之外的文件夹中找到，请输入正确的路径或点击“浏览”。
PathLabel=路径(&P)：
FileNotInDir2=“%2”中找不到文件“%1”。请插入正确的磁盘或选择其他文件夹。
SelectDirectoryLabel=请指定下一张磁盘的位置。
; *** 安装阶段消息
SetupAborted=安装程序未完成安装。%n%n请修正这个问题并重新运行安装程序。
AbortRetryIgnoreSelectAction=选择操作
AbortRetryIgnoreRetry=重试(&T)
AbortRetryIgnoreIgnore=忽略错误并继续(&I)
AbortRetryIgnoreCancel=关闭安装程序
RetryCancelSelectAction=选择操作
RetryCancelRetry=重试(&T)
RetryCancelCancel=取消(&C)
; *** 安装状态消息
StatusClosingApplications=正在关闭应用程序...
StatusCreateDirs=正在创建目录...
StatusExtractFiles=正在提取文件...
StatusDownloadFiles=正在下载文件...
StatusCreateIcons=正在创建快捷方式...
StatusCreateIniEntries=正在创建 INI 条目...
StatusCreateRegistryEntries=正在创建注册表条目...
StatusRegisterFiles=正在注册文件...
StatusSavingUninstall=正在保存卸载信息...
StatusRunProgram=正在完成安装...
StatusRestartingApplications=正在重启应用程序...
StatusRollback=正在撤销更改...
; *** 其他错误
ErrorInternal2=内部错误：%1
ErrorFunctionFailedNoCode=%1 失败
ErrorFunctionFailed=%1 失败；错误代码 %2
ErrorFunctionFailedWithMessage=%1 失败；错误代码 %2.%n%3
ErrorExecutingProgram=无法执行文件：%n%1
; *** 注册表错误
ErrorRegOpenKey=打开注册表项时出错：%n%1\%2
ErrorRegCreateKey=创建注册表项时出错：%n%1\%2
ErrorRegWriteKey=写入注册表项时出错：%n%1\%2
; *** INI 错误
ErrorIniEntry=在文件“%1”中创建 INI 条目时出错。
; *** 文件复制错误
FileAbortRetryIgnoreSkipNotRecommended=跳过此文件(&S) (不推荐)
FileAbortRetryIgnoreIgnoreNotRecommended=忽略错误并继续(&I) (不推荐)
SourceIsCorrupted=源文件已损坏
SourceDoesntExist=源文件“%1”不存在
SourceVerificationFailed=源文件验证失败: %1
VerificationSignatureDoesntExist=签名文件“%1”不存在
VerificationSignatureInvalid=签名文件“%1”无效
VerificationKeyNotFound=签名文件“%1”使用了未知密钥
VerificationFileNameIncorrect=文件名不正确
VerificationFileTagIncorrect=文件标签不正确
VerificationFileSizeIncorrect=文件大小不正确
VerificationFileHashIncorrect=文件哈希值不正确
ExistingFileReadOnly2=无法替换现有文件，它是只读的。
ExistingFileReadOnlyRetry=移除只读属性并重试(&R)
ExistingFileReadOnlyKeepExisting=保留现有文件(&K)
ErrorReadingExistingDest=尝试读取现有文件时出错：
FileExistsSelectAction=选择操作
FileExists2=文件已经存在。
FileExistsOverwriteExisting=覆盖已存在的文件(&O)
FileExistsKeepExisting=保留现有的文件(&K)
FileExistsOverwriteOrKeepAll=为所有冲突文件执行此操作(&D)
ExistingFileNewerSelectAction=选择操作
ExistingFileNewer2=现有的文件比安装程序将要安装的文件还要新。
ExistingFileNewerOverwriteExisting=覆盖已存在的文件(&O)
ExistingFileNewerKeepExisting=保留现有的文件(&K) (推荐)
ExistingFileNewerOverwriteOrKeepAll=为所有冲突文件执行此操作(&D)
ErrorChangingAttr=尝试更改下列现有文件的属性时出错：
ErrorCreatingTemp=尝试在目标目录创建文件时出错：
ErrorReadingSource=尝试读取下列源文件时出错：
ErrorCopying=尝试复制下列文件时出错：
ErrorDownloading=下载文件时出错：
ErrorExtracting=解压压缩文件时出错：
ErrorReplacingExistingFile=尝试替换现有文件时出错：
ErrorRestartReplace=重启并替换失败：
ErrorRenamingTemp=尝试重命名下列目标目录中的一个文件时出错：
ErrorRegisterServer=无法注册 DLL/OCX：%1
ErrorRegSvr32Failed=RegSvr32 失败；退出代码 %1
ErrorRegisterTypeLib=无法注册类库：%1
; *** 卸载显示名字标记
; used for example as 'My Program (32-bit)'
UninstallDisplayNameMark=%1 (%2)
; used for example as 'My Program (32-bit, All users)'
UninstallDisplayNameMarks=%1 (%2, %3)
UninstallDisplayNameMark32Bit=32 位
UninstallDisplayNameMark64Bit=64 位
UninstallDisplayNameMarkAllUsers=所有用户
UninstallDisplayNameMarkCurrentUser=当前用户
; *** 安装后错误
ErrorOpeningReadme=尝试打开自述文件时出错。
ErrorRestartingComputer=安装程序无法重启电脑，请手动重启。
; *** 卸载消息
UninstallNotFound=文件“%1”不存在。无法卸载。
UninstallOpenError=文件“%1”不能被打开。无法卸载。
UninstallUnsupportedVer=此版本的卸载程序无法识别卸载日志文件“%1”的格式。无法卸载
UninstallUnknownEntry=卸载日志中遇到一个未知条目 (%1)
ConfirmUninstall=您确认要完全移除 %1 及其所有组件吗？
UninstallOnlyOnWin64=仅允许在 64 位 Windows 中卸载此程序。
OnlyAdminCanUninstall=仅使用管理员权限的用户能完成此卸载。
UninstallStatusLabel=正在从您的电脑中移除 %1，请稍候。
UninstalledAll=已顺利从您的电脑中移除 %1。
UninstalledMost=%1 卸载完成。%n%n有部分内容未能被删除，但您可以手动删除它们。
UninstalledAndNeedsRestart=为完成 %1 的卸载，需要重启您的电脑。%n%n立即重启电脑吗？
UninstallDataCorrupted=文件“%1”已损坏。无法卸载
; *** 卸载状态消息
ConfirmDeleteSharedFileTitle=删除共享的文件吗？
ConfirmDeleteSharedFile2=系统表示下列共享的文件已不有其他程序使用。您希望卸载程序删除这些共享的文件吗？%n%n如果删除这些文件，但仍有程序在使用这些文件，则这些程序可能出现异常。如果您不能确定，请选择“否”，在系统中保留这些文件以免引发问题。
SharedFileNameLabel=文件名：
SharedFileLocationLabel=位置：
WizardUninstalling=卸载状态
StatusUninstalling=正在卸载 %1...
; *** Shutdown block reasons
ShutdownBlockReasonInstallingApp=正在安装 %1。
ShutdownBlockReasonUninstallingApp=正在卸载 %1。
; The custom messages below aren't used by Setup itself, but if you make
; use of them in your scripts, you'll want to translate them.
[CustomMessages]
NameAndVersion=%1 版本 %2
AdditionalIcons=附加快捷方式：
CreateDesktopIcon=创建桌面快捷方式(&D)
CreateQuickLaunchIcon=创建快速启动栏快捷方式(&Q)
ProgramOnTheWeb=%1 网站
UninstallProgram=卸载 %1
LaunchProgram=运行 %1
AssocFileExtension=将 %2 文件扩展名与 %1 建立关联(&A)
AssocingFileExtension=正在将 %2 文件扩展名与 %1 建立关联...
AutoStartProgramGroupDescription=启动：
AutoStartProgram=自动启动 %1
AddonHostProgramNotFound=您选择的文件夹中无法找到 %1。%n%n您要继续吗？

1
src/CMakeLists.txt
View File

@ -9,6 +9,7 @@
# add_subdirectory(controller) # 联动编排 # add_subdirectory(controller) # 联动编排
# #
add_subdirectory(core) add_subdirectory(core)
add_subdirectory(io)
add_subdirectory(data) add_subdirectory(data)
add_subdirectory(net) add_subdirectory(net)
add_subdirectory(render) add_subdirectory(render)

78
src/app/AnomalyPropertiesDialog.cpp Normal file
View File

@ -0,0 +1,78 @@
#include "AnomalyPropertiesDialog.hpp"
#include <QPlainTextEdit>
#include <QVBoxLayout>
#include <QWidget>
#include "FormKit.hpp"
#include "Theme.hpp"
namespace geopro::app {
namespace {
QString markTypeLabel(geopro::core::AnomalyMarkType t) {
switch (t) {
case geopro::core::AnomalyMarkType::Point: return QStringLiteral("点");
case geopro::core::AnomalyMarkType::Polyline: return QStringLiteral("折线");
case geopro::core::AnomalyMarkType::Polygon: return QStringLiteral("多边形");
}
return QStringLiteral("—");
}
QString orDash(const std::string& s) {
return s.empty() ? QStringLiteral("—") : QString::fromStdString(s);
}
} // namespace
AnomalyPropertiesDialog::AnomalyPropertiesDialog(const geopro::core::Anomaly& a, QWidget* parent)
: QDialog(parent) {
setWindowTitle(QStringLiteral("异常属性"));
formkit::DetailForm form;
form.group(QStringLiteral("异常"))
.row(QStringLiteral("名称"), orDash(a.name))
.row(QStringLiteral("类型"), orDash(a.typeName))
.row(QStringLiteral("标记类型"), markTypeLabel(a.markType))
.row(QStringLiteral("归属"), orDash(a.remarkSourceId))
.row(QStringLiteral("异常体"), a.consortiumId.empty()
? QStringLiteral("（未分组）")
: QString::fromStdString(a.consortiumId));
// 顶点世界坐标（只读列表，x/y/z 每行一个点）—— 作为附加只读区，复用统一分组标题样式。
auto* vertexBox = new QWidget(this);
auto* vlay = new QVBoxLayout(vertexBox);
vlay->setContentsMargins(0, 0, 0, 0);
vlay->setSpacing(geopro::app::space::kSm);
formkit::addSection(vlay, QStringLiteral("顶点坐标（%1 个）").arg(a.worldPts.size()), vertexBox,
false);
auto* pts = new QPlainTextEdit(vertexBox);
pts->setReadOnly(true);
pts->setFixedHeight(geopro::app::scaledPx(120));
QString text;
for (std::size_t i = 0; i < a.worldPts.size(); ++i) {
const auto& p = a.worldPts[i];
text += QStringLiteral("%1: (%2, %3, %4)\n")
.arg(i + 1)
.arg(p.x, 0, 'f', 2)
.arg(p.y, 0, 'f', 2)
.arg(p.z, 0, 'f', 2);
}
pts->setPlainText(text);
vlay->addWidget(pts);
// 备注（只读）。
auto* remarkBox = new QWidget(this);
auto* rlay = new QVBoxLayout(remarkBox);
rlay->setContentsMargins(0, 0, 0, 0);
rlay->setSpacing(geopro::app::space::kSm);
formkit::addSection(rlay, QStringLiteral("备注"), remarkBox, false);
auto* remark = new QPlainTextEdit(remarkBox);
remark->setReadOnly(true);
remark->setFixedHeight(geopro::app::scaledPx(60));
remark->setPlainText(QString::fromStdString(a.remark));
rlay->addWidget(remark);
formkit::buildDetailDialog(this, form.build(), {vertexBox, remarkBox});
}
} // namespace geopro::app

17
src/app/AnomalyPropertiesDialog.hpp Normal file
View File

@ -0,0 +1,17 @@
#pragma once
#include <QDialog>
#include "model/Anomaly.hpp"
namespace geopro::app {
// 异常属性对话框（#4c-3，需求 R83）：双击异常列表项弹出，只读展示选中异常的
// 名称/类型/标记类型/备注/归属三维体/异常体分组/顶点世界坐标。
// 截图：模型与异常端点均无截图字段（保存对话框的截图仅为 mock 预览、未持久化），故不展示。
class AnomalyPropertiesDialog : public QDialog {
Q_OBJECT
public:
AnomalyPropertiesDialog(const geopro::core::Anomaly& a, QWidget* parent = nullptr);
};
} // namespace geopro::app

157
src/app/AnomalySaveDialog.cpp Normal file
View File

@ -0,0 +1,157 @@
#include "AnomalySaveDialog.hpp"
#include <QComboBox>
#include "EmptyAwareComboBox.hpp"
#include <QFormLayout>
#include <QJsonArray>
#include <QJsonObject>
#include <QLabel>
#include <QLineEdit>
#include <QPainter>
#include <QPen>
#include <QPixmap>
#include <QPlainTextEdit>
#include <QPointer>
#include <algorithm>
#include "FormKit.hpp"
#include "Theme.hpp"
#include "repo/IDatasetCommandRepository.hpp"
namespace geopro::app {
AnomalySaveDialog::AnomalySaveDialog(const QString& screenshotPath, int shotW, int shotH,
geopro::data::IDatasetCommandRepository* cmdRepo,
const QString& projectId, int remarkSourceType,
QWidget* parent)
: QDialog(parent), cmdRepo_(cmdRepo), remarkSourceType_(remarkSourceType) {
setWindowTitle(QStringLiteral("保存异常"));
setModal(true);
auto* root = formkit::dialogRoot(this);
auto* card = formkit::formCard(this);
auto* cardLay = formkit::cardBody(card);
auto* form = formkit::makeEditForm();
name_ = new QLineEdit(QStringLiteral("异常"));
formkit::capField(name_);
form->addRow(formkit::editLabel(QStringLiteral("名称")), name_);
type_ = new EmptyAwareComboBox();
type_->setPlaceholderText(QStringLiteral("请选择异常类型")); // 空(如该形态平台无类型)时显灰占位+「暂无数据」
formkit::capField(type_);
form->addRow(formkit::editLabel(QStringLiteral("异常类型")), type_);
// 样式预览：选中类型的 legend 派生样式可视化(点=色球/线=线型/面=描边矩形)。
stylePreview_ = new QLabel(QStringLiteral("—"));
stylePreview_->setMinimumWidth(geopro::app::scaledPx(92));
form->addRow(formkit::editLabel(QStringLiteral("样式")), stylePreview_);
// 选中类型变化 → 拉其平台样式(legend)，使保存的异常按平台类型样式渲染 + 刷新预览。
connect(type_, qOverload<int>(&QComboBox::currentIndexChanged), this,
[this](int) { loadStyleForCurrent(); });
loadTypes(cmdRepo, projectId, remarkSourceType); // 异步拉平台异常类型填充（与平台一致）
remark_ = new QPlainTextEdit();
remark_->setFixedHeight(geopro::app::scaledPx(60));
formkit::capField(remark_);
form->addRow(formkit::editLabel(QStringLiteral("备注")), remark_);
cardLay->addLayout(form);
// 截图预览 + 大小（R50「确定截图大小」）。
if (!screenshotPath.isEmpty()) {
cardLay->addWidget(new QLabel(QStringLiteral("截图（%1 × %2）").arg(shotW).arg(shotH)));
QPixmap pm(screenshotPath);
if (!pm.isNull()) {
auto* img = new QLabel();
img->setPixmap(pm.scaledToWidth(geopro::app::scaledPx(320), Qt::SmoothTransformation));
cardLay->addWidget(img);
}
}
root->addWidget(card);
formkit::addDialogButtons(root, this);
}
void AnomalySaveDialog::loadTypes(geopro::data::IDatasetCommandRepository* cmdRepo,
const QString& projectId, int remarkSourceType) {
if (cmdRepo == nullptr || projectId.isEmpty()) return; // 无仓储/项目 → 下拉留空(空态提示)
QPointer<AnomalySaveDialog> self(this);
cmdRepo->listExceptionTypes(
projectId, QString::number(remarkSourceType),
[self](bool ok, QJsonArray list, const QString&) {
if (!self || !ok) return; // 对话框已关 / 失败 → 留空
for (const QJsonValue& v : list) {
const QJsonObject o = v.toObject();
// 平台响应项：{label:类型名, value:类型id}（实测扁平 data 数组，net 层已归一 value）。
self->type_->addItem(o.value(QStringLiteral("label")).toString(),
o.value(QStringLiteral("value")).toString());
}
self->loadStyleForCurrent(); // 首项自动选中 → 预取其样式
});
}
void AnomalySaveDialog::loadStyleForCurrent() {
if (cmdRepo_ == nullptr) return;
const QString typeId = type_->currentData().toString();
if (typeId.isEmpty()) return;
QPointer<AnomalySaveDialog> self(this);
cmdRepo_->getExceptionTypeDetail(typeId, [self](bool ok, QJsonObject detail, const QString&) {
if (!self || !ok) return;
const QJsonObject lg = detail.value(QStringLiteral("legend")).toObject();
// 按形态(1点/2线/3面)从 legend 派生样式：点用 pointColor；线/面用 polyline*。
if (self->remarkSourceType_ == 1) {
self->styleColor_ = lg.value(QStringLiteral("pointColor")).toString();
} else {
self->styleColor_ = lg.value(QStringLiteral("polylineColor")).toString();
self->styleWidth_ = lg.value(QStringLiteral("polylineWidth")).toDouble();
self->styleDashed_ =
lg.value(QStringLiteral("polylineShape")).toString().contains(QStringLiteral("dash"));
}
self->updateStylePreview();
});
}
void AnomalySaveDialog::updateStylePreview() {
if (stylePreview_ == nullptr) return;
const QColor col(styleColor_);
if (!col.isValid()) { // 未取到样式 → 占位
stylePreview_->setPixmap(QPixmap());
stylePreview_->setText(QStringLiteral("—"));
return;
}
const int w = geopro::app::scaledPx(92), h = geopro::app::scaledPx(22);
QPixmap pm(w, h);
pm.fill(Qt::transparent);
QPainter p(&pm);
p.setRenderHint(QPainter::Antialiasing, true);
QPen pen(col);
pen.setWidthF(std::clamp(styleWidth_ > 0.0 ? styleWidth_ : 2.0, 1.0, 4.0));
if (styleDashed_) pen.setStyle(Qt::DashLine);
if (remarkSourceType_ == 1) { // 点：实心色球
p.setPen(Qt::NoPen);
p.setBrush(col);
p.drawEllipse(QPointF(w / 2.0, h / 2.0), h * 0.3, h * 0.3);
} else if (remarkSourceType_ == 2) { // 线：按线宽/虚实画线
p.setPen(pen);
p.drawLine(QPointF(w * 0.1, h / 2.0), QPointF(w * 0.9, h / 2.0));
} else { // 面：描边矩形 + 淡填充
p.setPen(pen);
p.setBrush(QColor(col.red(), col.green(), col.blue(), 40));
p.drawRect(QRectF(w * 0.12, h * 0.22, w * 0.76, h * 0.56));
}
p.end();
stylePreview_->setText(QString());
stylePreview_->setPixmap(pm);
}
QString AnomalySaveDialog::anomalyName() const {
const QString n = name_->text().trimmed();
return n.isEmpty() ? QStringLiteral("异常") : n;
}
QString AnomalySaveDialog::typeName() const { return type_->currentText(); }
QString AnomalySaveDialog::typeId() const { return type_->currentData().toString(); }
QString AnomalySaveDialog::remark() const { return remark_->toPlainText(); }
} // namespace geopro::app

59
src/app/AnomalySaveDialog.hpp Normal file
View File

@ -0,0 +1,59 @@
#pragma once
#include <QDialog>
#include <QString>
class QLineEdit;
class QComboBox;
class QPlainTextEdit;
class QLabel;
namespace geopro::data {
class IDatasetCommandRepository;
}
namespace geopro::app {
// 异常保存对话框（#4b，需求 R50）：名称 + 异常类型 + 备注 + 截图预览/大小。
// 异常类型从平台按标注形态(remarkSourceType)异步拉取，与平台保持一致。accept 后取 name/typeName/typeId/remark。
class AnomalySaveDialog : public QDialog {
Q_OBJECT
public:
// screenshotPath：圈定结束截图的本地路径（为空则不显示预览）；w/h：截图像素尺寸（R50「确定截图大小」）。
// cmdRepo/projectId：异步拉取平台异常类型填充下拉（与平台一致）；remarkSourceType：标注形态 1点/2线/3面，
// 决定查询哪一类平台异常类型。cmdRepo 为空则下拉留空（空态由 EmptyAwareComboBox 提示）。
AnomalySaveDialog(const QString& screenshotPath, int shotW, int shotH,
geopro::data::IDatasetCommandRepository* cmdRepo, const QString& projectId,
int remarkSourceType, QWidget* parent = nullptr);
QString anomalyName() const;
QString typeName() const;
QString typeId() const;
QString remark() const;
// 选中类型的平台样式（从 legend 按形态派生，与平台一致）。styleColor 空 = 未取到，调用方用默认样式。
QString styleColor() const { return styleColor_; }
double styleWidth() const { return styleWidth_; }
bool styleDashed() const { return styleDashed_; }
private:
// 异步拉平台异常类型(label→显示, value→id)填充下拉；空/失败时下拉留空（EmptyAwareComboBox 提示）。
void loadTypes(geopro::data::IDatasetCommandRepository* cmdRepo, const QString& projectId,
int remarkSourceType);
// 拉当前选中类型的详情 legend → 按形态(点/线/面)派生 styleColor/Width/Dashed。
void loadStyleForCurrent();
// 据当前样式按形态画预览(点=色球/线=线型/面=描边矩形)，画到 stylePreview_。
void updateStylePreview();
geopro::data::IDatasetCommandRepository* cmdRepo_ = nullptr;
int remarkSourceType_ = 3;
QString styleColor_; // legend 派生线/点色（空=未取到）
double styleWidth_ = 0.0; // legend.polylineWidth
bool styleDashed_ = false; // legend.polylineShape 含 "dash"
QLineEdit* name_ = nullptr;
QComboBox* type_ = nullptr;
QLabel* stylePreview_ = nullptr; // 选中类型样式预览(色块/线型)
QPlainTextEdit* remark_ = nullptr;
};
} // namespace geopro::app

59
src/app/AxesSettingsDialog.cpp Normal file
View File

@ -0,0 +1,59 @@
#include "AxesSettingsDialog.hpp"
#include <QCheckBox>
#include <QDialogButtonBox>
#include <QDoubleSpinBox>
#include <QGridLayout>
#include <QLabel>
#include <QPushButton>
namespace geopro::app {
namespace {
constexpr double kSpinAbsLimit = 1e6;
}
AxesSettingsDialog::AxesSettingsDialog(AxisRange x, AxisRange y, AxisRange z, QWidget* parent)
: QDialog(parent) {
setWindowTitle(QStringLiteral("坐标轴设置"));
auto* grid = new QGridLayout(this);
grid->addWidget(new QLabel(QStringLiteral("轴")), 0, 0);
grid->addWidget(new QLabel(QStringLiteral("显示")), 0, 1);
grid->addWidget(new QLabel(QStringLiteral("最小")), 0, 2);
grid->addWidget(new QLabel(QStringLiteral("最大")), 0, 3);
auto build = [&](int gridRow, const QString& label, const AxisRange& r, Row& out) {
grid->addWidget(new QLabel(label), gridRow, 0);
out.show = new QCheckBox(this);
out.show->setChecked(r.show);
grid->addWidget(out.show, gridRow, 1);
out.lo = new QDoubleSpinBox(this);
out.lo->setRange(-kSpinAbsLimit, kSpinAbsLimit);
out.lo->setValue(r.min);
grid->addWidget(out.lo, gridRow, 2);
out.hi = new QDoubleSpinBox(this);
out.hi->setRange(-kSpinAbsLimit, kSpinAbsLimit);
out.hi->setValue(r.max);
grid->addWidget(out.hi, gridRow, 3);
};
build(1, QStringLiteral("X"), x, x_);
build(2, QStringLiteral("Y"), y, y_);
build(3, QStringLiteral("深度"), z, z_);
auto* btns = new QDialogButtonBox(QDialogButtonBox::Ok | QDialogButtonBox::Cancel, this);
btns->button(QDialogButtonBox::Ok)->setText(QStringLiteral("应用"));
btns->button(QDialogButtonBox::Cancel)->setText(QStringLiteral("取消"));
connect(btns, &QDialogButtonBox::accepted, this, &QDialog::accept);
connect(btns, &QDialogButtonBox::rejected, this, &QDialog::reject);
grid->addWidget(btns, 4, 0, 1, 4);
}
static AxisRange readRow(QCheckBox* show, QDoubleSpinBox* lo, QDoubleSpinBox* hi) {
return {show->isChecked(), lo->value(), hi->value()};
}
AxisRange AxesSettingsDialog::x() const { return readRow(x_.show, x_.lo, x_.hi); }
AxisRange AxesSettingsDialog::y() const { return readRow(y_.show, y_.lo, y_.hi); }
AxisRange AxesSettingsDialog::z() const { return readRow(z_.show, z_.lo, z_.hi); }
} // namespace geopro::app

Some files were not shown because too many files have changed in this diff Show More