# pissm

**Repository Path**: nanaxuu/pissm

## Basic Information

- **Project Name**: pissm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PISSM：物理引导的 ISAR 图像序列自监督基础模型 —— 实验代码

本工程是综述《近三年 ISAR 图像识别研究综述与创新课题建议》第 6 节所提创新课题
**PISSM（Physics-informed ISAR Sequence Self-supervised Model）** 的配套参考实现，
覆盖课题的四个研究内容（RC1–RC4），可直接运行、可扩展至真实数据。

## 核心创新点与代码对应

| 课题创新点 | 代码实现 |
|---|---|
| 创新点一-a：相邻帧对比（姿态连续性作为免费监督信号） | `pissm/losses.py::adjacent_contrastive_loss` |
| 创新点一-b：方位角排序/帧序预测代理任务 | `pissm/losses.py::order_loss` + 数据集乱序排列 |
| 创新点二：ASC 物理引导掩码建模 | `pissm/physics.py::saliency_to_mask` + `masked_recon_loss` |
| 创新点三：仿真→实测轻量跨域适配（GRL 域对抗 + 原型对齐） | `pissm/adapt_domain.py` |
| RC1：带 ASC/姿态角标注的 ISAR 序列仿真数据 | `pissm/simulator.py`（回波域点散射模型 + RD 成像） |
| RC2：空间 ViT + 时间 S6(Mamba 式) 时空联合编码器 | `pissm/models.py` |
| RC4：少样本/线性探测/跨域统一评测 | `pissm/eval_fewshot.py` |

## 目录结构

```
pissm/
├── configs/default.yaml      # 正式预训练配置
├── pissm/
│   ├── simulator.py          # RC1 ISAR 序列仿真器（sim/real 双域）
│   ├── physics.py            # ASC 显著性掩码、散射点检测、patch 化
│   ├── models.py             # RC2 空间ViT + S6时序块 + 三类代理任务头
│   ├── losses.py             # 相邻帧InfoNCE / 帧序CE / 掩码重建MSE
│   ├── dataset.py            # 序列数据集 & 帧级分类数据集
│   ├── train_pretrain.py     # 预训练入口
│   ├── adapt_domain.py       # RC3 跨域适配（GRL+原型对齐）
│   └── eval_fewshot.py       # RC4 少样本/线性探测评测
├── scripts/smoke_test.py     # 端到端冒烟测试
└── requirements.txt
```

## 快速开始（本地三步流程：生成数据集 → 训练 → 验证）

```bash
pip install -r requirements.txt

# 第 0 步（可选）: 端到端冒烟测试，约 10 秒，验证环境无误
python scripts/smoke_test.py

# 第 1 步: 离线生成仿真数据集（生成三个 .npz 到 data/）
python scripts/generate_dataset.py --out data \
    --n_pretrain 1200 --n_eval 240 --T 6 --img_size 64

# 第 2 步: 用离线数据集预训练（mini 配置，CPU 约 30 分钟）
python -m pissm.train_pretrain --config configs/offline_mini.yaml

# 第 3 步: 验证（冻结特征原型评测 + 少样本微调对比）
python scripts/validate_offline.py \
    --ckpt checkpoints_offline/pissm_pretrained.pt \
    --config configs/offline_mini.yaml \
    --eval_npz data/eval_real.npz --shots 5 20
```

参考结果（n_pretrain=400/10epoch 的沙箱复现）：少样本微调预训练初始化
5-shot 0.513 / 20-shot 0.517，从头训练 0.473 / 0.442；预训练数据量越大
增益越明显（1200 序列在线模式下达 +19.5/+32.2 pp，见 docs/实验记录.md）。

正式规模训练请使用 `configs/default.yaml`（在线生成数据，无需第 1 步），
或将第 1 步 `--n_pretrain` 调至 20000 以上。另有在线模式验证脚本
`pissm/eval_fewshot.py` 与 `scripts/finetune_fewshot.py` 可用。

## 仿真器物理设定

- 点散射模型：每类目标（战斗机/舰船/卫星/导弹）由带幅度的散射中心模板构成，
  实例化时加入位置/幅度扰动、随机翻转；
- 回波合成：`E[n,m] = Σ_k A_k exp(-j4π(fc+f_n)r_k(θ+ωτ_m)/c)`，
  基带项承载距离向、载频项承载多普勒（横向）信息，二维 FFT 得 RD 图像；
- **sim 域**：理想成像（预训练燃料）；**real 域**：乘性斑点 + 残余相位误差散焦
  + 加性热噪声 + 8% 随机缺采样（模拟实测退化，用于适配与评测）；
- 机动模型：帧间转角 = 匀速分量 + 随机游走扰动（对应课题风险预案一：
  非匀速机动下"帧序预测"可退化为"相对姿态差回归"）。

