<!-- affiliation:"1,2"# (Multiple affiliations must be quoted) -->

affiliations:

...

...

@@ -100,7 +101,7 @@ bibliography: paper.bib

---

# Statement of need

Advanced experimental materials science is entering a new era with thanks to the performance and availability of tomography allowing full-3D studies, and often 3D-timeseries.

Advanced experimental materials science is entering a new era thanks to the performance and availability of tomography allowing full-3D studies, and often 3D-timeseries.

However in the analysis of these advanced measurements, the attractiveness of closed-source and black-box solutions to 3D measurement problems seems to be precipitating a reproducibility crisis in this domain.

A radically open approach to measurement science with the disclosure of analysis tools will allow validation and verification of tools and results, rendering the whole chain more robust.

Furthermore, the hope is that there is a community-driven improvement of the tools with time.

...

...

@@ -113,27 +114,27 @@ The tools are organised as follows:

-`DIC`: toolkit for Digital image/volume correlation. This toolkit provides tools to measure the deformation between two images/volumes. A robust registration tool based on the same-modality version of @tudisco2017extension is provided, as well as some cutting edge tools such as multi-modal registration that implements @roubin2019colours.

A version of Global-DVC as per @mendoza2019complete is in the process of being developed.

-`deformation`: toolkit of tools for manipulating deformation functions called $\Phi$ (expressed in homogeneous coordinates) as well the more usual transformation gradient tensor $F$.

Tools are also provided to compute fields of $F$ from a displacement field measured on a regular grid (coming from a *local* DIC for example), either using square/cubic finite element shape functions, or the method proposed in @geers1996computing.

-`deformation`: toolkit of tools for manipulating deformation functions called $\Phi$ (expressed in homogeneous coordinates), as well as the more usual transformation gradient tensor $F$.

Tools are also provided to compute fields of $F$ from a displacement field measured on a regular grid (coming from a "local" DIC for example), either using square/cubic finite element shape functions, or the method proposed in @geers1996computing.

For a displacement field on an irregular grid (for example defined at particle centres from a *discrete* DIC), a Delaunay triangulation based method [@bagi1996stress; @zhang2015large; @catalano2014] is implemented.

Both large strains and small strains frameworks are implemented for both regular and irregular grids.

Both finite (large) strain and infinitesimal (small) strain frameworks are implemented for both regular and irregular grids.

-`excursions`: library of tools for the excursion set of correlated random fields theory [@adler2008new]. It includes functions that gives the analytical predictions of the global descriptors (or Lipschitz-Killing curvatures) of excursions in spaces of arbitrary dimensions [@roubin2015meso; @roubin2016perco] along with the generation of correlated random fields using "RandomFields" in R through rpy2 [@R; @rpy2; @schlather2013randomfields].

-`excursions`: library of tools for the excursion set of correlated random fields theory [@adler2008new]. It includes functions that give the analytical predictions of the global descriptors (or Lipschitz-Killing curvatures) of excursions in spaces of arbitrary dimensions [@roubin2015meso; @roubin2016perco] along with the generation of correlated random fields using "RandomFields" in R through rpy2 [@R; @rpy2; @schlather2013randomfields].

-`filters`: toolkit of 3D filters that provide some functionality missing in ``scipy.ndimage.filters`` such as the computation of a local hessian, or functions which are slow (such as the computation of a local variance).

-`helpers`: a toolkit of internal helper functions such as the the parsers for the scripts, as well as tools for reading and writing TSV and VTK files (the latter partially uses ``meshio``).

-`helpers`: a toolkit of internal helper functions such as the parsers for the scripts, as well as tools for reading and writing TSV and VTK files (the latter partially uses ``meshio``).

-`kalisphera`: wrapper for C++ version of `kalisphera` [@tengattini2015kalisphera] which generates analytically-correct partial-volume spheres which are useful for testing discrete analysis code (see `label` below).

-`label`: Library of functions to measure and manipulated "labelled" images, where discrete particles are labelled with integer voxel patches. The computation of standard quantities such as the volume, barycentre and moment of inertia tensor of each particle can be done very rapidly.

-`label`: library of functions to measure and manipulate "labelled" images, where discrete particles are labelled with integer voxel patches. The computation of standard quantities such as the volume, barycentre and moment of inertia tensor of each particle can be done very rapidly.

An estimation of an ellipse fitting of each particle is implemented with the algorithm from @ikeda:2000.

