spam.helpers package

spam.helpers package#

Submodules#

spam.helpers.histogramTools module#

spam.helpers.histogramTools.findHistogramPeaks(image, valley1=20000, valley2=[], phases=2, gaussianFit=False, returnSigma=False, mask=True, showGraph=False, greyRange=[0, 65535], bins=256, saveFigPath=None)[source]#

This function finds the peaks of the phases of a greylevel image (16bit or 8bit). The peaks are in greylevel units. Minimum number of Phases is 2 and Maximum is 3.

Parameters:

  • image (3D numpy array)

  • valley1 (float) – An initial guess (arbitrary) greylevel value between peak phase 1 and peak phase 2, where peak phase 1 < valley1 < peak phase 2.

  • valley2 (float) – An initial guess (arbitrary) greylevel value between peak phase 2 and peak phase 3, where peak phase 2 < valley2 < peak phase 3. If the image has 2 phases, value 2 is [].

  • phases (int (2 or 3)) – The phases that exist in the greylevel image. Easy way to determine by looking how many peaks the histogram has.

  • gaussianFit (bool, optional) – Should the peaks be fitted with a Gaussian, or just the bin with the max value returned? Default = True

  • returnSigma (bool, optional) –

    Return a list of standard deviations from the Gaussian Fit?

    Requires gaussianFit=True Default= False

  • mask (bool) – If image is masked with mask set to 0.

  • showGraph (bool, optional) – If True, showing two matplotlib graphs - one corresponding to the histogram as returned in the spam.plotting.greyLevelHistogram and one corresponding to the histogram with the peaks of the phases. Default = False

  • greyRange (list, optional) – If a 16-bit greylevel image –> greyRange = [0,65535] If a 8-bit greylevel image –> greyRange = [0,255] Default = [0,65535]

  • bins (int, optional) – Default = 256

  • saveFigPath (string, optional) – Path to save figure to. Default = None

Return type:

The peaks of the phases of the image.

spam.helpers.histogramTools.histogramNorm(im_Or, twoPeaks, peaksNormed=[0.25, 0.75], cropGreyvalues=[-inf, inf])[source]#

This function normalise the histogram in order to range beween 0 and 1, presenting two peaks at p1 and p2 (p1<p2)

Parameters:

  • im_Or (3D numpy array)

  • twoPeaks (list of two floats) – First and second peak of the original histogram

  • peaksNormed (list of two floats, optional) – The desired level for the first and second peak of the normalized histogram. Default = [0.25, 0.75]

  • cropGreyvalues (list of two floats, optional) – The limits on the generated normalised values. Default = [-numpy.inf, numpy.inf]

Returns:

im_Norm

Return type:

3D numpy array. Image with grey range between [0,1] and peaks at 0.25 and 0.75

spam.helpers.imageManipulation module#

spam.helpers.imageManipulation.stackToArray(prefix, suffix='.tif', stack=range(0, 10), digits='05d')[source]#

Convert of stack of 2D sequential tif images into a 3D array.

Parameters:

  • prefix (string) – The common name of the 2D images files before the sequential number

  • suffix (string, default='.tif') – The common name and extension of the 2D images after the sequential number

  • stack (sequence, default=range(10)) – The numbers of the slices with no formating (with no leading zeros)

  • digits (string, default='05d') – The format (number of digits) of the numbers (add leading zeros).

Returns:

The 3D image

Return type:

numpy array

spam.helpers.imageManipulation.crop(im, boxSize, boxOrigin=None)[source]#

This function crops an image using slicing.

Parameters:

im – The image to crop.

Returns:

The cropped image.

Return type:

array

spam.helpers.imageManipulation.rescale(im, scale=(0, 1))[source]#

This function rescales the values of an image according to a scale and save it to as 4 bytes floats (float32).

Parameters:

  • im (array) – The image to rescale

  • scale ((float, float), default=(0 1)) – The min and max of the rescaled image

