Command-line apps

Deformetrica is made of 3 executable commands for data in 2D or 3D: sparseMatching2/3, sparseAtlas2/3, ShootAndFlow2/3. The syntax and the description of these apps are as follows. Examples in the Tutorials show how to use them.

sparseMatching

This command allows the registration between two sets of shapes. A set of shapes is made of the union of different objects (Object1, Object2, etc..) embedded in the ambient 2D or 3D space. See below for the description of available object types in Deformetrica. The syntax of the command is the following:

sparseMatching3 paramDiffeos.xml paramObject1.xml source1 target1 paramObject2.xml source2 target2 …

where:

• paramDiffeos.xml is the file name of an xml file containing the parameter settings of the deformation framework and for the optimization algorithm,
• paramObjectK.xml sourceK targetK are triplets of file names. The first one is an xml file containing the parameter settings of the kth object within the shape set, the second one is the file of the kth object in the source shape set (denoted $\mathcal T_k$), the third one is the file of the kth object in the target shape set (denoted $\mathcal O_k$). See below of the accepted formats of the files.

This command minimizes the following cost function:

$E(c_0,\alpha_0) = \sum_{k=1}^N \left\{ \frac{1}{2\sigma_k^2} D(\phi_1\star\mathcal T_k, \mathcal O_k)^2\right\} + Reg(\phi_1)$

where:

• $\mathcal T_k$ and $\mathcal O_k$ are the kth source and target object respectively
• $\sigma_k$ is the weight of each object within the cost function (their values are set in the paramObject.xml files)
• D is a distance between objects of the same kind, which is determined in the paramObject.xml files
• $\phi_t$ is a time-varying deformation of the ambient space (for t a variable of integration between 0 and 1). The final deformation $\phi_1$ is the deformation of interest that warps the set of source shapes to the set of target shapes. The flow of deformation $\phi_t$ is parameterized by a set of control points $c_0$ and momentum vectors attached to them $\alpha_0$.
• $\phi\star\mathcal T_k$ denotes the deformation of the kth source object
• $Reg(\phi_1)$ is a measure of the regularity of the deformation

The optimization method is initialized with control points at the nodes of a regular lattice and momentum vectors equal to zero, namely no deformation. User-defined initializations are possible by giving the name of .txt files for the control points and momentum vectors in paramDiffeos.xml file (see below).

The command produces the following outputs:

• CP_final.txt: a text file containing the coordinates of the optimal position of the control points
• Mom_final.txt: a text file containing the values of the optimal momentum vectors attached to the control points, together parameterizing the optimal flow of deformation $\phi_t$ warping the source to the target
• sourceK__t_*: a set of files of the same format as the kth input object file. These file give the deformation of the object along the optimal deformation $\phi_t\star\mathcal T_k$. The number of files depends on the discretization of the unit time interval, 10 time-steps by default. The last file is the deformed source object that is as close as possible to the corresponding target object $\mathcal O_k$.

sparseAtlas

This command allows the construction of an atlas from a collection of $N_{su}$ shape sets, each set being made of N objects. Typically, N is the number of structures segmented in $N_{su}$ images of different subjects. An atlas denotes a set of N template objects, which average out the shape of each object in the collection, and N deformations warping the template object set to each object set in the collection.

The syntax of the command is the following:

sparseAtlas3 paramsDiffeos.xml NumberOfObjects paramsObject1.xml InitialTemplate1 Subject1 Subject2 Subject3 … paramsObject2.xml InitialTemplate2 Subject1 Subject2 Subject3 …

where:

• paramDiffeos.xml is the file name of an xml file containing the parameter settings of the deformation framework and for the optimization algorithm,
• NumberOfObjects is the number of objects (N with our notations)
• paramObjectK.xml InitialTemplateK Subject1 Subject2 Subject3 … Subject$N_{su}$ are (N+2)-uple of file names. The first one is an xml file containing the parameter settings of the kth object, the second one is the file of the kth object of an initial template shape, the following ones are the files of the kth object in the ith set of shapes within the collection for $i=1,\ldots, N_{su}$.