Tools for characterising inter-particle contacts based on the work of @wiebicke2017.

A wrapper for ITK's morphological watershed [@schroeder2003itk; @beare2006watershed] is also provided.

-`measurements`: toolkit implementing the measurement of covariance, porosity and global descriptors (volume, perimeter, surface area, and Euler characteristic).

-`mesh`: toolkit of tools for the creation or manipulation of meshes -- in ``spam`` tetrahedral meshes are principally used. Meshers based on ``gmsh`` are used through ``pygmsh`` and weighted Delaunay triangulation (Laguerre triangulation) is provided through an interface with ``CGAL`` [@cgal] -- alpha-shapes are also implemented to help clean up badly-shaped tetrahedra. In addition and set of projection functions creates meshed able to represents heterogeneities (phases and interfaces of a given meso/micro structure) based on binary or trinary images or continuous fields (level set) with outputs easily convertible to any FE Softwares [@roubin2015multi; @stamati2018tensile].

-`mesh`: toolkit of tools for the creation or manipulation of meshes -- in ``spam`` tetrahedral meshes are principally used. Meshers based on ``gmsh`` are used through ``pygmsh`` and weighted Delaunay triangulation (Laguerre triangulation) is provided through an interface with ``CGAL`` [@cgal] -- alpha-shapes are also implemented to help clean up badly-shaped tetrahedra. In addition a set of projection functions creates meshes able to represent heterogeneities (phases and interfaces of a given meso/micro structure) based on binary or trinary images or continuous fields (level set) with outputs easily convertible to any FE Softwares [@roubin2015multi; @stamati2018tensile].

-`plotting`: toolkit of plotting tools based on `matplotlib` [@matplotlib] for creating complex plots such as a 3D orientation plot.

...

...

@@ -153,9 +154,9 @@ A number of scripts are available to be called from the command line, at the mom

# Technical details

``spam`` is based on simple Python data types, avoiding complex data structures, and all functions have a reasonable and safe set of default parameters, with required parameters kept to a minimum. ``spam`` has a number of different use cases:

- Use in a highly interactive manner in iPython or Jupyter. Many outputs from 3D analysis in materials science are highly sensitive the parameters used, encouraging a ``live'' exploration of optimal settings.

- Use in a highly interactive manner in iPython or Jupyter. Many outputs from 3D analysis in materials science are highly sensitive to the parameters used, encouraging a ``live'' exploration of optimal settings.

- To be imported and used within user-written Python scripts

- To be imported and used within user-written Python scripts.

- Standalone use of more complex ``spam`` scripts. These chain together a number of functions and are intended to be called from a command line, and produce output as live plots, or files saved to disk.

...

...

@@ -209,13 +210,13 @@ Compilation for Windows has not been attempted given the large number of depende

- @roubin2016perco: Use of `excursions` toolkit to predict percolation threshold in n-dimensional Euclidean spaces.

- @stamati2018phase: Use of `filters` toolkit to identify aggregates in concrete.

- @stamati2018tensile: Use of Local Digital Image Correlation script to measured deformation in a concrete sample subjected to a tension test and mesh projection functions to conduct the FE analysis.

- @stavropoulou2019liquid: Use of Local Digital Image Correlation script to measure deformation of a claystone.

- @stamati2018tensile: Use of `spam-ldic` and `spam-ddic` scripts to measure deformation in a concrete sample subjected to a tension test and `mesh` projection functions to conduct the FE analysis.

- @stavropoulou2019liquid: Use of `spam-ldic` script to measure deformation of a claystone.

- @wiebicke2019benchmark: Use of `kalisphera` and `label` toolkits to benchmark sand-grain contact measurements, provides an example script.

- @ando2019peek: Use of Discrete Digital Image Correlation script and the `label` toolkit to measure small displacements in a creep test on sand.

- @ando2019peek: Use of `spam-ddic` script and the `label` toolkit to measure small displacements in a creep test on sand.

- @roubin2019colours: Application of Multi Modal Registration to concrete.

- @stavropoulou2020: Use of Multi-Modal Registration, Global Digital Image Correlation script, and the `mesh` toolkit.

- @hurley2019situ: Use of `deformation` toolkit to measure deformation in concrete.

- @stavropoulou2020: Use of Multi-Modal Registration, `spam-gdic` script, and the `mesh` toolkit to measure water absorption in claystone.