preprocessing 模块

核心处理流程 (Core Pipeline)

BatchProcessor 是预处理模块的核心入口，用于批量执行图像处理任务。

图像校正 (Correction)

class habit.core.preprocessing.n4_correction.N4BiasFieldCorrection(keys: str | List[str], mask_keys: str | List[str] | None = None, num_fitting_levels: int = 4, num_iterations: List[int] | None = None, convergence_threshold: float = 0.001, shrink_factor: int = 4, allow_missing_keys: bool = False, **kwargs)

基类：BasePreprocessor

Apply N4 bias field correction to images using SimpleITK.

This preprocessor applies N4 bias field correction to correct for intensity inhomogeneity in medical images.

__init__(keys: str | List[str], mask_keys: str | List[str] | None = None, num_fitting_levels: int = 4, num_iterations: List[int] | None = None, convergence_threshold: float = 0.001, shrink_factor: int = 4, allow_missing_keys: bool = False, **kwargs)

Initialize the N4 bias field correction preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the images to be corrected.

• mask_keys (Optional[Union[str, List[str]]]) -- Keys of the masks to use for correction. If None, no mask will be used.

• num_fitting_levels (int) -- Number of fitting levels for the bias field correction.

• num_iterations (List[int]) -- Number of iterations at each fitting level. If None, will use [50] * num_fitting_levels.

• convergence_threshold (float) -- Convergence threshold for the correction.

• shrink_factor (int) -- Shrink factor to accelerate computation (default 4).

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

• **kwargs -- Additional parameters for N4 correction.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Apply N4 bias field correction to the specified images.

参数:

data (Dict[str, Any]) -- Input data dictionary containing SimpleITK image objects.

返回:

Data dictionary with corrected images.

返回类型:

Dict[str, Any]

标准化与归一化 (Normalization)

class habit.core.preprocessing.histogram_standardization.HistogramStandardization(keys: str | List[str], percentiles: List[float] | None = None, target_min: float = 0.0, target_max: float = 100.0, mask_key: str | None = None, allow_missing_keys: bool = False)

基类：BasePreprocessor

Apply Nyúl histogram standardization to images.

This preprocessor implements the Nyúl histogram standardization method, which maps image intensities to a standard scale using percentile landmarks. Unlike histogram matching, this method does not require a reference image, but instead maps intensities to predefined target values.

Reference:

Nyúl, L.G., Udupa, J.K., Zhang, X., 2000. New variants of a method of MRI scale standardization. IEEE Trans. Med. Imaging 19, 143-150.

__init__(keys: str | List[str], percentiles: List[float] | None = None, target_min: float = 0.0, target_max: float = 100.0, mask_key: str | None = None, allow_missing_keys: bool = False)

Initialize the histogram standardization preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the images to be standardized.

• percentiles (Optional[List[float]]) -- Percentile landmarks for standardization. Default is [1, 10, 20, 30, 40, 50, 60, 70, 80, 90, 99].

• target_min (float) -- Target minimum value for standardization. Default is 0.0.

• target_max (float) -- Target maximum value for standardization. Default is 100.0.

• mask_key (Optional[str]) -- Key of the mask image to use for computing percentiles. If None, uses all non-zero voxels. Default is None.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Apply histogram standardization to the specified images.

参数:

data (Dict[str, Any]) -- Input data dictionary containing SimpleITK image objects.

返回:

Data dictionary with histogram-standardized images.

返回类型:

Dict[str, Any]

class habit.core.preprocessing.zscore_normalization.ZScoreNormalization(keys: str | List[str], only_inmask: bool = False, mask_key: str | None = None, clip_values: Tuple[float, float] | None = None, allow_missing_keys: bool = False, **kwargs)

基类：BasePreprocessor

Apply Z-score normalization to medical images.

This preprocessor normalizes image intensities by subtracting the mean and dividing by the standard deviation, resulting in a distribution with zero mean and unit variance.

__init__(keys: str | List[str], only_inmask: bool = False, mask_key: str | None = None, clip_values: Tuple[float, float] | None = None, allow_missing_keys: bool = False, **kwargs)

Initialize the Z-score normalization preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the images to be normalized.

• only_inmask (bool) -- If True, only calculate statistics within the mask.

• mask_key (Optional[str]) -- Key of the mask to use when only_inmask is True.

• clip_values (Optional[Tuple[float, float]]) -- Optional tuple of (min, max) values to clip normalized results. Useful to prevent extreme values, e.g. (-3, 3).

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

• **kwargs -- Additional parameters.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Apply Z-score normalization to the specified images.

参数:

data (Dict[str, Any]) -- Input data dictionary containing SimpleITK image objects.

返回:

Data dictionary with normalized images.

返回类型:

Dict[str, Any]

