MRI quantification modules for 3D Slicer — ADC histogram analysis and three T2 relaxometry variants, packaged as one installable bundle.
All four modules are Python scripted extensions. They add a 1 - MF MR Quant Tools category to Slicer, work on the volumes and segmentations already in the scene, and write their results back as new volume nodes plus a statistics table — no external binaries, no network access, no extra Python environment.
Research and educational software — not a medical device. The maps are apparent relaxometry values, not validated clinical measurements. See Limitations.
| Module | Input | Output | Reference |
|---|---|---|---|
| ADC Histogram | ADC volume + segmentation | Histogram with Gaussian fit, Q-Q plot, statistics table, CSV export | — |
| T2 Mapping (2 TE) | Two T2-weighted volumes + TE₁/TE₂ | T2 map + ROI histogram and statistics | Mono-exponential decay |
| T2 Mapping (1 TE) | One T2-weighted volume + TE + anchor tissue | T2 map + ROI histogram and statistics | Anchor-tissue calibration |
| T2 Mapping AutoRef | One T2-weighted volume + muscle/fat segments | Pseudo-T2 map + ROI statistics | Sørland et al. 2022; Zhu et al. 2023 |
Every module works on a segmentation ROI, so measurements are restricted to the tissue you delineated.
- 3D Slicer 5.6 – 5.12 (verified on 5.12.3, Linux)
- No additional Python packages: the modules use only what Slicer bundles (numpy, scipy, SimpleITK, VTK, Qt)
- For the unit tests outside Slicer: Python ≥ 3.10 with
numpy,scipy,pytest
git clone https://github.com/lippisch2/MR_Quant_tools.git
cd MR_Quant_tools
python install.pyinstall.py locates your Slicer installation, copies the four modules into
lib/Slicer-X.Y/qt-scripted-modules, and clears stale bytecode. Restart Slicer
afterwards and look for the 1 - MF MR Quant Tools category.
python install.py --list # show detected Slicer installations
python install.py --slicer PATH # explicit installation directory
python install.py --dry-run # show what would be copied
python install.py --uninstall # remove the modules againManual copy, "additional module paths", drag-and-drop, and the reason the Extensions Manager's Install from file does not work on 5.12.3 are covered in INSTALL.md.
Whole-lesion apparent diffusion coefficient distribution analysis.
Inputs — an ADC volume, a segmentation node, and one segment.
What it computes
-
Extracts finite, positive ADC voxels inside the segment.
-
Bins them at a fixed width (
range / bins, default 50 bins, adjustable 5–200). -
Fits a Gaussian to the raw voxel values (not to the bar heights, which would bias σ), with μ and σ (ddof = 1).
-
Scales the fitted density back to expected counts:
fitted_counts(x) = N · bin_width · pdf(x)so the curve is comparable to the histogram bars in any ADC unit.
-
Reports mean, median, standard deviation, ADC10, ADC25, skewness, excess kurtosis and a Shapiro–Wilk normality test (subsampled above 5000 voxels, which is scipy's limit).
-
Optional Q-Q plot with Blom's normal scores, reference lines for mean/median/ADC10/ADC25, a results table, and CSV export (voxel values, histogram + fit, statistics).
Useful for characterising lesion heterogeneity: a low ADC mean with a wide, right-skewed distribution behaves differently from a narrow one, and the histogram makes that visible before you commit to a number.
Unit tests: 20 (modules/ADC_histogram/tests).
The most direct of the three T2 modules: two co-registered echoes, no reference tissue needed.
S(TE₁) = S₀ · exp(−TE₁/T2)
S(TE₂) = S₀ · exp(−TE₂/T2)
T2 = (TE₂ − TE₁) / ln( S(TE₁) / S(TE₂) )
S₀ cancels in the ratio, so no flip-angle or proton-density normalisation is required. The implementation rejects, with an explicit warning, voxels where
- either signal is non-positive or non-finite;
S(TE₂) ≥ S(TE₁)— physically impossible for T2 decay (wrong echo order, or noise dominating);- T2 exceeds the ceiling (default 2000 ms, i.e. noise).
Options: ROI segmentation, output volume name, optional ROI histogram with mean / median / SD / min / max / P10 / P90, and a literature reference table of T2 values for ten organs. Output geometry (origin, spacing, direction) is copied from the TE₁ volume.
Requirement: the two volumes must be co-registered and share the same geometry — the module does not register them.
Unit tests: 19 (modules/T2_mapping_2TE/tests).
Single-echo T2 from an internal reference anchor, for protocols where only one echo was acquired.
S = S₀ · exp(−TE/T2)
S_ref = S₀ · exp(−TE/T2_ref)
T2 = TE / ( (TE/T2_ref) − ln(S/S_ref) )
The anchor is a tissue whose T2 is known: CSF (T2_ref = 2000 ms) or
fat (T2_ref = 70 ms). S_ref is either detected automatically (CSF peak /
fat peak after CSF stripping) or measured inside a segment you draw — tick
Measure S_ref from anchor segment and pick the segmentation, segment and
statistic (mean, median, P10 or P90).
Instead of a single global S_ref, the module can build a spatial reference map to compensate for B1 and coil-sensitivity variation:
| Method | poly_degree / map_sigma |
|---|---|
| Global scalar | map_sigma = 0 |
| Nearest-neighbour | map_sigma > 0, poly_degree = 0 |
| Polynomial surface fit | poly_degree = 1..3 |
Additional processing: Rician noise-floor correction, optional noise masking,
T2 smoothing, clamp range, and an ROI histogram. Physics check: a voxel whose
signal equals S_ref maps to exactly T2_ref.
Failure mode to know about: automatic anchor detection can fail on unusual contrast or pathology. If the map looks wrong, measure S_ref from a segment instead — that path is deterministic.
Unit tests: 6 (modules/T2_mapping_1TE/tests).
A pseudo-T2 map from a single echo by linear two-anchor rescaling, per Sørland et al. 2022 — used for regional muscle and pelvic tissue.
pseudo-T2 = T2_low + (I − I_low) · (T2_high − T2_low) / (I_high − I_low)
You provide one segmentation with a muscle segment (low T2) and a fat segment (high T2). I_low and I_high are robust ROI statistics — by default the 10th percentile of muscle and the 90th percentile of fat, which tolerate imprecise ROI delineation. Mean, median and P90/P10 are also selectable.
Four anchor sets are available, and picking one updates the anchor labels and priors:
| Method | Low anchor | High anchor | T2 high (ms) |
|---|---|---|---|
AutoRef_F |
Obturator internus muscle (37.4 ± 0.9) | Ischioanal fossa fat | 129.7 ± 1.9 |
AutoRef_FH |
Obturator internus muscle | Yellow marrow, femoral heads | 137.0 ± 2.7 |
AutoRef_PB |
Obturator internus muscle | Pelvic bone marrow | 98.7 ± 7.6 |
AutoRef_Zhu2023 |
Gluteus maximus muscle (51.0 ± 4.4) | Subcutaneous fat | 134.8 ± 3.9 |
AutoRef_Zhu2023 uses the 1.5 T values of Zhu et al. 2023 and is intended for
pelvic/uterine imaging, where gluteus maximus and subcutaneous fat share the
field of view. Both papers' reference tables are reproduced in the module panel
as an aide-mémoire.
Pre-processing (all off by default): N4 bias-field correction via SimpleITK, P99 rescaling, and ROI cleanup (largest connected component + morphological opening). Output is optionally clipped to the anchor range; unclipped, voxels outside it are extrapolated as in the paper, which also amplifies noise.
Unit tests: 23 (modules/T2_mapping_AutoRef/tests).
The computation layer of every module is deliberately Slicer-free, so it can be tested with plain numpy/scipy:
python -m pip install -r requirements-dev.txt
python -m pytest -q # 74 passedCoverage is concentrated where errors are silent: the relaxometry equations (known-T2 phantoms), the validity rules, ROI masking, histogram binning, Gaussian-fit scaling, anchor statistics, clipping behaviour, and the literature tables. The Qt widget code is not unit-tested — it is exercised by loading the modules in Slicer.
Run the suite locally with python -m pytest -q (74 tests). The same
configuration can be added as a GitHub Actions workflow
(.github/workflows/tests.yml) once a push token with workflow scope is
available.
MR_Quant_tools/
├── modules/
│ ├── ADC_histogram/
│ │ ├── ADC_histogram.py # module registration
│ │ ├── ADC_histogramLib/
│ │ │ ├── adc_computation.py # pure math, no Slicer
│ │ │ ├── ADC_histogramLogic.py # Slicer I/O, VTK plots, CSV
│ │ │ └── ADC_histogramWidget.py # Qt panel
│ │ ├── tests/
│ │ └── AGENTS.md # architecture + API notes
│ ├── T2_mapping_1TE/ # same structure
│ ├── T2_mapping_2TE/
│ └── T2_mapping_AutoRef/
├── docs/slicer-modules.png
├── install.py # copy into a Slicer installation
├── INSTALL.md
├── pyproject.toml # version, pytest and ruff config
└── requirements-dev.txt
Each module keeps its own AGENTS.md: file map, formulas, Slicer 5.12 widget
API gotchas, verified behaviours and known limitations. Read it before changing
a module.
- Apparent values only. No B₀/B₁ correction, no T2* or multi-component fitting, no motion correction, no registration between echoes.
- The 2-TE module requires co-registered inputs with identical geometry.
- The 1-TE and AutoRef maps depend on their anchors. Wrong contrast, mis-placed ROIs, or pathology in the reference tissue bias the whole map. Anchor segmentation is the more reproducible path for the 1-TE module.
- ADC histogram binning is bin-count driven in the GUI (bin width = range/bins); it changes the visual shape, not the statistics.
- Not validated clinically. No phantom study, no reader study, no comparison against a commercial relaxometry package.
- Windows and macOS are untested. The API calls used are identical, and
install.pysupports both, but only Linux 5.12.3 has been verified.
- Sørland, K. et al. Regional muscle tissue: mapping of T2 applied to a single echo. Magn Reson Mater Phy 35, 493–501 (2022).
- Zhu, M. et al. T2 mapping of pelvic and uterine tissues at 1.5 T and 3.0 T. BMC Med Imaging 23, 1 (2023). doi:10.1186/s12880-022-00960-w
- 3D Slicer: https://www.slicer.org — scripted module documentation, https://slicer.readthedocs.io/en/latest/developer_guide/modules/
MIT — see LICENSE.
The software is provided for research and education. It is not a medical device, has not been cleared or approved by any regulatory body, and must not be used to make patient-care decisions.
