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 工程默认路径：

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

当前默认权重源路径：

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

## CLI Usage

```bash
/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](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

```python
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`。