The model.xml file for the configuration of any Deformetrica run must contain:
The type of model used. This type can be one of DeterministicAtlas, BayesianAtlas, Regression, Registration, Shooting, ParallelTransport.
The dimension of the ambient space. This dimension is 2 for 2D images and meshes embedded in 2D space and 3 for 3D images and 3D meshes.
A template section. This section describes the objects used in the computation
A deformation-parameters section.
The template section
Deformetrica supports multi-objects, that is each observation is a collection of shapes living in the same ambient space (e.g. hippocampus and amygdala, or a mesh and some landmarks). Consequently, the template section of the model.xml can comport several template objects. Each of these objects is declared with an id e.g. <object id='skull'>...</object>.
Each object follows the same architecture:
The id of the shape, as attribute of the object section: <object id="skull">.
The deformable-object-type: the type of the object, which must be SurfaceMesh, PolyLine, PointCloud, Landmark or Image (see description of the objects).
The attachment-type i.e. the type of distance that is used between objects (see description of the objects), if required. For Landmark, Pointcloud and Image this is not required, since the attachment will be by default \ell^2, the pointcloud distance and \ell^2 respectively.
The kernel-width for the distance computation, as explained here. It is only required if the attachment-type is varifold, current or pointcloud.
The kernel-type for the distance computation. It can be set to keops or torch. For large objects, keops is advised to prevent memory overflow. This is only required if the attachment-type is varifold, current or pointcloud.
The noise-std which controls how well we want this object to be fit. In the case of a single-object like in this example, it only controls the tradeoff between data attachment and regularization. When the template is composed of several objects, it controls the importance we grant to the fit of this particular object of the template. A lower value of noise-std gives more importance to the data attachment cost for this object.
A filename, pointing to the file that will be used as an initialization and/or for metadata about the object such as the image dimension.
Additionally, a field dense-mode can be set to On and Off. If it is set to On, there must be a single mesh object, and the control points will be set and fixed to the template mesh vertices.
The deformation-parameters section
This section configures the deformation used in the run. The only mandatory field for all models is:
kernel-width: the width of the Gaussian kernel used in the convolutions to generate deformations. We advise to start with a large value for this kernel. Note that by default, Deformetrica will initialize the control points so as to fill a box containing the objects and so that the spacing between the control points is the kernel width. The number of control points therefore grows very rapidly with the inverse of the kernel width.
The other fields are
number-of-timepoints: for an atlas or a registration, it controls the number of discretization steps used for the integration of the deformations. The default value is 11. Computations are more precise with more time points, but also (linearly) more expensive.
concentration-of-timepoints: for geodesic regression, parallel transport and the longitudinal atlas, it controls the number of points per unit of time on the main deformation. For parallel transport, note that it controls the number of points along the main geodesic, while the final shooting is performed with number-of-timepoints points. For the longitudinal atlas, it controls the number of points per unit of time on the main geodesic, while the shooting from this geodesic is performed with number-of-timepoints points.
kernel-type: the type of kernel used to make the computations. This can be set to torchor keops. For objects with a large number of points, such as images and large meshes, we advise the use of keops. Note that keops is only available with a GPU backend, although its integration with CPU backend is scheduled for further releases.
t0, tmax, tmin: for the geodesic regression, the parallel transport and the longitudinal atlas, it controls the origin, maximum and minimum time of definition of the geodesic. t0 must be specified for a geodesic regression.
Some other parameters can be set in the model xml file:
initial-control-points: the initial position of the control points. It can be used to prescribe manually where the deformation should take place, or to use the same set of control points for different runs. The expected format is txt with the same form as any control points file saved by a Deformetrica run.
initial-momenta: the initial momenta used for the run.