spam.measurements package

spam.measurements package#

Submodules#

spam.measurements.covariance module#

Measure correlation of a given field with two different approach.

View examples in the gallery.

How to import#

>>> import spam.measurements
>>> spam.measurements.covarianceAlongAxis(im, d)
>>> spam.measurements.covarianceSubPixel(im)
spam.measurements.covariance.covarianceAlongAxis(im, d, mask=None, axis=[0, 1, 2])[source]#

Compute the covariance function of 2D or 3D images along specific axis.

This function computes the covariance of a field (grey values or binary) with or without a mask. The covariance is computed at integer distances (in voxels). No interpolation is made but specific direction can be asked.

Parameters:

  • im (array, string) – The image as a name of an input file (grey or binary) or directly an array

  • d (array) – The list of distances (in voxels) considered to compute the covariance. It can’t be bigger than the size of image and it has to be integers.

  • mask (array, optional) – The name of the mask file (binary, 1 for phase of interest) or directly an array

  • axis (array, default=[0,1,2]) – The list of axis in wich the direction is computed.

Returns:

c – A 2D array with list of values of the covariance at the different distances for each axis.

Return type:

array

Examples

>>> import numpy
>>> import tifffile
>>> im = tifffile.imread( "snow.tif" )
This image of size 100x100x100 is a field of grey values
>>> d = numpy.arange( 0, )
array([ 0,  1,  2,  3,  4])
>>> c = spam.measurements.covarianceAlongAxis( im, d )
array([[86833030., 74757580., 53643410., 35916468.],                 # axis 0
.      [86833030., 76282920., 56910720., 39792388.],                 # axis 1
.      [86833030., 76410500., 57040076., 39938920.]], dtype=float32) # axis 2
spam.measurements.covariance.covarianceSubPixel(im, distance=25, step=10, normType=None, n_threads=1)[source]#

Compute the covariance function of 2D or 3D images.

The correlation function is computed on the zero mean image. The code behind – for pre-allocation reasons – works on a number of unique distances, which in 3D is closely unders=estimated by the square of the distance asked for. To change this a pre-allocated precision (i.e., 0.2 px) and distance could be used in the C-code. A sub pixel interpolation of the grey values in made.

Parameters:

  • im (array) – The image. It is automatically converted into a 32 bit float <f4.

  • distance (int, optional) – The approximate distance in pixels over which to make this measurement.

  • step (int, optional) – The step parameter, which is how many pixels to jump when moving the pixel of interest when calculating the correaltion function (this is the best way to save time). The smaller the step the longer the computational time and the better the measure of each value of the covariance.

  • normType (string, optional) – Select the of normalisation for the covariance output. normType="None": no normalisation, normType="variance": divide the covariance by the variance of the image, normType="first": divide the covariance by its value at 0.

  • n_threads (int, optional) – Number of threads for the c++ #pragma command using openmp.

Returns:

  • d (array) – The list of distances in pixel where the correlation is computed.

  • c (array) – The list of calues of the covariance at the different distances.

Examples

>>> import numpy
>>> import tifffile
>>> im = tifffile.imread( "snow.tif" )
This image of size 100x100x100 is a field of grey values
>>> d = numpy.arange( 0, 4 )
array([ 0,  1,  2,  3,  4])
>>> c = spam.measurements.covarianceSubPixel( im, distance=2 )
(array([0.        , 1.        , 1.41421354, 1.73205078]), # distances
array( [89405248. , 77995006. , 69534446. , 62701681.]))  # covariance

Warning

The multithread version is bugged… openmp gives random values.

spam.measurements.covariance.betaCovariance(d, lc, b)[source]#

Sample correlation function: Beta correlation function

$$C(d) = exp(-(d/l_c)^b) $$

Parameters:

  • d (array) – The list of distances where the function is evaluated.

  • lc (float) – The correlation length.

  • b (float) – The first parameter of the function. If b=2 this is the gaussian function

Returns:

c – The list of values of the function corresponding to the given distances.

Return type:

array

spam.measurements.covariance.gaussianCovariance(d, lc)[source]#

Sample correlation function: Gaussian correlation function

