README_local.md

SAMIHS ICH Segmentation Package

本目录封装当前项目中正在使用的 SAMIHS 出血分割模型，提供一个稳定的单例接口：输入 3D brain CT NIfTI，输出二值化出血 label NIfTI。

Contents

Path	Description
segment_ich.py	单个 3D CT NIfTI 到 binary mask NIfTI 的 CLI/API wrapper。
weights/SAMIHS_09170527_2_0.483.pth	当前使用的 SAMIHS 权重软链接。
scripts/run_segment_example.sh	命令行调用示例。
INPUT_SPEC.md	输入格式、灰度值分布、方向和 slice axis 要求。

依赖的原始 SAMIHS 工程默认路径：

/data/wxh/Medical/to_cfff/metrics/brain_bleed/SAMIHS

当前默认权重源路径：

/data/wxh/Medical/to_cfff/metrics/brain_bleed/SAMIHS/ckpts/Extended_add_neg_210/SAMIHS_09170527_2_0.483.pth

CLI Usage

/data/wxh/miniconda3/envs/flowmatching/bin/python \
  /data/wxh/Medical/samihs_ich_segmentation_package/segment_ich.py \
  --input /path/to/brain_ct.nii.gz \
  --output /path/to/brain_ct_ich_mask.nii.gz \
  --device cuda:0 \
  --batch-size 8 \
  --threshold 0.5

输出是与输入 shape/affine 一致的 uint8 NIfTI，取值为 0/1。

Input Requirements

详细要求见 INPUT_SPEC.md。重点如下：

• 输入必须是单个 3D CT NIfTI，.nii 或 .nii.gz。
• 不支持 DICOM 文件夹、4D NIfTI、多通道图像。
• 像素值应是有限数值，不能含 NaN/Inf。
• 推荐输入是与项目数据一致的轴位脑 CT，例如 /data2/gzk/256_standardized_brain_rescale/**/*.nii。
• wrapper 会逐 slice 做 0.5%-99.5% percentile clipping 和 min-max normalization，因此模型不直接使用绝对 HU 阈值。
• 默认 --slice-axis auto 会把最小维度作为 depth/slice 轴；如果输入不是这种排列，需要显式指定 --slice-axis 0/1/2。
• wrapper 不会根据 NIfTI affine 自动重排方向；模型使用的是数组切片顺序。输入方向应与项目标准 CT 一致。

Python API

from pathlib import Path
from segment_ich import segment_nii

metadata = segment_nii(
    input_nii=Path("/path/to/brain_ct.nii.gz"),
    output_nii=Path("/path/to/brain_ct_ich_mask.nii.gz"),
    device="cuda:0",
    batch_size=8,
    threshold=0.5,
)
print(metadata)

Method

1. 读取 3D NIfTI。
2. 自动选择 slice axis：默认选择最小维度作为 depth/slice 维度；也可用 --slice-axis 0/1/2 显式指定。
3. 对每个 2D slice 做 percentile clipping，默认 0.5% 到 99.5%，再 min-max normalize 到 [0,1]。
4. resize 到 1024x1024，按原 SAMIHS 推理约定做 rot90 方向校正。
5. SAMIHS 输出 logits，sigmoid 得概率图。
6. 概率图旋回并 resize 回原始 slice 尺寸。
7. prob >= 0.5 得 binary mask，堆回原始 3D shape。

Important Parameters

Parameter	Default	Meaning
--threshold	0.5	概率二值化阈值。
--encoder-input-size	1024	SAMIHS 2D encoder 输入尺寸。
--batch-size	8	slice-level batch size；1024 输入下该值在当前 44GB GPU 上稳定。
--slice-axis	auto	slice/depth 轴；默认取最小维度。
--no-rotate	off	关闭原 SAMIHS 推理中的 rot90 方向校正，一般不建议。

Notes

• 该模型是 2D slice segmentation，不是 3D UNet；3D mask 是逐 slice 推理后堆叠得到。
• 权重文件在本包中是软链接，避免重复占用 359MB。如需迁移到其他机器，需要同时复制原始 SAMIHS 工程和权重文件。
• 如果出现 CUDA OOM，优先减小 --batch-size，例如 4 或 2。