albumentations.augmentations.blur.functional

View Source on GitHub

Functional implementations of various blur operations for image processing. This module provides a collection of low-level functions for applying different blur effects to images, including standard blur, glass blur, defocus, and zoom effects. These functions form the foundation for the corresponding transform classes.

Members

functionbox_blur
functionglass_blur
functioncreate_defocus_kernel
functiondefocus
functioncentral_zoom
functionzoom_blur
functionmode_filter
functionprocess_blur_range
functioncreate_motion_kernel
functionsample_odd_from_range
functioncreate_gaussian_kernel
functioncreate_gaussian_kernel_1d
functioncreate_pillow_gaussian_kernel
functionpillow_gaussian_blur
functioncreate_gaussian_kernel_input_array

box_blurfunction

box_blur(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    ksize: int
)

Smooth image with uniform rectangular kernel (moving average). ksize sets size. Use for mild noise reduction or downscale prep. This function applies a blur to an image. Args: img (NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]): Input image. ksize (int): Kernel size. Returns: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]: Blurred image.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
ksize	int	-	-

glass_blurfunction

glass_blur(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    sigma: float,
    max_delta: int,
    iterations: int,
    dxy: np.ndarray,
    mode: Literal['fast', 'exact']
)

Glass-like effect: Gaussian blur then random pixel swaps. Sigma, max_delta, iterations, dxy. Use for frosted-glass look. This function applies a glass blur to an image. Args: img (NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]): Input image. sigma (float): Sigma. max_delta (int): Maximum delta. iterations (int): Number of iterations. dxy (np.ndarray): Dxy. mode (Literal['fast', 'exact']): Mode. Returns: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]: Glass blurred image.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
sigma	float	-	-
max_delta	int	-	-
iterations	int	-	-
dxy	np.ndarray	-	-
mode	One of: 'fast' 'exact'	-	-

create_defocus_kernelfunction

create_defocus_kernel(
    radius: int,
    alias_blur: float
)

Create defocus (aliased disk) convolution kernel. radius, alias_blur control disk shape and smoothing. Returns kernel for convolve.

Parameters

Name	Type	Default	Description
radius	int	-	-
alias_blur	float	-	-

defocusfunction

defocus(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    radius: int,
    alias_blur: float
)

Blur with aliased disk kernel to simulate out-of-focus. radius, alias_blur set size and softness. Use for depth-of-field or bokeh-style effects.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
radius	int	-	-
alias_blur	float	-	-

central_zoomfunction

central_zoom(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    zoom_factor: int
)

Zoom from center by integer factor: crop center, upsample, trim to original size. Used in zoom-blur pipeline; zoom_factor must be positive. This function zooms an image. Args: img (NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]): Input image. zoom_factor (int): Zoom factor. Returns: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]: Zoomed image.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
zoom_factor	int	-	-

zoom_blurfunction

zoom_blur(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    zoom_factors: np.ndarray | Sequence[int]
)

Radial zoom blur: blend image with center-zoomed copies. zoom_factors; normalized result. Use for motion or out-of-focus style. Float32 working arithmetic with output clipped to [0, 1]. This function zooms and blurs an image. Args: img (NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]): Input image. zoom_factors (np.ndarray | Sequence[int]): Zoom factors. Returns: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]: Zoomed and blurred image.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
zoom_factors	One of: np.ndarray Sequence[int]	-	-

mode_filterfunction

mode_filter(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    kernel_size: int
)

Replace each pixel with the most frequent value in its local square neighborhood. Float inputs are quantized to uint8 for the discrete mode operation, then restored to the input dtype. Ties choose the smallest value and borders use reflect padding.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
kernel_size	int	-	-

process_blur_rangefunction

process_blur_range(
    value: tuple[int, int],
    info: ValidationInfo,
    min_value: int = 0
)

Validate a blur kernel range tuple, enforcing the `min_value` lower bound and odd kernel sizes (non-odd values auto-adjusted with a warning).

Parameters

Name	Type	Default	Description
value	tuple[int, int]	-	-
info	ValidationInfo	-	-
min_value	int	0	-

create_motion_kernelfunction

create_motion_kernel(
    kernel_size: int,
    angle: float,
    direction: float,
    allow_shifted: bool,
    random_state: random.Random
)