class habit.core.preprocessing.adaptive_histogram_equalization.AdaptiveHistogramEqualization(keys: str | List[str], alpha: float = 0.3, beta: float = 0.3, radius: int | Tuple[int, int, int] = 5, allow_missing_keys: bool = False)

基类：BasePreprocessor

Apply adaptive histogram equalization to images using SimpleITK.

This preprocessor uses SimpleITK's AdaptiveHistogramEqualizationImageFilter to perform contrast-limited adaptive histogram equalization (CLAHE). It enhances local contrast while limiting noise amplification.

The filter divides the image into regions (controlled by radius parameter) and performs histogram equalization in each region, with bilinear interpolation to eliminate boundary artifacts.

__init__(keys: str | List[str], alpha: float = 0.3, beta: float = 0.3, radius: int | Tuple[int, int, int] = 5, allow_missing_keys: bool = False)

Initialize the adaptive histogram equalization preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the images to be processed.

• alpha (float) -- Controls how much the filter acts like the classical histogram equalization method. Range [0, 1]. - alpha=0: Unsharp mask (edge enhancement) - alpha=1: Classical histogram equalization Default is 0.3.

• beta (float) -- Controls how much the filter acts like an unsharp mask. Range [0, 1]. - beta=0: No window adaptation (global equalization) - beta=1: Full window adaptation (local equalization) Default is 0.3.

• radius (Union[int, Tuple[int, int, int]]) -- Radius of the local region in pixels for each dimension. Larger values result in smoother output but less local contrast enhancement. Can be a single int (same for all dimensions) or a tuple (x, y, z). Default is 5.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Apply adaptive histogram equalization to the specified images.

参数:

data (Dict[str, Any]) -- Input data dictionary containing SimpleITK image objects.

返回:

Data dictionary with processed images.

返回类型:

Dict[str, Any]

空间变换 (Spatial Transform)

class habit.core.preprocessing.resample.ResamplePreprocessor(keys: str | List[str], target_spacing: Sequence[float], img_mode: str = 'bilinear', padding_mode: str = 'border', align_corners: bool = False, allow_missing_keys: bool = False, **kwargs)

基类：BasePreprocessor

Resample images to a target spacing using SimpleITK.

This preprocessor resamples images and masks to a specified target spacing. Images and masks are processed separately with different interpolation modes: - Images: use specified interpolation mode (default: bilinear) - Masks: use nearest neighbor interpolation

__init__(keys: str | List[str], target_spacing: Sequence[float], img_mode: str = 'bilinear', padding_mode: str = 'border', align_corners: bool = False, allow_missing_keys: bool = False, **kwargs)

Initialize the resample preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the corresponding items to be transformed. Should include both image and mask keys.

• target_spacing (Sequence[float]) -- Target spacing to resample to, e.g., (2.0, 2.0, 2.0).

• img_mode (str) -- Interpolation mode for image data. Defaults to "bilinear".

• padding_mode (str) -- Padding mode for out-of-bound values. Defaults to "border".

• align_corners (bool) -- Whether to align corners. Defaults to False.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

• **kwargs -- Additional parameters for resampling.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Resample the images and masks to the target spacing.

参数:

data (Dict[str, Any]) -- Input data dictionary containing SimpleITK image objects and metadata. The values for image and mask keys should be SimpleITK Image objects.

返回:

Data dictionary with resampled images and masks.

返回类型:

Dict[str, Any]

class habit.core.preprocessing.registration.RegistrationPreprocessor(keys: str | List[str], fixed_image: str, mask_keys: str | List[str] | None = None, type_of_transform: str = 'SyN', metric: str = 'MI', optimizer: str | None = None, use_mask: bool = False, allow_missing_keys: bool = False, replace_by_fixed_image_mask: bool = True, **kwargs)

基类：BasePreprocessor

Register images to a reference image using ANTs.

This preprocessor performs image registration using ANTs (Advanced Normalization Tools). It supports various registration methods including SyN, Rigid, Affine, etc.

__init__(keys: str | List[str], fixed_image: str, mask_keys: str | List[str] | None = None, type_of_transform: str = 'SyN', metric: str = 'MI', optimizer: str | None = None, use_mask: bool = False, allow_missing_keys: bool = False, replace_by_fixed_image_mask: bool = True, **kwargs)

Initialize the registration preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the images to be registered.

• fixed_image (str) -- Key of the reference image to register to.

• mask_keys (Optional[Union[str, List[str]]]) -- Keys of the masks to use for registration.

