grains

Find grains in an image.

class topostats.grains.Grains(image: numpy.typing.NDArray, filename: str, pixel_to_nm_scaling: float, unet_config: dict[str, str | int | float | tuple[int | None, int, int, int] | None] | None = None, threshold_method: str | None = None, otsu_threshold_multiplier: float | None = None, threshold_std_dev: dict | None = None, threshold_absolute: dict | None = None, absolute_area_threshold: dict | None = None, direction: str | None = None, smallest_grain_size_nm2: float | None = 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.

• unet_config (dict[str, str | int | float | tuple[int | None, int, int, int] | None]) –

  Configuration for the UNet model. model_path: str

  Path to the UNet model.

  grain_crop_padding: int

  Padding to add to the bounding box of the grain before cropping.

  upper_norm_bound: float

  Upper bound for normalising the image.

  lower_norm_bound: float

  Lower bound for normalising the image.

• 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’.

Methods

area_thresholding(image, area_thresholds)	Remove objects larger and smaller than the specified thresholds.
calc_minimum_grain_size(image)	Calculate the minimum grain size in pixels squared.
colour_regions(image, **kwargs)	Colour the regions.
find_grains()	Find grains.
get_bounding_boxes(direction)	Derive a list of bounding boxes for each region from the derived region_properties.
get_region_properties(image, **kwargs)	Extract the properties of each region.
improve_grain_segmentation_unet(filename, ...)	Use a UNet model to re-segment existing grains to improve their accuracy.
keep_largest_labelled_region(labelled_image)	Keep only the largest region in a labelled image.
label_regions(image[, background])	Label regions.
remove_noise(image, **kwargs)	Remove noise which are objects smaller than the 'smallest_grain_size_nm2'.
remove_objects_too_small_to_process(image, ...)	Remove objects whose dimensions in pixels are too small to process.
remove_small_objects(image, **kwargs)	Remove small objects from the input image.
tidy_border(image, **kwargs)	Remove grains touching the border.

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

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

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

find_grains()

Find grains.

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

static get_region_properties(image: 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

static improve_grain_segmentation_unet(filename: str, direction: str, unet_config: dict[str, str | int | float | tuple[int | None, int, int, int] | None], image: numpy.typing.NDArray, labelled_grain_regions: numpy.typing.NDArray) → tuple[numpy.typing.NDArray, numpy.typing.NDArray]

Use a UNet model to re-segment existing grains to improve their accuracy.

Parameters:

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

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

• unet_config (dict[str, str | int | float | tuple[int | None, int, int, int] | None]) –

  Configuration for the UNet model. model_path: str

  Path to the UNet model.

  grain_crop_padding: int

  Padding to add to the bounding box of the grain before cropping.

  upper_norm_bound: float

  Upper bound for normalising the image.

  lower_norm_bound: float

  Lower bound for normalising the image.

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

• labelled_grain_regions (npt.NDArray) – 2-D Numpy array of labelled grain regions.

Returns:

• npt.NDArray – NxNxC Numpy array of the UNet mask.

• npt.NDArray – NxNxC Numpy array of the labelled regions from the UNet mask.

static keep_largest_labelled_region(labelled_image: numpy.typing.NDArray.<class 'numpy.int32'>) → numpy.typing.NDArray.<class 'numpy.bool_'>

Keep only the largest region in a labelled image.

Parameters:

labelled_image (npt.NDArray) – 2-D Numpy array of labelled regions.

Returns:

2-D Numpy boolean array of labelled regions with only the largest region.

Return type:

npt.NDArray

static 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

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_objects_too_small_to_process(image: numpy.typing.NDArray, minimum_size_px: int, minimum_bbox_size_px: int) → numpy.typing.NDArray.<class 'numpy.bool_'>

Remove objects whose dimensions in pixels are too small to process.

Parameters:

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

• minimum_size_px (int) – Minimum number of pixels for an object.

• minimum_bbox_size_px (int) – Limit for the minimum dimension of an object in pixels. Eg: 5 means the object’s bounding box must be at least 5x5.

Returns:

2-D Numpy array of image with objects removed that are too small to process.

Return type:

npt.NDArray

remove_small_objects(image: 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

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