biapy.data.generators.augmentors

Augmentation utilities for image and mask data in deep learning workflows.

This module provides a variety of data augmentation functions for images and masks, including cutout, cutblur, cutmix, cutnoise, misalignment, cropping, flipping, rotation, zoom, gamma/contrast adjustment, blurring, dropout, elastic deformation, shear, shift, and more. These augmentations are designed to improve model robustness and generalization for both 2D and 3D data formats.

biapy.data.generators.augmentors.cutout(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]], z_size: int, nb_iterations: Tuple[int, int] = (1, 3), size: Tuple[float, float] = (0.2, 0.4), cval: int = 0, res_relation: Tuple[float, ...] = (1.0, 1.0), apply_to_mask: bool = False) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Apply augmentation using Cutout technique.

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

Parameters:

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

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

  • 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 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 (Numpy array) – Transformed image. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

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

Examples

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

../../../_images/orig_cutout.png

Input image
../../../_images/orig_cutout_mask.png

Corresponding mask
../../../_images/cutout.png

Augmented image
../../../_images/cutout_mask.png

Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.cutblur(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], size: Tuple[float, float] = (0.2, 0.4), down_ratio_range: Tuple[int, int] = (2, 8), only_inside: bool = True) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Apply CutBlur data augmentation.

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 (Numpy array) – Image to transform. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

  • 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) for 2D or (y, x, z, channels) for 3D.

Return type:

Numpy array

Examples

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

../../../_images/orig_cutblur.png

Input image
../../../_images/cutblur.png

Augmented image
../../../_images/orig_cutblur2.png

Input image
../../../_images/cutblur2.png

Augmented image

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

biapy.data.generators.augmentors.cutmix(im1: ndarray[tuple[int, ...], dtype[_ScalarType_co]], im2: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask1: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask2: ndarray[tuple[int, ...], dtype[_ScalarType_co]], heat1: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None, heat2: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None, size: Tuple[float, float] = (0.2, 0.4)) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None][source]

Apply Cutmix data augmentation.

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 (Numpy array) – Image to transform. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

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

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

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

  • heat1 (Numpy array or None) – Heatmap to transform (belongs to im1). E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D. If None, no heatmap is used.

  • heat2 (Numpy array or None) – Heatmap to paste into the region of heat1. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D. If None, no heatmap is used.

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

Returns:

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

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

  • h_out (Numpy array or None) – Transformed heatmap. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

Examples

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

../../../_images/orig_cutmix.png

Input image
../../../_images/orig_cutmix_mask.png

Corresponding mask
../../../_images/cutmix.png

Augmented image
../../../_images/cutmix_mask.png

Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.cutnoise(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], scale: Tuple[float, float] = (0.1, 0.2), nb_iterations: Tuple[int, int] = (1, 3), size: Tuple[float, float] = (0.2, 0.4)) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Apply Cutnoise data augmentation.

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 (Numpy array) – Image to transform. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

  • 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) for 2D or (y, x, z, channels) for 3D.

Return type:

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:

../../../_images/orig_cutnoise.png

Input image
../../../_images/cutnoise.png

Augmented image
../../../_images/orig_cutnoise2.png

Input image
../../../_images/cutnoise2.png

Augmented image

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

biapy.data.generators.augmentors.misalignment(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]], displacement: int = 16, rotate_ratio: float = 0.0) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Apply mis-alignment data augmentation.

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 (Numpy array) – Image to transform. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

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

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

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

Returns:

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

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

Examples

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

../../../_images/orig_miss.png

Input image
../../../_images/orig_miss_mask.png

Corresponding mask
../../../_images/miss.png

Augmented image
../../../_images/miss_mask.png

Augmented mask

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.brightness(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], brightness_factor: Tuple[float, float] = (0, 0)) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Randomly adjust brightness between a range.

Parameters:

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

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

Returns:

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

Return type:

Numpy array

Examples

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

../../../_images/orig_bright.png

Input image
../../../_images/bright.png

Augmented image
../../../_images/orig_bright2.png

Input image
../../../_images/bright2.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.contrast(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], contrast_factor: Tuple[float, float] = (0, 0)) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Contrast augmentation.

Parameters:

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

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

Returns:

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

Return type:

Numpy array

Examples

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

../../../_images/orig_contrast.png

Input image
../../../_images/contrast.png

Augmented image
../../../_images/orig_contrast2.png