Returns:

The rescaled image.

Return type:

array, float

Examples

>>> im = numpy.random.randn( 100, 100, 100 ).astype( '<f4' )
produce float32 array of positive and negative numbers
>>> imRescaled = rescale( im, scale=[-1, 1] )
produce float32 array of numbers between -1 and 1
spam.helpers.imageManipulation.rescaleToInteger(im, nBytes=1, scale=None)[source]#

This function rescales a 4 bytes float image values to a unsigned integers of nBytes.

Parameters:

  • im (float32 numpy array) – The image to rescale

  • nBytes (int, default=1) –

    The number of bytes of the unsigned interger output. Possible values are power of 2

    reminder
1 byte  =  8 bits -> ouput from 0 to           255
2 bytes = 16 bits -> ouput from 0 to        65 535
4 bytes = 32 bits -> ouput from 0 to 4 294 967 295

  • scale ((float, float), default=None) – If None, the maximum and minimum use for the rescaling is the maximum and the minimum of the image

Returns:

The rescaled image

Return type:

numpy array, uint

Examples

>>> im = numpy.random.randn( 100, 100, 100 ).astype( '<f4' )
produce float32 array of positive and negative numbers
>>> imRescaled = rescaleToInteger( im, nBytes=4 )
produce uint32 array of numbers between 0 and 4 294 967 295
spam.helpers.imageManipulation.convertUnsignedIntegers(im, nBytes=1)[source]#

This function converts an images of unsigned integers.

Note: this function does not rescale.

Parameters:

  • im (array, uint) – The image to convert.

  • nBytes (int, default=1) –

    The number of bytes of the unsigned interger output. Possible values are power of 2.

    reminder
1 byte  =  8 bits -> ouput from 0 to           255
2 bytes = 16 bits -> ouput from 0 to        65 535
4 bytes = 32 bits -> ouput from 0 to 4 294 967 295

Returns:

The converted image.

Return type:

array, uint

Examples

>>> im = numpy.random.randint( 12, high=210, size=(100, 100, 100) ).astype( '<u1' )
produce an uint8 array of numbers between 12 and 210
>>> imRescaled = rescaleToInteger( im, nBytes=2 )
produce an uint16 array 3084 and 53970
spam.helpers.imageManipulation.singleShift(im, shift, axis, sub=0)[source]#

This function shift the image and replace the border by an substitution value.

It uses numpy.roll.

Parameters:

  • im (array) – The input to shift.

  • shift (int) – The number of places by which elements are shifted (from numpy.roll). Default: 1

  • axis (int) – The axis along which elements are shifted (from numpy.rool).

  • sub (foat, default=0) – The substitution value of the border

Returns:

The shifted image.

Return type:

array

spam.helpers.imageManipulation.multipleShifts(im, shifts, sub=0)[source]#

This function call singleShift multiple times.

Parameters:

  • im (array) – The input to shift.

  • shifts ([int, int, int]) –

    Defines the number of shifts to apply in every axis.

    shift = [s_x, s_y, s_z] applies a shift of:
.   s_x on axis 0
.   s_y on axis 1
.   s_z on axis 2

  • sub (float, default=0) – The substitution value of the border

Returns:

The shifted image.

Return type:

array

spam.helpers.imageManipulation.slicePadded(im, startStop, createMask=False, padValue=0, verbose=False)[source]#

Extract slice from im, padded with zeros, which is always of the dimensions asked (given from startStop)

Parameters:

  • im (3D numpy array) – The image to be sliced

  • startStop (6 component list of ints) – This array contains: [Zmin, Zmax, Ymin, Ymax, Xmin, Xmax]

  • createMask (bool, optional) – If True, return a padded slice, which is False when the slice falls outside im Default = False

Returns:

  • imSliced (3D numpy array) – The sliced image

  • mask (3D numpy array of bools) – The 3D mask, only returned if createMask is True