$$C(d) = exp(-(d/l_c)^2) $$

Parameters:

  • d (array) – The list of distances where the function is evaluated.

  • lc (float) – The correlation length.

Returns:

The list of values of the function corresponding to the given distances.

Return type:

array

spam.measurements.covariance.fitCovariance(d, c, functionType='gaussian')[source]#

For autofitting, a helper function…

Parameters:

  • d (array) – The list of distances of the covariance.

  • c (array) – The list of value of covariance corresponding to the distances.

  • functionType ({"gaussian","beta"}) – The type of covariance function

Returns:

popt – The optimisation parameters

Return type:

array

spam.measurements.globalDescriptors module#

spam.measurements.globalDescriptors.volume(segmented, phase=1, aspectRatio=(1.0, 1.0, 1.0), specific=False, ROI=None)[source]#

Computes the (specific) volume of a given phase for a certain Region Of Interest.

Parameters:

  • segmented (array of integers) – Array where integers represent the phases. The value 0 is stricly reserved for not Region Of Interest.

  • phase (integer, default=1) – The phase for which the fraction volume is computed. The phase should be greater than 0 if ROI is used.

  • aspectRatio (tuple of floats, default=(1.0, 1.0, 1.0)) – Length between two nodes in every direction e.g. size of a cell. The length of the tuple is the same as the spatial dimension.

  • specific (boolean, default=False) – Returns the specific volume if True.

  • ROI (array of boolean, default=None) – If not None, boolean array which represents the Region Of Interest. Segmented will be 0 where ROI is False.

Returns:

The (specific) volume of the phase.

Return type:

float

spam.measurements.globalDescriptors.eulerCharacteristic(segmented, phase=1, ROI=None, verbose=False)[source]#

Compute the Euler Characteristic of a given phase by counting n-dimensionnal topological features using the formula:

1D: X = #{ Vertices } - #{ Edges }
2D: X = #{ Vertices } - #{ Edges } + #{ Faces }
3D: X = #{ Vertices } - #{ Edges } + #{ Faces } - #{ Polyedra }

This function as been implemented using a optimized algorithm using rolled views with unsymetrical structuring elements to count, thus avoiding n nested loops.

Parameters:

  • segmented (array of integers) – Array where integers represent the phases. The value 0 is stricly reserved for not Region Of Interest.

  • phase (integer, default=1) – The phase for which the fraction volume is computed. The phase should be greater than 0 if ROI is used.

  • ROI (array of boolean, default=None) – If not None, boolean array which represents the Region Of Interest. Segmented will be 0 where ROI is False.

  • verbose (boolean, default=False,) – Verbose mode.

Returns:

The Euler Characteristic

Return type:

int

spam.measurements.globalDescriptors.surfaceArea(field, level=0.0, aspectRatio=(1.0, 1.0, 1.0))[source]#

Computes the surface area of a continuous field over a given level set.

This function is based on a marching cubes algorithm of skimage.

Parameters:

  • field (array of floats) – Array where some level sets represent the interface between phases.

  • level (float, default=0.0) – The level set. See skimage.measure.marching_cubes. Contour value to search for isosurfaces in volume. If not given or None, the average of the min and max of vol is used.

  • aspectRatio (length 3 tuple of floats, default=(1.0, 1.0, 1.0)) – Length between two nodes in every direction e.g. size of a cell. It corresponds to spacing in skimage.measure.marching_cubes.

Returns:

The surface area.

Return type:

float

spam.measurements.globalDescriptors.totalCurvature(field, level=0.0, aspectRatio=(1.0, 1.0, 1.0), stepSize=None, getMeshValues=False, fileName=None)[source]#

Computes the total curvature of a continuous field over a given level set.

This function is based on a marching cubes algorithm of skimage.

Parameters:

  • field (array of floats) – Array where some level sets represent the interface between phases

  • level (float) – The level set See skimage.measure.marching_cubes. Contour value to search for isosurfaces in volume. If None is given, the average of the min and max of vol is used Default = 0.0

  • aspectRatio (length 3 tuple of floats) – Length between two nodes in every direction e.g., size of a cell. It corresponds to spacing in skimage.measure.marching_cubes Default = (1.0, 1.0, 1.0)

  • step_size (int) – Step size in voxels Larger steps yield faster but coarser results. The result will always be topologically correct though. Default = 1

  • getMeshValues (boolean) – Return the mean and gauss curvatures and the areas of the mesh vertices Default = False

  • fileName (string) – Name of the output vtk file Only if getMeshValues = True Default = None

