topostats.grains

Find grains in an image.

Module Contents

Classes

Grains

Find grains in an image.

Attributes

LOGGER

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)

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

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

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

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

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

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

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

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

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

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()

Find grains.