## 代理任务设计要点

1. **相邻帧对比**：正对 = 同序列相邻帧（姿态微小变化的"免费正样本"），
   负对 = 批内其他序列帧 + 同序列远隔帧（|Δt|>2）。无需任何人工增广，
   规避了 SAR 自监督中"增广破坏散射特性"的争议；
2. **帧序预测**：输入按随机排列乱序的帧序列（帧 token 乱序、位置嵌入不动），
   逐位置预测原始帧索引的 T 类分类，迫使模型学习散射随转动的演化规律；
3. **ASC 引导掩码**：由散射中心真值生成物理显著性图，高散射 patch 以
   `boost` 倍概率被掩码，重建目标为逐 patch 归一化像素，损失可用 ASC
   幅度加权（`asc_gamma`，设 0 即消融）。对无真值的真实数据，
   `physics.detect_scatterers` 提供近似 CFAR 散射点检测以生成伪显著性图。

## 消融开关（论文实验设计）

| 消融项 | 操作 |
|---|---|
| 无物理引导掩码 | `configs: boost=1.0`（退化为 MAE 均匀掩码）|
| 无 ASC 损失加权 | `asc_gamma=0` |
| 仅单帧（无序列） | `data: T=1`（对比/排序损失自动失效，可注释对应权重）|
| 无相邻帧对比 | `loss_weights: contrast=0` |
| 无帧序任务 | `loss_weights: order=0` |
| 机动鲁棒性 | `data: maneuver=false` 训练、`true` 测试 |

## 接入真实实测图片（pissm/real_data.py）

```bash
# 目录组织: 类别名/序列名/帧图片（同一观测窗口的连续帧）
#   my_real_data/fighter/seq001/f000.png f001.png ...
# 1) 一键转换（建议先加 --preview 检查处理效果，会输出 real_data_preview.png）
python scripts/prepare_real_data.py --root my_real_data \
    --out data/real_observed.npz --preview

# 2) 与仿真数据完全相同的验证/微调命令
python scripts/validate_offline.py \
    --ckpt checkpoints_offline/pissm_pretrained.pt \
    --config configs/offline_mini.yaml \
    --eval_npz data/real_observed.npz --shots 5 20
```

处理链路：灰度化 → 能量阈值裁剪居中（`--no_crop` 可关）→ 缩放 64×64 →
对数压缩 + min-max 归一化（与仿真器完全一致）→ 近似 CFAR 散射点检测生成
伪显著性图（`--sal_k` 调节，噪声大时 3.0~3.5）。
注意：本流程假设输入已是**成像后**的 ISAR 图片；若为原始回波，需先完成
运动补偿与 RD 成像。无类别标签时把序列放在 `unknown/` 目录下即可
（仅用于域适配/特征提取）。

## mini 规模验证结果

已完成的端到端验证（详见 [docs/实验记录.md](docs/实验记录.md)）：

- 三类代理任务均收敛，少样本微调（real 域）5-shot **0.539** / 20-shot **0.661**，
  而随机初始化从头训练仅 0.344 / 0.339——预训练增益 **+19.5/+32.2 个百分点**；
- 调试中发现并修复了三个有价值的设计陷阱（乱序-对比任务耦合 bug、
  同序列远隔帧作负样本导致特征"姿态编码化"、预训练类别过少导致同类碰撞），
  可直接作为论文消融实验素材；
- 随机初始化特征在简单任务上是强基线，主实验须采用少样本微调/
  跨域/开集等有区分度的评测协议。

![mini 实验结果](docs/results_mini.png)

## 部件分割（单类目标，pissm/segmentation.py）

```bash
python scripts/train_segmentation.py \
    --ckpt checkpoints_offline/pissm_pretrained.pt \
    --config configs/offline_mini.yaml \
    --label 2 --n_train 400 --n_test 60 --epochs 15 \
    --train_domain mix --out seg_vis.png
```

- `--label` 选择目标类别（0战斗机/1舰船/2卫星/3导弹，单类目标就用一类）；
- 仿真器自动渲染部件掩码真值（零标注成本），解码头为 UPer 式轻量结构，
  可直接加载 PISSM 预训练骨干，`--freeze_backbone` 适合标注极少场景；
- `--train_domain mix`（sim+real 混合）对实测退化至关重要——实验对比：
  仅 sim 训练 real 域 mIoU 仅 0.45，混合域训练后 **0.77**（sim 域保持 0.77）；
- 部件定义在 `pissm/seg_templates.py`，可改成你自己的部件划分；
- 实测掩码微调：用 `scripts/prepare_real_data.py` 转换图片后，
  将人工勾画的 mask 组织为同形 ndarray 传给 `SegDataset` 即可。
