Kernels Filters and Masking

Kernels as different structural shapes

imagemks.structures.divergent(size, centered=True)

Creates two grids that specify the x and y values at each point in 2d space.

Parameters

  • size (tuple) – The size of the output grids.

  • centered (boolean, optional) – If true, the center will be in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the center will be at the origin pixel (0,0). Defaults to True.

Returns

divergent_grid – A grid that defines the x and y values at each point in 2d space. If the graph quadrants are recalled, a centered grid will produce an array with quadrants ordered as such:

[ 2 | 1 ]

[——-]

[ 3 | 4 ]

Return type

tuple of ndarrays

imagemks.structures.circle(r, size=None, centered=True, dtype=<class 'numpy.bool_'>)

Makes a circle with specified dtype. If bool or int, can be used as a mask.

Parameters

  • r (numeric) – The radius of the circle.

  • size (tuple, optional) – The size of the output array that contains the circle. Defaults to (round(2*r+1), round(2*r+1)).

  • centered (boolean, optional) – If true, the circle will be centered in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the circle will be centered at the origin pixel (0,0). Defaults to True.

  • dtype (object, optional) – A valid numpy dtype. Defaults to boolean.

Returns

circle – A circle that obeys the equation \(x^2 + y^2 < r^2\)

Return type

ndarray

imagemks.structures.donut(r_outer, r_inner, size=None, centered=True, dtype=<class 'numpy.bool_'>)

Makes a 2d donut with specified dtype. If bool or int, can be used as a mask.

Parameters

  • r_outer (numeric) – The radius of the outer border.

  • r_inner (numeric) – The radius of the inner border.

  • size (tuple, optional) – The size of the output array that contains the donut. Defaults to (round(2*r_outer+1), round(2*r_outer+1)).

  • centered (boolean, optional) – If true, the donut will be centered in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the donut will be centered at the origin pixel (0,0). Defaults to True.

  • dtype (object, optional) – A valid numpy dtype. Defaults to boolean.

Returns

donut – A donut that obeys the equation \(r_inner^2 < x^2 + y^2 < r_outer^2\)

Return type

ndarray

imagemks.structures.wheel(n_quad, width, size, r=None, start=0, centered=True, dtype=<class 'numpy.bool_'>)

Makes a 2d wheel with specified dtype. If bool or int, can be used as a mask.

Parameters

  • n_quad (int) – The number of spokes per quadrant (graph quadrant).

  • width (int) – The width of a spoke.

  • size (tuple, optional) – The size of the output array that contains the wheel.

  • r (numeric, optional) – The maximum length of a spoke. Optional.

  • start (float, optional) – Offset of the first spoke from 0 in radians.

  • centered (boolean, optional) – If true, the wheel will be centered in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the wheel will be centered at the origin pixel (0,0).

  • dtype (object, optional) – A valid numpy dtype.

Returns

wheel – A wheel that is composed of lines (called spokes) that are evenly rotated around the center pixel.

Return type

ndarray

imagemks.structures.gauss(sigma, theta=0, size=None, centered=True)

Generates a 2d gaussian distribution. Usually used as a filter or kernel.

Parameters

  • sigma (float) – The standard deviation of the gaussian. First value of tuple is the x st. dev., second value is the y st. dev.. If one value is given, x and y st. dev. are the same.

  • size (tuple, optional) – The size of the output array that contains the object. Defaults to (round(4*sigma+1), round(4*sigma+1)).

  • centered (boolean, optional) – If true, the center will be in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the center will be at the origin pixel (0,0). Defaults to True.

Returns

gauss_distribution – A 2d gaussian distribution.

Return type

ndarray

imagemks.structures.conical(r, slope=1, size=None, centered=True)

Generates a 2d array of z values for a cone in range [0,1]. The location of each value is tied to the x,y location of the pixel.

Parameters

  • r (numeric) – The radius of the base of the cone

  • slope (float) – The slope of the sides of the cone. Determines how quickly the cone approaches the maximum value of 1.

  • size (tuple, optional) – The size of the output array that contains the object. Defaults to (round(4*sigma+1), round(4*sigma+1)).

  • centered (boolean, optional) – If true, the center will be in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the center will be at the origin pixel (0,0). Defaults to True.

Returns

cone – A cone described by a 2d array.

Return type

ndarray

imagemks.structures.drop(r, threshold=None, size=None, centered=True)

Generates a 2d array of z values for a drop shape in range [0,1]. The location of each z value is tied to the x,y location of the pixel.

