biapy.data.generators.single_base_data_generator

Single image data generator for BiaPy.

This module provides the SingleBaseDataGenerator class, which supports flexible data loading, augmentation, and normalization for single image data in deep learning workflows. It includes a wide range of augmentation options for both 2D and 3D data, and is designed to work with BiaPyDataset objects and normalization modules.

class biapy.data.generators.single_base_data_generator.SingleBaseDataGenerator(ndim: int, X: BiaPyDataset, norm_module: Dict, seed: int = 0, da: bool = True, da_prob: float = 0.5, rotation90: bool = False, rand_rot: bool = False, rnd_rot_range=(-180, 180), shear: bool = False, shear_range=(-20, 20), zoom: bool = False, zoom_range=(0.8, 1.2), zoom_in_z: bool = False, shift: bool = False, shift_range=(0.1, 0.2), affine_mode: Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap'] = 'constant', vflip: bool = False, hflip: bool = False, elastic: bool = False, e_alpha=(240, 250), e_sigma: int = 25, e_mode: Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap'] = 'constant', g_blur: bool = False, g_sigma: Tuple[float, float] = (1.0, 2.0), median_blur: bool = False, mb_kernel: Tuple[int, int] = (3, 7), motion_blur: bool = False, motb_k_range: Tuple[int, int] = (3, 8), gamma_contrast: bool = False, gc_gamma: Tuple[float, float] = (1.25, 1.75), dropout: bool = False, drop_range: Tuple[float, float] = (0, 0.2), val: bool = False, resize_shape: Tuple[int, ...] = (256, 256, 1), convert_to_rgb: bool = False, preprocess_f=None, preprocess_cfg=None)[source]

Bases: Dataset

Custom BaseDataGenerator to transform single image data.

Parameters:

ndim (int) – Dimensions of the data (2 for 2D and 3 for 3D).
X (BiaPyDataset) – X data.
norm_module (Dict) – Normalization module that defines the normalization steps to apply.
seed (int, optional) – Seed for random functions.
da (bool, optional) – To activate the data augmentation.
da_prob (float, optional) – Probability of doing each transformation.
rotation90 (bool, optional) – To make square (90, 180,270) degree rotations.
rand_rot (bool, optional) – To make random degree range rotations.
rnd_rot_range (tuple of float, optional) – Range of random rotations. E. g. (-180, 180).
shear (bool, optional) – To make shear transformations.
shear_range (tuple of int, optional) – Degree range to make shear. E. g. (-20, 20).
zoom (bool, optional) – To make zoom on images.
zoom_range (tuple of floats, optional) – Zoom range to apply. E. g. (0.8, 1.2).
zoom_in_z (bool, optional) – Whether to apply or not zoom in Z axis.
shift (float, optional) – To make shifts.
shift_range (tuple of float, optional) – Range to make a shift. E. g. (0.1, 0.2).
affine_mode (str, optional) – Method to use when filling in newly created pixels. Same meaning as in skimage (and numpy.pad()). E.g. constant, reflect etc.
vflip (bool, optional) – To activate vertical flips.
hflip (bool, optional) – To activate horizontal flips.
elastic (bool, optional) – To make elastic deformations.
e_alpha (tuple of ints, optional) – Strength of the distortion field. E. g. (240, 250).
e_sigma (int, optional) – Standard deviation of the gaussian kernel used to smooth the distortion fields.
e_mode (str, optional) – Parameter that defines the handling of newly created pixels with the elastic transformation.
g_blur (bool, optional) – To insert gaussian blur on the images.
g_sigma (tuple of floats, optional) – Standard deviation of the gaussian kernel. E. g. (1.0, 2.0).
median_blur (bool, optional) – To blur an image by computing median values over neighbourhoods.
mb_kernel (tuple of ints, optional) – Median blur kernel size. E. g. (3, 7).
motion_blur (bool, optional) – Blur images in a way that fakes camera or object movements.
motb_k_range (int, optional) – Kernel size to use in motion blur.
gamma_contrast (bool, optional) – To insert gamma constrast changes on images.
gc_gamma (tuple of floats, optional) – Exponent for the contrast adjustment. Higher values darken the image. E. g. (1.25, 1.75).
dropout (bool, optional) – To set a certain fraction of pixels in images to zero.
drop_range (tuple of floats, optional) – Range to take a probability p to drop pixels. E.g. (0, 0.2) will take a p folowing 0<=p<=0.2 and then drop p percent of all pixels in the image (i.e. convert them to black pixels).
val (bool, optional) – Advise the generator that the images will be to validate the model to not make random crops (as the val. data must be the same on each epoch).
resize_shape (tuple of ints, optional) – If defined the input samples will be scaled into that shape.
convert_to_rgb (bool, optional) – In case RGB images are expected, e.g. if crop_shape channel is 3, those images that are grayscale are converted into RGB.
preprocess_f (function, optional) – The preprocessing function, is necessary in case you want to apply any preprocessing.
preprocess_cfg (dict, optional) – Configuration parameters for preprocessing, is necessary in case you want to apply any preprocessing.

