topostats.grains#

Find grains in an image.

Attributes#

Classes#

Grains

Find grains in an image.

Functions#

threshold(→ float)

Thresholding for producing masks.

_get_mask(→ numpy.typing.NDArray)

Calculate a mask for pixels that exceed the threshold.

get_thresholds(→ dict)

Obtain thresholds for masking data points.

Module Contents#

topostats.grains.LOGGER_NAME = 'topostats'#
topostats.grains.threshold(image: numpy.typing.NDArray, method: str = None, otsu_threshold_multiplier: float = None, **kwargs: dict) float[source]#

Thresholding for producing masks.

Parameters:
  • image (npt.NDArray) – 2-D Numpy array of image for thresholding.

  • method (str) – Method to use for thresholding, currently supported methods are otsu (default), mean and minimum.

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

  • **kwargs (dict) – Additional keyword arguments to pass to skimage methods.

Returns:

Threshold of image using specified method.

Return type:

float

topostats.grains._get_mask(image: numpy.typing.NDArray, thresh: float, threshold_direction: str, img_name: str = None) numpy.typing.NDArray[source]#

Calculate a mask for pixels that exceed the threshold.

Parameters:
  • image (np.array) – Numpy array representing image.

  • thresh (float) – A float representing the threshold.

  • threshold_direction (str) – A string representing the direction that should be thresholded. (“above”, “below”).

  • img_name (str) – Name of image being processed.

Returns:

Numpy array of image with objects coloured.

Return type:

npt.NDArray

topostats.grains.get_thresholds(image: numpy.typing.NDArray, threshold_method: str, otsu_threshold_multiplier: float = None, threshold_std_dev: dict = None, absolute: dict = None, **kwargs) dict[source]#

Obtain thresholds for masking data points.

Parameters:
  • image (npt.NDArray) – 2D Numpy array of image to be masked.

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

  • otsu_threshold_multiplier (float) – Scaling value for Otsu threshold.

  • threshold_std_dev (dict) – Dict of above and below thresholds for the standard deviation method.

  • absolute (tuple) – Dict of below and above thresholds.

  • **kwargs – Dictionary passed to ‘topostats.threshold(**kwargs)’.

Returns:

Dictionary of thresholds, contains keys ‘below’ and optionally ‘above’.

Return type:

Dict

topostats.grains.LOGGER#
class topostats.grains.Grains(image: numpy.typing.NDArray, filename: str, pixel_to_nm_scaling: float, threshold_method: str = None, otsu_threshold_multiplier: float = None, threshold_std_dev: dict = None, threshold_absolute: dict = None, absolute_area_threshold: dict = None, direction: str = None, smallest_grain_size_nm2: float = None, remove_edge_intersecting_grains: bool = True)[source]#

Find grains in an image.

Parameters:
  • image (npt.NDArray) – 2-D Numpy array of image.

  • filename (str) – File being processed (used in logging).

  • pixel_to_nm_scaling (float) – Scaling of pixels to nanometres.

  • threshold_method (str) – Method for determining thershold to mask values, default is ‘otsu’.

  • otsu_threshold_multiplier (float) – Factor by which the below threshold is to be scaled prior to masking.

  • threshold_std_dev (dict) – Dictionary of ‘below’ and ‘above’ factors by which standard deviation is multiplied to derive the threshold if threshold_method is ‘std_dev’.

  • threshold_absolute (dict) – Dictionary of absolute ‘below’ and ‘above’ thresholds for grain finding.

  • absolute_area_threshold (dict) – Dictionary of above and below grain’s area thresholds.

  • direction (str) – Direction for which grains are to be detected, valid values are ‘above’, ‘below’ and ‘both’.

  • smallest_grain_size_nm2 (float) – Whether or not to remove grains that intersect the edge of the image.

  • remove_edge_intersecting_grains (bool) – Direction for which grains are to be detected, valid values are ‘above’, ‘below’ and ‘both’.

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

Remove grains touching the border.

Parameters:
  • image (npt.NDarray) – 2-D Numpy array representing the image.

  • **kwargs – Arguments passed to ‘skimage.segmentation.clear_border(**kwargs)’.

Returns:

2-D Numpy array of image without objects touching the border.

Return type:

npt.NDarray

label_regions(image: numpy.typing.NDArray, background: int = 0) numpy.typing.NDArray[source]#

Label regions.

This method is used twice, once prior to removal of small regions and again afterwards which is why an image must be supplied rather than using ‘self’.

Parameters:
  • image (npt.NDArray) – 2-D Numpy array of image.

  • background (int) – Value used to indicate background of image. Default = 0.

Returns:

2-D Numpy array of image with regions numbered.

Return type:

npt.NDArray

calc_minimum_grain_size(image: numpy.typing.NDArray) float[source]#

Calculate the minimum grain size in pixels squared.

Very small objects are first removed via thresholding before calculating the below extreme.

Parameters:

image (npt.NDArray) – 2-D Numpy image from which to calculate the minimum grain size.

Returns:

Minimum grains size in pixels squared. If there are areas a value of -1 is returned.

Return type:

float

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

Remove noise which are objects smaller than the ‘smallest_grain_size_nm2’.

This ensures that the smallest objects ~1px are removed regardless of the size distribution of the grains.

Parameters:
  • image (npt.NDArray) – 2-D Numpy array to be cleaned.

  • **kwargs – Arguments passed to ‘skimage.morphology.remove_small_objects(**kwargs)’.

Returns:

2-D Numpy array of image with objects < smallest_grain_size_nm2 removed.

Return type:

npt.NDArray

remove_small_objects(image: numpy.array, **kwargs) numpy.typing.NDArray[source]#

Remove small objects from the input image.

Threshold determined by the minimum grain size, in pixels squared, of the classes initialisation.

Parameters:
  • image (np.array) – 2-D Numpy array to remove small objects from.

  • **kwargs – Arguments passed to ‘skimage.morphology.remove_small_objects(**kwargs)’.

Returns:

2-D Numpy array of image with objects < minimumm_grain_size removed.

Return type:

npt.NDArray

area_thresholding(image: numpy.typing.NDArray, area_thresholds: tuple) numpy.typing.NDArray[source]#

Remove objects larger and smaller than the specified thresholds.

Parameters:
  • image (npt.NDArray) – Image array where the background == 0 and grains are labelled as integers >0.

  • area_thresholds (tuple) – List of area thresholds (in nanometres squared, not pixels squared), first is the lower limit for size, second is the upper.

Returns:

Array with small and large objects removed.

Return type:

npt.NDArray

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

Colour the regions.

Parameters:
  • image (npt.NDArray) – 2-D array of labelled regions to be coloured.

  • **kwargs – Arguments passed to ‘skimage.color.label2rgb(**kwargs)’.

Returns:

Numpy array of image with objects coloured.

Return type:

np.array

static get_region_properties(image: numpy.array, **kwargs) list[source]#

Extract the properties of each region.

Parameters:
  • image (np.array) – Numpy array representing image.

  • **kwargs – Arguments passed to ‘skimage.measure.regionprops(**kwargs)’.

Returns:

List of region property objects.

Return type:

list

get_bounding_boxes(direction: str) dict[source]#

Derive a list of bounding boxes for each region from the derived region_properties.

Parameters:

direction (str) – Direction of threshold for which bounding boxes are being calculated.

Returns:

Dictionary of bounding boxes indexed by region area.

Return type:

dict

find_grains()[source]#

Find grains.