Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
BrainLes preprocessing is a comprehensive, modular toolkit for preprocessing multi-modal brain MRI and other biomedical imaging data. It provides flexible preprocessing pipelines that can be customized to your specific needs.
- Normalization: Intensity normalization using various methods (e.g., percentile-based)
- Co-registration: Align multiple modalities to a reference modality
- Atlas Registration: Register images to standard atlas spaces (MNI152, SRI24, etc.)
- Brain Extraction: Skull stripping using state-of-the-art methods (HD-BET, SynthStrip)
- N4 Bias Correction: Correct intensity inhomogeneities
- Defacing: Anonymize images by removing facial features
- Atlas-Centric: Process images in atlas space with optional atlas-based intensity correction
- Native Space: Process images in patient/native space without atlas registration
- Modular & Backend-Agnostic: Easily swap or skip preprocessing steps and choose from multiple backends
- Flexible Output Options: Generate any combination of outputs (brain extracted, with skull, defaced, raw, normalized)
- Bidirectional Transforms: Transform images and segmentations between native and atlas space
- Extensible: Add custom normalizers, registrators, brain extractors, or defacing methods
With a Python 3.10+ environment you can install directly from pypi.org:
pip install brainles-preprocessing
We recommend using Python 3.10 / 3.11 / 3.12.
Note
For python 3.13 the installation can currently fail with the error Failed to build antspyx. This usually means that there is no pre-built wheel for the package and it has to be build locally. This will require cmake (install e.g. with pip install cmake) and quite some time. Rerunning the installation with cmake installed should fix the error.
Use AtlasCentricPreprocessor to register images to an atlas, perform atlas correction, and skull strip. This is useful when you want all images in a common atlas space.
Key features:
- Co-registration of moving modalities to center modality
- Registration to atlas space
- Optional atlas correction (intensity adjustment based on atlas)
- N4 bias correction
- Brain extraction
- Defacing for anonymization
Example with all output options:
This example demonstrates all possible output paths. You can specify any combination of:
- Raw outputs (without normalization): raw_bet_output_path, raw_skull_output_path, raw_defaced_output_path
- Normalized outputs (requires a normalizer): normalized_bet_output_path, normalized_skull_output_path, normalized_defaced_output_path
- Masks (only for CenterModality): bet_mask_output_path, defacing_mask_output_path
Note: At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.
from pathlib import Path
from brainles_preprocessing.modality import Modality, CenterModality
from brainles_preprocessing.normalization.percentile_normalizer import (
PercentileNormalizer,
)
from brainles_preprocessing.preprocessor import AtlasCentricPreprocessor
patient_folder = Path("/path/to/patient")
output_folder = Path("/path/to/output")
# specify a normalizer (required if using any normalized_* output paths)
percentile_normalizer = PercentileNormalizer(
lower_percentile=0.1,
upper_percentile=99.9,
lower_limit=0,
upper_limit=1,
)
# define center modality with all possible outputs
center = CenterModality(
modality_name="t1c", # required
input_path=patient_folder / "t1c.nii.gz", # required
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
# Raw outputs (optional)
raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz", # brain extracted
raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz", # with skull
raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz", # defaced
# Normalized outputs (optional, requires normalizer)
normalized_bet_output_path=output_folder / "normalized_bet/t1c_bet_normalized.nii.gz",
normalized_skull_output_path=output_folder / "normalized_skull/t1c_skull_normalized.nii.gz",
normalized_defaced_output_path=output_folder / "normalized_defaced/t1c_defaced_normalized.nii.gz",
# Masks (optional, only for CenterModality)
bet_mask_output_path=output_folder / "masks/t1c_bet_mask.nii.gz",
defacing_mask_output_path=output_folder / "masks/t1c_defacing_mask.nii.gz",
# Optional parameters
atlas_correction=True, # default: True
n4_bias_correction=False, # default: False
)
# define moving modalities
moving_modalities = [
Modality(
modality_name="flair", # required
input_path=patient_folder / "flair.nii.gz", # required
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
# Raw outputs (optional)
raw_bet_output_path=output_folder / "raw_bet/flair_bet_raw.nii.gz",
raw_skull_output_path=output_folder / "raw_skull/flair_skull_raw.nii.gz",
raw_defaced_output_path=output_folder / "raw_defaced/flair_defaced_raw.nii.gz",
# Normalized outputs (optional, requires normalizer)
normalized_bet_output_path=output_folder / "normalized_bet/flair_bet_normalized.nii.gz",
normalized_skull_output_path=output_folder / "normalized_skull/flair_skull_normalized.nii.gz",
normalized_defaced_output_path=output_folder / "normalized_defaced/flair_defaced_normalized.nii.gz",
# Optional parameters
atlas_correction=True, # default: True
n4_bias_correction=False, # default: False
)
]
# instantiate and run the preprocessor
preprocessor = AtlasCentricPreprocessor(
center_modality=center,
moving_modalities=moving_modalities,
# Optional: customize backends (defaults shown below)
# registrator=ANTsRegistrator(),
# brain_extractor=HDBetExtractor(),
# n4_bias_corrector=SitkN4BiasCorrector(),
# defacer=QuickshearDefacer(),
)
preprocessor.run(
# Optional: save intermediate results to these directories
save_dir_coregistration=output_folder / "coregistration",
save_dir_atlas_registration=output_folder / "atlas_registration",
save_dir_atlas_correction=output_folder / "atlas_correction",
save_dir_n4_bias_correction=output_folder / "n4_bias_correction",
save_dir_brain_extraction=output_folder / "brain_extraction",
save_dir_defacing=output_folder / "defacing",
)Use NativeSpacePreprocessor to perform coregistration, N4 bias correction, brain extraction, and defacing while keeping images in native space (no atlas registration).
Key features:
- Co-registration of moving modalities to center modality
- N4 bias correction
- Brain extraction
- Defacing for anonymization
- No atlas registration - stays in native/patient space
Example with all output options:
This example demonstrates all possible output paths. You can specify any combination of:
- Raw outputs (without normalization): raw_bet_output_path, raw_skull_output_path, raw_defaced_output_path
- Normalized outputs (requires a normalizer): normalized_bet_output_path, normalized_skull_output_path, normalized_defaced_output_path
- Masks (only for CenterModality): bet_mask_output_path, defacing_mask_output_path
Note: At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.
from pathlib import Path
from brainles_preprocessing.modality import Modality, CenterModality
from brainles_preprocessing.normalization.percentile_normalizer import (
PercentileNormalizer,
)
from brainles_preprocessing.preprocessor import NativeSpacePreprocessor
patient_folder = Path("/path/to/patient")
output_folder = Path("/path/to/output")
# specify a normalizer (required if using any normalized_* output paths)
percentile_normalizer = PercentileNormalizer(
lower_percentile=0.1,
upper_percentile=99.9,
lower_limit=0,
upper_limit=1,
)
# define center modality with all possible outputs
center = CenterModality(
modality_name="t1c", # required
input_path=patient_folder / "t1c.nii.gz", # required
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
# Raw outputs (optional)
raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz", # brain extracted
raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz", # with skull
raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz", # defaced
# Normalized outputs (optional, requires normalizer)
normalized_bet_output_path=output_folder / "normalized_bet/t1c_bet_normalized.nii.gz",
normalized_skull_output_path=output_folder / "normalized_skull/t1c_skull_normalized.nii.gz",
normalized_defaced_output_path=output_folder / "normalized_defaced/t1c_defaced_normalized.nii.gz",
# Masks (optional, only for CenterModality)
bet_mask_output_path=output_folder / "masks/t1c_bet_mask.nii.gz",
defacing_mask_output_path=output_folder / "masks/t1c_defacing_mask.nii.gz",
# Optional parameters (not applicable for native space: no atlas_correction)
n4_bias_correction=False, # default: False
)
# define moving modalities
moving_modalities = [
Modality(
modality_name="flair", # required
input_path=patient_folder / "flair.nii.gz", # required
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
# Raw outputs (optional)
raw_bet_output_path=output_folder / "raw_bet/flair_bet_raw.nii.gz",
raw_skull_output_path=output_folder / "raw_skull/flair_skull_raw.nii.gz",
raw_defaced_output_path=output_folder / "raw_defaced/flair_defaced_raw.nii.gz",
# Normalized outputs (optional, requires normalizer)
normalized_bet_output_path=output_folder / "normalized_bet/flair_bet_normalized.nii.gz",
normalized_skull_output_path=output_folder / "normalized_skull/flair_skull_normalized.nii.gz",
normalized_defaced_output_path=output_folder / "normalized_defaced/flair_defaced_normalized.nii.gz",
# Optional parameters (not applicable for native space: no atlas_correction)
n4_bias_correction=False, # default: False
)
]
# instantiate and run the preprocessor
preprocessor = NativeSpacePreprocessor(
center_modality=center,
moving_modalities=moving_modalities,
# Optional: customize backends (defaults shown below)
# registrator=ANTsRegistrator(),
# brain_extractor=HDBetExtractor(),
# n4_bias_corrector=SitkN4BiasCorrector(),
# defacer=QuickshearDefacer(),
)
preprocessor.run(
# Optional: save intermediate results to these directories
save_dir_coregistration=output_folder / "coregistration",
save_dir_n4_bias_correction=output_folder / "n4_bias_correction",
save_dir_brain_extraction=output_folder / "brain_extraction",
save_dir_defacing=output_folder / "defacing",
)The package allows to choose registration backends, brain extraction tools and defacing methods.
An example notebook with 4 modalities and further outputs and customizations can be found following these badges:
For further information please have a look at our Jupyter Notebook tutorials in our tutorials repo (WIP).
Important
If you use brainles-preprocessing in your research, please cite it to support the development!
Kofler, F., Rosier, M., Astaraki, M., Möller, H., Mekki, I. I., Buchner, J. A., Schmick, A., Pfiffer, A., Oswald, E., Zimmer, L., Rosa, E. de la, Pati, S., Canisius, J., Piffer, A., Baid, U., Valizadeh, M., Linardos, A., Peeken, J. C., Shit, S., … Menze, B. (2025). BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis arXiv preprint arXiv:2507.09036
@misc{kofler2025brainlesionsuiteflexibleuserfriendly,
title={BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis},
author={Florian Kofler and Marcel Rosier and Mehdi Astaraki and Hendrik Möller and Ilhem Isra Mekki and Josef A. Buchner and Anton Schmick and Arianna Pfiffer and Eva Oswald and Lucas Zimmer and Ezequiel de la Rosa and Sarthak Pati and Julian Canisius and Arianna Piffer and Ujjwal Baid and Mahyar Valizadeh and Akis Linardos and Jan C. Peeken and Surprosanna Shit and Felix Steinbauer and Daniel Rueckert and Rolf Heckemann and Spyridon Bakas and Jan Kirschke and Constantin von See and Ivan Ezhov and Marie Piraud and Benedikt Wiestler and Bjoern Menze},
year={2025},
eprint={2507.09036},
archivePrefix={arXiv},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2507.09036},
}
We provide a (WIP) documentation. Have a look here
Please credit the authors by citing their work.
We currently fully support:
We also offer basic support for:
- greedy (Optional dependency, install via: pip install brainles_preprocessing[picsl_greedy])
- elastix (Optional dependency, install via: pip install brainles_preprocessing[itk-elastix])
As of now we do not offer inverse transforms for greedy and elastix. Please resort to ANTs or Niftyreg for this.
We provide a range of different atlases via zenodo, namely:
- SRI24 and its skull-stripped version
- MNI152: MNI_ICBM_2009c_Nonlinear_Symmetric
- Slightly modified MNI152 and SRI24 atlas versions as employed for the BraTS challenge algorithms
Note
Custom atlases of your choice in NIfTI format are also supported
We currently provide support for N4 Bias correction based on SimpleITK
We currently support:
- HD-BET
- SynthStrip (Optional dependency, install via: pip install brainles_preprocessing[synthstrip])
We currently provide support for Quickshear.