# 二维数据集视图（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>