# radar_convert — 雷达原始数据 → 规范化格式 转换插件（本地原型）

把厂商原始雷达数据转换成客户端**规范化格式** `.head / .data / .cor (/.index)`，供三维雷达
渲染器消费。本目录是**未来"服务端下发转换插件"的本地原型**：今天的 Python 工具实现的
`convert` 契约，将来由客户端按设备型号拉取对应插件执行，接口不变。

当前实现型号：**`RADAR_TYPE_MALAMIRA`**（Mala Mira rSlicer，`.rad + .rd3|.rd7 + _G01.pos`）。

---

## 插件契约（本地工具 = 未来插件，接口一致）

```
plugin_id           : RADAR_TYPE_MALAMIRA
supports(fileset)   -> bool                       # 据文件组成判断是否本插件可处理
convert(lineDir, prefix, outDir) -> {head,data,cor}
```

- **输入**：一条测线三件套 `{prefix}.rad` + `{prefix}.rd3|.rd7` + `{prefix}_G01.pos`（轨迹可选）。
- **输出**：规范化目录 `{prefix}.head` + `{prefix}.data` + `{prefix}.cor`。
- 映射规则源自客户《雷达业务开发说明》§3.3（.rad→.head）/ §3.5（.rd3→.data）/ §2.2.2（.pos→.cor）。

## 用法

```bash
# 1) 列出目录内测线 + 维度一致性校验（不写文件）
python tools/radar_convert/malamira.py info  <lineDir>

# 2) 转换（--prefix 省略=全部测线）
python tools/radar_convert/malamira.py convert <lineDir> --out <outDir> [--prefix 南同大道_000]

# 3) probe：出图核对 .rd3 数据体主序（写一张 PNG 到 --out）
python tools/radar_convert/malamira.py probe <lineDir> --prefix 南同大道_000 --out <dir>
```

---

## 数据体维度与排列（★渲染器必读，已用真实数据核对）

- 体维度：`K`(道/切片，沿运动) × `M`(通道) × `N`(采样/深度)。
  - `M = NUMBER_OF_CH`，`N = SAMPLES`，`K = LAST_TRACE / NUMBER_OF_CH`。
  - `.rad` 的 `LAST TRACE` 是**总扫描数**（=K×M），不是道数 K。`.head` 原样透传该值，
    渲染器按 `K = LAST_TRACE / NUMBER_OF_CH` 求道数。
- **`.data` 主序 = position-major（已 probe 核对，MALA南同大道_000）**：
  磁盘扫描顺序 = `(道0: 通道0..M-1)(道1: 通道0..M-1)…`，每个 sweep 内 `N` 个采样连续。
  即 `flat.reshape(K, M, N)[道][通道][采样]`。
  - 直接对应 geopro 体轴 `X=道(nx=K)`、`Y=通道(ny=M)`、`Z=采样(nz=N)`，**无需转置**。
  - 反例（错误主序）：channel-major `reshape(M,K,N)` 的 B-scan 呈竖条乱码——probe 已排除。
- 数据类型：`int16` 小端（`.rd3`）/ `int32` 小端（`.rd7`）。`.rd3` 中出现 `-32768`
  为直达波饱和的真实值，非空值哨兵。

---

## 与客户文档的偏差（实现时的取舍，便于后端对齐）

| # | 项 | 文档 | 本工具 | 理由 |
|---|---|---|---|---|
| 1 | `BITS` 计算 | `文件大小/LAST_TRACE/NUMBER_OF_CH×8` | `bytes = 文件大小/(LAST_TRACE×SAMPLES)`，×8；并与扩展名(.rd3→16/.rd7→32)交叉校验 | 文档公式漏了 SAMPLES 维、量纲不符；本式对 6 条线均得 16，且 `文件大小==LAST_TRACE×SAMPLES×bytes` 严格成立 |
| 2 | `ENDIAN_TYPE` | §3.3 表："留空" | 填 `1`（小端） | 同节要点 1 明确"通常小端即 1"；渲染需确定字节序 |
| 3 | `WHEEL_CALIBRATION` | §3.3 表："留空" | 透传 `.rad` 实际值 | `.rad` 有该字段，透传更忠实（不影响渲染） |
| 4 | `.cor` 坐标 | 北→纬度 / 东→经度 | 同文档直映，N/E/M 为占位标识，解状态=4 | `.pos` 是本地投影坐标(米)、非经纬度；CRS 未知。单线渲染不依赖 .cor 配准，多线阶段再处理 |
| 5 | `.index` | 可选打标文件 | 本数据集无打标 → 不产出 | 该目录仅有 FCODES.TXT(编码字典)，无 .index 源 |

---

## 已验证（MALA南同大道_rSlicer，6 条测线，2026-06-29）

- `info`：6 条线全部通过 `文件大小 == LAST_TRACE×SAMPLES×bytes` 校验。
  K∈[2333,3778]，M=16，N=516，bits=16，距离模式，dx≈0.095–0.099m，时窗 96.42ns，均含轨迹。
- `convert`：6 条线 `.head/.data/.cor` 全部产出；`.data` 与源 `.rd3` 字节数严格一致。
- `probe`：position-major B-scan 出现连续直达波 + 地层 + 双曲线绕射 → 主序确认。