pyBIA.data_augmentation

Created on Thu Sep 27 08:28:20 2021

@author: daniel

Functions

augmentation(channel1[, channel2, channel3, channel4, ...])

Offline image augmentation for up to three aligned channels (bands), with optional stacking.

random_cutout(images[, mask_size, num_masks, seed, ...])

Cutout augmentation: randomly applies square or circular zeroed masks to each image.

image_blending(images[, num_augmentations, ...])

Blend multiple single-band images to create augmented samples.

resize(data[, size])

Center-crop square images to a fixed size.

random_skew(→ numpy.ndarray)

Apply a random 2‑D shear (“skew”) to an image without using OpenCV.

random_zoom(images[, zoom_min, zoom_max, seed])

Randomly apply isotropic zoom to 2D or 3D image arrays.

plot(data[, cmap, title])

Plot a 2D image (or stacked-channel image) with robust contrast limits.

Module Contents

pyBIA.data_augmentation.augmentation(channel1, channel2=None, channel3=None, channel4=None, channel5=None, batch=1, width_shift=0, height_shift=0, horizontal=False, vertical=False, rotation=False, fill='nearest', image_size=None, zoom_range=None, mask_size=None, num_masks=None, blend_multiplier=0, blending_func='mean', num_images_to_blend=2, skew_angle=0, return_stacked=False)[source]

Offline image augmentation for up to three aligned channels (bands), with optional stacking.

Parameters:

  • channel1 (ndarray) – First channel as a single image (H×W) or a stack (N×H×W). Always required.

  • channel2 (ndarray or None, optional) – Second channel aligned to channel1, shape (H×W) or (N×H×W). Default is None.

  • channel3 (ndarray or None, optional) – Third channel aligned to channel1, shape (H×W) or (N×H×W). Default is None.

  • channel4 (ndarray or None, optional) – Fourth channel aligned to channel1, shape (H×W) or (N×H×W). Default is None.

  • channel5 (ndarray or None, optional) – Fifth channel aligned to channel1, shape (H×W) or (N×H×W). Default is None.

  • batch (int, optional) – Number of augmented samples to generate per input image. Default is 1.

  • width_shift (int, optional) – Maximum horizontal pixel shift (both directions). Default is 0.

  • height_shift (int, optional) – Maximum vertical pixel shift (both directions). Default is 0.

  • horizontal (bool, optional) – Random left–right flips if enabled. Default is False.

  • vertical (bool, optional) – Random up–down flips if enabled. Default is False.

  • rotation (bool, optional) – Random rotation by an angle uniformly sampled in [0°, 360°] if enabled. Default is False.

  • fill ({'constant','nearest','reflect','wrap'}, optional) – Fill mode used for pixels introduced by shifts/rotations. Default is ‘nearest’.

  • image_size (int or None, optional) – Output side length for cropping/resizing after transforms (returns H=W=image_size); if None, keep original size. Default is None.

  • zoom_range (tuple[float, float] or None, optional) – (min_zoom, max_zoom) factor applied uniformly at random (e.g., (0.9, 1.1)); if None, no zoom is applied. Default is None.

  • mask_size (int or None, optional) – Diameter of circular cutout mask applied at random locations; if None, cutouts are disabled. Default is None.

  • num_masks (int or None, optional) – Number of cutouts per image when mask_size is set; requires mask_size. Default is None.

  • blend_multiplier (float, optional) – Ratio controlling the number of synthetic blended images (≥1 replaces/expands the set, <1 disables blending); 0 disables entirely. Default is 0.

  • blending_func ({'mean','max','min','random'}, optional) – Reduction used when blending multiple images into one. Default is ‘mean’.

  • num_images_to_blend (int, optional) – Number of images randomly selected to compose each blend when blending is enabled. Default is 2.

  • skew_angle (float, optional) – Maximum absolute skew angle in degrees (sampled uniformly from [-skew_angle, +skew_angle]); 0 disables skew. Default is 0.

  • return_stacked (bool, optional) – If True, return channels concatenated along a last dimension (N×H×W×C); otherwise return one array per input channel. Default is False.

Returns:

  • aug1 (ndarray) – Augmented images for channel1, shape (M×H×W) when not stacked, where M = N×batch possibly modified by zoom/blend steps.

  • aug2 (ndarray, optional) – Augmented images for channel2 when provided and return_stacked is False, same length and shape as aug1.

  • aug3 (ndarray, optional) – Augmented images for channel3 when provided and return_stacked is False, same length and shape as aug1.

  • aug4 (ndarray, optional) – Augmented images for channel4 when provided and return_stacked is False, same length and shape as aug1.

  • aug5 (ndarray, optional) – Augmented images for channel5 when provided and return_stacked is False, same length and shape as aug1.

  • stacked (ndarray) – If return_stacked is True, a single array of shape (M×H×W×C) with C equal to the number of provided channels (2 or 3 or 4 or 5).

Notes

  • Channels must be input in order, i.e., do not input channel4 is channel3 is None!

  • Identical random seeds are reused across channels so that all spatial transforms (shift/flip/rotate/zoom/skew, blending, cutouts) are aligned.

  • If mask_size is provided, num_masks must also be provided (and vice-versa).

  • width_shift and height_shift must be integers specifying pixel ranges.

  • Setting blend_multiplier >= 1 generates blended samples; e.g., 1.0 replaces with blends, 1.5 increases the set by 50% using blends.

pyBIA.data_augmentation.random_cutout(images, mask_size=16, num_masks=1, seed=None, mask_type='circle')[source]

Cutout augmentation: randomly applies square or circular zeroed masks to each image.

