filters#

Module for filtering 2D Numpy arrays.

class topostats.filters.Filters(image: numpy.typing.NDArray, filename: str, pixel_to_nm_scaling: float, row_alignment_quantile: float = 0.5, threshold_method: str = 'otsu', otsu_threshold_multiplier: float = 1.7, threshold_std_dev: dict = None, threshold_absolute: dict = None, gaussian_size: float = None, gaussian_mode: str = 'nearest', remove_scars: dict = None)[source]#

Class for filtering scans.

Parameters:

  • image (npt.NDArray) – The raw image from the Atomic Force Microscopy machine.

  • filename (str) – The filename (used in logging only).

  • pixel_to_nm_scaling (float) – Value for converting pixels to nanometers.

  • row_alignment_quantile (float) – Quantile (0.0 to 1.0) to be used to determine the average background for the image below values may improve flattening of large features.

  • threshold_method (str) – Method for thresholding, default ‘otsu’, valid options ‘otsu’, ‘std_dev’ and ‘absolute’.

  • otsu_threshold_multiplier (float) – Value for scaling the derived Otsu threshold.

  • threshold_std_dev (dict) – If using the ‘std_dev’ threshold method. Dictionary that contains above and below threshold values for the number of standard deviations from the mean to threshold.

  • threshold_absolute (dict) – If using the ‘absolute’ threshold method. Dictionary that contains above and below absolute threshold values for flattening.

  • gaussian_size (float) – If using the ‘absolute’ threshold method. Dictionary that contains above and below absolute threshold values for flattening.

  • gaussian_mode (str) – Method passed to ‘skimage.filters.gaussian(mode = gaussian_mode)’.

  • remove_scars (dict) – Dictionary containing configuration parameters for the scar removal function.

Methods

average_background(image[, mask])

Zero the background by subtracting the non-masked mean from all pixels.

calc_diff(array)

Calculate the difference between the last and first rows of a 2-D array.

calc_gradient(array, shape)

Calculate the gradient of an array.

filter_image()

Process a single image, filtering, finding grains and calculating their statistics.

gaussian_filter(image, **kwargs)

Apply Gaussian filter to an image.

median_flatten(image[, mask, ...])

Flatten images using median differences.

remove_nonlinear_polynomial(image[, mask])

Fit and remove a "saddle" shaped nonlinear polynomial from the image.

remove_quadratic(image[, mask])

Remove the quadratic bowing that can be seen in some large-scale AFM images.

remove_tilt(image[, mask])

Remove the planar tilt from an image (linear in 2D spaces).
average_background(image: numpy.typing.NDArray, mask: numpy.typing.NDArray = None) → numpy.typing.NDArray[source]#

Zero the background by subtracting the non-masked mean from all pixels.

Parameters:

  • image (npt.NDArray) – Numpy array representing the image.

  • mask (npt.NDArray) – Mask of the array, should have the same dimensions as image.

Returns:

Numpy array of image zero averaged.

Return type:

npt.NDArray

static calc_diff(array: numpy.typing.NDArray) → numpy.typing.NDArray[source]#

Calculate the difference between the last and first rows of a 2-D array.

Parameters:

array (npt.NDArray) – A Numpy array.

Returns:

An array of the difference between the last and first rows of an array.

Return type:

npt.NDArray

calc_gradient(array: numpy.typing.NDArray, shape: int) → numpy.typing.NDArray[source]#

Calculate the gradient of an array.

Parameters:

  • array (npt.NDArray) – Array for gradient to be calculated.

  • shape (int) – Shape of the array.

Returns:

Gradient across the array.

Return type:

npt.NDArray

filter_image() → None[source]#

Process a single image, filtering, finding grains and calculating their statistics.

Returns:

Does not return anything.

Return type:

None

Examples

from topostats.io import LoadScan from topostats.topotracing import Filter, process_scan

filter = Filter(image=load_scan.image, … pixel_to_nm_scaling=load_scan.pixel_to_nm_scaling, … filename=load_scan.filename, … threshold_method=’otsu’) filter.filter_image()

gaussian_filter(image: numpy.typing.NDArray, **kwargs) → numpy.typing.NDArray[source]#

Apply Gaussian filter to an image.

Parameters:

  • image (npt.NDArray) – Numpy array representing the image.

  • **kwargs – Keyword arguments passed on to the skimage.filters.gaussian() function.

Returns:

Numpy array that represent the image after Gaussian filtering.

Return type:

npt.NDArray

median_flatten(image: numpy.typing.NDArray, mask: numpy.typing.NDArray = None, row_alignment_quantile: float = 0.5) → numpy.typing.NDArray[source]#

Flatten images using median differences.

Flatten the rows of an image, aligning the rows and centering the median around zero. When used with a mask, this has the effect of centering the background data on zero.

Note this function does not handle scars.

Parameters:

  • image (npt.NDArray) – 2-D image of the data to align the rows of.

  • mask (npt.NDArray) – Boolean array of points to mask (ignore).

  • row_alignment_quantile (float) – Quantile (in the range 0.0 to 1.0) used for defining the average background.

Returns:

Copy of the input image with rows aligned.

Return type:

npt.NDArray

remove_nonlinear_polynomial(image: npt.NDArray, mask: npt.NDArray | None = None) → npt.NDArray[source]#

Fit and remove a “saddle” shaped nonlinear polynomial from the image.

“Saddles” with the form a + b * x * y - c * x - d * y from the supplied image. AFM images sometimes contain a “saddle” shape trend to their background, and so to remove them we fit a nonlinear polynomial of x and y and then subtract the fit from the image.

If these trends are not removed, then the image will not flatten properly and will leave opposite diagonal corners raised or lowered.

Parameters:

  • image (npt.NDArray) – 2-D numpy height-map array of floats with a polynomial trend to remove.

  • mask (npt.NDArray, optional) – 2-D Numpy boolean array used to mask any points in the image that are deemed not to be part of the height-map’s background data.

Returns:

Image with the polynomial trend subtracted.

Return type:

npt.NDArray

remove_quadratic(image: numpy.typing.NDArray, mask: numpy.typing.NDArray = None) → numpy.typing.NDArray[source]#

Remove the quadratic bowing that can be seen in some large-scale AFM images.

Use a simple quadratic fit on the medians of the columns of the image and then subtracts the calculated quadratic from the columns.

Parameters:

  • image (npt.NDArray) – 2-D image of the data to remove the quadratic from.

  • mask (npt.NDArray) – Boolean array of points to mask (ignore).

Returns:

Image with the quadratic bowing removed.

Return type:

npt.NDArray

remove_tilt(image: numpy.typing.NDArray, mask: numpy.typing.NDArray = None) → numpy.typing.NDArray[source]#

Remove the planar tilt from an image (linear in 2D spaces).

Uses a linear fit of the medians of the rows and columns to determine the linear slants in x and y directions and then subtracts the fit from the columns.

Parameters:

  • image (npt.NDArray) – 2-D image of the data to remove the planar tilt from.

  • mask (npt.NDArray) – Boolean array of points to mask (ignore).

Returns:

Numpy array of image with tilt removed.

Return type:

npt.NDArray