GAKTpore: Stereological Characterisation Methods

Installation

To install the package from PyPi:

bash $ pip install GAKTpore

Quick Use

GAKTpore is distributed with a function utilising the GAKTpore 'AnalysePores' class to output the relevant data files into a save folder and generate a colour map. This outputs the data used for the initial GAKTpore paper. Test-case files are included on Github, with images.

A user guide is available to help get started with GAKTpore and Python.

The syntax of the function are as follows:

GAKTpore.analysis.run

Parameters

       IMAGE_NAME: str,

             The directory path for the image to be analysed. The image is expected to be grayscale. The image formats supported can be found on the OpenCV imread reference.

       SAVE_FOLDER: str,

             The directory where the output files will be saved to. There are 3 output files by default: * A file containing the standard evaluation parameters (such as mean diameter, number of samples etc.) per radial step. * A file containing the standard evaluation parameters (such as pore area, cirularity etc.) for each pore, allowing further analysis. * The Area fraction image generated using the 'jet' colourmap via Matplotlib.

The filename will be determined by the name of the image file and input parameters (Threshold, upscale multiplier, contour filtering method (FFT or Savgol) and the data) as <Image name>-<Threshold>-<Upscale Multiplier>-<type of data><filtering method>.<file type>, for example 'Test1-127-1xFFT.csv'.

       THRES: int,

             The binarisation integer, expected to be between 0-255.

       SCALE: float,

             Distance per pixel, presumed to be taken from the 'scale' bar of a microstructure image.

       UPSCALE_MULTIPLIER: int, Optional. Default Value = 1

             The number to upscale the image being processed. Will multiply the image resulution by the value given.

       W_BG: bool, Optional. Default Value = True,

             Whether the background of the image is white (True) or black (False).

       FFT: bool, Optional. Default Value = True,

             Whether to use FFT bandpass to smooth contours. Setting this to False will use the Savgol Filter from Scipy instead (Not validated yet, but much faster).

       parallel: bool, Optional. Default Value = True,

             Whether to use multiple cpu cores to process the image in parallel.

       cpu_count: int, Optional. Default Value = -1,

             The number of parallel computations used when a multiprocessing function is used. -1 to use the number of available cores.

       npy_save: bool, Optional. Default Value = False,

             Whether to save the numpy array of the territory map. This map is a mask containing integers, where the integers refer to the pore number the territory belongs to.

       plt_save: bool, Optional. Default Value = False,

             Whether to use matplotlib.save to save the area fraction image. Matplotlib.save is slow and will crash when using extremely high resolution images (> 25k x 25k), but is otherwise stable. If set to false, will use cv2.imsave to save the area fraction image.

       draw_contours: bool, Optional. Default Value=True,

             Whether to draw the pores onto the map in black.

       vmin: float, Optional. Default Value=0,

             For the area fraction colour map, sets the minimum value to correspond with starting colour of the colour map.

       vmax: float, Optional. Default Value=1,

             For the area fraction colour map, sets the maximum value to correspond with final colour of the colour map.

       radii_n: int, Optional. Default Value=10

             Number of segmented steps to use between the centre of the image and the maximum radius.

Usage

GAKTpore provides a class 'AnalysePores' with multiple analytical tools.

GAKTpore.AnalysePores

The initialisation for the class works as a simple binarisation and pore detection tool utilising the OpenCV implementation of findContours.

Parameters:

       img: np.array,

             2D Grayscale Image

       threshold_value: int, Optional. Default Value: 125

             Threshold value for binarising the image

       scale = float, Optional. Default Value: 1

             Distance per pixel, presumed to be taken from the 'scale' bar of a microstructure image.

       G = bool, Optional. Default Value:False

             Whether to apply a Gaussian filter of sigma=2

       white_background= bool, Optional. Default Value: True

             Whether the background of the image is white (True) or black (False)

       cpu_count= int, Optional. Default Value:-1

             The number of parallel computations used when a multiprocessing function is used. -1 to use the number of available cores.

GAKTpore.AnalysePores.process

The next major function is process (process_parallel for the multiprocessing version). This function computes the properties of the pores (Area, Circularity etc.). Note that this must be run before the territory areas can be calculated.

Parameters:

       FFT: bool, Optional. Default Value: True

             Whether to use FFT bandpass to smooth contours. Setting this to False will use the Savgol Filter from Scipy instead (Not validated yet, but much faster).

GAKTpore.AnalysePores.processfreearea

This function (and its parallel counterpart, processfreearea_parallel) calculates the territory area for each pore by computing the closest pore contour for each pixel of the image provided.

Parameters:

       zoom: int, Optional. Default Value: 1

             Increase the resolution of the map used for computing the territory area. Example: zoom=2 will use double the resolution of the input image to calculate the territory area.

GAKTpore.AnalysePores.processhomogeneitycolour_map

This function (and its parallel counterpart, processhomogeneitycolourmapparallel) generates a colour map using the area fractions (Pore area divided by Territory area).

Parameters:

       mapper: matplotlib.colors.LinearSegmentedColormap, Optional. Default Value: matplotlib.cm.get_cmap("jet")

             Sets the colourmap to be used when colouring the image. Uses the colour "jet" by default. Provided in this layout to support custom matplotlib maps.

       vmin: float, Optional. Default Value: 0

             Sets the minimum value to correspond with starting colour of the colour map.

       vmax: float, Optional. Default Value: 1

             Sets the maximum value to correspond with final colour of the colour map.

       draw_contours: bool, Optional. Default Value: False

             Whether to draw the pores onto the map.

Returns:

       Colour map of the same resolution as the one in processfreearea.

GAKTpore.AnalysePores.processradialcontour:

Computes the number of pores and the porosity percentage in segmented steps from the centre of the image.

Parameters:

       radii_n: int, Optional. Default Value: 10

             Number of segmented steps to use between the centre and the maximum radius.

       radius_centre: np.array, Optional. Default Value: None

             The pixel position to use as the centre for the segmented circle. If not supplied, simply takes the centre of the image.

       radius_max: float, Optional. Default Value: None

             The maximum radius to do the calculations for. If not supplied, simply calculates the distance to edge of the image from the centre.

       draw_contours: bool, Optional. Default Value: False

             Whether to draw the pores onto the map.

Citation

When using this package please cite:

• Sheppard, G.; Tassenberg, K.; Nenchev, B.; Strickland, J.; Mesalam, R.; Shepherd, J.; Williams, H. GAKTpore: Stereological Characterisation Methods for Porous Foams in Biomedical Applications. Materials 2021, 14, 1269. https://doi.org/10.3390/ma14051269

Changelog

v1.1.2 (08/03/21)

• Fixes a crash in GAKTpore.analysis.run** radial processing section, which occurs when there are no pores within a radial step. Will output nans into the output data file.