README.md

---
library_name: ilex
tags:
- jax
- equinox
- ilex
- neuroimaging
- white
license: apache-2.0
license_link: https://www.apache.org/licenses/LICENSE-2.0
---

# TractSeg -- white matter bundle / endings segmentation (2D U-Net + 3-axis ensemble) -- TractSeg tract_segmentation v3 (42 bundles)

## Description

JAX / Equinox port of TractSeg (Wasserthal et al., *NeuroImage*
2018; github.com/MIC-DKFZ/TractSeg). A 2D U-Net with deep
supervision that, per slice, predicts binary masks for each
white-matter bundle (or each bundle's endpoint regions) from a
9-channel FOD-peak input volume. The upstream's canonical
inference path runs the per-slice forward on all three principal
slice orientations (axial, coronal, sagittal) and averages the
three resulting 3D mask predictions; the ilex
TractSegPipeline class wraps that end to end.

Two task variants ship in v0:
- tract_segmentation_v3 (42 bundles, the upstream's current
  default)
- endings_segmentation_v4 (72 endpoint regions)

Both share parameter-identical bodies (~37 M trainable
scalars); only the three 1x1 head Conv2ds at output_2,
output_3, and conv_5 differ in ``out_channels`` to match the
task's ``n_classes``.


## Intended use

Predict per-bundle binary masks for 42 white-matter bundles from a 9-channel FOD-peak input volume. The ``TractSegPipeline`` 3-axis ensemble produces a 4D ``(42, D, H, W)`` sigmoid probability volume; consumers threshold + run downstream tractography filtering. Zenodo record 3634539, epoch 266.

## Usage

```python
from ilex.models.tract_seg import TractSeg
model = TractSeg.from_pretrained('ilex-hub/tract_seg.tract-segmentation-v3.1')
```

## Authors

Wasserthal J., Neher P. F., Maier-Hein K. H. (MIC-DKFZ, German Cancer Research Center, Heidelberg University)

## Citation

Wasserthal J., Neher P. F., Maier-Hein K. H. (2018). TractSeg -- Fast and accurate white matter tract segmentation. NeuroImage 183, 239-253. doi:10.1016/j.neuroimage.2018.07.070.

### References

- Wasserthal J., Neher P. F., Maier-Hein K. H. (2018). TractSeg -- Fast and accurate white matter tract segmentation. NeuroImage 183, 239-253. doi 10.1016/j.neuroimage.2018.07.070.
- Wasserthal J., Neher P. F., Hirjak D., Maier-Hein K. H. (2020). Multiparametric mapping of white matter microstructure in 100,000 subjects from the UK Biobank.
- Upstream code, license, training scripts -- github.com/MIC-DKFZ/TractSeg (Apache-2.0).
- Upstream weights -- Zenodo records 3634539 (tract_segmentation v3, epoch 266) and 3518348 (endings_segmentation v4, epoch 220).

## License

HF Hub license tag: `apache-2.0`

**Effective terms:** Apache-2.0 (MIC-DKFZ) on both the network code (github.com/MIC-DKFZ/TractSeg) and the pretrained weights (Zenodo records 3634539 and 3518348). The ilex JAX / Equinox port code is separately licensed under Apache-2.0 / GPL-3.0.

Upstream license reference: https://www.apache.org/licenses/LICENSE-2.0

### Copyright

TractSeg is copyright (c) MIC-DKFZ (German Cancer Research
Center), Apache-2.0-licensed on both the network code
(github.com/MIC-DKFZ/TractSeg) and the pretrained weights
(Zenodo records 3634539 + 3518348). The ilex JAX / Equinox
port code is separately licensed under Apache-2.0 / GPL-3.0.


## Upstream source

Original weights / reference implementation: https://github.com/MIC-DKFZ/TractSeg

## Provenance

This artefact was produced by [ilex](https://github.com/hypercoil/ilex)'s
save/load pipeline. The architecture is implemented in
`ilex.models.tract_seg.TractSeg` and the weights have been converted
from their upstream format. See the upstream source above
for the canonical reference.