@@ -141,37 +141,48 @@ 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.

The `DIC` toolkit is presented in the [introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#image-correlation-deformation-toolkit), discussed in detail in tutorials covering [theory](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-02a-DIC-theory.html), [practice](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-02b-DIC-practice.html) and [discrete DIC](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-04-discreteDIC.html), and illustrated in the [examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#digital-image-correlation-examples)

-`deformation`: toolkit for manipulating deformation functions called $\Phi$ (expressed in homogeneous coordinates), as well as the more usual in continuum mechanics 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" correlation 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 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.

The `deformation` toolkit is presented (together with `DIC`) in the [introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#image-correlation-deformation-toolkit), discussed in detail in the [continuum mechanics refresher](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-00-refreshments.html) the start of [DIC theory](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-02a-DIC-theory.html) and [strain tutorial](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-07-strain.html), and is used throughout the DIC examples (see above)

-`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; @schlather2015randomfields].

The `excursions` toolkit is illustrated in the [examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#random-fields-and-excursion-sets)

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

The `filters` toolkit is used in the [projection tutorial](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-06-projection.html), and illustrated [examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#image-operations)

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

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

The `kalisphera` toolkit is presented in the [introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#kalisphera), is used in the [contacts tutorial](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-08-contacts.html), and is illustrated in the [examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#kalisphera-sphere-generation)

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

Please see label toolkit in[introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#label-toolkit), [tutorial](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-03-labelToolkit.html), and [examples](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#labeltoolkit-examples)

The `label` toolkit is presented in the[introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#label-toolkit), discussed in detail in tutorials covering [the base toolkit](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-03-labelToolkit.html) and[contacts](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-08-contacts.html), and illustrated in the[examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#labeltoolkit-examples)

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

The `measurements` toolkit is used [in the examples](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#random-fields-and-excursion-sets)

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

The `mesh` toolkit is presented in the [introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#mesh-tools), at the heart of the [projection tutorial](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/tutorial-06-projection.html), and illustrated in the [examples gallery](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/spam_examples/index.html#mesh)

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

The `plotting` toolkit is presented in the [introduction](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/intro.html#plotting-tools) and used throughout tutorials and examples

-`visual`: toolkit of graphical helper functions for scripts.

A number of scripts are available to be called from the command line, at the moment the most-used scripts are related to image correlation:

-`spam-ldic` and `spam-regularStrain`: A "local" image correlation script, working for series of greyscale 2D or 3D images where kinematics are measured on independent points spread on a regular grid, accompanied by a strain computation script.

...

...

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

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

- @roubin2018perco: Use of `excursions` toolkit to predict percolation threshold in n-dimensional Euclidean spaces, see Figures 1 and 2.

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

- @roubin2016perco: Use of `excursions` toolkit to predict percolation threshold in n-dimensional Euclidean spaces (Figures 1 and 2).

- @stamati2018phase: Use of `filters` toolkit to identify aggregates in concrete (Figure 5).

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

- @stavropoulou2019liquid: Use of `spam-ldic` script to measure deformation of a claystone (Figures 10 and 11).

- @wiebicke2020benchmark: Use of `kalisphera` (Figure 5) and `label` toolkits to benchmark sand-grain contact measurements (Figure 8 and others), provides an example script.

- @wiebicke2019benchmark: Use of `kalisphera` (Figure 5) and `label` toolkits to benchmark sand-grain contact measurements (Figure 8 and others), provides an example script.

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

- @roubin2019colours: Application of Multi Modal Registration to concrete, see Figure 4 onwards.

- @roubin2019colours: Application of Multi Modal Registration to concrete (Figure 4 onwards).

- @hurley2019situ: Use of `deformation` toolkit to measure deformation in concrete (strain in Figure 2b).

- @wiebicke2020measuring: Use of `label` toolkit for the analysis of inter-particle contacts (Figure 1) as well as the `plotting` toolkit to plot the distribution of orientations (Figures 7 and 8).

- @stavropoulou2020: Use of `spam-mmr` and `spam-gdic` scripts (respectively Figures 2, 3, 4; and 7), and the `mesh` toolkit to measure water absorption in claystone (Figures 8 and 9).