Metadata-Version: 2.4
Name: gliomamatch
Version: 0.1.0
Summary: 脑部胶质瘤以图搜图 + 分级评分：Triplet 检索 + 13 头多任务分类 + 前景敏感分割 + A/B 博弈出分（npz 输入，训练 & 推理）
Author: Liu Enyou
License-Expression: MIT
Project-URL: Homepage, https://github.com/liuenyou/gliomamatch
Keywords: glioma,image-retrieval,triplet-loss,medical-imaging,3d-cnn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: torch>=2.0
Requires-Dist: scipy>=1.9
Provides-Extra: config
Requires-Dist: pyyaml>=6.0; extra == "config"
Provides-Extra: xgb
Requires-Dist: xgboost>=2.0; extra == "xgb"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: xgboost>=2.0; extra == "all"

# GliomaMatch — 脑部胶质瘤 以图搜图 + 分级评分（训练 & 推理工程）

三维 MRI 胶质瘤病例的**相似病灶检索（以图搜图）+ 分级/良恶性评分**工程，
技术路线来自《以图搜图以及结节良恶性》分享（npz 输入版，目录化工程）。

## 目录结构

```
foryibaobisai/
├── gliomamatch/               # 【核心包】训练 & 推理库
│   ├── data/                  #   npz 读取、中心 crop、三维旋转增强、P-K 采样器
│   │   ├── npz_io.py          #     load_npz / zscore（labelset 由首个文件决定）
│   │   ├── transforms.py      #     病灶中心 crop、三维旋转(Rx·Ry·Rz)、翻转
│   │   ├── dataset.py         #     NpzDataset、collate
│   │   └── sampler.py         #     PKSampler（P 类 x K 例）
│   ├── models/                #   3D-ResNet -> 128 维向量 + 多头分类头 + 前景敏感分割头
│   ├── losses/                #   Triplet（在线难样本挖掘）、Dice 辅助
│   ├── engine/                #   训练循环、Recall@K 检索指标
│   ├── inference/             #   编码建库、以图搜图 query、出分预测
│   ├── malignancy/            #   A/B 数据集博弈：KNN 修标签、最近邻距离打分
│   ├── config.py / cli.py     #   配置加载（yaml/json）、CLI
│   └── __main__.py            #   python -m gliomamatch ...
├── scripts/                   # 【命令薄封装】等价 python -m gliomamatch <cmd>
│   ├── train.py / build_index.py / query.py / eval.py / predict.py
├── configs/                   # 【默认配置】键名 == 命令行参数名
│   ├── default.yaml           #   训练
│   └── predict.yaml           #   A/B 博弈出分
├── tools/
│   ├── make_synthetic_npz.py  # 生成合成数据供联调
│   ├── make_mock_packed_npz.py # 生成「打包 npz」mock（整个数据集一个文件）
│   ├── unpack_big_npz.py      # 打包 npz -> 每例一个 npz（如 cv3_kaikou_train.npz）
│   └── labels_from_csv.py     # 标注表 csv -> npz labels + head_dict.json
├── tests/
│   └── smoke_test.py          # CPU 端到端冒烟（全流程）
├── standalone/
│   └── gliomamatch_single.py  # “单文件云端粘贴”版本（与本包功能一致，保留）
├── data/
│   └── README_DATA.md         # 数据目录与 npz 样例
└── requirements.txt
```

## 数据约定（npz，每个病例一个文件）

```python
np.savez("case_001.npz",
         image=img,          # (D,H,W) 单模态 或 (C,D,H,W) 多模态
         labels=np.array({"grade": 2, "necrosis": 1, "margin": 0}, dtype=object),
                             # 多头标签！某头没标注就不要写（训练时自动掩码）
         seg=seg,            # 可选 (D,H,W)，>0 为病灶 -> 启用前景敏感分割
         )
# 目录根再放一个 head_dict.json：{"grade": 5, "necrosis": 2, "margin": 2, ...}
# 有标注表 csv 时用：python tools/labels_from_csv.py --csv ... --npz_dir data/train
```

