Augmentors

biapy.data.generators.augmentors.cutout(img, mask, channels, z_size, nb_iterations=(1, 3), size=(0.2, 0.4), cval=0, res_relation=(1, 1), apply_to_mask=False)

Cutout data augmentation presented in Improved Regularization of Convolutional Neural Networks with Cutout.

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• mask (3D Numpy array) – Mask to transform. E.g. (y, x, channels).

• channels (int) – Size of channel dimension. Used for 3D images as the channels have been merged with the z axis.

• z_size (int) – Size of z dimension. Used for 3D images as the z axis has been merged with the channels. Set to -1 to when do not want to be applied.

• nb_iterations (tuple of ints, optional) – Number of areas to fill the image with. E.g. (1, 3).

• size (tuple of floats, optional) – Range to choose the size of the areas to create.

• cval (int, optional) – Value to fill the area with.

• res_relation (tuple of ints/floats, optional) – Relation between axis resolution in (x,y,z). E.g. (1,1,0.27) for anisotropic data of 8umx8umx30um resolution.

• apply_to_mask (boolean, optional) – To apply cutout to the mask.

Returns:

• out (3D Numpy array) – Transformed image. E.g. (y, x, channels).

• mask (3D Numpy array) – Transformed mask. E.g. (y, x, channels).

Examples

Calling this function with nb_iterations=(1,3), size=(0.05,0.3), apply_to_mask=False may result in:

Input image	Corresponding mask
Augmented image	Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.cutblur(img, size=(0.2, 0.4), down_ratio_range=(2, 8), only_inside=True)

CutBlur data augmentation introduced in Rethinking Data Augmentation for Image Super-resolution: A Comprehensive Analysis and a New Strategy and adapted from https://github.com/clovaai/cutblur .

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• size (float, optional) – Size of the region to transform.

• down_ratio_range (tuple of ints, optional) – Downsampling ratio range to be applied. E.g. (2, 8).

• only_inside (bool, optional) – If True only the region inside will be modified (cut LR into HR image). If False the 50% of the times the region inside will be modified (cut LR into HR image) and the other 50% the inverse will be done (cut HR into LR image). See Figure 1 of the official paper.

Returns:

out – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with size=(0.2,0.4), down_ratio_range=(2,8), only_inside=True may result in:

Input image	Augmented image
Input image	Augmented image

The grid and the red square are painted for visualization purposes.

biapy.data.generators.augmentors.cutmix(im1, im2, mask1, mask2, size=(0.2, 0.4))

Cutmix augmentation introduced in CutMix: Regularization Strategy to Train Strong Classifiers with Localizable Features. With this augmentation a region of the image sample is filled with a given second image. This implementation is used for semantic segmentation so the masks of the images are also needed. It assumes that the images are of the same shape.

Parameters:

