# CBT_project（Cortical Bone Trajectory）

在腰椎 CT（L1–L5）上自動規劃椎弓根螺絲（pedicle screw）軌跡的研究程式：把螺絲建模為圓柱體，用 PSO / DE / Nelder-Mead 最佳化在骨頭分割結果上評分，求得每節脊椎左/右最佳螺絲的位置、角度與尺寸，再映回 native CT 空間輸出可視化結果。

## 管線

```
CTSpine1K 原始 CT + label
        │
        ▼
xfr_preprocess.py          裁切 / 0.5mm 重取樣 / 方向正規化
        │                    （symmetry plane、upper endplate plane）
        ▼
xfr_pso.py / xfr_de.py     每 level 左/右螺絲軌跡最佳化（GPU）
        │                    圓柱 × 骨頭 mask 評分（皮質骨、VBODY、
        │                    tip 處罰、入口端 0.5mm 豁免）
        ▼
xfr_check_spinous.py       棘突檢查 / 驗證
xfr_cbt_native.py          映回 native CT → cbt.nii.gz + X 光投影片
```

- 最佳化參數：`pos = [z, y, x, azimuth°, altitude°, 直徑 mm, 長度 mm]`，直徑/長度吸附到臨床允許值。
- 評分函數：`core/objective.py` 的 `OptimizationContext` + `make_objective_function[_xfr]`。
- 映回 native 以各 volume 的 `transform.json` 仿射鏈為單一事實來源（`imaging/transforms.py`）。

## 環境

- Python 環境管理：**pixi**（`pixi.toml`；conda env `cbt` 已棄用）
- 首次建置 / 更新：`pixi install`
- 主要依賴：`torch`（CUDA 12.6 wheel）、`SimpleITK`、`scipy`、`scikit-learn`、`numpy`、`nibabel`、`tinydb`、`pyswarm`、`matplotlib`
- 多 GPU 批次：`run_all_cases.py --gpu N --total_gpus M`

## 執行

入口腳本皆有 pixi task（`pixi run <task> -- <args>`，見 `pixi.toml` 的 `[tasks]`）；或 `pixi shell` 後直接執行（腳本 shebang 為 `#!/usr/bin/env python`）：

```bash
# 預處理（全部 volume；或 --max-images 取前 N 支）
pixi run preprocess -- [--max-images N] [--output-dir DIR]

# 最佳化（缺省跑標準化目錄內所有 volume 的 L1–L5）
pixi run pso -- [volume_id [level]] [--screw-shape cone|cylinder]
pixi run de  -- [volume_id [level]]

# 棘突檢查
pixi run check-spinous

# 映回 native CT（run_id 為最佳化輸出的日期時間目錄）
pixi run cbt-native -- <run_id> [volumes...] [--date D]
```

資料路徑（CTSpine1K 原始檔、標準化輸出、最終輸出）hardcode 在各 `xfr_*.py` 頂部，跨機器/世代執行時先確認這些常數；元數據存於 `xfr_image_metadata.json`（TinyDB），日誌在 `logs/`，結果 CSV 在 `results/`。

## 目錄結構

| 路徑 | 說明 |
|---|---|
| `core/` | 圓柱生成（torch）、中心線相交、評分（`scoring.py`）、objective、optimizer（PSO/DE/NM） |
| `imaging/` | NIfTI I/O、預處理、重取樣、仿射、方向正規化、分割、transform 鏈 |
| `visualization/` | 四視角螺絲圖（`res_bone_figure`）、3D 繪圖、圓柱存 NIfTI / overlay 到 CT |
| `config/` | `constant.py`（LABEL_MAP、螺絲尺寸、OVERLAP_THRESH、spacing）、`device.py` |
| `utils/` | NFS 重試、唯一檔名、輔助函數 |
| `xfr_*.py` | 現世代管線入口腳本 |
| `run_*.py` | 舊世代多 GPU 批次 / benchmark 腳本 |
| `references/` | 參考文獻 PDF |
| `experiment.ipynb` | 實驗 notebook |

## 輸出

- 每 volume 的螺絲：標準化目錄下 `Output/<run_id>/<vol>/` 的四視角 PNG 與 CSV。
- Native 空間：`Output_dir/<run_date>/<vol>/cbt.nii.gz`（label 1–10 = L1L…L5R）與 x-ap / x-lat / z-ap / z-lat X 光投影片（含螺絲標註版）。
- 驗收標準見 `xfr_cbt_native.py` docstring（螺絲柱 in-label ≥ 92%、2-voxel 膨脹 ≥ 98%）。