|
|
## Mathematics of the atlas
|
|
|
|
|
|
Given a family of objects, the atlas model proposes to learn a **template shape** which corresponds to a **mean of the objects**, as well as to compute a low number of **coordinates for each object** from this template shape. A complete description of the mathematics of the deterministc atlas is given on the [LDDMM](LDDMM) page, including its loss function.
|
|
|
|
|
|
The figure below describes the deterministic atlas model.
|
|
|
|
|
|
|
|
|
![skull_atlas](/uploads/a3837e5f40164867e33fbb84b2d279a5/skull_atlas.png)
|
|
|
|
|
|
|
|
|
## The configuration
|
|
|
|
|
|
We need to configurate the three different xml files: `model.xml`, `data_set.xml`, `optimization_parameters.xml`. We will follow this and run the example in `examples/atlas/landmark/2d/skulls`.
|
|
|
|
|
|
#### The `model.xml` file
|
|
|
|
|
|
This file requires:
|
|
|
- **The name of the model**. Here for atlas it must be set to 'DeterministicAtlas': `<model-type>DeterministicAtlas</model-type>`.
|
|
|
- **The dimension**: 2 for 2D images or 2D meshes (which is the case here) and 3 for 3D images of 3D meshes
|
|
|
|
|
|
- The **template** section: this section defines the list of objects considered in the computation. In our case, a single polyline object is considered, so that there is a unique <object> section in the template section.
|
|
|
|
|
|
- The **deformation-parameters** section. In our case we only need:
|
|
|
* the **kernel-width**: controls the typical width of the deformation as explained in the [LDDMM](LDDMM) page.
|
|
|
* the **kernel-type**: can be set to keops or torch. For a large number of control points, keops is advised.
|
|
|
|
|
|
The model.xml file now looks like:
|
|
|
|
|
|
`<?xml version="1.0"?>
|
|
|
<model deformetrica-min-version="3.0.0">
|
|
|
<model-type>DeterministicAtlas</model-type>
|
|
|
<dimension>2</dimension>
|
|
|
<template>
|
|
|
<object id="skull">
|
|
|
<deformable-object-type>Polyline</deformable-object-type>
|
|
|
<attachment-type>Varifold</attachment-type>
|
|
|
<kernel-width>20</kernel-width>
|
|
|
<kernel-type>torch</kernel-type>
|
|
|
<noise-std>1</noise-std>
|
|
|
<filename>data/template.vtk</filename>
|
|
|
</object>
|
|
|
</template>
|
|
|
<deformation-parameters>
|
|
|
<kernel-width>20</kernel-width>
|
|
|
<kernel-type>keops</kernel-type>
|
|
|
</deformation-parameters>
|
|
|
</model>`
|
|
|
|
|
|
|
|
|
Details about how to construct a general model xml file are available [here](UsersManual/ModelXMLFile).
|
|
|
|
|
|
### The `data_set.xml` file
|
|
|
|
|
|
This file contains the paths to all the objects. Each observation is a **subject** section with a subject id. Each subject section contains a single visit which contains the list of filenames, with the id of the shape as attribute. In our example, a subject looks like:
|
|
|
|
|
|
`<subject id="australopithecus">
|
|
|
<visit id="experiment">
|
|
|
<filename object_id="skull">data/skull_australopithecus.vtk</filename>
|
|
|
</visit>
|
|
|
</subject>`
|
|
|
|
|
|
### The `optimization_parameters.xml` file.
|
|
|
|
|
|
It is kept at a minimum for this example, and simply indicates the **optimization-method-type**, the **max-iterations** number and the use of a Sobolev gradient (use to obtain a smoother template).
|
|
|
|
|
|
## Running the example
|
|
|
|
|
|
The example can be run using the command:
|
|
|
|
|
|
`deformetrica model.xml data_set.xml optimization_parameters.xml`
|
|
|
|
|
|
This will run the estimation and save output in the output folder. In this output, there will be:
|
|
|
- Every reconstructed shape. Their name contains `__Reconstruction__`, the id of subject and of the shape.
|
|
|
- The estimated template: one file for each shape of the template.
|
|
|
- The set of control points used, in txt format. A standard initialization is used, and they are fixed by default during the optimization, although it is also possible to estimate them by setting `<freeze-cp>Off</freeze-cp>` in the `optimization_parameters.xml` file.
|
|
|
- The set of momenta used, in txt format. Each paragraph of this file is the set of momenta used for one subject. They can be used to perform statistical tasks on a population.
|
|
|
- The residuals of the fit: the list of distances between the targets and the reconstructed objects.
|
|
|
|
|
|
## Pre-processing
|
|
|
|
|
|
In general, we advise to have the shapes rigidly aligned before running an atlas. It is also advised to use a relevant initialization for the initial template shape e.g. using one of the observations.
|
|
|
|
|
|
<!-- # Registration
|
|
|
|
|
|
A registration uses the Deterministic Atlas code with only two objects: the template and the target, and with the template fixed. This is best done by setting **Registration** for the model type in the model.xml and by only specifying the target in the data_set.xml file. An example of image registration can be found in the folder `examples/registration/image/2d/turtles`. Below if the estimated flow for this example which registers two turtle masks:
|
|
|
|
|
|
![turtle_trajectory](/uploads/af12fa2a9631f5d1cb1e10e01044da00/turtle_trajectory.png)
|
|
|
|
|
|
--> |