CBT_project/README.md

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）：

# 預處理（全部 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%）。