Create motion blur kernel (2D float32). kernel_size (odd), angle, direction (-1 to 1), allow_shifted, random_state. Returns normalized kernel. Args: kernel_size (int): Size of the kernel (must be odd) angle (float): Angle in degrees (counter-clockwise) direction (float): Blur direction (-1.0 to 1.0) allow_shifted (bool): Allow kernel to be randomly shifted from center random_state (random.Random): Python's random.Random instance Returns: np.ndarray: Motion blur kernel

Parameters

Name	Type	Default	Description
kernel_size	int	-	-
angle	float	-	-
direction	float	-	-
allow_shifted	bool	-	-
random_state	random.Random	-	-

sample_odd_from_rangefunction

sample_odd_from_range(
    random_state: random.Random,
    low: int,
    high: int
)

Sample odd number from [low, high] (inclusive). Low/high normalized to odd (min 3). For blur transforms when sampling kernel size from a range. Args: random_state (random.Random): instance of random.Random low (int): lower bound (will be converted to nearest valid odd number) high (int): upper bound (will be converted to nearest valid odd number) Returns: int: Randomly sampled odd number from the range Note: - Input values will be converted to nearest valid odd numbers: * Values less than 3 will become 3 * Even values will be rounded up to next odd number - After normalization, high must be >= low

Parameters

Name	Type	Default	Description
random_state	random.Random	-	-
low	int	-	-
high	int	-	-

create_gaussian_kernelfunction

create_gaussian_kernel(
    sigma: float,
    ksize: int = 0
)

Create a discrete 2D Gaussian kernel. Sigma and ksize (0 = auto). Returns normalized float32 kernel for separable or 2D convolution. Args: sigma (float): Standard deviation for Gaussian kernel. ksize (int): Kernel size. If 0, size is computed as int(sigma * 3.5) * 2 + 1. Otherwise, must be positive and odd. Returns: np.ndarray: 2D normalized Gaussian kernel.

Parameters

Name	Type	Default	Description
sigma	float	-	-
ksize	int	0	-

create_gaussian_kernel_1dfunction

create_gaussian_kernel_1d(
    sigma: float,
    ksize: int = 0
)

Create a discrete 1D Gaussian kernel. Sigma and ksize (0 = auto). For separable Gaussian blur; returns normalized float32 1D array. Args: sigma (float): Standard deviation for Gaussian kernel. ksize (int): Kernel size. If 0, size is computed as int(sigma * 3.5) * 2 + 1. Otherwise, must be positive and odd. Returns: np.ndarray: 1D normalized Gaussian kernel.

Parameters

Name	Type	Default	Description
sigma	float	-	-
ksize	int	0	-

create_pillow_gaussian_kernelfunction

create_pillow_gaussian_kernel(
    sigma: float
)

Build the fixed-point extended-box kernel that Pillow uses to approximate Gaussian blur, including fractional edge weights for exact uint8 rounding. Args: sigma (float): Standard deviation of the target Gaussian. Returns: np.ndarray: One-dimensional uint32 kernel in Pillow's 24-bit fixed-point scale.

Parameters

Name	Type	Default	Description
sigma	float	-	-

pillow_gaussian_blurfunction

pillow_gaussian_blur(
    img: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32],
    kernel: np.ndarray
)

Blur an image with Pillow's three-pass extended-box Gaussian approximation, reproducing uint8 rounding without importing Pillow at runtime. Float16 and float32 inputs use the same normalized kernel and replicated borders without uint8 quantization. Floating work uses float32; float16 is rounded once on output. Non-native NumPy byte order is restored after filtering. Args: img (NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]): Input image. kernel (np.ndarray): Fixed-point extended-box kernel from `create_pillow_gaussian_kernel`. Returns: NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]: Blurred image with the input shape and dtype.

Parameters

Name	Type	Default	Description
img	One of: NDArray[np.uint8] NDArray[np.float16] NDArray[np.float32]	-	-
kernel	np.ndarray	-	-

create_gaussian_kernel_input_arrayfunction

create_gaussian_kernel_input_array(
    size: int
)

1-D x-coordinates -size/2 to size/2 for Gaussian kernel. Piecewise for size < 100 (faster than np.linspace). Returns float array. Piecewise function is needed as equivalent python list comprehension is faster than np.linspace for values of size < 100 Args: size (int): kernel size Returns: np.ndarray: x-coordinate array which will be input for gaussian function that will be used for separable gaussian blur

Parameters

Name	Type	Default	Description
size	int	-	-