• type_of_transform (str) -- Type of transform to use. Options: - "Rigid": Rigid transformation - "Affine": Affine transformation - "SyN": Symmetric normalization (deformable) - "SyNRA": SyN + Rigid + Affine - "SyNOnly": SyN without initial rigid/affine - "TRSAA": Translation + Rotation + Scaling + Affine - "Elastic": Elastic transformation - "SyNCC": SyN with cross-correlation metric - "SyNabp": SyN with mutual information metric - "SyNBold": SyN optimized for BOLD images - "SyNBoldAff": SyN + Affine for BOLD images - "SyNAggro": SyN with aggressive optimization - "TVMSQ": Time-varying diffeomorphism with mean square metric

• metric (str) -- Similarity metric to use. Options: - "CC": Cross-correlation - "MI": Mutual information - "MeanSquares": Mean squares - "Demons": Demons metric

• optimizer (str) -- Optimizer to use. Options: - "gradient_descent": Gradient descent - "lbfgsb": L-BFGS-B - "amoeba": Amoeba

• use_mask (bool) -- If True, use mask for registration.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

• replace_by_fixed_image_mask (bool) -- If True, use fixed image's mask to replace moving image's mask after registration.

• **kwargs -- Additional parameters for registration.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Register the specified images to the reference image.

参数:

data (Dict[str, Any]) -- Input data dictionary containing ANTs image objects.

返回:

Data dictionary with registered images.

返回类型:

Dict[str, Any]

格式转换 (Format Conversion)

DICOM to NIfTI converter using dcm2niix tool.

This module provides functionality to batch convert DICOM files to NIfTI format using the dcm2niix tool, with integration into the HABIT preprocessing pipeline.

class habit.core.preprocessing.dcm2niix_converter.Dcm2niixConverter(keys: str | List[str], dcm2niix_path: str | None = None, filename_format: str | None = None, adjacent_dicoms: bool = True, compress: bool = True, anonymize: bool = False, ignore_derived: bool = False, crop_images: bool = False, generate_json: bool = False, verbose: bool = False, batch_mode: bool = True, merge_slices: str | None = '2', single_file_mode: bool | None = None, allow_missing_keys: bool = False, **kwargs)

基类：BasePreprocessor

Convert DICOM files to NIfTI format using dcm2niix tool.

This preprocessor takes DICOM directories and converts them to NIfTI format using the dcm2niix command-line tool. It supports batch processing and integrates with the HABIT preprocessing pipeline.

__init__(keys: str | List[str], dcm2niix_path: str | None = None, filename_format: str | None = None, adjacent_dicoms: bool = True, compress: bool = True, anonymize: bool = False, ignore_derived: bool = False, crop_images: bool = False, generate_json: bool = False, verbose: bool = False, batch_mode: bool = True, merge_slices: str | None = '2', single_file_mode: bool | None = None, allow_missing_keys: bool = False, **kwargs)

Initialize the dcm2niix converter.

参数:

• keys (Union[str, List[str]]) -- Keys containing DICOM directory paths to convert

• dcm2niix_path (Optional[str]) -- Full path to dcm2niix executable or directory containing it

• filename_format (Optional[str]) -- Output filename format (default: uses subject name)

• compress (bool) -- Compress output files (default: True)

• anonymize (bool) -- Anonymize filenames (default: False)

• ignore_derived (bool) -- Ignore derived images (default: False)

• crop_images (bool) -- Crop images (default: False)

• generate_json (bool) -- Generate BIDS JSON sidecar files (default: False)

• verbose (bool) -- Verbose output (default: False)

• batch_mode (bool) -- Enable batch mode (default: True)

• merge_slices (Optional[str]) -- Merge mode - "y"/"1"=default merge, "2"=merge by series, "n"/"0"=no merge, None=don't specify (default: "2")

• single_file_mode (Optional[bool]) -- Single file mode - True=force single file (-s y), False=allow multiple (-s n), None=don't specify/use default (default: None)

• allow_missing_keys (bool) -- Allow missing keys (default: False)

• **kwargs -- Additional parameters

batch_convert_subjects(subjects_data: Dict[str, Dict[str, str]]) → Dict[str, Dict[str, Image]]

Batch convert DICOM directories for multiple subjects.

参数:

subjects_data (Dict[str, Dict[str, str]]) -- Dictionary with subject IDs as keys and sequence dictionaries as values Format: {subject_id: {sequence_name: dicom_dir_path}}

返回:

Dictionary containing SimpleITK Image objects

Format: {subject_id: {sequence_name: sitk_image}}

返回类型:

Dict[str, Dict[str, sitk.Image]]

__call__(data: Dict[str, Any]) → Dict[str, Any]

Process the input data to convert DICOM directories to SimpleITK Image objects.

参数:

data (Dict[str, Any]) -- Input data dictionary containing DICOM directory paths

返回:

Data dictionary with SimpleITK Image objects added

返回类型:

Dict[str, Any]

