Skip to content

Commit 6878ce1

Browse files
neuronflowneuronflow
authored
Merge pull request #164 from BrainLesion/copilot/update-readme-example
Update README with comprehensive AtlasCentricPreprocessor and NativeSpacePreprocessor examples and improved documentation
2 parents 4e742b0 + 4beb2b5 commit 6878ce1

File tree

1 file changed

+191
-35
lines changed

1 file changed

+191
-35
lines changed

‎README.md‎

Lines changed: 191 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,27 @@
88
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
99
<!-- [![codecov](https://codecov.io/gh/BrainLesion/brainles-preprocessing/graph/badge.svg?token=A7FWUKO9Y4)](https://codecov.io/gh/BrainLesion/brainles-preprocessing) -->
1010

11-
`BrainLes preprocessing` is a comprehensive tool for preprocessing tasks in biomedical imaging, with a focus on (but not limited to) multi-modal brain MRI. It can be used to build modular preprocessing pipelines:
11+
`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.
1212

13-
This includes **normalization**, **co-registration**, **atlas registration**, **skullstripping / brain extraction**, **N4 Bias correction** and **defacing**.
14-
We provide means to transform images and segmentations in both directions between native and atlas space.
13+
## Features
1514

16-
BrainLes is written modular and `backend-agnostic` meaning it allows to skip or swap registration, brain extraction, N4 bias correction and defacing tools.
15+
### Core Preprocessing Steps
16+
- **Normalization**: Intensity normalization using various methods (e.g., percentile-based)
17+
- **Co-registration**: Align multiple modalities to a reference modality
18+
- **Atlas Registration**: Register images to standard atlas spaces (MNI152, SRI24, etc.)
19+
- **Brain Extraction**: Skull stripping using state-of-the-art methods (HD-BET, SynthStrip)
20+
- **N4 Bias Correction**: Correct intensity inhomogeneities
21+
- **Defacing**: Anonymize images by removing facial features
22+
23+
### Preprocessing Modes
24+
- **Atlas-Centric**: Process images in atlas space with optional atlas-based intensity correction
25+
- **Native Space**: Process images in patient/native space without atlas registration
26+
27+
### Key Benefits
28+
- **Modular & Backend-Agnostic**: Easily swap or skip preprocessing steps and choose from multiple backends
29+
- **Flexible Output Options**: Generate any combination of outputs (brain extracted, with skull, defaced, raw, normalized)
30+
- **Bidirectional Transforms**: Transform images and segmentations between native and atlas space
31+
- **Extensible**: Add custom normalizers, registrators, brain extractors, or defacing methods
1732

1833
<!-- TODO include image here -->
1934

@@ -36,64 +51,205 @@ We recommend using Python `3.10 / 3.11 / 3.12`.
3651
3752

3853
## Usage
39-
A minimal example to register (to the standard atlas using ANTs) and skull strip (using HDBet) a t1c image (center modality) with 1 moving modality (flair) could look like this:
54+
55+
### Atlas-Centric Preprocessing
56+
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.
57+
58+
**Key features:**
59+
- Co-registration of moving modalities to center modality
60+
- Registration to atlas space
61+
- Optional atlas correction (intensity adjustment based on atlas)
62+
- N4 bias correction
63+
- Brain extraction
64+
- Defacing for anonymization
65+
66+
**Example with all output options:**
67+
68+
This example demonstrates all possible output paths. You can specify any combination of:
69+
- **Raw outputs** (without normalization): `raw_bet_output_path`, `raw_skull_output_path`, `raw_defaced_output_path`
70+
- **Normalized outputs** (requires a normalizer): `normalized_bet_output_path`, `normalized_skull_output_path`, `normalized_defaced_output_path`
71+
- **Masks** (only for CenterModality): `bet_mask_output_path`, `defacing_mask_output_path`
72+
73+
> **Note:** At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.
74+
4075
```python
4176
from pathlib import Path
4277
from brainles_preprocessing.modality import Modality, CenterModality
4378
from brainles_preprocessing.normalization.percentile_normalizer import (
4479
PercentileNormalizer,
4580
)
46-
from brainles_preprocessing.preprocessor import Preprocessor
81+
from brainles_preprocessing.preprocessor import AtlasCentricPreprocessor
4782

48-
patient_folder = Path("/home/marcelrosier/preprocessing/patient")
83+
patient_folder = Path("/path/to/patient")
84+
output_folder = Path("/path/to/output")
4985

50-
# specify a normalizer
86+
# specify a normalizer (required if using any normalized_* output paths)
5187
percentile_normalizer = PercentileNormalizer(
5288
lower_percentile=0.1,
5389
upper_percentile=99.9,
5490
lower_limit=0,
5591
upper_limit=1,
5692
)
5793

58-
# define center and moving modalities
94+
# define center modality with all possible outputs
5995
center = CenterModality(
60-
modality_name="t1c",
61-
input_path=patient_folder / "t1c.nii.gz",
62-
normalizer=percentile_normalizer,
63-
# specify the output paths for the raw and normalized images of each step - here only for atlas registered and brain extraction
64-
raw_skull_output_path="patient/raw_skull_dir/t1c_skull_raw.nii.gz",
65-
raw_bet_output_path="patient/raw_bet_dir/t1c_bet_raw.nii.gz",
66-
raw_defaced_output_path="patient/raw_defaced_dir/t1c_defaced_raw.nii.gz",
67-
normalized_skull_output_path="patient/norm_skull_dir/t1c_skull_normalized.nii.gz",
68-
normalized_bet_output_path="patient/norm_bet_dir/t1c_bet_normalized.nii.gz",
69-
normalized_defaced_output_path="patient/norm_defaced_dir/t1c_defaced_normalized.nii.gz",
70-
# specify output paths for the brain extraction and defacing masks
71-
bet_mask_output_path="patient/masks/t1c_bet_mask.nii.gz",
72-
defacing_mask_output_path="patient/masks/t1c_defacing_mask.nii.gz",
96+
modality_name="t1c", # required
97+
input_path=patient_folder / "t1c.nii.gz", # required
98+
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
99+
# Raw outputs (optional)
100+
raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz", # brain extracted
101+
raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz", # with skull
102+
raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz", # defaced
103+
# Normalized outputs (optional, requires normalizer)
104+
normalized_bet_output_path=output_folder / "normalized_bet/t1c_bet_normalized.nii.gz",
105+
normalized_skull_output_path=output_folder / "normalized_skull/t1c_skull_normalized.nii.gz",
106+
normalized_defaced_output_path=output_folder / "normalized_defaced/t1c_defaced_normalized.nii.gz",
107+
# Masks (optional, only for CenterModality)
108+
bet_mask_output_path=output_folder / "masks/t1c_bet_mask.nii.gz",
109+
defacing_mask_output_path=output_folder / "masks/t1c_defacing_mask.nii.gz",
110+
# Optional parameters
111+
atlas_correction=True, # default: True
112+
n4_bias_correction=False, # default: False
73113
)
74114

115+
# define moving modalities
75116
moving_modalities = [
76117
Modality(
77-
modality_name="flair",
78-
input_path=patient_folder / "flair.nii.gz",
79-
normalizer=percentile_normalizer,
80-
# specify the output paths for the raw and normalized images of each step - here only for atlas registered and brain extraction
81-
raw_skull_output_path="patient/raw_skull_dir/fla_skull_raw.nii.gz",
82-
raw_bet_output_path="patient/raw_bet_dir/fla_bet_raw.nii.gz",
83-
raw_defaced_output_path="patient/raw_defaced_dir/fla_defaced_raw.nii.gz",
84-
normalized_skull_output_path="patient/norm_skull_dir/fla_skull_normalized.nii.gz",
85-
normalized_bet_output_path="patient/norm_bet_dir/fla_bet_normalized.nii.gz",
86-
normalized_defaced_output_path="patient/norm_defaced_dir/fla_defaced_normalized.nii.gz",
118+
modality_name="flair", # required
119+
input_path=patient_folder / "flair.nii.gz", # required
120+
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
121+
# Raw outputs (optional)
122+
raw_bet_output_path=output_folder / "raw_bet/flair_bet_raw.nii.gz",
123+
raw_skull_output_path=output_folder / "raw_skull/flair_skull_raw.nii.gz",
124+
raw_defaced_output_path=output_folder / "raw_defaced/flair_defaced_raw.nii.gz",
125+
# Normalized outputs (optional, requires normalizer)
126+
normalized_bet_output_path=output_folder / "normalized_bet/flair_bet_normalized.nii.gz",
127+
normalized_skull_output_path=output_folder / "normalized_skull/flair_skull_normalized.nii.gz",
128+
normalized_defaced_output_path=output_folder / "normalized_defaced/flair_defaced_normalized.nii.gz",
129+
# Optional parameters
130+
atlas_correction=True, # default: True
131+
n4_bias_correction=False, # default: False
87132
)
88133
]
89134

90-
# instantiate and run the preprocessor using defaults for backends (registration, brain extraction, bias correction, defacing)
91-
preprocessor = Preprocessor(
135+
# instantiate and run the preprocessor
136+
preprocessor = AtlasCentricPreprocessor(
92137
center_modality=center,
93138
moving_modalities=moving_modalities,
139+
# Optional: customize backends (defaults shown below)
140+
# registrator=ANTsRegistrator(),
141+
# brain_extractor=HDBetExtractor(),
142+
# n4_bias_corrector=SitkN4BiasCorrector(),
143+
# defacer=QuickshearDefacer(),
144+
)
145+
146+
preprocessor.run(
147+
# Optional: save intermediate results to these directories
148+
save_dir_coregistration=output_folder / "coregistration",
149+
save_dir_atlas_registration=output_folder / "atlas_registration",
150+
save_dir_atlas_correction=output_folder / "atlas_correction",
151+
save_dir_n4_bias_correction=output_folder / "n4_bias_correction",
152+
save_dir_brain_extraction=output_folder / "brain_extraction",
153+
save_dir_defacing=output_folder / "defacing",
94154
)
95155

96-
preprocessor.run()
156+
```
157+
158+
### Native Space Preprocessing
159+
Use `NativeSpacePreprocessor` to perform coregistration, N4 bias correction, brain extraction, and defacing while keeping images in native space (no atlas registration).
160+
161+
**Key features:**
162+
- Co-registration of moving modalities to center modality
163+
- N4 bias correction
164+
- Brain extraction
165+
- Defacing for anonymization
166+
- **No atlas registration** - stays in native/patient space
167+
168+
**Example with all output options:**
169+
170+
This example demonstrates all possible output paths. You can specify any combination of:
171+
- **Raw outputs** (without normalization): `raw_bet_output_path`, `raw_skull_output_path`, `raw_defaced_output_path`
172+
- **Normalized outputs** (requires a normalizer): `normalized_bet_output_path`, `normalized_skull_output_path`, `normalized_defaced_output_path`
173+
- **Masks** (only for CenterModality): `bet_mask_output_path`, `defacing_mask_output_path`
174+
175+
> **Note:** At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.
176+
177+
```python
178+
from pathlib import Path
179+
from brainles_preprocessing.modality import Modality, CenterModality
180+
from brainles_preprocessing.normalization.percentile_normalizer import (
181+
PercentileNormalizer,
182+
)
183+
from brainles_preprocessing.preprocessor import NativeSpacePreprocessor
184+
185+
patient_folder = Path("/path/to/patient")
186+
output_folder = Path("/path/to/output")
187+
188+
# specify a normalizer (required if using any normalized_* output paths)
189+
percentile_normalizer = PercentileNormalizer(
190+
lower_percentile=0.1,
191+
upper_percentile=99.9,
192+
lower_limit=0,
193+
upper_limit=1,
194+
)
195+
196+
# define center modality with all possible outputs
197+
center = CenterModality(
198+
modality_name="t1c", # required
199+
input_path=patient_folder / "t1c.nii.gz", # required
200+
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
201+
# Raw outputs (optional)
202+
raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz", # brain extracted
203+
raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz", # with skull
204+
raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz", # defaced
205+
# Normalized outputs (optional, requires normalizer)
206+
normalized_bet_output_path=output_folder / "normalized_bet/t1c_bet_normalized.nii.gz",
207+
normalized_skull_output_path=output_folder / "normalized_skull/t1c_skull_normalized.nii.gz",
208+
normalized_defaced_output_path=output_folder / "normalized_defaced/t1c_defaced_normalized.nii.gz",
209+
# Masks (optional, only for CenterModality)
210+
bet_mask_output_path=output_folder / "masks/t1c_bet_mask.nii.gz",
211+
defacing_mask_output_path=output_folder / "masks/t1c_defacing_mask.nii.gz",
212+
# Optional parameters (not applicable for native space: no atlas_correction)
213+
n4_bias_correction=False, # default: False
214+
)
215+
216+
# define moving modalities
217+
moving_modalities = [
218+
Modality(
219+
modality_name="flair", # required
220+
input_path=patient_folder / "flair.nii.gz", # required
221+
normalizer=percentile_normalizer, # optional: required for normalized_* outputs
222+
# Raw outputs (optional)
223+
raw_bet_output_path=output_folder / "raw_bet/flair_bet_raw.nii.gz",
224+
raw_skull_output_path=output_folder / "raw_skull/flair_skull_raw.nii.gz",
225+
raw_defaced_output_path=output_folder / "raw_defaced/flair_defaced_raw.nii.gz",
226+
# Normalized outputs (optional, requires normalizer)
227+
normalized_bet_output_path=output_folder / "normalized_bet/flair_bet_normalized.nii.gz",
228+
normalized_skull_output_path=output_folder / "normalized_skull/flair_skull_normalized.nii.gz",
229+
normalized_defaced_output_path=output_folder / "normalized_defaced/flair_defaced_normalized.nii.gz",
230+
# Optional parameters (not applicable for native space: no atlas_correction)
231+
n4_bias_correction=False, # default: False
232+
)
233+
]
234+
235+
# instantiate and run the preprocessor
236+
preprocessor = NativeSpacePreprocessor(
237+
center_modality=center,
238+
moving_modalities=moving_modalities,
239+
# Optional: customize backends (defaults shown below)
240+
# registrator=ANTsRegistrator(),
241+
# brain_extractor=HDBetExtractor(),
242+
# n4_bias_corrector=SitkN4BiasCorrector(),
243+
# defacer=QuickshearDefacer(),
244+
)
245+
246+
preprocessor.run(
247+
# Optional: save intermediate results to these directories
248+
save_dir_coregistration=output_folder / "coregistration",
249+
save_dir_n4_bias_correction=output_folder / "n4_bias_correction",
250+
save_dir_brain_extraction=output_folder / "brain_extraction",
251+
save_dir_defacing=output_folder / "defacing",
252+
)
97253

98254
```
99255

0 commit comments

Comments
 (0)