Input image
../../../_images/contrast2.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.missing_sections(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], iterations: Tuple[int, int] = (30, 40), channel_prob: float = 0.5) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

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

Implementation based on PyTorch Connectomics’ missing_parts.py.

Parameters:

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

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

  • channel_prob (float, optional) – Probability of applying a missing section to each channel individually.

Returns:

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

Return type:

Numpy array

Examples

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

../../../_images/orig_missing.png

Input image
../../../_images/missing.png

Augmented image
../../../_images/orig_missing2.png

Input image
../../../_images/missing2.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.shuffle_channels(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Augment the image by shuffling its channels.

Parameters:

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

Returns:

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

Return type:

3D/4D Numpy array

Examples

../../../_images/orig_chshuffle.png

Input image
../../../_images/chshuffle.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.grayscale(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Augment the image by converting it into grayscale.

Parameters:

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

Returns:

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

Return type:

3D/4D Numpy array

Examples

../../../_images/orig_grayscale.png

Input image
../../../_images/grayscale.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.GridMask(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], z_size: int, ratio: float = 0.6, d_range: Tuple[float, ...] = (30.0, 60.0), rotate: int = 1, invert: bool = False) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Apply GridMask data augmentation presented in GridMask Data Augmentation.

GridMask is a data augmentation technique that randomly masks out grid-like regions in the image, which helps the model to learn more robust features by forcing it to focus on different parts of the image Code adapted from https://github.com/dvlab-research/GridMask/blob/master/imagenet_grid/utils/grid.py.

Parameters:

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

  • 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 floats, 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) for 2D or (y, x, z, channels) for 3D.

Return type:

Numpy array

Examples

Calling this function with the default settings may result in:

../../../_images/orig_GridMask.png

Input image
../../../_images/GridMask.png

Augmented image

The grid is painted for visualization purposes.

biapy.data.generators.augmentors.random_crop_pair(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]], random_crop_size: Tuple[int, ...], val: bool = False, draw_prob_map_points: bool = False, img_prob: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, weight_map: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, scale: Tuple[int, ...] = (1, 1)) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], int, int, int, int][source]

Apply 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, channels).

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

  • 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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]], random_crop_size: Tuple[int, ...], val: bool = False, img_prob: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, weight_map: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, draw_prob_map_points: bool = False, scale: Tuple[int, ...] = (1, 1, 1)) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], int, int, int, int, int, int][source]

Extract 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. (z, 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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], random_crop_size: Tuple[int, ...], val: bool = False, draw_prob_map_points: bool = False, weight_map: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], int, int, int, int][source]

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) for 2D or (y, x, z, channels) for 3D.

  • 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) for 2D or (y, x, z, channels) for 3D.

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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], random_crop_size: Tuple[int, ...], val: bool = False, draw_prob_map_points: bool = False, weight_map: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], int, int, int, int, int, int][source]

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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], crop_shape: Tuple[int, ...]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], shape: Tuple[int, ...]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Resize 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.

  • shape (2D/3D int tuple) – Shape to resize the image to. 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: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, angles: Tuple[int, int] | List[int] = [], mode: str = 'reflect', mask_type: str = 'as_mask') → ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None, ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None][source]

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 (y, x, z, channels) for 3D.

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

  • heat (3D/4D Numpy array, optional) – Heatmap (float mask) to rotate. E.g. (y, x, channels) for 2D or (y, x, z, 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: constant, reflect, wrap, symmetric.

  • mask_type (str, optional) – How to treat the mask during interpolation. Either as β€œas_mask” (order 0) or β€œas_image” (order 1).

Returns:

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

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

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

biapy.data.generators.augmentors.zoom(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], zoom_range: Tuple[float, ...], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, zoom_in_z: bool = False, mode: str = 'reflect', mask_type: str = 'as_mask') → ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None, ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None][source]

Apply zoom to input image and mask (if provided).

Parameters:

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

  • zoom_range (tuple of floats) – Defines minimum and maximum factors to scale the images. E.g. (0.8, 1.2).

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

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

  • zoom_in_z (bool, optional) – Whether to apply or not zoom in Z axis.

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

  • mask_type (str, optional) – How to treat the mask during interpolation. Either as β€œas_mask” (order 0) or β€œas_image” (order 1).

Returns:

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

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

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

biapy.data.generators.augmentors.gamma_contrast(img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], gamma: Tuple[float, float] = (0, 1)) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Apply gamma contrast to input image.

