# 三维雷达 导入→处理→渲染 全链路方案（结合 POC 评估）

> 2026-06-30。本文把用户给出的雷达产品目标落成方案，并结合 POC（明星路 13G）已验证的资产，
> 评估复用/缺口、定关键架构缝与决策、排风险与分期。范围限定**三维雷达**（渲染/切片/异常 +
> 其上游的导入/处理管线）；不含 2D 雷达图、不含后端反演链。

## 1. 用户目标（七步）

1. 设备经 USB 接到用户电脑。
2. 客户端「设备连接」功能：自动识别设备、打开 USB 存储，用户选文件导入。
3. 另一导入分支：文件已在用户电脑，经**文件夹选择**导入。
4. 导入过程按文件类型（不同型号雷达）**自动加载插件**，对数据做 **ds 标准化转换**。
5. 导入完成自动形成 **项目 / GS / TM / ds** 结构（建 GS/TM 的「方案」待细化）。
6. 数据集详情页：用**数据处理插件**处理原始数据，插件支持多种方法（用户勾选）；
   另**固定加入两个客户端内置处理方法**：**插值**、**预渲染**（即为 LOD 做准备）。
   处理后**存为新 ds**。
7. VTK 视图：选三维雷达 ds 渲染、切片等；**所选 ds 可能是未处理原数据，也可能是处理后数据**（不同 ds）。

## 2. 关键决策（用户已拍板）

- **D1 — 预渲染（LOD 烘焙）是可选的。** 默认勾选，但用户可取消。
  → **渲染路径必须同时支持「未预渲染」与「已预渲染」两类 ds**（不能假设所有大体都已烘焙 LOD）。
  → 采用**混合渲染源**（见 §4）：原/插值 ds 走整卷源；预渲染 ds 走 LOD 源。

## 3. POC ↔ 目标 映射（复用 vs 缺口）

**结论：算法基本齐（POC/app 已有标准化、插值、增益、LOD 引擎、渲染源抽象）；缺的是三层"框架/管线"
+ 设备接入。**

| 步骤 | 已有（POC/现状） | 缺口 |
|---|---|---|
| 1–2 设备 USB/存储 | 无 | **全新**：Windows 设备识别 + USB 盘浏览（与 POC 无关，纯平台 plumbing） |
| 3 文件夹导入 | 已有导入入口、`tools/radar_convert` malamira 转换器 | 文件夹选择 + 批量 |
| 4 按型号插件标准化 | 转换算法有（malamira→规范化 `.head/.data`、`RadarVolumeAssembler`、int16 量化） | **导入插件框架**（按文件类型注册 reader）；现写死一种 |
| 5 项目/GS/TM/ds 结构 | ds 树（`sourceShowParentId` 派生嵌套）已在 | 自动建 GS/TM 的「方案」 |
| 6 处理插件 + 两内置 | 两内置**算法都有**：插值=`createRadarVolumeGrid` 通道插值(targetDy)；预渲染=`ChunkedVolumeStore::write`+`buildPyramidStreaming`。增益(dewow/AGC/tpow)亦有 | **处理插件框架** + 「处理→存为新 ds」管线 + 多方法勾选 UI |
| 7 选 ds 渲染/切片 | **渲染源抽象 `IVolumeRenderSource`（整卷/LOD 多态，含 `sliceSource()`）** + 整卷渲染 + 切片 + 异常 | 把 app 雷达路径迁到 `IVolumeRenderSource`；LOD 源接进 app（Track D） |

## 4. 架构缝：`IVolumeRenderSource`（已设计好，最低风险）

POC 已建好渲染源抽象（`src/render/source/IVolumeRenderSource.hpp`）：上层（控制器/`SliceTool`）只认此接口，
运行时在两种实现间切换：

- **`WholeVolumeSource`（整卷）** —— 给**未预渲染**的原/插值 ds（小体，单纹理够用）。
- **`ViewAdaptiveVolumeSource`（核外金字塔 LOD）** —— 给**已预渲染**的 ds（大体，按相机选层/选块重组单纹理）。

接口自带 `update(vtkCamera)`、`currentImages()`、**`sliceSource()`**（切片/异常的 reslice 基底也走它），
故"切片在两种源上都能切"是接口内建能力，不需两套切片代码。

> **D1 落到这里**：选 ds 渲染时按"该 ds 是否带 LOD store"路由到对应源。未预渲染 → 整卷源（现有内存
> 体路径迁入即可）；已预渲染 → LOD 源（Track D 接入）。

## 5. 处理与数据血缘模型

- 处理一律**产出新 ds**，挂在源 ds 下（复用现有派生树 `sourceShowParentId`）：
  ```
  原始 ds ─[插值]→ 插值 ds ─[预渲染]→ 预渲染 ds(LOD store)
        └─[增益/migration/…(可多选)]→ 处理 ds
  ```