spam.helpers.imageManipulation.splitImage(im, divisions, margin, verbose=True)[source]#

Divides the image in zDiv x yDiv x xDiv blocks, each block is padded with a margin.

Parameters:

  • im (3D numpy array) – The image to be splitted

  • divisions (3-component list of ints) – Desired number of blocks along Z, Y, X axes

  • margin (int) – Overlapping margin between each block. For applying a filter on subvolumes, it is recommended to use a margin of 1.5 times the filter diameter. For labelled data it is recommended that the margin is at least 1.5 times bigger than the particles largest axis

  • verbose (bool) – Print the parameters of the operations (number of blocks and margin) Default = True

Returns:

Dictionary with keys labelled acoording to the position of the block along each axis (e.g., 000, 001, 002,…) Each element (e.g., 001) within the dictionary carries the block origin and the resulting block, in that order

Return type:

Dictionary

Note

This function should be used along spam.helpers.imageManipulation.rebuildImage()

spam.helpers.imageManipulation.rebuildImage(listBlocks, listCoordinates, margin, mode, keepLabels=False, verbose=True)[source]#

Rebuilds splitted image from spam.helpers.imageManipulation.splitImage().

Parameters:

  • listBlocks (list) – List of the 3D blocks that will form the re-built the image. Note: The order of listBlocks should be equivalent to the order of listCoordinates

  • listCoordinates (list) – List of the origin coordinates of each block. (Usually taken from spam.helpers.imageManipulation.splitImage()) Note: The order of listCoordinates should be equivalent to the order of listBlocks

  • margin (integer) – Value of the margin used for the images. (Usually taken from spam.helpers.imageManipulation.splitImage())

  • mode (string) – ‘grey’ : re-builds 3D greyscale arrays ‘label’ : re-builds 3D labelled arrays

  • keepLabels (bool) – Do we need to want to keep the current labels from the blocks, or create a new one? Default = False

  • verbose (bool) – Print the evolution of the operation Default = True

Returns:

imBuild – Re-built image without the margins

Return type:

3D numpy array

Note

This function should be used along with spam.helpers.imageManipulation.splitImage()

spam.helpers.imageManipulation.checkerBoard(im1, im2, n=5, inv=False, rescale=True)[source]#

This function generates a “checkerboard” mix of two 2D images of the same size. This is useful to see if they have been properly aligned, especially if the two images are quantitatively different (i.e., one is a neutron tomography and the other is an x-ray tomography).

Parameters:

  • im1 (2D numpy array) – This is the first image

  • im2 (2D/3D numpy array) – This is the second image, should be same shape as first image

  • n (integer, optional) – The number of divisions of the checkerboard to aim for. Default = 5

  • inv (bool, optional) – Whether im2 should be -im2 in the checkerboard. Default = False

  • rescale (bool, optional) – Whether greylevels should be rescaled with spam.helpers.rescale. Default = True

Returns:

im1G

Return type:

checkerBoard mix of im1 and im2

spam.helpers.optionsParser module#

Library of SPAM functions for parsing inputs to the scripts Copyright (C) 2020 SPAM Contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

spam.helpers.optionsParser.str2bool(v)[source]#
spam.helpers.optionsParser.isTwoDtiff(filename)[source]#

Returns true if the passed TIFF file is 2D, this function inspects the header but does not load the image

spam.helpers.optionsParser.displaySettings(args, scriptName)[source]#

spam.helpers.test module#

class spam.helpers.test.TestSpam(*args, **kwargs)[source]#

Bases: TestCase

Overwrites setUp and tearDown of unitest.TestCase to create and delete a .dump folder for files created during tests.

DEBUG = False#
setUp()[source]#

Hook method for setting up the test fixture before exercising it.

tearDown()[source]#

Hook method for deconstructing the test fixture after testing it.

spam.helpers.tsvio module#