Returns:

totalCurvature – If getMeshValues = True, total curvature and a (nx3) array of n vertices where 1st column is the mean curvature, 2nd column is the gaussian curvature and 3rd column is the area

Return type:

float

spam.measurements.globalDescriptors.perimeter(segmented, phase=1, aspectRatio=(1.0, 1.0), ROI=None)[source]#

Computes the perimeter of a given phase.

Parameters:

  • segmented (array of integers) – Array where integers represent the phases. The value 0 is stricly reserved for not Region Of Interest.

  • phase (integer, default=1) – The phase for which the fraction volume is computed. The phase should be greater than 0 if ROI is used.

  • aspectRatio (length 2 tuple of floats, default=(1.0, 1.0)) – Length between two nodes in every direction e.g. size of a cell.

  • ROI (array of boolean, default=None) – If not None, boolean array which represents the Region Of Interest. Segmented will be 0 where ROI is False.

Returns:

The perimeter.

Return type:

float

spam.measurements.globalDescriptors.generic(segmented, n, phase=1, level=0.0, aspectRatio=(1.0, 1.0, 1.0), specific=False, ROI=None, verbose=False)[source]#

Maps all measures in a homogeneous format

Parameters:

  • segmented (array of integers) – Array where integers represent the phases. The value 0 is stricly reserved for not Region Of Interest.

  • n (int) –

    The number of the measure. The meaning depends of the dimension.

    * In 1D:
    * n=0: Euler characteristic
    * n=1: (specific) length
* In 2D:
    * n=0: Euler characteristic
    * n=1: perimeter
    * n=2: (specific) surface
* In 3D:
    * n=0: Euler Characteristic
    * n=1: ?
    * n=2: surface
    * n=3: (specific) volume

  • phase (integer, default=1) – The phase for which the fraction volume is computed. The phase should be greater than 0 if ROI is used.

  • level (float, default=0.0) – The level set. See skimage.measure.marching_cubes. Contour value to search for isosurfaces in volume. If not given or None, the average of the min and max of vol is used.

  • specific (boolean, default=False) – Returns the specific volume if True.

  • aspectRatio (length 3 tuple of floats, default=(1.0, 1.0, 1.0)) – Length between two nodes in every direction e.g. size of a cell.

  • ROI (array of boolean, default=None) – If not None, boolean array which represents the Region Of Interest. Segmented will be 0 where ROI is False.

  • verbose (boolean, default=False,) – Verbose mode.

Returns:

The measure

Return type:

float

spam.measurements.porosityField module#

spam.measurements.porosityField.porosityField(image, poreValue=None, solidValue=None, maskValue=None, nodeSpacing='auto', hws=10, showGraph=False)[source]#

This function calculates a porosity field on a greyscale image, outputting a field in % porosity. A list of half-window sizes can be given, allowing for porosity measurement stability to to evaluate easily.

Parameters:

  • image (3D numpy array)

  • poreValue (float) – The grey value corresponding to the peak of the pores. Grey values of this value as considered 100% pore. In the case of 2 peaks in the pores (having water and air), should put the principal one.

  • solidValue (float) – The grey value corresponding to the peak of the solids. Grey values of this value as considered 100% solid.

  • maskValue (float, optional) – Indicate whether there is a special value in the input image that corrseponds to a mask which indicates voxels that are not taken into account in the porosity calculation. Default = None

  • hws (int or list, optional) – half-window size for cubic measurement window Default = 10

  • nodeSpacing (int, optional) – spacing of nodes in pixels Default = 10 pixels

  • showGraph (bool, optional) – If a list of hws is input, show a graph of the porosity evolution Default = False

Return type:

3D (or 4D) numpy array for constant half-window size (list of half-window sizes)

Module contents#

Contents