This command minimizes the following cost function:

$E(c_0,\alpha^1_0,\ldots,\alpha^{N_{su}},\mathcal T_1, \ldots, \mathcal T_N) = \frac{1}{N_{su}} \sum_{i=1}^{N_{su}} \left\{ \sum_{k=1}^N \left\{ \frac{1}{2\sigma_k^2} D(\phi^i_1\star\mathcal T_k, \mathcal O^i_k)^2 \right\}+ Reg(\phi^i_1)\right\}$

where:

• $\mathcal T_k$ is the kth template object
• $\mathcal O^i_k$ is the kth object within the ith shape set ($k=1,\ldots,N$, $i=1,\ldots,N_{su}$)
• $\sigma_k$ is the weight of each object within the cost function (their values are set in the paramObject.xml files)
• D is a distance between objects of the same kind, which is determined in the paramObject.xml files
• $\phi^i_t$ is a time-varying deformation of the ambient space (for t a variable of integration between 0 and 1). The final deformation $\phi^i_1$ is the deformation of interest that warps the set of template shapes to the ith set of shapes. The flow of deformation $\phi^i_t$ is parameterized by a set of control points $c_0$ (independent of i) and momentum vectors attached to them $\alpha^i_0$.
• $\phi^i\star\mathcal T_k$ denotes the deformation of the kth template object
• $Reg(\phi^i_1)$ is a measure of the regularity of the deformation

The optimization method is initialized with template shape given in files InitialTemplateK, control points at the nodes of a regular lattice and momentum vectors equal to zero, namely no deformation. User-defined initializations are possible by giving the name of .txt files for the control points and momentum vectors in paramDiffeos.xml file (see below).

The command produces the following outputs:

• CP_final.txt: a text file containing the coordinates of the optimal position of the control points
• MOM_final.txt: a text file containing the $\latex N_{su}$ sets of optimal momentum vectors attached to the control points, which parameterize each flow of deformation $\phi^i_t$ warping the template to each set of shapes within the collection.
• InitlalTemplateK_template: a file of the same format as InitialTemplateK containing the optimal shape of the kth template object.
• InitialTemplateK_to_subject_i__t_*: a set of files of the same format as InitialTemplateK. These file give the deformation of the kth template object along the ith deformation $\phi^i_t\star\mathcal T_k$. The number of files depends on the discretization of the unit time interval, 10 time-steps by default. The last file is the deformed template object that matches the corresponding target object within the ith set of shapes $\mathcal O^i_k$.

ShootAndFlow

This command allows to deform any object embedded in the ambient 2D or 3D space using deformation parameters. These deformation parameters are typically the outputs of sparseMatching.

The syntax of the command is as follows:

ShootAndFlow3 paramsDiffeos.xml Direction CP.txt Mom.txt paramsObject1.xml object1 paramsObject2.xml object2 …

where:

• paramDiffeos.xml is the file name of an xml file containing the parameter settings of the deformation framework,
• Direction should be equal to either 1 or -1. For Direction=1, objects are deformed by the deformation: $\phi$. For Direction = -1, objects are deformed by the inverse deformation $\phi^{-1}$
• paramObjectK.xml ObjectK are pairs file names. The first one is an xml file containing the parameter settings of the kth object, the second one is the file of the kth object in the ambient space to be deformed.

The command produces the following outputs:

• ObjectK_flow__t_* : a set of files of the same format as ObjectK. These file give the deformation of the kth object along the deformation $\phi_t\star\mathcal O_k$ if Direction = 1, $\phi^{-1}_t\star\mathcal O_k$ if Direction = -1. The number of files depends on the discretization of the unit time interval, 10 time-steps by default.

References:

Durrleman et al. Neuroimage 2014