Library of SPAM functions for reading and writing TSV files. Copyright (C) 2020 SPAM Contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

spam.helpers.tsvio.writeRegistrationTSV(fileName, regCentre, regReturns)[source]#

This function writes a correctly formatted TSV file from the result of a single register() call, allowing it to be used as an initial registration.

Parameters:

  • fileName (string) – The file name for output, suggestion: it should probably end with “.tsv”

  • regCentre (3-component list) – A list containing the point at which Phi has been measured. This is typically the middle of the image, and can be obtained as follows: (numpy.array( im.shape )-1)/2.0 The conversion to a numpy array is necessary, since tuples cannot be divided by a number directly.

  • regReturns (dictionary) – This should be the return dictionary from register. From this dictionary will be extracted: ‘Phi’, ‘error’, ‘iterations’, ‘returnStatus’, ‘deltaPhiNorm’

spam.helpers.tsvio.writeStrainTSV(fileName, points, decomposedFfield, firstColumn='StrainPointNumber', startRow=0)[source]#

This function writes strains to a TSV file, hiding the complexity of counting and naming columns

Parameters:

  • fileName (string) – fileName including full path and .tsv at the end to write

  • points (Nx3 numpy array) – Points at which the strain is defined

  • decomposedFfield (dictionary) – Dictionary containing strain components as per output from spam.deformation.FfieldRegularQ8, FfieldRegularGeers or FfieldBagi

  • firstColumn (string, optional) – How to name the first column (series number) of the TSV Default = “StrainPointNumber”

  • startRow (int, optional) – Are your points and strains offset from zero? Offset TSV by adding blank lines, don’t use this if you don’t know what you’re doing Default = 0

Return type:

None

spam.helpers.tsvio.readCorrelationTSV(fileName, fieldBinRatio=1.0, readOnlyDisplacements=False, readConvergence=True, readPixelSearchCC=False, readError=False, readLabelDilate=False)[source]#

This function reads a TSV file containing a field of deformation functions Phi at one or a number of points. This is typically the output of the spam-ldic and spam-ddic scripts, or anything written by writeRegistrationTSV.

Parameters:

  • fileName (string) – Name of the file

  • fieldBinRatio (int, optional) – if the input field is refer to a binned version of the image e.g., if fieldBinRatio = 2 the field_name values have been calculated for an image half the size of what the returned PhiField is referring to Default = 1.0

  • readOnlyDisplacements (bool, optional) – Read “zDisp”, “yDisp”, “xDisp”, displacements from the TSV file, and not the rest of the Phi matrix? Default = False

  • readConvergence (bool, optional) – Read “returnStatus”, “deltaPhiNorm”, “iterations”, from file Default = True

  • readPixelSearchCC (bool, optional) – Read “pixelSearchCC” from file Default = False

  • readError (bool, optional) – Read ‘“error”from file Default = False

  • readLabelDilate (bool, optional) – Read “LabelDilate” from file Default = False

Returns:

fieldDims: 1x3 array of the field dimensions (ZYX) (for a regular grid DIC result)

numberOfLabels: number of labels (for a discrete DIC result)

fieldCoords: nx3 array of n points coordinates (ZYX)

PhiField: nx4x4 array of n points transformation operators

returnStatus: nx1 array of n points returnStatus from the correlation

deltaPhiNorm: nx1 array of n points deltaPhiNorm from the correlation

iterations: nx1 array of n points iterations from the correlation

pixelSearchCC: nx1 array of n points pixelSearchCC from the correlation

error: nx1 array of n points error from the correlation

labelDilate: nx1 array of n points labelDilate from the correlation

Return type:

Dictionary containing

spam.helpers.tsvio.readStrainTSV(fileName)[source]#

This function reads a strain TSV file written by spam-discreteStrain or spam-regularStrain

Parameters:

fileName (string) – Name of the file

Returns:

fieldDims: 1x3 array of the field dimensions (ZYX)