• im1 (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• im2 (3D Numpy array) – Image to paste into the region of im1. E.g. (y, x, channels).

• mask1 (3D Numpy array) – Mask to transform (belongs to im1). E.g. (y, x, channels).

• mask2 (3D Numpy array) – Mask to paste into the region of mask1. E.g. (y, x, channels).

• size (tuple of floats, optional) – Range to choose the size of the areas to transform. E.g. (0.2, 0.4).

Returns:

• out (3D Numpy array) – Transformed image. E.g. (y, x, channels).

• m_out (3D Numpy array) – Transformed mask. E.g. (y, x, channels).

Examples

Calling this function with size=(0.2,0.4) may result in:

Input image	Corresponding mask
Augmented image	Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.cutnoise(img, scale=(0.1, 0.2), nb_iterations=(1, 3), size=(0.2, 0.4))

Cutnoise data augmentation. Randomly add noise to a cuboid region in the image to force the model to learn denoising when making predictions.

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• scale (tuple of floats, optional) – Scale of the random noise. E.g. (0.1, 0.2).

• nb_iterations (tuple of ints, optional) – Number of areas with noise to create. E.g. (1, 3).

• size (boolean, optional) – Range to choose the size of the areas to transform. E.g. (0.2, 0.4).

Returns:

out – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with scale=(0.1,0.2), nb_iterations=(1,3) and size=(0.2,0.4) may result in:

Input image	Augmented image
Input image	Augmented image

The grid and the red squares are painted for visualization purposes.

biapy.data.generators.augmentors.misalignment(img, mask, displacement=16, rotate_ratio=0.0, c_relation='1_1')

Mis-alignment data augmentation of image stacks. This augmentation is applied to both images and masks.

Implementation based on PyTorch Connectomics’ misalign.py.

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• mask (3D Numpy array) – Mask to transform. E.g. (y, x, channels)

• displacement (int, optional) – Maximum pixel displacement in xy-plane.

• rotate_ratio (float, optional) – Ratio of rotation-based mis-alignment.

Returns:

• out (3D Numpy array) – Transformed image. E.g. (y, x, channels).

• m_out (3D Numpy array) – Transformed mask. E.g. (y, x, channels).

Examples

Calling this function with displacement=16 and rotate_ratio=0.5 may result in:

Input image	Corresponding mask
Augmented image	Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.random_rotate_matrix(height, displacement)

Auxiliary function for missaligmnet.

biapy.data.generators.augmentors.brightness(image, brightness_factor=(0, 0), mode='2D')

Randomly adjust brightness between a range.

Parameters:

• image (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• brightness_factor (tuple of 2 floats, optional) – Range of brightness’ intensity. E.g. (0.1, 0.3).

• mode (str, optional) – One of 2D or 3D.

Returns:

image – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with brightness_factor=(0.1,0.3), mode='mix', invert=False and invert_p=0 may result in:

Input image	Augmented image
Input image	Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.contrast(image, contrast_factor=(0, 0), mode='2D')

Contrast augmentation.

Parameters:

• image (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• contrast_factor (tuple of 2 floats, optional) – Range of contrast’s intensity. E.g. (0.1, 0.3).

• mode (str, optional) – One of 2D or 3D.

Returns:

image – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with contrast_factor=(0.1,0.3), mode='mix', invert=False and invert_p=0 may result in:

Input image	Augmented image
Input image	Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.brightness_em(image, brightness_factor=(0, 0), mode='2D', invert=False, invert_p=0)

Randomly adjust brightness, randomly invert the color space and apply gamma correction.

Implementation based on PyTorch Connectomics’ grayscale.py.

Parameters:

• image (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• brightness_factor (tuple of 2 floats, optional) – Range of brightness’ intensity. E.g. (0.1, 0.3).

• mode (str, optional) – One of 2D or 3D.

• invert (bool, optional) – Whether to invert the images.

• invert_p (float, optional) – Probability of inverting the images.

Returns:

image – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with brightness_factor=(0.1,0.3), mode='mix', invert=False and invert_p=0 may result in:

Input image	Augmented image
Input image	Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.contrast_em(image, contrast_factor=(0, 0), mode='2D', invert=False, invert_p=0)

Contrast augmentation. Randomly invert the color space and apply gamma correction.

Implementation based on PyTorch Connectomics’ grayscale.py.

Parameters:

• image (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• contrast_factor (tuple of 2 floats, optional) – Range of contrast’s intensity. E.g. (0.1, 0.3).

• mode (str, optional) – One of 2D or 3D.

• invert (bool, optional) – Whether to invert the image.

• invert_p (float, optional) – Probability of inverting the image.

Returns:

image – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with contrast_factor=(0.1,0.3), mode='mix', invert=False and invert_p=0 may result in:

Input image	Augmented image
Input image	Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.missing_sections(img, iterations=(30, 40))

Augment the image by creating a black line in a random position.

Implementation based on PyTorch Connectomics’ missing_parts.py.

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• iterations (tuple of 2 ints, optional) – Iterations to dilate the missing line with. E.g. (30, 40).

Returns:

out – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with iterations=(30,40) may result in:

Input image	Augmented image
Input image	Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.shuffle_channels(img)

Augment the image by shuffling its channels.

Parameters:

img (3D/4D Numpy array) – Image to transform. E.g. (y, x, channels) or (z, y, x, channels).

Returns:

out – Transformed image. E.g. (y, x, channels) or (z, y, x, channels).

Return type:

3D/4D Numpy array

Examples

Input image

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.grayscale(img)

Augment the image by converting it into grayscale.

Parameters:

img (3D/4D Numpy array) – Image to transform. E.g. (y, x, channels) or (z, y, x, channels).

Returns:

out – Transformed image. E.g. (y, x, channels) or (z, y, x, channels).

Return type:

3D/4D Numpy array

Examples

Input image

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.GridMask(img, channels, z_size, ratio=0.6, d_range=(30, 60), rotate=1, invert=False)

GridMask data augmentation presented in GridMask Data Augmentation. Code adapted from https://github.com/dvlab-research/GridMask/blob/master/imagenet_grid/utils/grid.py.

Parameters:

• img (3D Numpy array) – Image to transform. E.g. (y, x, channels).

• channels (int) – Size of channel dimension. Used for 3D images as the channels have been merged with the z axis.

• z_size (int) – Size of z dimension. Used for 3D images as the z axis has been merged with the channels. Set to -1 to when do not want to be applied.

• ratio (tuple of floats, optional) – Range to choose the size of the areas to create.

• d_range (tuple of ints, optional) – Range to choose the d value in the original paper.

• rotate (float, optional) – Rotation of the mask in GridMask. Needs to be between [0,1] where 1 is 360 degrees.

• invert (bool, optional) – Whether to invert the mask.

Returns:

out – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

Examples

Calling this function with the default settings may result in:

Input image

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.random_crop_pair(image, mask, random_crop_size, val=False, draw_prob_map_points=False, img_prob=None, weight_map=None, scale=(1, 1))

Random crop for an image and its mask. No crop is done in those dimensions that random_crop_size is greater than the input image shape in those dimensions. For instance, if an input image is 400x150 and random_crop_size is 224x224 the resulting image will be 224x150.

Parameters:

• image (Numpy 3D array) – Image. E.g. (y, x, channels).

• mask (Numpy 3D array) – Image mask. E.g. (y, x, channels).

• random_crop_size (2 int tuple) – Size of the crop. E.g. (height, width).

• val (bool, optional) – If the image provided is going to be used in the validation data. This forces to crop from the origin, e. g. (0, 0) point.

• draw_prob_map_points (bool, optional) – To return the pixel chosen to be the center of the crop.

• img_prob (Numpy 3D array, optional) – Probability of each pixel to be chosen as the center of the crop. E. .g. (y, x, channels).

• weight_map (bool, optional) – Weight map of the given image. E.g. (y, x, channels).

• scale (tuple of 2 ints, optional) – Scale factor the second image given. E.g. (2,2).

Returns:

• img (2D Numpy array) – Crop of the given image. E.g. (y, x).

• weight_map (2D Numpy array, optional) – Crop of the given image’s weigth map. E.g. (y, x).

• ox (int, optional) – X coordinate in the complete image of the chose central pixel to make the crop.

• oy (int, optional) – Y coordinate in the complete image of the chose central pixel to make the crop.

• x (int, optional) – X coordinate in the complete image where the crop starts.

• y (int, optional) – Y coordinate in the complete image where the crop starts.

biapy.data.generators.augmentors.random_3D_crop_pair(image, mask, random_crop_size, val=False, img_prob=None, weight_map=None, draw_prob_map_points=False, scale=(1, 1, 1))

Extracts a random 3D patch from the given image and mask. No crop is done in those dimensions that random_crop_size is greater than the input image shape in those dimensions. For instance, if an input image is 10x400x150 and random_crop_size is 10x224x224 the resulting image will be 10x224x150.

Parameters:

• image (4D Numpy array) – Data to extract the patch from. E.g. (z, y, x, channels).

• mask (4D Numpy array) – Data mask to extract the patch from. E.g. (z, y, x, channels).

• random_crop_size (3D int tuple) – Shape of the patches to create. E.g. (z, y, x).

• val (bool, optional) – If the image provided is going to be used in the validation data. This forces to crop from the origin, e.g. (0, 0) point.

• img_prob (Numpy 4D array, optional) – Probability of each pixel to be chosen as the center of the crop. E. g. (z, y, x, channels).

• weight_map (bool, optional) – Weight map of the given image. E.g. (y, x, channels).

• draw_prob_map_points (bool, optional) – To return the voxel chosen to be the center of the crop.

• scale (tuple of 3 ints, optional) – Scale factor the second image given. E.g. (2,4,4).

Returns:

• img (4D Numpy array) – Crop of the given image. E.g. (z, y, x, channels).

• weight_map (4D Numpy array, optional) – Crop of the given image’s weigth map. E.g. (z, y, x, channels).

• oz (int, optional) – Z coordinate in the complete image of the chose central pixel to make the crop.

• oy (int, optional) – Y coordinate in the complete image of the chose central pixel to make the crop.

• ox (int, optional) – X coordinate in the complete image of the chose central pixel to make the crop.

• z (int, optional) – Z coordinate in the complete image where the crop starts.

• y (int, optional) – Y coordinate in the complete image where the crop starts.

• x (int, optional) – X coordinate in the complete image where the crop starts.

biapy.data.generators.augmentors.random_crop_single(image, random_crop_size, val=False, draw_prob_map_points=False, weight_map=None)

Random crop for a single image. No crop is done in those dimensions that random_crop_size is greater than the input image shape in those dimensions. For instance, if an input image is 400x150 and random_crop_size is 224x224 the resulting image will be 224x150.

Parameters:

• image (Numpy 3D array) – Image. E.g. (y, x, channels).

• random_crop_size (2 int tuple) – Size of the crop. E.g. (y, x).

• val (bool, optional) – If the image provided is going to be used in the validation data. This forces to crop from the origin, e. g. (0, 0) point.

• draw_prob_map_points (bool, optional) – To return the pixel chosen to be the center of the crop.

• weight_map (bool, optional) – Weight map of the given image. E.g. (y, x, channels).

Returns:

• img (2D Numpy array) – Crop of the given image. E.g. (y, x).

• weight_map (2D Numpy array, optional) – Crop of the given image’s weigth map. E.g. (y, x).

• oy (int, optional) – Y coordinate in the complete image of the chose central pixel to make the crop.

• ox (int, optional) – X coordinate in the complete image of the chose central pixel to make the crop.

• y (int, optional) – Y coordinate in the complete image where the crop starts.

• y (int, optional) – X coordinate in the complete image where the crop starts.

biapy.data.generators.augmentors.random_3D_crop_single(image, random_crop_size, val=False, draw_prob_map_points=False, weight_map=None)

Random crop for a single image. No crop is done in those dimensions that random_crop_size is greater than the input image shape in those dimensions. For instance, if an input image is 50x400x150 and random_crop_size is 30x224x224 the resulting image will be 30x224x150.

Parameters:

• image (Numpy 3D array) – Image. E.g. (z, y, x, channels).

• random_crop_size (2 int tuple) – Size of the crop. E.g. (z, y, x).

• val (bool, optional) – If the image provided is going to be used in the validation data. This forces to crop from the origin, e. g. (0, 0) point.

• draw_prob_map_points (bool, optional) – To return the pixel chosen to be the center of the crop.

• weight_map (bool, optional) – Weight map of the given image. E.g. (z, y, x, channels).

Returns:

• img (2D Numpy array) – Crop of the given image. E.g. (z, y, x).

• weight_map (2D Numpy array, optional) – Crop of the given image’s weigth map. E.g. (z, y, x).

• ox (int, optional) – Z coordinate in the complete image of the chose central pixel to make the crop.

• oy (int, optional) – Y coordinate in the complete image of the chose central pixel to make the crop.

• ox (int, optional) – X coordinate in the complete image of the chose central pixel to make the crop.

• z (int, optional) – Z coordinate in the complete image where the crop starts.

• y (int, optional) – Y coordinate in the complete image where the crop starts.

• x (int, optional) – X coordinate in the complete image where the crop starts.

biapy.data.generators.augmentors.center_crop_single(img, crop_shape)

Extract the central patch from a single image.

Parameters:

• img (3D/4D array) – Image. E.g. (y, x, channels) or (z, y, x, channels).

• crop_shape (2/3 int tuple) – Size of the crop. E.g. (y, x) or (z, y, x).

Returns:

img – Center crop of the given image. E.g. (y, x, channels) or (z, y, x, channels).

Return type:

3D/4D Numpy array

biapy.data.generators.augmentors.resize_img(img, shape)

Resizes input image to given shape.

Parameters:

• img (3D/4D Numpy array) – Data to extract the patch from. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• crop_shape (2D/3D int tuple) – Shape of the patches to create. E.g. (y, x) for 2D (z, y, x) for 3D.

Returns:

img – Resized image. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

Return type:

3D/4D Numpy array

biapy.data.generators.augmentors.rotation(img, mask=None, heat=None, angles=[], mode='reflect', mask_type='as_mask')

Apply a rotation to input image and mask (if provided).

Parameters:

• img (3D/4D Numpy array) – Image to rotate. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• mask (3D/4D Numpy array, optional) – Mask to rotate. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• heat (3D/4D Numpy array, optional) – Heatmap (float mask) to rotate. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• angles (List of ints, optional) – List of angles to choose the rotation to be made. E.g. [90,180,360].

• mode (str, optional) – How to fill up the new values created. Options: reflect, grid-mirror, constant, grid-constant, nearest, mirror, grid-wrap, wrap.

• mask_type (str, optional) – How mask is going to be treated. Options: as_mask, as_image. With as_mask the interpolation order will be 0 (nearest).

Returns:

• img (3D/4D Numpy array) – Rotated image. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• mask (3D/4D Numpy array, optional) – Rotated mask. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.

• heat (3D/4D Numpy array, optional) – Rotated heatmap. Returned if mask is provided. E.g. (y, x, channels) for 2D or (z, y, x, channels) for 3D.