brainles_preprocessing
modality
- class brainles_preprocessing.modality.CenterModality(modality_name: str, input_path: str | Path, normalizer: Normalizer | None = None, raw_bet_output_path: str | Path | None = None, raw_skull_output_path: str | Path | None = None, raw_defaced_output_path: str | Path | None = None, normalized_bet_output_path: str | Path | None = None, normalized_skull_output_path: str | Path | None = None, normalized_defaced_output_path: str | Path | None = None, atlas_correction: bool = True, bet_mask_output_path: str | Path | None = None, defacing_mask_output_path: str | Path | None = None)
Bases:
Modality
Represents a medical image center modality with associated preprocessing information.
- Parameters:
modality_name (str) – Name of the modality, e.g., “T1”, “T2”, “FLAIR”.
input_path (str or Path) – Path to the input modality data.
normalizer (Normalizer, optional) – An optional normalizer for intensity normalization.
raw_bet_output_path (str or Path, optional) – Path to save the raw brain extracted modality data.
raw_skull_output_path (str or Path, optional) – Path to save the raw modality data with skull.
raw_defaced_output_path (str or Path, optional) – Path to save the raw defaced modality data.
normalized_bet_output_path (str or Path, optional) – Path to save the normalized brain extracted modality data. Requires a normalizer.
normalized_skull_output_path (str or Path, optional) – Path to save the normalized modality data with skull. Requires a normalizer.
normalized_defaced_output_path (str or Path, optional) – Path to save the normalized defaced modality data. Requires a normalizer.
atlas_correction (bool, optional) – Indicates whether atlas correction should be performed.
bet_mask_output_path (str or Path, optional) – Path to save the brain extraction mask.
defacing_mask_output_path (str or Path, optional) – Path to save the defacing mask.
- modality_name
Name of the modality.
- Type:
str
- input_path
Path to the input modality data.
- Type:
str or Path
- normalizer
An optional normalizer for intensity normalization.
- Type:
Normalizer, optional
- raw_bet_output_path
Path to save the raw brain extracted modality data.
- Type:
str or Path, optional
- raw_skull_output_path
Path to save the raw modality data with skull.
- Type:
str or Path, optional
- raw_defaced_output_path
Path to save the raw defaced modality data.
- Type:
str or Path, optional
- normalized_bet_output_path
Path to save the normalized brain extracted modality data. Requires a normalizer.
- Type:
str or Path, optional
- normalized_skull_output_path
Path to save the normalized modality data with skull. Requires a normalizer.
- Type:
str or Path, optional
- normalized_defaced_output_path
Path to save the normalized defaced modality data. Requires a normalizer.
- Type:
str or Path, optional
- bet
Indicates whether brain extraction is enabled.
- Type:
bool
- atlas_correction
Indicates whether atlas correction should be performed.
- Type:
bool
- bet_mask_output_path
Path to save the brain extraction mask.
- Type:
Path, optional
- defacing_mask_output_path
Path to save the defacing mask.
- Type:
Path, optional
Example
>>> t1_modality = CenterModality( ... modality_name="T1", ... input_path="/path/to/input_t1.nii", ... normalizer=PercentileNormalizer(), ... raw_bet_output_path="/path/to/raw_bet_t1.nii", ... normalized_bet_output_path="/path/to/norm_bet_t1.nii", ... bet_mask_output_path="/path/to/bet_mask_t1.nii", ... )
- deface(defacer, defaced_dir_path: str | Path) Path
Deface the current modality using the specified defacer.
- Parameters:
defacer (Defacer) – The defacer object.
defaced_dir_path (str or Path) – Directory to store defacing results.
- Returns:
Path to the extracted brain mask.
- Return type:
Path
- extract_brain_region(brain_extractor: BrainExtractor, bet_dir_path: str | Path) Path
Extract the brain region using the specified brain extractor.
- Parameters:
brain_extractor (BrainExtractor) – The brain extractor object.
bet_dir_path (str or Path) – Directory to store brain extraction results.
- Returns:
Path to the extracted brain mask.
- Return type:
Path
- save_mask(mask_path: str | Path, output_path: Path) None
Save the mask to the specified output path.
- Parameters:
mask_path (Union[str, Path]) – Mask NifTI file path.
output_path (Path) – Output NifTI file path.
- class brainles_preprocessing.modality.Modality(modality_name: str, input_path: str | Path, normalizer: Normalizer | None = None, raw_bet_output_path: str | Path | None = None, raw_skull_output_path: str | Path | None = None, raw_defaced_output_path: str | Path | None = None, normalized_bet_output_path: str | Path | None = None, normalized_skull_output_path: str | Path | None = None, normalized_defaced_output_path: str | Path | None = None, atlas_correction: bool = True)
Bases:
object
Represents a medical image modality with associated preprocessing information.
- Parameters:
modality_name (str) – Name of the modality, e.g., “T1”, “T2”, “FLAIR”.
input_path (str or Path) – Path to the input modality data.
normalizer (Normalizer, optional) – An optional normalizer for intensity normalization.
raw_bet_output_path (str or Path, optional) – Path to save the raw brain extracted modality data.
raw_skull_output_path (str or Path, optional) – Path to save the raw modality data with skull.
raw_defaced_output_path (str or Path, optional) – Path to save the raw defaced modality data.
normalized_bet_output_path (str or Path, optional) – Path to save the normalized brain extracted modality data. Requires a normalizer.
normalized_skull_output_path (str or Path, optional) – Path to save the normalized modality data with skull. Requires a normalizer.
normalized_defaced_output_path (str or Path, optional) – Path to save the normalized defaced modality data. Requires a normalizer.
atlas_correction (bool, optional) – Indicates whether atlas correction should be performed.
- modality_name
Name of the modality.
- Type:
str
- input_path
Path to the input modality data.
- Type:
str or Path
- normalizer
An optional normalizer for intensity normalization.
- Type:
Normalizer, optional
- raw_bet_output_path
Path to save the raw brain extracted modality data.
- Type:
str or Path, optional
- raw_skull_output_path
Path to save the raw modality data with skull.
- Type:
str or Path, optional
- raw_defaced_output_path
Path to save the raw defaced modality data.
- Type:
str or Path, optional
- normalized_bet_output_path
Path to save the normalized brain extracted modality data. Requires a normalizer.
- Type:
str or Path, optional
- normalized_skull_output_path
Path to save the normalized modality data with skull. Requires a normalizer.
- Type:
str or Path, optional
- normalized_defaced_output_path
Path to save the normalized defaced modality data. Requires a normalizer.
- Type:
str or Path, optional
- bet
Indicates whether brain extraction is enabled.
- Type:
bool
- atlas_correction
Indicates whether atlas correction should be performed.
- Type:
bool
Example
>>> t1_modality = Modality( ... modality_name="T1", ... input_path="/path/to/input_t1.nii", ... normalizer=PercentileNormalizer(), ... raw_bet_output_path="/path/to/raw_bet_t1.nii", ... normalized_bet_output_path="/path/to/norm_bet_t1.nii", ... )
- apply_bet_mask(brain_extractor: BrainExtractor, mask_path: str | Path, bet_dir: str | Path) None
Apply a brain mask to the current modality using the specified brain extractor.
- Parameters:
brain_extractor (BrainExtractor) – The brain extractor object.
mask_path (str or Path) – Path to the brain mask.
bet_dir (str or Path) – Directory to store computed bet images.
- Returns:
None
- apply_deface_mask(defacer: Defacer, mask_path: str | Path, deface_dir: str | Path) None
Apply a deface mask to the current modality using the specified brain extractor.
- Parameters:
defacer (Defacer) – The Defacer object.
mask_path (str or Path) – Path to the deface mask.
defaced_masked_dir_path (str or Path) – Directory to store masked images.
- property bet: bool
Check if any brain extraction output is specified.
- Returns:
True if any brain extraction output is specified, False otherwise.
- Return type:
bool
- deface(defacer, defaced_dir_path: str | Path) Path
WARNING: Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.
Deface the current modality using the specified defacer.
- Parameters:
defacer (Defacer) – The defacer object.
defaced_dir_path (str or Path) – Directory to store defacing results.
- Returns:
Path to the extracted brain mask.
- Return type:
Path
- extract_brain_region(brain_extractor: BrainExtractor, bet_dir_path: str | Path) Path
WARNING: Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.
Extract the brain region using the specified brain extractor.
- Parameters:
brain_extractor (BrainExtractor) – The brain extractor object.
bet_dir_path (str or Path) – Directory to store brain extraction results.
- Returns:
Path to the extracted brain mask.
- Return type:
Path
- normalize(temporary_directory: str | Path, store_unnormalized: str | Path | None = None) None
Normalize the image using the specified normalizer.
- Parameters:
temporary_directory (str or Path) – Path to the temporary directory.
store_unnormalized (str or Path, optional) – Path to store unnormalized images.
- Returns:
None
- register(registrator: Registrator, fixed_image_path: str | Path, registration_dir: str | Path, moving_image_name: str, step: PreprocessorSteps) Path
Register the current modality to a fixed image using the specified registrator.
- Parameters:
registrator (Registrator) – The registrator object.
fixed_image_path (str or Path) – Path to the fixed image.
registration_dir (str or Path) – Directory to store registration results.
moving_image_name (str) – Name of the moving image.
- Returns:
Path to the registration matrix.
- Return type:
Path
- property requires_deface: bool
Check if any defacing output is specified.
- Returns:
True if any defacing output is specified, False otherwise.
- Return type:
bool
- save_current_image(output_path: str | Path, normalization: bool = False) None
Save the current image to the specified output path.
- Parameters:
output_path (str or Path) – The output file path.
normalization (bool, optional) – If True, apply normalization before saving.
- Returns:
None
- transform(registrator: Registrator, fixed_image_path: str | Path, registration_dir_path: str | Path, moving_image_name: str, transformation_matrix_path: str | Path, step: PreprocessorSteps) None
Transform the current modality using the specified registrator and transformation matrix.
- Parameters:
registrator (Registrator) – The registrator object.
fixed_image_path (str or Path) – Path to the fixed image.
registration_dir_path (str or Path) – Directory to store transformation results.
moving_image_name (str) – Name of the moving image.
transformation_matrix_path (str or Path) – Path to the transformation matrix.
- Returns:
None
preprocessor
- class brainles_preprocessing.preprocessor.Preprocessor(center_modality: CenterModality, moving_modalities: List[Modality], registrator: Registrator | None = None, brain_extractor: BrainExtractor | None = None, defacer: Defacer | None = None, atlas_image_path: str | Path | None = None, temp_folder: str | Path | None = None, use_gpu: bool | None = None, limit_cuda_visible_devices: str | None = None)
Bases:
object
Preprocesses medical image modalities using coregistration, normalization, brain extraction, and more.
- Parameters:
center_modality (CenterModality) – The central modality for coregistration.
moving_modalities (List[Modality]) – List of modalities to be coregistered to the central modality.
registrator (Registrator) – The registrator object for coregistration and registration to the atlas.
brain_extractor (Optional[BrainExtractor]) – The brain extractor object for brain extraction.
defacer (Optional[Defacer]) – The defacer object for defacing images.
atlas_image_path (Optional[str or Path]) – Path to the atlas image for registration (default is the T1 atlas).
temp_folder (Optional[str or Path]) – Path to a folder for storing intermediate results.
use_gpu (Optional[bool]) – Use GPU for processing if True, CPU if False, or automatically detect if None.
limit_cuda_visible_devices (Optional[str]) – Limit CUDA visible devices to a specific GPU ID.
- _configure_gpu(use_gpu: bool | None, limit_cuda_visible_devices: str | None = None) None
Configures the environment for GPU usage based on the use_gpu parameter and CUDA availability.
- Parameters:
use_gpu (Optional[bool]) – Determines the GPU usage strategy.
- static _cuda_is_available() bool
Checks if CUDA is available on the system by attempting to run ‘nvidia-smi’.
- Returns:
True if ‘nvidia-smi’ can be executed successfully, indicating CUDA is available.
- Return type:
bool
- _save_output(src: str | Path, save_dir: str | Path | None)
Save the output from a source directory to the specified save directory.
- property all_modalities: List[Modality]
Returns a list of all modalities including the center modality.
- ensure_remove_log_file_handler()
- property requires_defacing: bool
Returns True if any modality requires defacing otherwise returns False.
- run(save_dir_coregistration: str | Path | None = None, save_dir_atlas_registration: str | Path | None = None, save_dir_atlas_correction: str | Path | None = None, save_dir_brain_extraction: str | Path | None = None, save_dir_defacing: str | Path | None = None, log_file: str | Path | None = None)
Execute the preprocessing pipeline, encompassing coregistration, atlas-based registration, atlas correction, and optional brain extraction.
- Parameters:
save_dir_coregistration (str or Path, optional) – Directory path to save intermediate coregistration results.
save_dir_atlas_registration (str or Path, optional) – Directory path to save intermediate atlas registration results.
save_dir_atlas_correction (str or Path, optional) – Directory path to save intermediate atlas correction results.
save_dir_brain_extraction (str or Path, optional) – Directory path to save intermediate brain extraction results.
save_dir_defacing (str or Path, optional) – Directory path to save intermediate defacing results.
log_file (str or Path, optional) – Path to save the log file. Defaults to a timestamped file in the current directory.
This method orchestrates the entire preprocessing workflow by sequentially performing:
Co-registration: Aligning moving modalities to the central modality.
Atlas Registration: Aligning the central modality to a predefined atlas.
Atlas Correction: Applying additional correction in atlas space if specified.
Brain Extraction: Optionally extracting brain regions using specified masks. Only executed if any modality requires a brain extraction output (or a defacing output that requires prior brain extraction).
Defacing: Optionally deface images to remove facial features. Only executed if any modality requires a defacing output.
Results are saved in the specified directories, allowing for modular and configurable output storage.
- run_atlas_correction(save_dir_atlas_correction: str | Path | None = None) None
Apply optional atlas correction to moving modalities.
- Parameters:
save_dir_atlas_correction (Optional[str or Path], optional) – Directory path to save intermediate atlas correction results. Defaults to None.
- run_atlas_registration(save_dir_atlas_registration: str | Path | None = None) None
Register center modality to atlas.
- Parameters:
save_dir_atlas_registration (Optional[str or Path], optional) – Directory path to save intermediate atlas registration results. Defaults to None.
- run_brain_extraction(save_dir_brain_extraction: str | Path | None = None) None
Extract brain regions using specified BrainExtractor.
- Parameters:
save_dir_brain_extraction (Optional[str or Path], optional) – Directory path to save intermediate brain extraction results. Defaults to None.
- run_coregistration(save_dir_coregistration: str | Path | None = None) None
Coregister moving modalities to center modality.
- Parameters:
save_dir_coregistration (str, optional) – Directory path to save intermediate coregistration results.
- run_defacing(save_dir_defacing: str | Path | None = None) None
Deface images to remove facial features using specified Defacer.
- Parameters:
save_dir_defacing (Optional[str or Path], optional) – Directory path to save intermediate defacing results. Defaults to None.