- **两个内置处理方法**（client 自带、固定加入）：
  - **插值**：线内通道插值（读真实道偏移、目标横向间距如 2.5cm，**绝不跨线**）。算法=`createRadarVolumeGrid` 的 targetDy 路径。
  - **预渲染（LOD 烘焙）**：把体烘成 **`ChunkedVolumeStore` 分块金字塔**（int16 量化、64³ brick、qCompress、
    逐级 2× 降采样、每块 min/max；流式 `buildPyramidStreaming` 不持整卷）。产出 = 一个 **store 目录**，
    不是普通稠密体 → 该 ds 须带「类型=LOD store + 路径」标记，供 §4 渲染路由。
- 顺序：通常先插值再预渲染（烘焙插值后的体）；模型支持任选基底（也可直接烘原始）。

## 6. 预渲染专用落盘格式（LOD 前置，已实现于 POC）

`ChunkedVolumeStore`（一个目录，非单文件）：
- `meta.json`：几何 + 量化(scale/offset) + 逐块索引(offset/压缩长/**每块 min/max**)；
- `data.bin`：逐块 int16 → qCompress；块内 i 最快、k 最慢；偏移全 64 位（卷 >2GB）；
- `data_L1.bin…`：金字塔各级（逐级 2× 降采样）。

构建：整卷 `write` 或流式 `StreamingVolumeWriter`（逐块写不持整卷）+ `buildPyramid(Streaming)`。
渲染：`ViewAdaptiveVolumeSource` 打开 store，`update(相机)`→选层+选块→`readBrick`→重组单 `vtkImageData`，
**内存恒定、绕 16384 纹理墙**。

## 7. 需要新建的三块骨架

1. **插件框架（两类，别混）**
   - **导入插件**（步4）：按文件类型/型号 → 标准化成 ds 的 reader 注册表。
   - **处理插件**（步6）：吃一个 ds → 产出新 ds 的 transform，可多选串联；两内置（插值、预渲染）即自带处理插件。
   - 待定：插件接口（输入 ds/参数 → 输出 ds）、发现/注册、进程内 DLL（ABI/崩溃隔离风险）vs 子进程。
2. **「处理 → 新 ds」管线**：血缘落树、预渲染 ds 的 store 路径/缓存/失效/磁盘占用、重处理**异步+进度+可取消**。
3. **设备/USB 接入**（步1–2）：Windows 设备识别 + USB 盘浏览。最独立、与 POC 无关，可最后做；先跑通文件夹导入。

## 8. 风险排序

1. **中**：插件框架（架构骨架，影响步4/6，定义不好后面返工）。
2. **中**：预渲染 ds 的渲染/切片路由（Track D 核心；但**引擎+缝已验证**，是"接线"风险非"能不能做"风险）。
3. **低–中**：处理管线异步/进度/缓存（工程量明确）。
4. **低**：设备 USB（plumbing，独立）。

## 9. 分期建议

- **P0 验证最高技术风险**：把 app 雷达渲染迁到 `IVolumeRenderSource`，使
  - 未预渲染 ds → `WholeVolumeSource`（迁现有内存体路径）；
  - 预渲染 ds → `ViewAdaptiveVolumeSource`；
  南同大道先烘一个小 store 验"选 ds→按是否预渲染路由→渲染+切片"全链路。**验通则整个方案立住。**
- **P1 插件框架**：先定**处理插件**接口（含两内置），跑通"原 ds→插值→预渲染→渲染"；导入插件框架并行。
- **P2 处理管线 UI/异步**：详情页多方法勾选、进度、新 ds 落树。
- **P3 设备 USB**：最后接。

## 10. 现状基线（本轮已落地的交互/渲染精修，作为接入前的稳定底座）

- 切片拾取**精确化**：光标射线 vs 切片真实矩形求交 + 可见数据(alpha)双判定，去除外扩（雷达+反演通用）。
- 取消选中：点击体/空白/帘面即取消（精确"命中切片"判据）+ Esc 兜底。
- 滚轮步长：按**沿法向体素间距 × N**（Shift 粗调），不随体长跳变。
- 双击正视：缩放到切片（按面内尺寸+视角框住），不再"又小又远"。
- 不透明度：各向异性体用特征尺度（门控；近立方反演维持原对角线）。
- **B 方案视角导航**：#1 绕拾取点旋转（无选中时绕光标射线穿体中段点，不甩飞）；
  #2 沿线位置滑块（雷达专属，沿最长轴 dolly 到窗口；仅细长体显示）。
- 雷达显示**增益模式**右键切换（AGC/保幅 tpow/关），纯显示重建、不动原始数据。

> 这些是**单内存体 + 渲染期采样距自适应**底座；多分辨率/视锥 LOD 仍属 §4/§9 的 Track D 接入范畴（未做）。