@@ -129,8 +129,8 @@ A radically open approach to measurement science with the disclosure of analysis

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

# Summary

``spam``, the Software for the Practical Analysis of Materials is a library that extends the extremely convenient framework of NumPy [@numpy] and SciPy [@SciPy2020] by providing or accelerating tools for the material- science/mechanics oriented analysis of 2D images or 3D volumes representing field measurements.

The package is organised into a library of python ``tools`` which are expected to be used in user-written scripts and a number of more sophisticated standalone scripts.

Spam, the Software for the Practical Analysis of Materials is a library that extends the extremely convenient framework of NumPy [@numpy] and SciPy [@SciPy2020] by providing or accelerating tools for the material- science/mechanics oriented analysis of 2D images or 3D volumes representing field measurements.

The package is organised into a library of Python tools which are expected to be used in user-written scripts and a number of more sophisticated standalone scripts.

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.

...

...

@@ -141,11 +141,13 @@ Tools are also provided to compute fields of $F$ from a displacement field measu

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

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

-`excursions`: toolkit 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].

-`excursions`: toolkit 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` [@Ritself; @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).

-`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`: 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`` [@meshio]).

-`helpers`: 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` [@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).

...

...

@@ -156,7 +158,8 @@ A wrapper for ITK's morphological watershed [@schroeder2003itk; @beare2006waters

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

-`mesh`: toolkit for the creation or manipulation of meshes -- in ``spam`` tetrahedral meshes are principally used. Meshers based on ``gmsh`` [@geuzaine2009gmsh] 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].

-`mesh`: toolkit for the creation or manipulation of meshes -- in `spam` tetrahedral meshes are principally used. Meshers based on gmsh [@geuzaine2009gmsh] 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 software [@roubin2015multi; @stamati2018tensile].

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

...

...

@@ -174,21 +177,22 @@ 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:

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 to the parameters used, encouraging a "live"" exploration of optimal settings.

- 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.

- 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.

Given the large data volumes often encountered in 3D analysis, critical parts of the code are written in C/C++ wrapped with appropriate Python calling functions which are responsible for checking input sanity.

The current wrapping method is with PyBind11 [@pybind11].

The current wrapping method is with pybind11 [@pybind11].

Building on the large number of functions already available in NumPy [@numpy], SciPy [@SciPy2020], scikit-image [@scikitimage] and making use of tifffile [@tifffile] and meshio [@meshio], ``spam`` adds a large amount of functionality, which means that a number of advanced forms of data analysis can be chained together in ways that are otherwise complex, requiring the combination of many different tools.

Building on the large number of functions already available in NumPy [@numpy], SciPy [@SciPy2020], scikit-image [@scikitimage] and making use of tifffile [@tifffile] and meshio [@meshio], `spam` adds a large amount of functionality, which means that a number of advanced forms of data analysis can be chained together in ways that are otherwise complex, requiring the combination of many different tools.

``spam`` uses `unittest` to check each commit with a coverage of almost 90\% of lines of code covered as of May 2020.

Details of coverage are currently available [at this address](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/coverage/).

Spam uses `unittest` to check each commit with a coverage of more than 90\% of lines of code covered as of June 2020.

Details of coverage are available [at this address](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/coverage/).

# Online documentation

...

...

@@ -198,7 +202,7 @@ The documentation for this project is currently available online here:

There are three main components to the documentation:

- The module index is built automatically by ``sphinx``, and function headers are written in such a way (following the NumPy norm) that a brief description appears in the module index.

- The module index is built automatically by `sphinx`, and function headers are written in such a way (following the NumPy norm) that a brief description appears in the module index.

- A partial "Gallery of Examples" using `sphinx-gallery` where downloadable python scripts or Jupyter notebooks are executed during the compilation of the documentation and whose results are visible.

...

...

@@ -211,24 +215,24 @@ Other open-source packages could be ITK [@schroeder2003itk] which remains quite

On the specific topic of Digital Image/Volume Correlation, a number of options exist (this is by far not an exhaustive list):

- CMV_3D: Developed at Laboratoire Navier [@bornert2004mesure]

- CMV\_3D: Developed at Laboratoire Navier [@bornert2004mesure]

- Correli: Developed by LMT Cachan, shared with colleagues but not open source [@hild2008correliq4]

- FIDVC: Open source code running on Matlab [@bar2014fast]

- LaVision: Closed-source software

- TomoWarp2: Developed by some of the co-authors [@tudisco2017tomowarp2], limited to displacements/rotations, slow line-search in rotation space

- VIC3D: Closed-source software

# Getting ``spam``

# Getting `spam`

Spam is currently available to all Linux users on Python 3 through a pip package.

Developers or curious users are encouraged to clone the git repository [here](https://gricad-gitlab.univ-grenoble-alpes.fr/ttk/spam).

`spam` is currently available to all Linux users on Python 3 through a `pip` on PyPI package.

Developers or curious users are encouraged to clone the Git repository [here](https://gricad-gitlab.univ-grenoble-alpes.fr/ttk/spam).

Solid build instructions exist for Debian-based environments (in principle any GNU/Linux distribution should work) and for some versions of OSX.

Compilation for Windows has not been attempted given the large number of dependencies, but the availability of Ubuntu through WSL has been sufficient for users.

# Use in existing work

``spam`` has already enabled research progress on a number of fronts, resulting in the following publications:

Spam has already enabled research progress on a number of fronts, resulting in the following publications:

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

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

...

...

@@ -250,7 +254,7 @@ We would like to acknowledge:

- Emmanuelle Gouillard

- Jose Luis Cercos-Pita at the ESRF

for discussions that have contributed to getting ``spam`` into its current form.

for discussions that have contributed to getting spam into its current form.