habit.core.preprocessing.dcm2niix_converter.batch_convert_dicom_directories(input_mapping: Dict[str, Dict[str, str]], dcm2niix_path: str | None = None, **kwargs) → Dict[str, Dict[str, Image]]

Utility function for batch DICOM to NIfTI conversion.

参数:

• input_mapping (Dict[str, Dict[str, str]]) -- Mapping of subjects to their DICOM directories Format: {subject_id: {sequence_name: dicom_dir_path}}

• dcm2niix_path (Optional[str]) -- Full path to dcm2niix executable or directory containing it

• **kwargs -- Additional parameters for Dcm2niixConverter

返回:

Dictionary containing SimpleITK Image objects

返回类型:

Dict[str, Dict[str, sitk.Image]]

示例

>>> input_data = {
...     "subject_001": {
...         "T1": "/path/to/subject_001/T1_dicom",
...         "T2": "/path/to/subject_001/T2_dicom"
...     },
...     "subject_002": {
...         "T1": "/path/to/subject_002/T1_dicom"
...     }
... }
>>> converted = batch_convert_dicom_directories(
...     input_data,
...     dcm2niix_path="/path/to/dcm2niix/bin"
... )

基类与工厂 (Base & Factory)

class habit.core.preprocessing.base_preprocessor.BasePreprocessor(keys: str | List[str], allow_missing_keys: bool = False)

基类：ABC

Base class for all image preprocessors in HABIT.

This class defines the basic interface that all preprocessors must implement.

__init__(keys: str | List[str], allow_missing_keys: bool = False)

Initialize the preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the corresponding items to be transformed.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

abstract __call__(data: Dict[str, Any]) → Dict[str, Any]

Process the input data.

参数:

data (Dict[str, Any]) -- Input data dictionary containing image and metadata.

返回:

Processed data dictionary.

返回类型:

Dict[str, Any]

class habit.core.preprocessing.preprocessor_factory.PreprocessorFactory

基类：object

Factory class for creating preprocessors.

This class manages the registration and instantiation of preprocessors.

classmethod register(name: str) → callable

Register a preprocessor class with the factory.

参数:

name (str) -- Name of the preprocessor to register.

返回:

Decorator function.

返回类型:

callable

classmethod create(name: str, **kwargs: Any) → BasePreprocessor

Create an instance of a registered preprocessor.

参数:

• name (str) -- Name of the preprocessor to create.

• **kwargs -- Additional arguments to pass to the preprocessor constructor.

返回:

Instance of the requested preprocessor.

返回类型:

BasePreprocessor

抛出:

ValueError -- If the requested preprocessor is not registered.

classmethod get_available_preprocessors() → List[str]

Get a list of all registered preprocessor names.

返回:

List of registered preprocessor names.

返回类型:

List[str]

class habit.core.preprocessing.custom_preprocessor_template.CustomPreprocessor(keys: str | List[str], allow_missing_keys: bool = False, **kwargs: Any)

基类：BasePreprocessor

Template for creating custom preprocessors.

This class serves as a template for users to create their own preprocessors. Users should: 1. Copy this file and rename it 2. Change the class name and registration name 3. Implement the __call__ method with their custom preprocessing logic 4. Add any necessary helper methods for preprocessing

示例

@PreprocessorFactory.register("my_preprocessor") class MyPreprocessor(BasePreprocessor):

def __init__(self, keys, param1, param2, **kwargs):

super().__init__(keys=keys) self.param1 = param1 self.param2 = param2

def __call__(self, data):

self._check_keys(data) for key in self.keys:

data[key] = self._process_image(data[key])

return data

__init__(keys: str | List[str], allow_missing_keys: bool = False, **kwargs: Any)

Initialize the custom preprocessor.

参数:

• keys (Union[str, List[str]]) -- Keys of the corresponding items to be transformed. If a single string is provided, it will be converted to a list.

• allow_missing_keys (bool) -- If True, allows missing keys in the input data.

• **kwargs -- Additional arguments specific to the custom preprocessor. These should be documented in the class docstring.

__call__(data: Dict[str, Any]) → Dict[str, Any]

Process the input data with custom preprocessing logic.

参数:

data (Dict[str, Any]) -- Input data dictionary containing image and metadata. The values for keys should be in the expected format (e.g., SimpleITK Image objects, numpy arrays, or torch tensors).

返回:

Processed data dictionary with the same structure as input.

返回类型:

Dict[str, Any]

示例

# 1. Check if required keys are present self._check_keys(data)

# 2. Process each key for key in self.keys:

# Get the data item = data[key]

# Process the data processed_item = self._process_item(item)

# Update the data dictionary data[key] = processed_item

# Update metadata if necessary meta_key = f"{key}_meta_dict" if meta_key in data:

data[meta_key]["processed"] = True data[meta_key]["processor"] = self.__class__.__name__

return data