fieldCoords : nx3 array of the field coordinates (ZYX)

numberOfLabels: number of labels (for a discrete strain result)

vol: nx1 array of n points with volumetric strain computed under the hypotesis of large strains (if computed)

dev: nx1 array of n points with deviatoric strain computed under the hypotesis of large strains (if computed)

volss: nx1 array of n points with volumetric strain computed under the hypotesis of small strains (if computed)

devss: nx1 array of n points with deviatoric strain computed under the hypotesis of small strains (if computed)

r : nx3 array of n points with the components of the rotation vector (if computed)

z : nx3 array of n points with the components of the zoom vector (if computed)

U : nx3x3 array of n points with the components of the right-hand stretch tensor (if computed)

e : nx3x3 array of n points with the components of the strain tensor in small strains (if computed)

Return type:

Dictionary containing

spam.helpers.tsvio.TSVtoTIFF(fileName, fieldBinRatio=1.0, lab=None, returnRS=False, outDir=None, prefix=None)[source]#

This function converts a TSV file (typically the output of spam-ldic and spam-ddic scripts) to a tiff file for visualising the deformation field.

Parameters:

  • fileName (string) – Name of the file

  • fieldBinRatio (int, optional) – if the input field is refer to a binned version of the image e.g., if fieldBinRatio = 2 the field_name values have been calculated for an image half the size of what the returned PhiField is referring to Default = 1.0

  • lab (3D numpy array, optional) – The labelled image of the reference state. Highly recommended argument in case of a discrete correlation result. Default = None

  • returnRS (bool, optional) – if True: will return the returnStatus of the correlation as a tiff file Default = False

  • outDir (string, optional) – Output directory Default is directory of the input field file

  • prefix (string, optional) – Prefix for output files Default is the basename of the input field file (without extension)

spam.helpers.tsvio.TSVtoVTK(fileName, fieldBinRatio=1.0, pixelSize=1.0, returnRS=False, outDir=None, prefix=None)[source]#

This function converts a TSV file (typically the output of the ldic and ddic scripts) to a VTK file for visualising the deformation field.

Parameters:

  • fileName (string) – Name of the file

  • fieldBinRatio (int, optional) – if the input field is refer to a binned version of the image e.g., if fieldBinRatio = 2 the field values have been calculated for an image half the size of what the returned PhiField is referring to Default = 1.0

  • pixelSize (float) – physical size of a pixel (i.e. 1mm/px) Default = 1.0

  • returnRS (bool, optional) – if True: will return the SubPixelReturnStatus of the correlation Default = False

  • outDir (string) – Output directory Default is directory of the input field file

  • prefix (string) – Prefix for output files Default is the basename of the input field file (without extension)

spam.helpers.vtkio module#

This module offers a set functions in order to read and writes VTK files.

This module is mainly made of meshio wrappers adapted to spam. The types of data currently handled are:

  • Structured meshes of cuboids

  • Unstructured meshes of tetrahedrs

  • List of objects (TODO)

VTK files are assumed to be in X,Y,Z format, and numpy arrays are in Z,Y,X, so the following policy is followed:

  • position arrays are simply reversed so Z comes out first

  • scalar arrays are left as they are

  • vectors and matrices are assumed to be positional (a surface vector for example) and are reversed

spam.helpers.vtkio.readStructuredVTK(f, fieldAsked=None)[source]#

Read a plain text VTK.

By default read the full text and put all fields in a dictionnay. Specific fields can be selected with fieldAsked.

Parameters:

  • f (string) – Name of the VTK file.

  • fieldAsked (array of string, default=None) – List of the field names.

Returns:

fields – Dictionnary of all the fields without nodal or cell distinctions.

fields = {
    "field1name": [field1value1, field1value2, ...],
    "field2name": [field2value1, field2value2, ...],
    # ...
}

Return type:

dict

Note

The outputs are kept flattened.

