# Introduction¶

## Welcome to spam¶

Welcome to spam – The Software for the Practical Analysis of Materials.

This is a Python package for handling and correlating 3D fields for applications in material science. It is built on top of Numpy and Scipy, and has some optimised C/C++ functions for speed,

### Developers¶

At the moment it is principally developed by Edward Andò, Rémi Cailletaud, Emmanuel Roubin and Olga Stamati, developers and contributions are welcome! Head over to How to Contribute to find out more.

It has evolved to cover needs of data analysis from 3D x-ray tomography work and correlated random fields with mechanical applications.

### Chat room¶

There is a riot/matrix.org chat room for spam, please join it here and come and talk to us – it is easy, there is a chat client that can run in your web broswer. All you need to do is choose a user name!

## Tools provided¶

### Image correlation Library¶

Tools for measuring the transformation between two 3D images.

This includes a number of simple python functions that can be called manually (most conveniently within an ipython context), as well as more fully-fledged clients for correlation a grid of points. This mean either a regular grid of points, or label-by-label on a labelled volume, the so-called discrete correlation.

A set of functions to manipulate the deformation function $$\Phi$$ is also available. This set of functions has already been used for the following publication:

Volumetric strain results from [Stavropoulou2018] of an unconfined Callovo-Oxfordian clay rock cracking from water uptake

Please take a look at the tutorial for a gentle introduction to the deformation function $$\Phi$$ and some examples of image correlation (both with python functions and with clients): imageCorrelationTutorial.

Furthermore, there is the ability to do Discrete DIC (see label handling in the next section), there is also a tutorial for that: Tutorial: Discrete Image correlation

A global DIC client (which solves a global correlation problem on a mesh) also exists, but is still being tested.

### Label toolkit¶

Tools to deal with labelled images (of particles) where a 3D image are provided. In these images, voxels are “labelled” with integer values that indicate what particle they belong to. Please see the Tutorial: Label Toolkit.

For example we offer a rapid calculation of bounding boxes like scipy.ndimage.find_objects but faster.

Also offered are calculations of:
• the volume of each label

• the centre of mass of each label

• the eigen-vectors and eigen values of the moment of intertia tensor of each label (convenient for orienting simple shapes in 3D)

• the length of the half-axes of an ellipse fitting the particle

Example of discrete correlation from [Ando2019], showing grains coloured by their measured vertical displacement

### Helper tools¶

This series of functions do generally useful and boring stuff like reading and writing files in a formatted way.

### Mesh tools¶

Tools to generate (random meshes, Delaunay trianulations), read and write meshes are provided in the mesh toolkit. Furthermore there is a strain calculation tool, with a full mathematical description in the Tutorial: Strain calculation. You can also find tools to project morphologies onto meshes which is detailed in the Tutorial: Projection of morphologies onto a FE mesh, and can be seen in an example below:

Example of the projection of a microstructure identified from tomography onto a finite-element mesh [Stamati2018b]

### Plotting tools¶

These tools contain standard and generally useful plotting tools. For example: .. For the moment there are two main tools:

#### orientationPlotter¶

This function allows distributions of 3D orientations to be visualised. It puts all 3D unit vectors onto the origin (so that the set of all possible unit vectors represents a sphere) and looks at the sphere from the +z-axis. All -z orientations are flipped, and the projection of the sphere onto the plane is an equal-area project, making it easier to detect clusters. A binning function is also provided to allow more subtle trends to be detected.

Figure of grain-to-grain contact orientations adapted from [Jacquet2013]

### Kalisphera¶

Kalisphera, a standalone analytical tool for the exact calculation of the partial volume effect of a sphere is also included in spam.

Illustration of the different analytical cases of a sphere intersection with a cube that are solved to calculate the exact partial volume effect on the edge of a sphere in Kalisphera [Tengattini2015]

It has been imported into this project for convenience for potential users, but also because it helps in the testing of some functions (the label ones for example). Here we use Félix Bertoni’s C++ version through a python helper function.

Below, for example, Kalisphera is used as a ground truth to which controlled measurement errors (blur and greyscale noise) are added to assess downstream errors in the analysis of contacts between spherical particles.

Simulation of measurement noise based on Kalisphera for a metrological study in [Wiebicke2017]

There is also a live example where you can see the generation of a synthetic image from DEM data: Kalisphera sphere assembly generation

### References¶

Ando2019

Andò, E., Dijkstra, J., Roubin, E., Dano, C., & Boller, E. (2019). A peek into the origin of creep in sand. Granular Matter, 21(1), 11. https://doi.org/10.1007/s10035-018-0863-5

Jacquet2013

Jaquet, C., Andò, E., Viggiani, G., & Talbot, H. (2013, May). Estimation of separating planes between touching 3D objects using power watershed. In International Symposium on Mathematical Morphology and Its Applications to Signal and Image Processing (pp. 452-463). Springer, Berlin, Heidelberg. https://doi.org/10.1007/978-3-642-38294-9_38

Kawamoto2016

Kawamoto, R., Andò, E., Viggiani, G., & Andrade, J. E. (2016). Level set discrete element method for three-dimensional computations with triaxial case study. Journal of the Mechanics and Physics of Solids, 91, 1-13. https://doi.org/10.1016/j.jmps.2016.02.021

Stamati2018b

Stamati, O., Roubin, E., Andò, E., & Malecot, Y. (2018). Tensile failure of micro-concrete: from mechanical tests to FE meso-model with the help of X-ray tomography. Meccanica, 1-16. https://doi.org/10.1007/s11012-018-0917-0

Stavropoulou2018

Stavropoulou, E., Andò, E., Tengattini, A., Briffaut M., Dufour, F., Atkins, D., Armand, G. (2018). Liquid water uptake in unconfined Callovo Oxfordian clay-rock studied with neutron and X-ray imaging. Acta Geotechnica. https://doi.org/10.1007/s11440-018-0639-4

Tengattini2015

Tengattini, A., & Andò, E. (2015). Kalisphera: an analytical tool to reproduce the partial volume effect of spheres imaged in 3D. Measurement Science and Technology, 26(9), 095606. https://doi. org/10.1088/0957-0233/26/9/095606

Wiebicke2017

Wiebicke, M., Andò, E., Herle, I., & Viggiani, G. (2017). On the metrology of interparticle contacts in sand from x-ray tomography images. Measurement Science and Technology, 28(12), 124007. https://doi.org/10.1088/1361-6501/aa8dbf