pyBIA.data_augmentation ======================= .. py:module:: pyBIA.data_augmentation .. autoapi-nested-parse:: Created on Thu Sep 27 08:28:20 2021 @author: daniel Functions --------- .. autoapisummary:: pyBIA.data_augmentation.augmentation pyBIA.data_augmentation.random_cutout pyBIA.data_augmentation.image_blending pyBIA.data_augmentation.resize pyBIA.data_augmentation.random_skew pyBIA.data_augmentation.random_zoom pyBIA.data_augmentation.plot Module Contents --------------- .. py:function:: 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) Offline image augmentation for up to three aligned channels (bands), with optional stacking. :param channel1: First channel as a single image (H×W) or a stack (N×H×W). Always required. :type channel1: ndarray :param channel2: Second channel aligned to `channel1`, shape (H×W) or (N×H×W). Default is None. :type channel2: ndarray or None, optional :param channel3: Third channel aligned to `channel1`, shape (H×W) or (N×H×W). Default is None. :type channel3: ndarray or None, optional :param channel4: Fourth channel aligned to `channel1`, shape (H×W) or (N×H×W). Default is None. :type channel4: ndarray or None, optional :param channel5: Fifth channel aligned to `channel1`, shape (H×W) or (N×H×W). Default is None. :type channel5: ndarray or None, optional :param batch: Number of augmented samples to generate per input image. Default is 1. :type batch: int, optional :param width_shift: Maximum horizontal pixel shift (both directions). Default is 0. :type width_shift: int, optional :param height_shift: Maximum vertical pixel shift (both directions). Default is 0. :type height_shift: int, optional :param horizontal: Random left–right flips if enabled. Default is False. :type horizontal: bool, optional :param vertical: Random up–down flips if enabled. Default is False. :type vertical: bool, optional :param rotation: Random rotation by an angle uniformly sampled in [0°, 360°] if enabled. Default is False. :type rotation: bool, optional :param fill: Fill mode used for pixels introduced by shifts/rotations. Default is 'nearest'. :type fill: {'constant','nearest','reflect','wrap'}, optional :param image_size: Output side length for cropping/resizing after transforms (returns H=W=image_size); if None, keep original size. Default is None. :type image_size: int or None, optional :param zoom_range: (min_zoom, max_zoom) factor applied uniformly at random (e.g., (0.9, 1.1)); if None, no zoom is applied. Default is None. :type zoom_range: tuple[float, float] or None, optional :param mask_size: Diameter of circular cutout mask applied at random locations; if None, cutouts are disabled. Default is None. :type mask_size: int or None, optional :param num_masks: Number of cutouts per image when `mask_size` is set; requires `mask_size`. Default is None. :type num_masks: int or None, optional :param blend_multiplier: Ratio controlling the number of synthetic blended images (≥1 replaces/expands the set, <1 disables blending); 0 disables entirely. Default is 0. :type blend_multiplier: float, optional :param blending_func: Reduction used when blending multiple images into one. Default is 'mean'. :type blending_func: {'mean','max','min','random'}, optional :param num_images_to_blend: Number of images randomly selected to compose each blend when blending is enabled. Default is 2. :type num_images_to_blend: int, optional :param skew_angle: Maximum absolute skew angle in degrees (sampled uniformly from [-skew_angle, +skew_angle]); 0 disables skew. Default is 0. :type skew_angle: float, optional :param return_stacked: If True, return channels concatenated along a last dimension (N×H×W×C); otherwise return one array per input channel. Default is False. :type return_stacked: bool, optional :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). .. rubric:: 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. .. py:function:: random_cutout(images, mask_size=16, num_masks=1, seed=None, mask_type='circle') Cutout augmentation: randomly applies square or circular zeroed masks to each image. :param images: Input as a single image (H×W) or a stack (N×H×W); values are preserved except where masked. Default is required. :type images: ndarray :param mask_size: Mask scale: radius for 'circle'; half-side for 'square' (final square = 2×mask_size by 2×mask_size). Default is 16. :type mask_size: int, optional :param num_masks: Number of masks to place per image; masks may overlap. Default is 1. :type num_masks: int, optional :param seed: Random seed for reproducible mask placement; if None, use current RNG state. Default is None. :type seed: int or None, optional :param mask_type: Shape of each mask region applied to the image(s). Default is 'circle'. :type mask_type: {'square','circle'}, optional :returns: Array with cutouts applied; same shape as input (H×W for a single image, N×H×W for a stack). :rtype: ndarray .. py:function:: image_blending(images, num_augmentations=1, blend_ratio=0.5, blending_func='mean', normalize_blend=True, num_images_to_blend=5, seed=None) Blend multiple single-band images to create augmented samples. :param images: 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. :type images: ndarray :param num_augmentations: Number of blended images to generate; must be a positive integer. Default is 1. :type num_augmentations: int, optional :param blend_ratio: Mixing weight for 'mean' blending where output = (1−blend_ratio)·A + blend_ratio·B; constrained to [0, 1]. Default is 0.5. :type blend_ratio: float, optional :param blending_func: Rule used to combine images where 'random' picks one of the other modes per blend. Default is 'mean'. :type blending_func: {'mean','max','min','random'}, optional :param normalize_blend: If True, divide each blended image by the number of images combined to keep overall intensity comparable. Default is True. :type normalize_blend: bool, optional :param num_images_to_blend: Maximum number of distinct images sampled (uniformly without replacement) to combine per augmentation; must be ≤ N. Default is 5. :type num_images_to_blend: int, optional :param seed: Random seed for reproducible sampling and mode selection when applicable. Default is None. :type seed: int or None, optional :returns: Blended images with shape (num_augmentations, H, W). :rtype: ndarray .. py:function:: resize(data, size=50) Center-crop square images to a fixed size. :param data: 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. :type data: ndarray :param size: Target side length in pixels for the center crop; if None, return the input unchanged. Default is 50. :type size: int or None, optional :returns: Cropped image(s) with shape (H'×W'), (N×H'×W'), or (N×H'×W'×C), where H'=W'=size. :rtype: ndarray :raises ValueError: If input is 1D, non-square, has more than 3 channels, or has an unsupported shape. .. rubric:: 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. .. py:function:: random_skew(image: numpy.ndarray, max_angle: float = 15.0, intensity: float = 0.1, seed: Optional[int] = None, order: int = 1, mode: str = 'constant', cval: float = 0.0) -> numpy.ndarray Apply a random 2‑D shear (“skew”) to an image without using OpenCV. :param image: 2‑D array representing the input image. :type image: np.ndarray :param max_angle: Maximum absolute shear angle (degrees) sampled independently for *x* and *y* directions. Default is 15°. :type max_angle: float, optional :param intensity: Additional multiplicative control on the magnitude of the shear. :type intensity: float, optional :param seed: Seed for the RNG; set for reproducibility. :type seed: int or None, optional :param order: Interpolation order passed to ``scipy.ndimage.affine_transform``. Defaults to 1. :type order: int, optional :param mode: How values outside the input are filled. Passed directly to ``affine_transform``. Default is ``'constant'``. :type mode: {'constant', 'nearest', 'mirror', 'wrap'}, optional :param cval: Constant value used when ``mode='constant'``. Default=0.0. :type cval: float, optional :returns: Skewed image with the same shape and dtype as *image*. :rtype: np.ndarray .. py:function:: random_zoom(images, zoom_min=0.9, zoom_max=1.1, seed=None) Randomly apply isotropic zoom to 2D or 3D image arrays. :param images: Input image(s) as (H×W) or (N×H×W); 2D input is treated as a single image. Default is required. :type images: ndarray :param zoom_min: Lower bound on the random zoom factor; values < 1.0 shrink and > 1.0 enlarge. Default is 0.9. :type zoom_min: float, optional :param zoom_max: Upper bound on the random zoom factor; must be ≥ `zoom_min`. Default is 1.1. :type zoom_max: float, optional :param seed: Random seed for reproducibility; if None, use global RNG state. Default is None. :type seed: int or None, optional :returns: Zoomed image(s), shape matches input dimensionality: (H×W) or (N×H×W). :rtype: ndarray :raises ValueError: If `images` is not 2D or 3D, or if `zoom_max` < `zoom_min`. .. rubric:: Notes - Nearest-neighbor interpolation is used (order=0) and edges are filled with nearest values. .. py:function:: plot(data, cmap='gray', title='') Plot a 2D image (or stacked-channel image) with robust contrast limits. :param data: 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. :type data: ndarray :param cmap: Matplotlib colormap name applied for 2D input; ignored for true-color (H×W×3). Default is 'gray'. :type cmap: str, optional :param title: Text displayed above the image; empty string shows no title. Default is ''. :type title: str, optional :returns: Handle from `matplotlib.pyplot.imshow`. :rtype: AxesImage .. rubric:: Notes Contrast limits are computed over finite pixels using a median/MAD-like scale: vmin = median − 3×MAD and vmax = median + 10×MAD.