- 推理可视化示例见 `docs/seg_vis_sim.png` 与 `docs/seg_vis_real_mix.png`。

## 已知局限（诚实声明）

- 点散射仿真无法复现爬行波、多次散射、材料涂层等复杂机制，
  sim→real 域差被低估，结论外推到真实数据需重验证（综述风险预案三）；
- S6 块为纯 PyTorch 简化实现，追求可读性而非极致性能，
  大规模训练可替换为官方 `mamba-ssm` CUDA 内核；
- ASC 显著性图当前按参考帧生成后复制到各帧（未逐帧随姿态旋转），
  更精确的版本应逐帧投影散射中心。




## 第一阶段：自监督预训练（需要大量无标注数据）

这是 PISSM 的"燃料"阶段——**不需要任何标注**，只需要大量 ISAR 图片序列就行。

| 规模 | 序列数 | 帧数 (T=6) | 说明 |
|------|--------|-----------|------|
| **mini 冒烟测试** | 400 条 | ~2,400 张 | 仅验证路线可行，预训练增益弱（[README L59](file:///e:/pissm/README.md#L59-L61)） |
| **mini 推荐** | 1,200 条 | ~7,200 张 | README 三步流程默认值，CPU 约 30 分钟，real 域 5-shot 就能 +19.5pp（[实验记录 L34-L35](file:///e:/pissm/docs/%E5%AE%9E%E9%AA%8C%E8%AE%B0%E5%BD%95.md#L34-L35)） |
| **正式规模** | ≥20,000 条 | ≥120,000 张 | [default.yaml](file:///e:/pissm/configs/default.yaml#L2-L5) 配置，建议用 GPU |
| **论文目标** | ~数万类 × 多姿态 | **≥20 万帧** | [实验记录 L97](file:///e:/pissm/docs/%E5%AE%9E%E9%AA%8C%E8%AE%B0%E5%BD%95.md#L97-L99)，预训练数据量越大增益越明显 |

> 💡 **注意**：这是**序列数**，每条序列包含 T=6 帧连续图（同一目标、相邻姿态）。真实数据按目录组织：
> ```
> 类别/序列名/帧图片
> fighter/seq001/f000.png f001.png ... f005.png
> ```
> 没有类别标签就放 `unknown/seq001/` 下，预训练完全不挑标签。

---

## 第二阶段：下游少样本微调（需要少量标注）

预训练完，在你关心的具体任务上微调，这才叫"小样本"：

### 1) 分类/识别任务（每类需要的标注量）

| 设置 | **每类标注图片数** | 说明 |
|------|-------------------|------|
| **5-shot** | 5 张 / 类 | mini 实验已验证，准确率 0.539（比从头训高 +19.5pp） |
| **20-shot** | 20 张 / 类 | mini 实验准确率 0.661（比从头训高 +32.2pp） |
| 线性探测 | 0 张（冻结骨干） | 直接用特征做最近邻分类，作为参考基线 |

验证集（测试集）建议：**每类 60 张**（[finetune_fewshot.py L47-L49](file:///e:/pissm/scripts/finetune_fewshot.py#L47-L49) 默认 `n_test=60`），保证评测稳定。

### 2) 部件分割任务（每张需要画掩码）

| 训练方式 | 真实标注量 | real 域 mIoU |
|---------|-----------|-------------|
| 纯仿真（零标注） | **0 张** | 约 0.45（凑合能用） |
| sim+real 混合微调 | **30~100 张** | 约 **0.77**（推荐） |

对应 [README L149-L152](file:///e:/pissm/README.md#L149-L152)。脚本默认 `--n_train 400`（仿真+真实混合）、`--n_test 60`（[train_segmentation.py L50-L51](file:///e:/pissm/scripts/train_segmentation.py#L50-L51)）。

---

## 快速决策表

根据你的实际情况直接对号入座：

| 你的情况 | 预训练数据 | 下游标注（每类） | 验证集 |
|---------|-----------|----------------|--------|
| **我就是跑跑看效果** | 仿真生成 1,200 序列（一键命令） | 5~20 张分类标注 | 每类 60 张 |
| **有真实数据，想做分类** | 真实无标注序列 ≥1,200 条，或仿真 + 真实混着预训练 | 5~20 张分类标签 | 每类 60 张 |
| **想做部件分割** | 仿真预训练即可，真实数据可选 | 30~100 张掩码 | 60 张掩码 |
| **追求论文级指标** | ≥20,000 条序列（仿真+真实），越多越好 | 20 张+，或按标准 benchmark | 按 benchmark 标准 |

如果你的真实数据比较少，**优先用仿真器预训练（几乎零成本），再拿少量真实数据做下游微调**——这正是 PISSM 设计的初衷。