目录：`data/train/`（金标准 A）、`data/train_doctor/`（主观标签 B，可选）、`data/val/`、`data/test/`。
兼容旧单标签格式（`label`/`labelset`）。完整说明见 [data/README_DATA.md](data/README_DATA.md)。
Triplet 的「同类」由 `--triplet_head` 定义（默认第一个头，建议 `grade`）。

## 快速开始

```bash
pip install -r requirements.txt

# 0. 生成本地通路验证数据（可选）
python tools/make_synthetic_npz.py --out demo_data --train 60 --val 12 --test 12

# 1. 训练（Triplet 在线难样本挖掘 + 分类 + 前景分割）
bash train.sh                                           # 按 configs/default.yaml 训练
EPOCHS=50 BATCH_SIZE=16 bash train.sh                   # 环境变量覆盖参数
SMOKE=1 bash train.sh                                   # 先用合成数据 2 epoch 试跑
LOG=1 bash train.sh --mining batch_semi_hard            # 写日志 + 透传额外参数
# 等价：python scripts/train.py --config configs/default.yaml
#      python -m gliomamatch train --config configs/default.yaml

# 2. 建库（标准病例库全库编码 -> 向量索引 npz）
python scripts/build_index.py --ckpt runs/exp1/best.pt \
    --gallery_dir data/train --out runs/exp1/index.npz

# 3. 以图搜图：Top-K 相似病例 + 距离打分
python scripts/query.py --ckpt runs/exp1/best.pt \
    --index runs/exp1/index.npz --case data/test/case_000.npz --topk 10

# 4. 检索指标：R@1/R@5/R@10/top1/knn5
python scripts/eval.py --ckpt runs/exp1/best.pt --val_dir data/val

# 5. 出分（三选一；xgb = A/B 博弈 -> KNN修标签(逐头) -> XGBoost(逐头)）
python scripts/predict.py --config configs/predict.yaml --mode knn
python scripts/predict.py --config configs/predict.yaml --mode head
python scripts/predict.py --config configs/predict.yaml --mode xgb \
    --set_b_dir data/train_doctor
```

## PPT → 代码位置

| PPT 章节 | 实现位置 |
|---|---|
| slide 3/4 以图搜图（encode->距离） | [gliomamatch/models/net.py](gliomamatch/models/net.py) `encode`，[gliomamatch/inference/retrieval.py](gliomamatch/inference/retrieval.py) |
| slide 5/6 Triplet / Hard·SemiHard·Easy | [gliomamatch/losses/triplet.py](gliomamatch/losses/triplet.py)（日志实时打印三类计数） |
| slide 7 病灶居中 crop / 占比小 | [gliomamatch/data/transforms.py](gliomamatch/data/transforms.py) `lesion_center`+`center_crop` |
| slide 8 三维旋转增强 | 同文件 `rotation_matrix_3d` + `rotate3d` + `random_flip` |
| slide 9 网络与 loss 设计 | [gliomamatch/models/net.py](gliomamatch/models/net.py) + [gliomamatch/engine/trainer.py](gliomamatch/engine/trainer.py) |
| slide 10/11 前景敏感 | `seg_head` + [gliomamatch/losses/dice.py](gliomamatch/losses/dice.py) |
| slide 12/13 A/B 博弈 + KNN修标签 + 距离打分 | [gliomamatch/malignancy/](gliomamatch/malignancy/)（`knn.py` 修正；`scoring.py` `1/(0.5+Reg·d)`） |
| slide 14 encode -> V -> XGBoost | [gliomamatch/inference/predictor.py](gliomamatch/inference/predictor.py) `--mode xgb`（无 xgboost 自动退 softmax） |

## 本地验证

```bash
python tests/smoke_test.py                          # 全流程 CPU 冒烟（~1 分钟）
python tests/smoke_test.py --venv .venv/bin/python  # 用虚拟环境跑
```

## 云端使用

1. **整包上传**：AutoDL / Kaggle / 平台直接上传本目录，`pip install -r requirements.txt` 后使用。
2. **单文件粘贴**：要粘成单文件用 [standalone/gliomamatch_single.py](standalone/gliomamatch_single.py)
   （上一版，功能与本包一致，用法 `python gliomamatch_single.py train ...`）。

仅用于科研与比赛，不构成临床诊断。