abstract save_aug_samples(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], orig_images: Dict, i: int, pos: int, out_dir: str, draw_grid: bool)[source]

Save transformed samples in order to check the generator.

Parameters:

img (3D/4D Numpy array) – Image to use as sample. E.g. (y, x, channels) for 2D and (z, y, x, channels) for 3D.
orig_images (dict) – Dict where the original image and mask are saved in “o_x” and “o_y”, respectively.
i (int) – Number of the sample within the transformed ones.
pos (int) – Number of the sample within the dataset.
out_dir (str) – Directory to save the images.
draw_grid (bool) – Whether to draw a grid or not.

load_sample(idx: int, first_load: bool = False) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], int][source]

Load one data sample given its corresponding index.

Parameters:

idx (int) – Sample index counter.
first_load (bool, optional) – Whether its the first time a sample is loaded to prevent normalizing it.

Returns:

img (3D/4D Numpy array) – X element. E.g. (y, x, channels) in 2D and (z, y, x, channels) in 3D.
img_class (int) – Class of the image.

getitem(index: int) → Tuple[Tensor, int][source]

Generate one sample of data.

Parameters:: index (int) – Index counter.
Returns:: item – X and Y (if avail) elements. X is (z, y, x, channels) if 3D or (y, x, channels) if 2D. Y is an integer.
Return type:: tuple of 3D/4D Numpy arrays

apply_transform(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Transform the input image with one of the selected choices based on a probability.

Parameters:: image (3D/4D Numpy array) – Image to transform. E.g. (y, x, channels) in 2D or (z, y, x, channels) in 3D.
Returns:: image – Transformed image. E.g. (y, x, channels) in 2D or (z, y, x, channels) in 3D.
Return type:: 3D/4D Numpy array

draw_grid(im: ndarray[tuple[int, ...], dtype[_ScalarType_co]], grid_width: int | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Draw grid of the specified size on an image.

Parameters:

im (3D/4D Numpy array) – Image to be modified. E.g. (y, x, channels) in 2D or (z, y, x, channels) in 3D.
grid_width (int, optional) – Grid’s width.

get_transformed_samples(num_examples: int, random_images: bool = True, save_to_dir: bool = True, out_dir: str = 'aug', train: bool = False, draw_grid: bool = True)[source]

Apply selected transformations to a defined number of images from the dataset.

Parameters:

num_examples (int) – Number of examples to generate.
random_images (bool, optional) – Randomly select images from the dataset. If False the examples will be generated from the start of the dataset.
save_to_dir (bool, optional) – Save the images generated. The purpose of this variable is to check the images generated by data augmentation.
out_dir (str, optional) – Name of the folder where the examples will be stored.
train (bool, optional) – To avoid drawing a grid on the generated images. This should be set when the samples will be used for training.
draw_grid (bool, optional) – Draw a grid in the generated samples. Useful to see some types of deformations.

Returns:

sample_x – Batch of data. E.g. (num_examples, y, x, channels) in 2D or (num_examples, z, y, x, channels) in 3D.

Return type:

4D/5D Numpy array