Parameters:

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

  • gamma (tuple of 2 floats, optional) – Range of gamma intensity. E.g. (0.8, 1.3).

Returns:

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

Return type:

Numpy array

biapy.data.generators.augmentors.shear(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], shear: tuple, mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, cval: float = 0, mask_type: str = 'as_mask', mode: str = 'constant')[source]

Apply a shear transformation to an image (and optional mask/heatmap).

Parameters:

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

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

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

  • shear (tuple) – Shear range (min, max) in degrees for both x and y directions.

  • cval (float) – Value used for points outside the boundaries.

  • mask_type (str) – How to treat the mask during interpolation. Either as β€œas_mask” (order 0) or β€œas_image” (order 1).

  • mode (str) – Points outside boundaries are filled according to this mode.

Returns:

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

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

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

biapy.data.generators.augmentors.shift(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, shift_range: tuple | None = None, cval: float = 0, mask_type: str = 'as_mask', mode: str = 'constant')[source]

Shift an image (and optional mask/heatmap) by a random amount within a range.

Parameters:

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

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

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

  • shift_range (Optional[tuple]) – Range (min, max) for random shift in both x and y directions.

  • cval (float) – Value used for points outside the boundaries.

  • mask_type (str) – How to treat the mask during interpolation. Either as β€œas_mask” (order 0) or β€œas_image” (order 1).

  • mode (str) – Points outside boundaries are filled according to this mode.

Returns:

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

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

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

biapy.data.generators.augmentors.flip_horizontal(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)[source]

Flip an image (and optional mask/heatmap) horizontally (left-right).

Parameters:

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

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

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

Returns:

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

  • mask (3D/4D Numpy array or None) – Flipped mask if provided, else None.

  • heat (3D/4D Numpy array or None) – Flipped heatmap if provided, else None.

biapy.data.generators.augmentors.flip_vertical(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)[source]

Flip an image (and optional mask/heatmap) vertically (up-down).

Parameters:

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

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

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

Returns:

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

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

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

biapy.data.generators.augmentors.gaussian_blur(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], sigma: float | tuple = (0.5, 1.5))[source]

Apply Gaussian blur to an image.

Parameters:

  • image (Numpy array) – Image to Blur. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

  • sigma (float or tuple) – Standard deviation for Gaussian kernel. If tuple, a random value is chosen from the range.

Returns:

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

Return type:

NDArray

biapy.data.generators.augmentors.median_blur(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], k_range: tuple | None = None)[source]

Apply median blur to an image.

Parameters:

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

  • k_range (Optional[tuple]) – Range (min, max) for random kernel size (must be odd).

Returns:

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

Return type:

NDArray

biapy.data.generators.augmentors.motion_blur(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], k_range: tuple | None = None)[source]

Apply motion blur to an image.

Parameters:

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

  • k_range (Optional[tuple]) – Range (min, max) for random kernel size (must be odd).

Returns:

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

Return type:

NDArray

biapy.data.generators.augmentors.dropout(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], drop_range: tuple = (0.1, 0.2), random_state: RandomState | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Randomly set a fraction of pixels in the image to zero (dropout).

Parameters:

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

  • drop_range (tuple) – Range for dropout probability. A value is randomly chosen from this range.

  • random_state (Optional[np.random.RandomState]) – Random state for reproducibility.

Returns:

img – Image after dropout. E.g. (y, x, channels) for 2D or (y, x, z, channels) for 3D.

Return type:

3D/4D Numpy array

biapy.data.generators.augmentors.elastic(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mask: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, heat: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, alpha: float | tuple = 14, sigma: float = 4, mask_type: str = 'as_mask', cval: float = 0, mode: str = 'constant', random_seed=None) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None, ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None][source]

Apply elastic deformation to an image (and optional mask/heatmap).

Parameters:

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

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

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

  • alpha (float, optional) – Scaling factor for deformation intensity.

  • sigma (float, optional) – Standard deviation for Gaussian filter.

  • cval (float, optional) – Value used for points outside the boundaries.

  • mode (str, optional) – Points outside boundaries are filled according to this mode.

  • mask_type (str, optional) – How to treat the mask during interpolation. Either as β€œas_mask” (order 0) or β€œas_image” (order 1).

  • random_seed (int, optional) – Random seed for reproducibility.

Returns:

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

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

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