To install the package from PyPi:
$ pip install GAKTporeGAKTpore 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:
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.
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-1x_FFT.csv'.
The binarisation integer, expected to be between 0-255.
Distance per pixel, presumed to be taken from the 'scale' bar of a microstructure image.
The number to upscale the image being processed. Will multiply the image resulution by the value given.
Whether the background of the image is white (True) or black (False).
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).
Whether to use multiple cpu cores to process the image in parallel.
The number of parallel computations used when a multiprocessing function is used. -1 to use the number of available cores.
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.
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.
Whether to draw the pores onto the map in black.
For the area fraction colour map, sets the minimum value to correspond with starting colour of the colour map.
For the area fraction colour map, sets the maximum value to correspond with final colour of the colour map.
Number of segmented steps to use between the centre of the image and the maximum radius.
GAKTpore provides a class 'AnalysePores' with multiple analytical tools.
The initialisation for the class works as a simple binarisation and pore detection tool utilising the OpenCV implementation of findContours.
2D Grayscale Image
Threshold value for binarising the image
Distance per pixel, presumed to be taken from the 'scale' bar of a microstructure image.
Whether to apply a Gaussian filter of sigma=2
Whether the background of the image is white (True) or black (False)
The number of parallel computations used when a multiprocessing function is used. -1 to use the number of available cores.
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.
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).
This function (and its parallel counterpart, process_free_area_parallel) calculates the territory area for each pore by computing the closest pore contour for each pixel of the image provided.
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.
This function (and its parallel counterpart, process_homogeneity_colour_map_parallel) generates a colour map using the area fractions (Pore area divided by Territory area).
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.
Sets the minimum value to correspond with starting colour of the colour map.
Sets the maximum value to correspond with final colour of the colour map.
Whether to draw the pores onto the map.
Colour map of the same resolution as the one in process_free_area.
Computes the number of pores and the porosity percentage in segmented steps from the centre of the image.
Number of segmented steps to use between the centre and the maximum radius.
The pixel position to use as the centre for the segmented circle. If not supplied, simply takes the centre of the image.
The maximum radius to do the calculations for. If not supplied, simply calculates the distance to edge of the image from the centre.
Whether to draw the pores onto the map.
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
- 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.