convster.filters.gaussian#

This module provides various functions to facilitate the usage of skimage.filters.gaussian

Attributes#

img_filter

Functions#

bpgaussian(data, **filter_params)

Applies a border-preserving Gaussian filter

compatible_border_size(sigma[, border])

Assert that the border size is compatible with the specified parameter

get_blur_params([diameter, sigma, truncate])

Compute Gaussian blur parameters from either diameter or sigma.

get_kernel_diameter(sigma, **params)

Compute the effective Gaussian kernel diameter in number of cells.

get_kernel_size(sigma, **params)

Return the radius of a Gaussian kernel (center to border distance).

Module Contents#

convster.filters.gaussian.bpgaussian(data, **filter_params)[source]#

Applies a border-preserving Gaussian filter

The approach considers a Gaussian blur to be a weighted average over all pixels within the kernel diameter with the weight being given by the Gaussian function. Pixels close to np.nan values should simply “ignore” np.nan pixels and perform the weighted average over all non-np.nan pixels within the Gaussian kernel. This can be achieved with a normal Gaussian filter in a three-step process:

  1. Perform a Gaussian filter on the data with np.nan substituted by the neutral element in terms of addition, i.e. 0.0. This leads to a weighted average that is not properly normalized as the former np.nan pixels do not contribute to the value, but are considered in the normalizing sum of the weights.

  2. To properly normalize all pixels, create a binary array in the same shape as data with np.nan values becoming 0 and all other pixels 1. Apply the same Gaussian filter to this binary array which results in an array holding the sum of weights for the weighted average.

  3. Dividing the blurred array from point 1. by the sum-of-weights array form step 2 results in a properly normalized weighted average and thus a blurred version of the input data with preserved borders.

Parameters:

  • data (NDArray) – Array to apply the Gaussian filter on.

  • **filter_params (dict) –

    Additional keyword arguments passed to skimage.filters.gaussian(). Common parameters include:

    • sigmafloat

      Standard deviation for Gaussian kernel.

    • truncatefloat

      Truncate filter at this many standard deviations.

    See skimage.filters.gaussian() for further parameters.

Returns:

Blurred version of data with borders preserved at NaN boundaries.

Return type:

NDArray

See also

get_kernel_diameter()

Compute the effective kernel diameter for a given sigma.

get_blur_params()

Compute Gaussian blur parameters from diameter or sigma.

convster.filters.gaussian.compatible_border_size(sigma, border=None, **params)[source]#

Assert that the border size is compatible with the specified parameter

This method asserts that the kernel size determined by sigma and further parametrization is smaller than the border. If no border is provided, then the minimal border size (in number of pixels) is returned.

Parameters:

  • sigma (float or int) – Standard deviation for Gaussian kernel

  • border (tuple[int, int] or None) – The border size (width, height) in number of pixels along each axis

  • **params – Additional keyword arguments passed to get_kernel_size().

Returns:

The border (width, height) compatible with the specified parameters. If a border was provided already, it is returned again, if no border was provided, the smallest compatible border is returned.

Return type:

tuple[int, int]

See also

get_kernel_size()

Compute the kernel radius used in compatibility checks.

get_kernel_diameter()

Compute the full diameter of the Gaussian kernel.

convster.filters.gaussian.get_blur_params(diameter=None, sigma=None, truncate=3)[source]#

Compute Gaussian blur parameters from either diameter or sigma.

Either diameter or sigma must be provided. Missing values are inferred from the others, and truncate is used or recomputed to maintain consistency.

Parameters:

  • diameter (float or None) – Kernel diameter. If provided with sigma, truncate is recomputed.

  • sigma (float or None) – Standard deviation of the Gaussian kernel. If provided with diameter, truncate is recomputed.

  • truncate (float) – Number of standard deviations at which to truncate the kernel. Default is 3. Ignored if both diameter and sigma are provided (recomputed).

Returns:

Dictionary containing: - diameter: computed kernel diameter - sigma: computed standard deviation - truncate: final truncate value

Return type:

dict[str, float]

Raises:

TypeError – If neither diameter nor sigma is provided.

Notes

The function ensures that diameter, sigma, and truncate are consistent according to Gaussian kernel conventions.

See also

get_kernel_diameter()

Compute the effective kernel diameter from sigma.

get_kernel_size()

Compute the kernel radius from sigma.

compatible_border_size()

Assert or compute a border compatible with the kernel.

Examples

>>> get_blur_params(diameter=15)
{'diameter': 15, 'sigma': 2.5, 'truncate': 3}
>>> get_blur_params(sigma=2.0)
{'diameter': 12.0, 'sigma': 2.0, 'truncate': 3}
>>> get_blur_params(diameter=15, sigma=3)
{'diameter': 15, 'sigma': 3, 'truncate': 2.5}
convster.filters.gaussian.get_kernel_diameter(sigma, **params)[source]#

Compute the effective Gaussian kernel diameter in number of cells.

The diameter is estimated by applying a Gaussian filter to a single impulse in the center of a zero image, and measuring the spread of the nonzero region. The result is always odd to ensure symmetry.

Parameters:

  • sigma (float) – Standard deviation for the Gaussian kernel. Currently only single scalar values are supported.

  • **params – Additional keyword arguments passed to the Gaussian filter.

Returns:

Estimated kernel diameter in pixels (always an odd number).

Return type:

int

Notes

This function determines the kernel diameter adaptively. Starting from an initial guess of 10 * sigma, the size is increased until the blurred impulse response fits within the kernel. Uses skimage.filters.gaussian() internally to compute the impulse response.

See also

get_kernel_size()

Return the radius (half-diameter) of the Gaussian kernel.

compatible_border_size()

Assert or compute a border size compatible with a kernel.

Examples

>>> get_kernel_diameter(1)
7
>>> get_kernel_diameter(2)
15
convster.filters.gaussian.get_kernel_size(sigma, **params)[source]#

Return the radius of a Gaussian kernel (center to border distance).

The kernel size is defined as half of the kernel diameter minus one, i.e. size = (diameter - 1) / 2 where diameter is determined by get_kernel_diameter().

Parameters:

  • sigma (float) – Standard deviation for the Gaussian kernel.

  • **params – Additional keyword arguments passed to get_kernel_diameter() (e.g. truncate, mode).

Returns:

The radius of the Gaussian kernel in pixels.

Return type:

int

See also

get_kernel_diameter()

Compute the full kernel diameter.

compatible_border_size()

Assert or compute a border size compatible with a kernel.

Examples

>>> get_kernel_size(1)
3
>>> get_kernel_size(2)
7
convster.filters.gaussian.img_filter[source]#