Package: medimageaugment
MedImageAugment.pyOverviewThis module provides a collection of image augmentation techniques that can be applied to 2D or 3D images. Image augmentation is commonly used in deep learning and computer vision tasks to increase the diversity of training data and improve the generalization of machine learning models. The module supports various augmentations, including rotations, flips, scaling, noise addition, and more.RequirementsTo use this module, you need to have the following Python packages installed:numpycv2(OpenCV)scipyscikit-imagesklearnYou can install them usingpip:pipinstallnumpyopencv-pythonscipyscikit-imagescikit-learnUsageImport the module and create an instance of ImageAugment:fromMedImageAugment.MedImageAugmentimportImageAugmentInstantiate theImageAugmentclass:augmenter=ImageAugment(seed=42,modality='MRI',random_rotation_3d=True,random_scaling_3d=True,random_crop_3d=True,random_horizontal_flip_3d=True,random_vertical_flip_3d=True)Add augmentations:You can add specific augmentations to theImageAugmentinstance using the provided methods. For example:# Add some augmentationsaugmenter.add_random_brightness(max_delta=30)augmenter.add_random_contrast(lower=0.7,upper=1.3)augmenter.add_elastic_deformation(alpha=9,sigma=0.7)augmenter.add_speckle_noise(mean=0,std=10)augmenter.add_random_rotation_3d(max_angle=30)# Add more augmentations as needed...Augment a single image:importcv2# Load an image (example)image_path="path_to_your_image.png"image=cv2.imread(image_path,cv2.IMREAD_GRAYSCALE)# Augment the imageaugmented_image=augmenter.augment_image(image)Augment a batch of images:importglob# Load a batch of images (example)image_paths=glob.glob("path_to_folder/*.png")images=[cv2.imread(path,cv2.IMREAD_GRAYSCALE)forpathinimage_paths]# Augment the batch of imagesaugmented_images=augmenter.augment_batch(images)Modality-specific augmentations:The module provides modality-specific augmentations for different medical imaging modalities, such as 'CT', 'X-ray', 'MRI', and 'Ultrasound'. When creating theImageAugmentinstance, you can specify the modality, and the augmentations will be automatically set accordingly.Additional Notes:Each augmentation function performs a specific image transformation.You can add multiple augmentations to theImageAugmentinstance to apply them sequentially.The augmentations are randomly shuffled before applying to introduce diversity.Some augmentations support 3D images, but make sure to set the corresponding parameters when creating theImageAugmentinstance.Example:Here's an example of using theImageAugmentclass to augment a single 2D image:importcv2fromMedImageAugment.MedImageAugmentimportImageAugment# Load an imageimage_path="path_to_your_image.png"image=cv2.imread(image_path,cv2.IMREAD_GRAYSCALE)# Instantiate the ImageAugment classaugmenter=ImageAugment(seed=42,modality='X-ray')# Add some augmentationsaugmenter.add_random_brightness(max_delta=30)augmenter.add_random_contrast(lower=0.7,upper=1.3)augmenter.add_speckle_noise(mean=0,std=10)augmenter.add_random_horizontal_flip()# Augment the imageaugmented_image=augmenter.augment_image(image)# Display the original and augmented images (example)cv2.imshow("Original Image",image)cv2.imshow("Augmented Image",augmented_image)cv2.waitKey(0)cv2.destroyAllWindows()Adding ParameterGrid for Hyperparameter SearchIn some cases, you may want to perform hyperparameter search to find the best combination of augmentation parameters for your specific use case. To facilitate this, you can add a method to theImageAugmentclass that generates a parameter grid containing all possible combinations of the augmentation parameters. Here's how you can do it:fromitertoolsimportproductclassImageAugment:# Previous class implementation...defgenerate_parameter_grid(self)->List[dict]:"""Generate a parameter grid for hyperparameter search.Returns:List[dict]: A list of dictionaries representing all possible combinations of augmentation parameters."""param_grid=[]# Define the hyperparameter rangesmax_angle_values=[15,30,45]scale_range_values=[(0.8,1.2),(0.9,1.1),(0.7,1.3)]crop_size_values=[(100,100),(120,120),(80,80)]# Add more hyperparameter ranges as needed...# Generate all possible combinations of hyperparametersformax_angle,scale_range,crop_sizeinproduct(max_angle_values,scale_range_values,crop_size_values):params={'max_angle':max_angle,'scale_range':scale_range,'crop_size':crop_size,# Add more hyperparameters here...}param_grid.append(params)returnparam_gridNow, you can use this method to generate the parameter grid and then loop through all the combinations to evaluate the performance of your model with different augmentations during hyperparameter search.augmenter=ImageAugment(seed=42,modality='X-ray')param_grid=augmenter.generate_parameter_grid()forparamsinparam_grid:# Instantiate the ImageAugment class with specific parametersaugmenter=ImageAugment(seed=42,modality='X-ray',random_rotation_3d=True,random_scaling_3d=True,random_crop_3d=True,random_horizontal_flip_3d=True,random_vertical_flip_3d=True)# Add augmentations with the specific hyperparametersaugmenter.add_random_rotation_3d(max_angle=params['max_angle'])augmenter.add_random_scaling_3d(scale_range=params['scale_range'])augmenter.add_random_crop_3d(crop_size=params['crop_size'])# Train and evaluate your model with the current augmentation settings# Perform hyperparameter search using different combinations of augmentations# ...Functions__init__(self, seed: Optional[int] = None, modality: str = 'general', ...):Constructor of the class that initializes the augmentation list, seed, and modality.Inputs:seed(Optional[int]): Seed value for reproducible randomness. Defaults toNone.modality(str): The modality of the images to be augmented (e.g., 'CT', 'X-ray', 'MRI', 'Ultrasound'). Defaults to'general'.Parameters for enabling specific 3D augmentations:random_rotation_3d(bool): Enable random 3D rotation. Defaults toFalse.random_scaling_3d(bool): Enable random 3D scaling. Defaults toFalse.random_crop_3d(bool): Enable random 3D cropping. Defaults toFalse.random_horizontal_flip_3d(bool): Enable random 3D horizontal flipping. Defaults toFalse.random_vertical_flip_3d(bool): Enable random 3D vertical flipping. Defaults toFalse.add_modality_specific_augmentations(self):Adds modality-specific augmentations based on the specifiedmodality.Raises aValueErrorif an invalid modality is provided.validate_range(self, value, min_val, max_val, value_name):Helper method to validate if a value is within a specified range.Inputs:value: The value to be validated.min_val: Minimum allowed value.max_val: Maximum allowed value.value_name: Name of the value for error messages.validate_positive(self, value, value_name):Helper method to validate if a value is positive.Inputs:value: The value to be validated.value_name: Name of the value for error messages.add_random_rotation(self, max_angle: float):Adds random rotation augmentation to the list of augmentations.Inputs:max_angle(float): Maximum rotation angle in degrees.add_random_horizontal_flip(self):Adds random horizontal flip augmentation to the list of augmentations.add_random_vertical_flip(self):Adds random vertical flip augmentation to the list of augmentations.add_random_brightness(self, max_delta: float):Adds random brightness augmentation to the list of augmentations.Inputs:max_delta(float): Maximum value for brightness adjustment.add_random_contrast(self, lower: float, upper: float):Adds random contrast augmentation to the list of augmentations.Inputs:lower(float): Lower bound for the contrast adjustment factor.upper(float): Upper bound for the contrast adjustment factor.add_elastic_deformation(self, alpha: float, sigma: float):Adds elastic deformation augmentation to the list of augmentations.Inputs:alpha(float): Elastic deformation intensity.sigma(float): Standard deviation of the Gaussian filter.add_random_shear(self, intensity: float):Adds random shear augmentation to the list of augmentations.Inputs:intensity(float): Maximum shear intensity.add_random_shift(self, max_shift: float):Adds random shift augmentation to the list of augmentations.Inputs:max_shift(float): Maximum shift value.add_random_scaling(self, scale_range: Tuple[float, float]):Adds random scaling augmentation to the list of augmentations.Inputs:scale_range(Tuple[float, float]): Range of scaling factors.add_random_crop(self, crop_size: Tuple[int, int]):Adds random crop augmentation to the list of augmentations.Inputs:crop_size(Tuple[int, int]): Size of the cropped region.add_random_blur(self, min_sigma: float, max_sigma: float):Adds random blur augmentation to the list of augmentations.Inputs:min_sigma(float): Minimum value for the Gaussian blur sigma.max_sigma(float): Maximum value for the Gaussian blur sigma.add_motion_blur(self, max_angle: int, max_kernel_size: int):Adds motion blur augmentation to the list of augmentations.Inputs:max_angle(int): Maximum angle for motion blur.max_kernel_size(int): Maximum kernel size for motion blur.add_random_rotation_3d(self, max_angle: float):Adds random 3D rotation augmentation to the list of augmentations.Inputs:max_angle(float): Maximum rotation angle in degrees for each axis.add_random_scaling_3d(self, scale_range: Tuple[float, float]):Adds random 3D scaling augmentation to the list of augmentations.Inputs:scale_range(Tuple[float, float]): Range of scaling factors for each axis.add_speckle_noise(self, mean: float, std: float):Adds speckle noise augmentation to the list of augmentations.Inputs:mean(float): Mean value for the noise.std(float): Standard deviation of the noise.add_rician_noise(self, mean: float, std: float):Adds Rician noise augmentation to the list of augmentations.Inputs:mean(float): Mean value for the noise.std(float): Standard deviation of the noise.add_random_crop_3d(self, crop_size: Tuple[int, int, int]):Adds random 3D crop augmentation to the list of augmentations.Inputs:crop_size(Tuple[int, int, int]): Size of the cropped region for each axis.add_random_horizontal_flip_3d(self):Adds random 3D horizontal flip augmentation to the list of augmentations.add_random_vertical_flip_3d(self):Adds random 3D vertical flip augmentation to the list of augmentations.augment_image(self, image: np.ndarray) -> np.ndarray:Applies the list of augmentations to a single image and returns the augmented image.Inputs:image(np.ndarray): The input image to be augmented.Output:(np.ndarray): The augmented image.augment_batch(self, images: List[np.ndarray]) -> List[np.ndarray]:Applies the list of augmentations to a batch of images and returns the augmented batch.Inputs:images(List[np.ndarray]): List of input images to be augmented.Output:(List[np.ndarray]): List of augmented images.add_gaussian_noise(self, mean: float = 0., std: float = 1.):Adds Gaussian noise augmentation to the list of augmentations.Inputs:mean(float): Mean value for the Gaussian noise. Defaults to 0.std(float): Standard deviation of the Gaussian noise. Defaults to 1.add_salt_pepper_noise(self, salt_prob: float = 0.05, pepper_prob: float = 0.05):Adds salt and pepper noise augmentation to the list of augmentations.Inputs:salt_prob(float): Probability of adding salt noise.pepper_prob(float): Probability of adding pepper noise.add_poisson_noise(self, lam: float = 1.):Adds Poisson noise augmentation to the list of augmentations.Inputs:lam(float): Poisson parameter (mean) for the noise. Defaults to 1.add_anisotropic_diffusion(self, max_iter=10, dt=0.1, kappa=50):Adds anisotropic diffusion augmentation to the list of augmentations.Inputs:max_iter(int): Maximum number of iterations for anisotropic diffusion. Defaults to 10.dt(float): Time step parameter for anisotropic diffusion. Defaults to 0.1.kappa(float): Conductance parameter for anisotropic diffusion. Larger values reduce diffusion across edges. Defaults to 50.ConclusionWith theImageAugmentclass and the ability to generate a parameter grid, you have a powerful tool to augment your 2D and 3D images and perform hyperparameter search to find the best augmentation settings for your particular use case. Experiment with different combinations of augmentations and hyperparameters to optimize the performance of your deep learning models and enhance their generalization capabilities.Note:Remember that the module contains both 2D and 3D augmentations. When working with 3D images, ensure that the image dimensions are correct for 3D-specific augmentations. Additionally, this documentation does not include the description of the 'add_random_shear', 'add_random_shift', 'add_random_blur', 'add_motion_blur', 'add_gaussian_noise', 'add_salt_pepper_noise', and 'add_poisson_noise' methods, as their usages are quite similar to other provided augmentations.Feel free to experiment with different combinations of augmentations to suit your specific needs and data.LicenseThis project is licensed under the MIT License - see LICENSE for details.