# segforge

**Repository Path**: Eason596/segforge

## Basic Information

- **Project Name**: segforge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SegForge

[English](https://gitee.com/Eason596/segforge/blob/main/README.md) | [中文](https://gitee.com/Eason596/segforge/blob/main/README.zh-CN.md)

[nnU-Net v2](https://github.com/MIC-DKFZ/nnUNet) 扩展框架：自定义 Trainer、网络工厂与查询命令。

**推荐用法：** 把 SegForge 当库安装；`nnUNet_extTrainer` 指向已安装的内置 Trainer，
项目专用 `-tr` 放在自己的实验目录里（不要为每个数据集 fork 一份 SegForge）。

## 环境要求

- Python ≥ 3.10
- [nnU-Net v2](https://github.com/MIC-DKFZ/nnUNet)（`nnunetv2≥2.8.1`），并已配置 `nnUNet_raw` / `nnUNet_preprocessed` / `nnUNet_results`

## 推荐配置

### 1. 当库安装

```bash
# 从 PyPI 安装（推荐给使用者）
pip install segforge
pip install "segforge[neuron]"     # NeuronSWC / npu
pip install "segforge[mamba]"      # U-Mamba / LightM / LKM / nnMamba
pip install "segforge[segmamba]"   # SegMamba BiMamba-v3
pip install "segforge[opaque]"     # Nuitka；把项目网络 .py 编成 .so
# pip install "segforge[full]"     # mamba + segmamba + scipy / scikit-image

# 本地开发 SegForge 本身
pip install -e ".[dev]"
```

Extras 说明见 [docs/networks.zh-CN.md](https://gitee.com/Eason596/segforge/blob/main/docs/networks.zh-CN.md#可选依赖)。

### 2. 挂接 nnU-Net（内置 + 可选项目 Trainer）

```bash
# 已安装包中的内置 Trainer
export SEGFORGE_TR="$(python -c 'import segforge.training.nnUNetTrainer as t; print(t.__path__[0])')"

# 推荐：再拼上项目自己的 trainers 目录
export nnUNet_extTrainer="${SEGFORGE_TR}:/path/to/my_project/trainers"
# 只用内置：
# export nnUNet_extTrainer="${SEGFORGE_TR}"
```

（Linux/macOS 用 `:`，Windows 用 `;`。）

### 3. 列出并训练

```bash
segforge_list_trainers -s external    # SegForge 内置 + 项目 Trainer
nnUNetv2_train DATASET_ID 3d_fullres 0 -tr YourProjectTrainer
```

**二值导出 ``{0, 255}``**（分割任务；写出时 remap，大数据量无需二次读写）：

```bash
# 参数与 nnUNetv2_predict 相同
segforge_predict_binary255 -d DATASET_ID -c 3d_fullres -f 0 -i INPUT -o OUTPUT -tr YourTrainer
```

**距离 / soft-map 回归推理**（默认 float32 连续场；勿用官方 predict，会被 uint8 截断）：

```bash
# 连续 soft map（约 [0,1]，默认 sigmoid）
segforge_predict_regression -d DATASET_ID -c 3d_fullres -f 0 -i INPUT -o OUTPUT \
  -p nnUNetPlans_reg -tr nnUNetDistanceTrainer

# 同时存连续场 .npz
segforge_predict_regression ... --save_probabilities

# 阈值二值图 {0,255} 或 {0,1}（可与 --save_probabilities 同用）
segforge_predict_regression ... --threshold 0.5 --binary-value 255
segforge_predict_regression ... --threshold 0.5 --binary-value 1
```

项目 Trainer 通过普通 `import` 使用 SegForge 的 bases / mixin / 现有 Trainer；
除非要向上游贡献，**不要**写进 SegForge 源码树。详见
[docs/customizing.zh-CN.md](https://gitee.com/Eason596/segforge/blob/main/docs/customizing.zh-CN.md)。

## 快速开始

```bash
segforge_list_trainers -s external
segforge_list_mixins -g optim
segforge_list_networks -b monai

nnUNetv2_train DATASET_ID 3d_fullres 0 -tr UNetTrainer
```

`segforge_list_trainers` / `segforge_list_mixins` 的 **NOTES** 列来自类 docstring
（摘要 + 可选的 ``paper:`` / ``dataset:``；``-v`` 显示全文）。
`segforge_list_networks -v` 会打印 module / builder 详情。

## 网络

Builder、`-tr`、CUDA / 2D–3D 限制、SegMamba BiMamba 说明见
[docs/networks.zh-CN.md](https://gitee.com/Eason596/segforge/blob/main/docs/networks.zh-CN.md)。

近期新增：MedNeXt-v2、SegMamba（`[segmamba]`）、SegFormer3D、D-LKA（2D）、
UNETR++、CMUNeXt（2D）。

## Trainer 结构

| 路径 | 作用 |
|------|------|
| `training/bases/arch.py` | 继承骨架（`NoDeepSupervisionTrainer`、`FullResTargetDeepSupervisionTrainer`、`MonaiDeepSupervisionTrainer` 等） |
| `training/bases/mixins/` | 可选配方（geometry / optim / loss / benchmark） |
| `training/nnUNetTrainer/` | 公开可跑的 `-tr` |

**命名建议：** `Model[_Patch][_Opt][_LR][_Schedule]` — 类名写清改了什么，
不要用论文数据集当类名；出处放进 docstring 的 `paper:` / `dataset:`。

**超参：** 用 `FixedHyperMixin`（或继承它的 Adam* mixin）设置
`fixed_initial_lr` / `fixed_weight_decay` / `fixed_num_epochs`。

**组合顺序：** mixin 在左，架构 trainer 在右：

```python
from segforge.training.bases import (
    AdamWCosineNoClipMixin,
    FixedPatchMixin,
    NoDeepSupervisionTrainer,
    SoftclDiceCELossMixin,
    SystemBenchmarkMixin,
)

class FooTrainer_128_AdamW1en3_Cosine(
    AdamWCosineNoClipMixin, FixedPatchMixin, NoDeepSupervisionTrainer
):
    """Foo；patch 128；AdamW lr=1e-3 + cosine。

    paper: …
    """

    fixed_patch_size = 128
    fixed_initial_lr = 1e-3

class CoTr_clDice(SoftclDiceCELossMixin, CoTrTrainer_128):
    pass

class MedNeXtBench(SystemBenchmarkMixin, MedNeXtTrainer_S_kernel3):
    benchmark_patch_size = 128
```

（示例里的 `CoTrTrainer_128` / `MedNeXtTrainer_S_kernel3` 从对应 `nnUNetTrainer/` 模块导入。）

- **强制 patch：** 名字带尺寸且使用 `FixedPatchMixin`（如 `CoTrTrainer_128`、`VNetTrainer_96`）。
- **跟 plans：** 类名不带尺寸（如 `VNetTrainer`、`UNETRTrainer`）。

## 数据集转换

挑战赛 → nnU-Net raw 的脚本在 `segforge/dataset_conversion/`
（不在训练 import 路径上）。配置好 `nnUNet_raw` 后：

```bash
python -m segforge.dataset_conversion.Parse2022 -i /path/to/PARSE2022 -d 501
python -m segforge.dataset_conversion.LiTS2017 -i /path/to/LiTS2017 -d 502
python -m segforge.dataset_conversion.DRIVE -i /path/to/DRIVE -d 503
python -m segforge.dataset_conversion.AIIB2023 -i /path/to/AIIB2023 -d 504
python -m segforge.dataset_conversion.BTCV -i /path/to/RawData -d 505
# 神经元：image + SWC → mask 或 dist
# pip install "segforge[neuron]"   # 从 PyPI 安装 neuron-process-utils (npu)
python -m segforge.dataset_conversion.NeuronSWC --image /data/img --swc /data/swc -d 601 --label-type mask
python -m segforge.dataset_conversion.NeuronSWC --image /data/img --swc /data/swc -d 602 --label-type dist -t soft_centerline
# -d 必填（输出目录为 DatasetXXX_<Name>）
```

## 文档

- [Changelog](https://gitee.com/Eason596/segforge/blob/main/CHANGELOG.md)
- [网络与可选依赖](https://gitee.com/Eason596/segforge/blob/main/docs/networks.zh-CN.md)
- [自定义模型、损失与 Trainer 组合](https://gitee.com/Eason596/segforge/blob/main/docs/customizing.zh-CN.md)
- [距离图回归](https://gitee.com/Eason596/segforge/blob/main/docs/regression.zh-CN.md)
- [隐藏未发表网络源码（`.so`）](https://gitee.com/Eason596/segforge/blob/main/docs/opaque.zh-CN.md)
- English: [Networks & optional extras](https://gitee.com/Eason596/segforge/blob/main/docs/networks.md) · [Customizing](https://gitee.com/Eason596/segforge/blob/main/docs/customizing.md) · [Regression](https://gitee.com/Eason596/segforge/blob/main/docs/regression.md) · [Opaque compile](https://gitee.com/Eason596/segforge/blob/main/docs/opaque.md)

English: [README.md](https://gitee.com/Eason596/segforge/blob/main/README.md)

## 许可证

**GPL-3.0-only**，见 [LICENSE](https://gitee.com/Eason596/segforge/blob/main/LICENSE)。

SegForge 基于 nnU-Net 及第三方网络/损失实现；使用对应组件时请引用原论文。
部分第三方文件仍保留**上游原许可**（如 CoTr 中的 Apache-2.0 片段、CMUNeXt 的 MIT）；**整个 SegForge 发行物**按 GPL-3.0 分发。详见 [docs/networks.zh-CN.md](https://gitee.com/Eason596/segforge/blob/main/docs/networks.zh-CN.md#许可说明)。