Parameters:

  • images (ndarray) – Input as a single image (H×W) or a stack (N×H×W); values are preserved except where masked. Default is required.

  • mask_size (int, optional) – Mask scale: radius for ‘circle’; half-side for ‘square’ (final square = 2×mask_size by 2×mask_size). Default is 16.

  • num_masks (int, optional) – Number of masks to place per image; masks may overlap. Default is 1.

  • seed (int or None, optional) – Random seed for reproducible mask placement; if None, use current RNG state. Default is None.

  • mask_type ({'square','circle'}, optional) – Shape of each mask region applied to the image(s). Default is ‘circle’.

Returns:

Array with cutouts applied; same shape as input (H×W for a single image, N×H×W for a stack).

Return type:

ndarray

pyBIA.data_augmentation.image_blending(images, num_augmentations=1, blend_ratio=0.5, blending_func='mean', normalize_blend=True, num_images_to_blend=5, seed=None)[source]

Blend multiple single-band images to create augmented samples.

Parameters:

  • images (ndarray) – Input as a stack (N×H×W) or a single image (H×W); values are linearly or elementwise combined to form new images. Default is required.

  • num_augmentations (int, optional) – Number of blended images to generate; must be a positive integer. Default is 1.

  • blend_ratio (float, optional) – Mixing weight for ‘mean’ blending where output = (1−blend_ratio)·A + blend_ratio·B; constrained to [0, 1]. Default is 0.5.

  • blending_func ({'mean','max','min','random'}, optional) – Rule used to combine images where ‘random’ picks one of the other modes per blend. Default is ‘mean’.

  • normalize_blend (bool, optional) – If True, divide each blended image by the number of images combined to keep overall intensity comparable. Default is True.

  • num_images_to_blend (int, optional) – Maximum number of distinct images sampled (uniformly without replacement) to combine per augmentation; must be ≤ N. Default is 5.

  • seed (int or None, optional) – Random seed for reproducible sampling and mode selection when applicable. Default is None.

Returns:

Blended images with shape (num_augmentations, H, W).

Return type:

ndarray

pyBIA.data_augmentation.resize(data, size=50)[source]

Center-crop square images to a fixed size.

Parameters:

  • data (ndarray) – Input as a single image (H×W), a stack (N×H×W), or a multi-channel stack (N×H×W×C with C ≤ 3); samples must be square. Default is required.

  • size (int or None, optional) – Target side length in pixels for the center crop; if None, return the input unchanged. Default is 50.

Returns:

Cropped image(s) with shape (H’×W’), (N×H’×W’), or (N×H’×W’×C), where H’=W’=size.

Return type:

ndarray

Raises:

ValueError – If input is 1D, non-square, has more than 3 channels, or has an unsupported shape.

Notes

  • If the current side length already equals size, the input is returned unchanged.

  • For a single sample with channels (H×W×C), reshape to (1×H×W×C) before calling.

pyBIA.data_augmentation.random_skew(image: numpy.ndarray, max_angle: float = 15.0, intensity: float = 0.1, seed: int | None = None, order: int = 1, mode: str = 'constant', cval: float = 0.0) → numpy.ndarray[source]

Apply a random 2‑D shear (“skew”) to an image without using OpenCV.

Parameters:

  • image (np.ndarray) – 2‑D array representing the input image.

  • max_angle (float, optional) – Maximum absolute shear angle (degrees) sampled independently for x and y directions. Default is 15°.

  • intensity (float, optional) – Additional multiplicative control on the magnitude of the shear.

  • seed (int or None, optional) – Seed for the RNG; set for reproducibility.

  • order (int, optional) – Interpolation order passed to scipy.ndimage.affine_transform. Defaults to 1.

  • mode ({'constant', 'nearest', 'mirror', 'wrap'}, optional) – How values outside the input are filled. Passed directly to affine_transform. Default is 'constant'.

  • cval (float, optional) – Constant value used when mode='constant'. Default=0.0.

Returns:

Skewed image with the same shape and dtype as image.

Return type:

np.ndarray

pyBIA.data_augmentation.random_zoom(images, zoom_min=0.9, zoom_max=1.1, seed=None)[source]

Randomly apply isotropic zoom to 2D or 3D image arrays.

Parameters:

  • images (ndarray) – Input image(s) as (H×W) or (N×H×W); 2D input is treated as a single image. Default is required.

  • zoom_min (float, optional) – Lower bound on the random zoom factor; values < 1.0 shrink and > 1.0 enlarge. Default is 0.9.

  • zoom_max (float, optional) – Upper bound on the random zoom factor; must be ≥ zoom_min. Default is 1.1.

  • seed (int or None, optional) – Random seed for reproducibility; if None, use global RNG state. Default is None.

Returns:

Zoomed image(s), shape matches input dimensionality: (H×W) or (N×H×W).

Return type:

ndarray

Raises:

ValueError – If images is not 2D or 3D, or if zoom_max < zoom_min.

Notes

  • Nearest-neighbor interpolation is used (order=0) and edges are filled with nearest values.

pyBIA.data_augmentation.plot(data, cmap='gray', title='')[source]

Plot a 2D image (or stacked-channel image) with robust contrast limits.

Parameters:

  • data (ndarray) – 2D array for a single-channel image, or 3D array with stacked channels (e.g., H×W×C where C∈{1,3}). Default is required.

  • cmap (str, optional) – Matplotlib colormap name applied for 2D input; ignored for true-color (H×W×3). Default is ‘gray’.

  • title (str, optional) – Text displayed above the image; empty string shows no title. Default is ‘’.

Returns:

Handle from matplotlib.pyplot.imshow.

Return type:

AxesImage

Notes

Contrast limits are computed over finite pixels using a median/MAD-like scale: vmin = median − 3×MAD and vmax = median + 10×MAD.