andreasneil13/Transparent-Deauville-score

# 自动化 Deauville 评分流水线 (FDG PET/CT) 一个用于淋巴瘤 **Deauville 治疗反应评分** 的自动化流水线。 该流水线基于配对的纵向 FDG PET/CT 检查数据。给定一个治疗周期内的基线和一次或多次 随访 PET/CT 检查，该流水线会为每对连续的检查生成一个 **Deauville 评分 (1–5)**，并提供每个病灶的细分详情、SUV 参考值和审核标记。 ## Deauville 5 分制量表 | 评分 | 解释 | |-------|----------------| | 1 | 无残留摄取 | | 2 | 摄取 ≤ 纵隔血池 | | 3 | 摄取 > 纵隔，但 ≤ 1.4× 肝脏 SUVpeak | | 4 | 摄取 > 1.4× 且 ≤ 2× 肝脏 SUVpeak | | 5 | 摄取 > 2× 肝脏 SUVpeak，或出现新病灶 | ## 流水线概述 该流水线在关键路径上运行九个阶段。分割/对齐和 病灶检测作为两个独立的分支运行，并在匹配和评分之前合并。 ``` Inputs (DICOM PET/CT) | BRANCH A (segmentation -> alignment) BRANCH B (lesion detection) ----------------------------------- -------------------------- [1] CT segmentation (TotalSegmentator) [5] lesion detection [2] derived masks (deep learning, nnU-Net) |- [3] liver VOI |- [4] mediastinal (blood-pool) VOI |- [6] alignment stage 1 (organ-wise ICP) | [7] alignment stage 2 (dense displacement field) | +---------------- MERGE -----------------+ | [8] lesion matching (follow-up -> baseline) | [9] Deauville scoring (per-lesion + pair aggregation) | Deauville result (JSON + CSV) ``` | 阶段 | 描述 | |-------|-------------| | 1. 分割 | 通过 TotalSegmentator 生成多器官 CT mask | | 2. 派生 mask | 区域分区与联合 mask | | 3. 肝脏 VOI | 肝脏 SUVpeak 参考 (1 mL 球体) | | 4. 纵隔 VOI | 胸主动脉血池参考 | | 5. 病灶检测 | 全身 PET/CT 病灶分割 | | 6. 对齐阶段 1 | 基于器官的 ICP (刚体/仿射变换) | | 7. 对齐阶段 2 | 密集 Laplace/Jacobi 位移场 | | 8. 病灶匹配 | 随访与基线病灶对应关系 | | 9. Deauville 评分 | 单病灶评分 + 检查对汇总 | ## 安装 要求 Python 3.10+。 ``` git clone cd deauville-pipeline-public python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` ### 外部依赖 (未打包) | 依赖 | 用途 | 备注 | |------------|---------|-------| | [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) ≥ 2.4 | CT 多器官分割 | 通过 `requirements.txt` 安装 | | 深度学习病灶模型 (nnU-Net, autoPET-3) | 阶段 5 病灶检测 | **外部依赖** — 需单独克隆模型仓库并下载权重 | | PyTorch + CUDA | GPU 加速 | 可选；支持 CPU 回退 | 病灶检测模型及其权重**不**在此处分发。请从其原始来源获取， 并将权重放置在配置预期的位置 (一个本地的 `models/` 目录，该目录已被 git 忽略)。 ## 用法 ``` / └── / └── / ├── Baseline/ │ ├── CT/ # DICOM series │ └── PET/ ├── FU1/ │ ├── CT/ │ └── PET/ └── FU2/ ... ``` 运行完整流水线： ``` python -m src.cli.run_pipeline -i -o ``` 常用选项： ``` # dense-field 对齐阶段的 GPU 加速 python -m src.cli.run_pipeline -i -o --device cuda # 在不运行的情况下预览计划 python -m src.cli.run_pipeline -i -o --dry-run # 限制到特定患者 python -m src.cli.run_pipeline -i -o --patients ``` ### 输出 对于每对检查，流水线会写入： - `/deauville//deauville_result.json` — 完整检查对结果 (包含两项评分、参考值、标记和警告) - `/deauville//lesion_deauville.csv` — 单病灶表格 - `/deauville_summary.{json,csv}` — 每对检查一行 结果报告包含两项评分：`final_deauville_score` (主要评分，包含新病灶规则) 和 `uptake_based_deauville_score` (仅基于摄取，用于审核)。 ## 仓库结构 ``` src/ ├── cli/ # command-line entry points (run_pipeline.py) ├── data/ # dataset discovery, manifests, reports ├── io/ # DICOM / image loading ├── qc/ # input quality control ├── segmentation/ # TotalSegmentator integration, derived masks ├── voi/ # liver and mediastinal reference VOIs ├── quantification/ # SUV / SUVpeak computation ├── lesion_detection/ # deep-learning lesion segmentation ├── alignment/ # two-stage registration (ICP + dense field) ├── alignment_qa/ # alignment quality metrics ├── matching/ # follow-up to baseline lesion matching ├── scoring/ # Deauville decision logic and pair aggregation ├── interpretation/ # optional pair-level response interpretation ├── exclusion/ # physiological-uptake exclusion rules ├── hotspots/ # uptake hotspot extraction ├── diagnostics/ # visualisation and audit helpers └── models/ # dataclasses / domain models ``` ## 许可证 基于 [MIT 许可证](LICENSE) 发布。 ## 免责声明 本软件仅供研究和教育目的使用。尚未经过临床验证，也未获批准用于任何诊断或治疗决策。使用风险由您自行承担。

标签：Vectored Exception Handling, 凭据扫描, 逆向工具