Parameters

  • r (numeric) – The radius of the base of the drop.

  • threshold (float) – The relative values beneath which we determine the drop is equal to 0.

  • size (tuple, optional) – The size of the output array that contains the object. Defaults to (round(4*sigma+1), round(4*sigma+1)).

  • centered (boolean, optional) – If true, the center will be in the middle of the array at pixel (size[0]//2, size[1]//2). If false, the center will be at the origin pixel (0,0). Defaults to True.

Returns

drop – A drop described by a 2d array.

Return type

ndarray

Filters that use kernels

imagemks.filters.local_avg(img, rad, mask=None)

Returns the local average of a neighborhood taking into account that the edges need to be treated differently. Averages are only calculated at the edges using values inside the image and the neighborhood.

Parameters

  • img ((M,N) array) – An image.

  • rad (numeric) – The radius of the neighborhood.

  • mask ((M,N) binary array, optional) – A binary array that can be used to define what is outside the image.

Returns

local_averages – The local averages at all pixel locations.

Return type

(M,N) array

imagemks.filters.fftgauss(img, sigma, theta=0, pad_type=None, **kwargs)

Smooths the input image with a gaussian kernel. Uses the fft method and allows specifying a custom pad type with **kwargs from numpy.pad documentation. Smoothing a color image will smooth each color channel individually.

Parameters

  • img ((M,N) or (M,N,3) array) – An image to be smoothed

  • sigma (tuple or float) – Tuple defining the standard deviation of the gaussian in x and y directions. A single value will assign the same value to x and y st. devs..

  • theta (float, optional) – The rotation of the gaussian in radians.

  • pad_type (string, optional) – The padding type to be used. For additional information see numpy.pad . Defaults to constant.

  • kwargs (varies) – See numpy.pad . Defaults to constant_values=0.

Returns

smoothed_image – A smoothed image. Keeps same shape and same number of color channels.

Return type

ndarray

Notes

There are many gaussian smoothing functions. This one is unique because it automatically handles color images. It also allows defining very unique gaussian kernels with strain and orientation.

imagemks.filters.smooth_segmentation(S, r=1, add_cond=0.5, rem_cond=None)

Smooths a segmented image, where the input is a binary segmentation.

Parameters

  • S (ndarray of booleans) – A binary image.

  • add_cond (float, optional) – Parameter that specifies the percentage of neighboring pixels that must be in the segmentation for that pixel to be converted to the segmentation.

  • rem_cond (float, optional) – Parameter that specifies the percentage of neighboring pixels outside the segmentation that cause a pixel to be removed from the segmentation.

  • r (numeric, optional) – The radius of the kernel used to define the neighboring pixels.

Returns

smooth_segmentation – A smoothed version of the segmented image.

Return type

ndarray of booleans

Notes

By default, pixels are only added to a segmentation. Alternatively, pixels can be removed and not added. Adding and removing does not make sense with this algorithm since a pixel used to calculate an add condition could be removed later resulting in a non-smooth segmentation. This method can be thought of as a generalization of binary erosion and dilation.

imagemks.filters.fftconvolve2d(h1, h2, r, pad_type=None, centered=True, **kwargs)

This method adds to the functionality of scipy.signal.fftconvolve by providing padding options for 2D arrays.

Parameters

  • h1 ((M,N) array, numeric) – The signal to be convolved, should be (M,N) and is usually the image.

  • h2 ((M,N) array, numeric) – The signal to convolve with, should be (M,N) and is usually the filter. Will always be padded with zeros.

  • r (int) – The padding width. Termed r since an int value will introduce a radius around the input. Different padding widths not supported.

  • pad_type (string, optional) – The padding type to be used. For additional information see numpy.pad . Defaults to constant.

  • centered (boolean, optional) – Needed since the filters in this package can be defined as centered or origin type.

  • kwargs (varies) – See numpy.pad . Defaults to constant_values=0.

Returns

a – A convolved 2d signal in real space. Imaginary outputs not supported.

Return type

(M,N) array, float

Masking space using kernels

imagemks.masking.maskfourier(image, mask, centered=True)

Masks the fourier transform of an image using the given mask.

Parameters

  • image ((M,N) array or (M,N,3) array) –

  • mask (An (M,N) array) – Will be expanded to 3 channels if image is color.

  • centered (boolean, optional) – Is the mask for a centered fourier transform?

Returns

(A, B) – Two images generated from the masked fourier transforms. A contains an image reconstructed from values in the mask. B contains an image reconstructed from values outside the mask.

Return type

tuple of ndarrays

Examples

>>> import numpy as np
>>> from imagemks.masking import maskfourier
>>> image = np.ones((3,3))
>>> mask_centered = np.array([[0,1,0],
                              [1,1,1],
                              [0,1,0]])

>>> mask_origin = np.fft.ifftshift(mask_centered)
>>> mask_origin
array([[1, 1, 1],
       [1, 0, 0],
       [1, 0, 0]])

The difference between centered masks and uncentered can be resolved by using np.fft.fftshift and np.ifftshift. By default all masks in structures are centered.

>>> maskfourier(image, mask_centered, centered=True)
(array([[1., 1., 1.],
        [1., 1., 1.],
        [1., 1., 1.]]),
 array([[0., 0., 0.],
        [0., 0., 0.],
        [0., 0., 0.]]))