spam.helpers.vtkio.writeStructuredVTK(aspectRatio=[1.0, 1.0, 1.0], origin=[0.0, 0.0, 0.0], cellData={}, pointData={}, fileName='spam.vtk')[source]#

Write a plain text regular grid vtk from

  • 3D arrays for 3D scalar fields

  • 4D arrays for 3D vector fields

Parameters:

  • aspectRatio (size 3 array, float) – Length between two nodes in every direction e.i. size of a cell Default = [1, 1, 1]

  • origin (size 3 array float) – Origin of the grid Default = [0, 0, 0]

  • cellData (dict {"field1name": field1, "field2name": field2, ...}) –

    Cell fields, not interpolated by paraview. The field values are reshaped into a flat array in the lexicographic order. field1 and field2 are ndimensional array

    (3D arrays are scalar fields and 4D array are vector valued fields).

  • pointData (dict {"field1name": field1, "field2name": field2, ...}) – Nodal fields, interpolated by paraview. pointData has the same shape as cellData.

  • fileName (string) – Name of the output file. Default = ‘spam.vtk’

Warning

This function deals with structured mesh thus x and z axis are swapped in python.

spam.helpers.vtkio.writeGlyphsVTK(coordinates, pointData, fileName='spam.vtk')[source]#

Write a plain text glyphs vtk.

Parameters:

  • coordinates (n by 3 array of float) – Coordinates of the centre of all n glyphs

  • pointData (dict {"field1name": field1, "field2name": field2, ...}) – Value attached to each glyph. field1 and field2 are n by 1 arrays for scalar values and n by 3 for vector values.

  • fileName (string, default='spam.vtk') – Name of the output file.

spam.helpers.vtkio.writeUnstructuredVTK(points, connectivity, elementType='tetra', pointData={}, cellData={}, fileName='spam.vtk')[source]#

Writes a binary VTK using meshio selecting only the tetrahedra.

Parameters:

  • points (2D numpy array) – The coordinates of the mesh nodes (zyx) Each line is [zPos, yPos, xPos]

  • connectivity (2D numpy array) – The connectivity matrix of the tetrahedra elements Each line is [node1, node2, node3, node4]

  • elementType (string, optional, default="tetra") – The type of element used for the mesh

  • cellData (dict, optional, default={}) –

    Cell fields, not interpolated by paraview. With field1 and field2 as 1D or 2D arrays. 1D arrays are scalar fields and 2D array are vector valued fields.

    cellData = {
    "field1name": field1,
    "field2name": field2,
    # ...
}

  • pointData (dict, optional, default={}) –

    Nodal fields, interpolated by paraview. pointData has the same shape as cellData.

    pointData = {
    "field1name": field1,
    "field2name": field2,
    # ...
}

  • fileName (string, optional, default="spam.vtk") – Name of the output file.

Note

VTK files are assumed to be in X,Y,Z format, and numpy arrays are in Z,Y,X, so the following policy is follwed:

  • position arrays are simply reversed so Z comes out first

  • scalar arrays are left as they are

  • vectors and matrices are assumed to be positional (a surface vector for example) and are reversed

  • node numbering in connectivity matrix is changed to ensure a positive Jacobian for each element

spam.helpers.vtkio.readUnstructuredVTK(fileName)[source]#

Read a binary VTK using meshio selecting only the tetrahedra.

Parameters:

fileName (string) – Name of the input file.

Returns:

  • numpy array – The list of node coordinates (zyx).

  • numpy array – The connectivity matrix (cell id starts at 0).

  • dict – Nodal fields, interpolated by paraview.

  • dict – Cell fields, not interpolated by paraview.

spam.helpers.vtkio.TIFFtoVTK(fileName, voxelSize=1.0)[source]#

Convert a tifffile to a vtk file for paraview. It saves it with the same base name.

Parameters:

fileName (string) – The name of the tif file to convert

Module contents#

Contents