The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'']], creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
 

The very last step of this process uses the function cmrep\_fit from the cm-rep package that we previously installed. Its inputs consist of the medialtemlate.cmrep files obtained above, the binary image as well as a parameter file and the output directory. The main command is
 

The main factor here is the pruning factor ''p''. If ''p''=0, there is no pruning at all and the skeleton is very rough. The point when it starts making a difference is when $p=1$. For the thinnest structures, it is advice to choose ''p''=1.3 or 1.4. For the structures that contains less detail, ''p''=1.8 to ''p''=2 might be a good estimate. Modifying $p$ gives reasonable results for most of the tracts, however, some issues might happen when the tracts are at the limit of being sheet-like. At this point, you can also tweak the parameter ''e'' that is the minimal number of mesh edges separating two generator points of a VD face for it to be considered. The last parameter, ''q'' is the number of bins in each dimension. It defines the speed with which the program runs. A good value is ''q''=20-50. Reducing ''q'' reduces the number of vertices in the skeleton. For more information on each of the parameters and additional ones, you can type the command cmrep_vskel on the command line.

BinaryThresholdImageFilter tensor\_fa.nii.gz wm.nii.gz 0 0.2 0 1

>>>>>>>>>>>>>>>>>>>>>
 
!!!Third Step: From the fiber tracts to the medial rep
The model behind this representation relies on [[Publications.Publications|Yushkevich et al., 2008]], which focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts, the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology. This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|here]]. It also utilizes the convert3D tools that you can find and download [[http://www.itksnap.org/pmwiki/pmwiki.php n=Convert3D.Documentation|here]].
Now you have your segmentations ready (they are grey-level images called, let's say, tract_greylevel.nii.gz), a few preprocessing steps are needed before building the cm-rep. These use convert3D. 
The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'']], creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
 
->1. Convert the grey level segmentation into a binary image:
->[@ 
c3d tract_greylevel.nii.gz -threshold 0.5 inf 1.0 0.0 -o tract_binary.nii.gz

(see note at the bottom of this paragraph)
 
->2.  Generate the speed function

c3d tract_binary.nii.gz -shift -0.1 -o tract_speed.nii.gz

->3. Generate the initialization function
->[@ c3d tract\_binary.nii.gz -threshold 0.25 inf -0.5 0.5 -o tract_init.nii.gz

->4.  Produce the levelset function

c3d tract_speed.nii.gz tract_init.nii.gz -levelset-curvature 0.02 -levelset 100 -o tract_levelset.nii.gz

 

->1. Filter the whole brain tractography with your inclusion ROIs: 
-> [@
TractTool -in tensor.vtk -filter filtered_tract1.vtk -roi ROI_inclusion1.nii.gz -label label_for_roi1

 
(this step is repeated for all the inclusion ROIs. ''-label'' is not required is the value of the label used in ITK-SNAP is 1)
 
->2. Filter the whole brain tractography with your exclusion ROIs/ exclude the erroneous tract:

TractTool -in filtered_tract1.vtk -filter filtered_tract2.vtk -roi ROI_inclusion2.nii.gz -label label_for_exclusion_roi -inclusion 0

->3. Transform the *.vtk into a grey level *.nii: Once the tract has been correctly filtered, the general output (here called filtered_tract2.vtk) is transformed into a nii file with
 
->[@ TractTool -in filtered_tract2.vtk -nifti output.nii.gz -target target.nii.gz

The output `output.nii.gz' will have the same dimensions as `-target', which can be a volume of your choice.
 
From there, if you notice that your fiber tract is not correct, you can refine the process by creating more exclusion ROIs (see \ref{first_step}) and re-creating your output (see \ref{second_step}). An example of what you can achieve for the CST is given in the example directory. 
>>>>>>>>>>>>>>>>>>>>>
 
!!!Third Step: From the fiber tracts to the medial rep
The model behind this representation relies on [[Publications.Publications|Yushkevich et al., 2008]], which focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts, the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology. This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|here]]. It also utilizes the convert3D tools that you can find and download [[http://www.itksnap.org/pmwiki/pmwiki.php n=Convert3D.Documentation|here]].
Now you have your segmentations ready (they are grey-level images called, let's say, tract_greylevel.nii.gz), a few preprocessing steps are needed before building the cm-rep. These use convert3D. 
The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'']], creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
 
->1. Convert the grey level segmentation into a binary image:

c3d tract_greylevel.nii.gz -threshold 0.5 inf 1.0 0.0 -o tract_binary.nii.gz 

(see note at the bottom of this paragraph)
 
->2.  Generate the speed function
->[@ 
c3d tract_binary.nii.gz -shift -0.1 -o tract_speed.nii.gz
@]
 
->3. Generate the initialization function
->[@ c3d tract\_binary.nii.gz -threshold 0.25 inf -0.5 0.5 -o tract_init.nii.gz
@]
 
->4.  Produce the levelset function
->[@ 
c3d tract_speed.nii.gz tract_init.nii.gz -levelset-curvature 0.02 -levelset 100 -o tract_levelset.nii.gz
@]
 

 
 
>>>>>>>>>>>>>>>>>>>>>
!!!Third Step: From the fiber tracts to the medial rep
The model behind this representation relies on [[Publications.Publications|Yushkevich et al., 2008]], which focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts, the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology. This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|here]]. It also utilizes the convert3D tools that you can find and download [[http://www.itksnap.org/pmwiki/pmwiki.php n=Convert3D.Documentation|here]].
Now you have your segmentations ready (they are grey-level images called, let's say, tract_greylevel.nii.gz), a few preprocessing steps are needed before building the cm-rep. These use convert3D. 
The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'']], creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)

->1. Convert the grey level segmentation into a binary image:
->[@ 
c3d tract_greylevel.nii.gz -threshold 0.5 inf 1.0 0.0 -o tract_binary.nii.gz

(see note at the bottom of this paragraph)
 
->2.  Generate the speed function

c3d tract_binary.nii.gz -shift -0.1 -o tract_speed.nii.gz

->3. Generate the initialization function
->[@ c3d tract\_binary.nii.gz -threshold 0.25 inf -0.5 0.5 -o tract_init.nii.gz

 
->4.  Produce the levelset function

c3d tract_speed.nii.gz tract_init.nii.gz -levelset-curvature 0.02 -levelset 100 -o tract_levelset.nii.gz

 

!!!First Step: delineating the fibers corresponding to each tract
If you are not familiar with brain white matter tracts in general, you can gather some information in [[Publications.Publications|Mori et al., 2002]]. This paper has been revealed to be particularly helpful to delineate the aforementioned structures. Other resources can be helpful, such as [[Publications.Publications| Wakana et al., 2003 and Mori et al., 2002]].
 
The current aim is to delineate each tract. This might be the most important step because everything else results from this.
 
# In ITK-Snap, open the FA image (figure 2)
# Open the white matter mask as an overlay (figure 2)
# Use the polygon tool to manually trace the ROIs through which the specific tract you are focusing on is passing
# Once you are satisfied, go to Segmentation -> Save as Image -> Save your ROI as a *.nii.gz
# To remember to which tract each ROI corresponds, you can use the label editor and name each ROI, then save the label descriptions -> Segmentation -> Save Label Descriptions
# You will realize very frequently (ok, all the time!) that you not only have to draw ROIs through which the fibers are supposed to go through, but you also have to draw ROIs to exclude some fibers. An example of inclusion ROIs is given for the corpus callosum in figure 2. An example of exclusion ROI is given in figure 3.
 
%center%%width=400px%Attach:FA_mask_ROI.jpg
%center%Figure 2: An example with the aging atlas. ''Top left'': FA - ''Top right'': FA with white matter mask ''Bottom'': ROIs delineating the corpus callosum
 
%center%%width=400px%Attach:ROI_exclusion.jpg
%center%Figure 3: Exclusion ROIs for the corpus callosum
 
!!!Second Step: Defining each tract
For each tract, you should have drawn a few ROIs through which you expect the fibers to go (the inclusion ROIs) and a few (the exclusion ROIs) through which you expect your fibers not to go, which are here to get rid of the ''extra'' annoying fibers. The main tool that is used to generate each tract is called ''Tracttool''. ''Tracttool'' will be used to 1/filter the tracts, i.e., create one .vtk file per fiber tract - 2/convert the *.vtk into a .nii file  (grey level image of the tract).
Obtaining each fiber tract is an iterative procedure. The whole brain tractography (called tensor.vtk see paragraph first step) is filtered again and again until a reasonable fiber tract is obtained. Here is the way to do it:
 
->1. Filter the whole brain tractography with your inclusion ROIs: 
-> [@
TractTool -in tensor.vtk -filter filtered_tract1.vtk -roi ROI_inclusion1.nii.gz -label label_for_roi1

 
(this step is repeated for all the inclusion ROIs. ''-label'' is not required is the value of the label used in ITK-SNAP is 1)
->2. Filter the whole brain tractography with your exclusion ROIs/ exclude the erroneous tract:

TractTool -in filtered_tract1.vtk -filter filtered_tract2.vtk -roi ROI_inclusion2.nii.gz -label label_for_exclusion_roi -inclusion 0 @]
 
->3. Transform the *.vtk into a grey level *.nii: Once the tract has been correctly filtered, the general output (here called filtered_tract2.vtk) is transformed into a nii file with
 
->[@ TractTool -in filtered_tract2.vtk -nifti output.nii.gz -target target.nii.gz

The output `output.nii.gz' will have the same dimensions as `-target', which can be a volume of your choice.
 
From there, if you notice that your fiber tract is not correct, you can refine the process by creating more exclusion ROIs (see \ref{first_step}) and re-creating your output (see \ref{second_step}). An example of what you can achieve for the CST is given in the example directory. 
 
>>>>>>>>>>>>>>>>>>>>>
 
>>>>>>>>>>>>>>>>>>>>>>>
 
!!Creating the Surface Representation- 2nd part- the Continuous medial representation}
We are going to switch to and focus on the cmp-rep model properly speaking, and use the [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|continuous medical rep]] tools only. The principle is to build the boundary and the corresponding skeleton for each tract.
 
%center%%width=600px%Attach:boun_skel.jpg
%center%Figure 5: ''Left'': An example of initial boundary for the corpus callosum - ''Right'': the corresponding skeleton
 
!!!Building the initial template -1
In order to initiate the cmrep model, you need a primary template. The construction of this initial template starts with the generation of a skeleton and boundary from the previous levelset file.
 
->1. [@ vtklevelset tract_levelset.nii.gz tract_boundary.vtk 0.0

The last and only parameter is the threshold value. The higher the value, the slimmer the boundary. 
 
->2. [@  cmrep_vskel -Q /PATH_TO_QVORONOI/qvoronoi -p ''p'' -e ''e'' -q ''q'' tract_boundary.vtk tract_skel.vtk

!!!Third Step: From the fiber tracts to the medial rep
The model behind this representation relies on [[Publications.Publications|Yushkevich et al., 2008]], which focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts, the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology. This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|here]]. It also utilizes the convert3D tools that you can find and download [[http://www.itksnap.org/pmwiki/pmwiki.php n=Convert3D.Documentation|here]].
Now you have your segmentations ready (they are grey-level images called, let's say, tract_greylevel.nii.gz), a few preprocessing steps are needed before building the cm-rep. These use convert3D. 
The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'']], creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
 
->1. Convert the grey level segmentation into a binary image:
->[@ 
c3d tract_greylevel.nii.gz -threshold 0.5 inf 1.0 0.0 -o tract_binary.nii.gz

(see note at the bottom of this paragraph)
 
->2.  Generate the speed function
->[@ 
c3d tract_binary.nii.gz -shift -0.1 -o tract_speed.nii.gz

->3. Generate the initialization function
->[@ c3d tract\_binary.nii.gz -threshold 0.25 inf -0.5 0.5 -o tract_init.nii.gz

Congratulations! You have made it through the first part. There is still quite a way to go, but we are almost there.
 
''Note'': In some cases, especially for the CST, the filtering step is not enough to delineate the portion of the structure that is sheet-like. Consequently, I strongly suggest to act on the binary structure once it is created in the first step (i.e., step that converts the grey level segmentation into a binary image). At this point, you can open the binary image in ITK-SNAP (opening it as the image and as the segmentation is fine). Go to the 3D window -> click update mesh -> click 3D scalpel tool in the 3D Toolbox -> Change the label number to clear label in the Segmentation options and cut the stem of the CST -> Accept and update mesh. Save the new segmentation.
 
Figure 4 gives you an example.
 
%center%%width=700px%Attach:img_binary.jpg
%center%Figure 4: An example of initial binary files for the cortico-spinal tract. In the bottom image, the stem was cut. The middle and right column illustrate how these two binaries are transformed into skeletons and boundaries during the next steps (see paragraph Building the initial template -1). Modeling the stem using the cmrep model would not be adapted.
 

!!First Step: delineating the fibers corresponding to each tract

!!Second Step: Defining each tract

!!Third Step: From the fiber tracts to the medial rep

!!Building the initial template -3

!!Building the initial template -1

!!Building the initial template -2

!!Checking your template

!!Building the whole brain white matter Atlas using DTITK

!!Main Goal

Creating a tract specific white matter atlas is the result of the combination of three main open-source software developed in PICSL. The first main part relies on DTI-TK. The last steps rely on the continuous medial representation model (cm-rep) (see [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation| url]] for installation and documentation).
Another companion tool that will be needed here is convert3D (see [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|here]]).
 

!!Building the initial template 1

The last and only parameter is the threshold value. The higher the value, the slimmer the boundary
 

The main factor here is the pruning factor ''p''. If ''p''=0, there is no pruning at all and the skeleton is very rough. The point when it starts making a difference is when $p=1$. For the thinnest structures, it is advice to choose ''p''=1.3 or 1.4. For the structures that contains less detail, ''p''=1.8 to ''p''=2 might be a good estimate. Modifying $p$ gives reasonable results for most of the tracts, however, some issues might happen when the tracts are at the limit of being sheet-like. At this point, you can also tweak the parameter $e$ that is the minimal number of mesh edges separating two generator points of a VD face for it to be considered. The last parameter, ''q'' is the number of bins in each dimension. It defines the speed with which the program runs. A good value is ''q''=20-50. Reducing ''q'' reduces the number of vertices in the skeleton. For more information on each of the parameters and additional ones, you can type the command cmrep_vskel on the command line. 
 

The very last step of this process uses the function cmrep\_fit from the cm-rep package that we previously installed. Its inputs consist of the medialtemlate.cmrep files obtained above, the binary image as well as a parameter file and the output directory.  
The main command is
 

The explanation for most of the parameters can be found on this [http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|page]].
The first part of this parameter file contains the default parameters that control the values that you will see appearing on your terminal after launching this command (see Figure 6 and the param_output.txt in the demo folder provided with this tutorial). A few important facts should be retained. During the different iterations you should control that the TOTAL (see Figure 6) is decreasing. Each of the values VOLOV to BNDTRI contribute to this TOTAL and are driven by the default parameters. So you can adjust them by modifying the term weights of the parameter file.
 

# BNDJAC is driven by DefaultParameters.BoundaryJacobianEnergyTerm.Weight, # #DefaultParameters.BoundaryJacobianEnergyTerm.PenaltyA and

# GRAD-R corresponds to DefaultParameters.BoundaryGradRPenaltyTerm.Weight

\end{itemize}
 

%center%%width=800px%Attach:work_flow.jpg

In order to check the accuracy of the template, it is worth comparing it to the original binary file, through a Dice overlap for instance.  
cmrep can be used to generate a binary file from the def3.med.vtk 
 

*The binary def3.nii.gz obtained from the information of the medial representation is then compared to the initial binary model through c3d -verbose def3.nii.gz tract_binary.nii.gz -overlap 1 (if the foreground of the binary image is 1).
This command results in the computation of the Dice overlap. A value of 0.88 is satisfying.

%center%Figure 6: Example of output after submitting the cmrep_fit command.  
 
%center%The total value decreases and each of the terms VOLOV to BNDTRI contribute to this decrease.
 

%center%%width=400px%Attach:img_binary.jpg

%center%%width=400px%Attach:boun_skel.jpg

->2. [@  cmrep_vskel -Q /PATH\_TO\_QVORONOI/qvoronoi -p ''p'' -e ''e'' -q ''q'' tract_boundary.vtk tract_skel.vtk

%center%%width=450px%Attach:default_iteration.png

TVAnisotropy -in tensor.nii.gz}. This will output tensor_fa.nii.gz

%center%Figure 2: An example with the aging atlas.  
 
%center%''Top left'': FA - ''Top right'': FA with white matter mask ''Bottom'': ROIs delineating the corpus callosum
 

%center%Figure 5: ''Left'': An example of initial boundary for the corpus callosum -  
%center%''Right'': the corresponding skeleton
 

This command results in the computation of the Dice overlap. A value of 0.92 is satisfying.

# Once you are satisfied, go to Segmentation $\rightarrow$ Save as Image $\rightarrow$ Save your ROI as a *.nii.gz

 
''Right'': the corresponding skeleton
 

 

%center%An example with the aging atlas. 

%center%Exclusion ROIs for the corpus callosum
 

%center%An example of initial binary files for the cortico-spinal tract. In the bottom image, the stem was cut. The middle and right column illustrate how these two binaries are transformed into skeletons and boundaries during the next steps (see paragraph \ref{Building the initial template -1}). Modeling the stem using the cmrep model would not be adapted.
 

%center%''Left'': An example of initial boundary for the corpus callosum - ''Right'': the corresponding skeleton
 

%center%%width=200px%Attach:default_iteration.png
%center%Example of output after submitting the cmrep_fit command. The total value decreases and each of the terms VOLOV to BNDTRI contribute to this decrease.
 

%center%Pipeline illustrated on the CST
 
Congratulations, you obtained your first white matter tract medial representation!
 

%center%An example with the aging atlas. ''Top left'': FA - ''Top right'': FA with white matter mask ''Bottom'': ROIs delineating the corpus callosum
 

(this step is repeated for all the inclusion ROIs. `-label' is not required is the value of the label used in ITK-SNAP is 1)

->3. Transform the *.vtk into a grey level *.nii: Once the tract has been correctly filtered, the general output (here called filtered\_tract2.vtk) is transformed into a nii file with
 
->[@ TractTool -in filtered\_tract2.vtk -nifti output.nii.gz -target target.nii.gz

The output of this final step will be located in the cmrep\_output/ directory, under three subdirectories, called cmrep, image and mesh. The optimized structure are in cmrep\_output/mesh/, and called def3.med.vtk (the medial representation) and def3.bnd.vtk (boundary). An example can be found in Figure 7.
 
%center%%width=600px%Attach:work_flow.jpg

%center%%width=150px%Attach:atlas_example.png
 

%center%%width=150px%Attach:FA_mask_ROI.jpg

%center%Attach:ROI_exclusion.jpg

%center%Attach:img_binary

%center%Attach:boun_skel

%center%Attach:default_iteration}

%center%Attach:work_flow

%center%Attach:atlas_example.png
 

%center%Attach:FA_mask_ROI.jpg

%center%Attach:FA_mask_ROI

%center%Attach:ROI_exclusion

The model behind this representation relies on the following paper \cite{yushkevich2008} that focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts, the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology. This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found [[http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation|here]]. It also utilizes the convert3D tools that you can find and download [[http://www.itksnap.org/pmwiki/pmwiki.php n=Convert3D.Documentation|here]].

The main goal is to obtain a levelset image from the grey level segmentation. As stated in [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|section''levelset n_iter'', creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
 

Another companion tool that will be needed here is convert3D (see [[http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation|here]).
 

SingleTensorFT -in tensor.nii.gz -seed wm.nii.gz -out tensor.vtk]
 

If you are not familiar with brain white matter tracts in general, you can gather some information in Mori et al., 2002 [[Publications.Publications]]. This paper
has been revealed to be particularly helpful to delineate the aforementioned structures. Other resources can be helpful, such as \cite{wakana2003, mori2008} and \url{http://www.loni.ucla.edu/Atlases/Atlas_Detail.jsp?atlas_id=15}.
\\

\begin{enumerate}
\item In ITK-Snap, open the FA image (figure 2)
\item Open the white matter mask as an overlay (figure 2)
\item Use the polygon tool to manually trace the ROIs through which the specific tract you are focusing on is passing
\item Once you are satisfied, go to Segmentation $\rightarrow$ Save as Image $\rightarrow$ Save your ROI as a *.nii.gz
\item To remember to which tract each ROI corresponds, you can use the label editor and name each ROI, then save
the label descriptions $\rightarrow$ Segmentation $\rightarrow$ Save Label Descriptions
\item You will realize very frequently (ok, all the time!) that you not only have to draw ROIs through which the fibers are supposed to go through, but you also have  
to draw ROIs to exclude some fibers. An example of inclusion ROIs is given for the corpus callosum in figure 2. An example of exclusion ROI is given in figure 3.
\end{enumerate}
 
\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=9cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/FA_mask_ROI}
    \label{fig2}
\caption{An example with the aging atlas. {\it Top left}: FA - {\it Top right}: FA with white matter mask - {\it Bottom}: ROIs delineating the corpus callosum}
  \end{center}
\end{figure}
 
\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=9cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/ROI_exclusion}
   \label{fig3}
\caption{Exclusion ROIs for the corpus callosum}
  \end{center}
\end{figure}
 
 
\subsection{Second Step: Defining each tract}
\label{second_step}
For each tract, you should have drawn a few ROIs through which you expect the fibers to go (the inclusion ROIs) and a few (the exclusion ROIs) through which you
expect your fibers not to go, which are here to get rid of the `extra' annoying fibers.
The main tool that is used to generate each tract is called `Tracttool'. `Tracttool' will be used to 1/filter the tracts, i.e., create one .vtk file per fiber tract - 2/convert the *.vtk into a .nii file  (grey level image of the tract).
Obtaining each fiber tract is an iterative procedure. The whole brain tractography (called tensor.vtk see paragraph \ref{first_step}) is filtered again and again until a reasonable fiber tract is obtained. Here is the way to do it:
\begin{itemize}
\item Filter the whole brain tractography with your inclusion ROIs: \\
TractTool -in tensor.vtk -filter filtered\_tract1.vtk -roi ROI\_inclusion1.nii.gz -label label\_for\_roi1 \\

\item Filter the whole brain tractography with your exclusion ROIs/ exclude the erroneous tract: \\
TractTool -in filtered\_tract1.vtk -filter filtered\_tract2.vtk -roi ROI\_inclusion2.nii.gz -label label\_for\_exclusion\_roi -inclusion 0
\item Transform the *.vtk into a grey level *.nii: Once the tract has been correctly filtered, the general output (here called filtered\_tract2.vtk) is transformed into a nii file with\\
TractTool -in filtered\_tract2.vtk -nifti output.nii.gz -target target.nii.gz. \\

\end{itemize}
 
From there, if you notice that your fiber tract is not correct, you can refine the process by creating more exclusion ROIs (see \ref{first_step}) and re-creating your output (see \ref{second_step}).
An example of what you can achieve for the CST is given in the example directory.

\subsection{Third Step: From the fiber tracts to the medial rep}
\label{third_step}
The model behind this representation relies on the following paper \cite{yushkevich2008} that focuses on white matter tracts that are thin sheet-like structures. After segmentation of these tracts,
the cm-rep model is fitted to them that describes the skeleton and the boundary of geometrical objects as parametric digital surfaces with predefined topology.
This step relies on the continuous medial representation tool developed by Yushkevich et al. The main documentation and binaries can be found at \url{http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation}. It also utilizes the convert3D tools that you can find and download here \url{http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation}.
Now you have your segmentations ready (they are grey-level images called, let's say, tract\_greylevel.nii.gz), a few preprocessing steps are needed before building the cm-rep. These use convert3D.
The main goal is to obtain a levelset image from the grey level segmentation. As stated in \url{http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Documentation}/ section {\it levelset n\_iter}, creating a levelset segmentation requires a speed function and an initialization function. The adapted commands are as follows (the recommended parameters are indicated here)
\begin{enumerate}
\item Convert the grey level segmentation into a binary image: \\ 
c3d tract\_greylevel.nii.gz -threshold 0.5 inf 1.0 0.0 -o tract\_binary.nii.gz (see note at the bottom of this paragraph)
\item Generate the speed function\\
c3d tract\_binary.nii.gz -shift -0.1 -o tract\_speed.nii.gz
\item Generate the initialization function\\
c3d tract\_binary.nii.gz -threshold 0.25 inf -0.5 0.5 -o tract\_init.nii.gz 
\item Produce the levelset function\\
c3d tract\_speed.nii.gz tract\_init.nii.gz -levelset-curvature 0.02 -levelset 100 -o tract\_levelset.nii.gz
\end{enumerate}
 

 
Note: In some cases, especially for the CST, the filtering step is not enough to delineate the portion of the structure that is sheet-like. Consequently, I strongly suggest
to act on the binary structure once it is created in the first step (i.e., step that converts the grey level segmentation into a binary image). At this point, you can open the binary  
image in ITK-SNAP (opening it as the image and as the segmentation is fine). Go to the 3D window $\rightarrow$ click update mesh $\rightarrow$ click 3D scalpel tool in the 3D Toolbox $\rightarrow$ Change the label number to clear label in the Segmentation options and cut the stem of the CST $\rightarrow$ Accept and update mesh. Save the new segmentation.

\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=9cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/img_binary}
    \label{fig5}
\caption{An example of initial binary files for the cortico-spinal tract. In the bottom image, the stem was cut. The middle and right column illustrate how these two binaries are transformed into skeletons and boundaries during the next steps (see paragraph \ref{Building the initial template -1}). Modeling the stem using the cmrep model would not be adapted.}
  \end{center}
\end{figure}
 
\section{Creating the Surface Representation- 2nd part- the Continuous medial representation}
\label{cmrep}
We are going to switch to and focus on the cmp-rep model properly speaking, and use the continuous medical rep tools only (\url{http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation}). The principle is to build the boundary and the corresponding skeleton for each tract
 
 
\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=5cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/boun_skel}
    \label{fig4}
\caption{{\it Left:} An example of initial boundary for the corpus callosum - {\it Right:} the corresponding skeleton}
  \end{center}
\end{figure}
 
\subsection{Building the initial template -1}
\label{Building the initial template -1}

\begin{enumerate}
\item vtklevelset tract\_levelset.nii.gz tract\_boundary.vtk 0.0 \\(the last and only parameter is the threshold value. The higher the value, the slimmer the boundary)
\item cmrep\_vskel -Q /PATH\_TO\_QVORONOI/qvoronoi -p {\it p} -e {\it e} -q {\it q} tract\_boundary.vtk tract\_skel.vtk \\
The main factor here is the pruning factor {\it p}. If $p=0$, there is no pruning at all and the skeleton is very rough. The point when it starts making a difference is when $p=1$. For the thinnest structures, it is advice to choose $p=1.3$ or $1.4$. For the structures that contains less detail, $p=1.8$ to $p=2$ might be a good estimate. Modifying $p$ gives reasonable results for most of the tracts, however, some issues might happen when the tracts are at the limit of being sheet-like. At this point, you can also tweak the parameter $e$ that is the minimal number of mesh edges separating two generator points of a VD face for it to be considered. The last parameter, $q$ is the number of bins in each dimension. It defines the speed with which the program runs. A good value is $q=20-50$. Reducing $q$ reduces the number of vertices in the skeleton. For more information on each of the parameters and additional ones, you can type the command cmrep\_vskel on the command line.
\end{enumerate}

\subsection{Building the initial template -2}
The next action is to build the true initial template, the one that will serve as an input in the final optimization. This is done with a matlab function, called tempinit.m.
This function calls a few other ones, such as vtk\_polydata\_read.m, vtk\_get\_point\_data.m as well as a package written by Kilian Weinberger that you can find here (\url{http://www.cse.wustl.edu/~kilian/code/code.html}). tempinit uses this maximum variable unfolding (MVU) algorithm, the general purpose of which is to reduce dimensionality.
This function also depends on a library called Csdp, which you can download here \url{https://projects.coin-or.org/Csdp/}. This library contains an executable (found in /bin/csdp), a copy of which should be put in the user's bin directory of the machine where you are running tempinit. The same applies to the c function called triangle \url{http://www.cs.cmu.edu/~quake/triangle.html}. Once compiled, the executable should similarly go to your local bin directory.
For more information about the different parameters of this matlab function, you can have a look at the .m file located in the example directory, where defaults and explanations are given for each of them.
This program should output two files: medialtemplate.cmrep and medialtemplate.vtk, which are be the starting point for the very last step.
 
 
\subsection{Building the initial template -3}
The very last step of this process uses the function cmrep\_fit from the cm-rep package that we previously installed.
Its inputs consist of the medialtemlate.cmrep files obtained above, the binary image as well as a parameter file and the output directory.

\begin{center}
cmrep\_fit param.txt medialtemplate.cmrep tract\_binary.nii.gz cmrep\_output/
\end{center}
The explanation for most of the parameters can be found in \url{http://www.itksnap.org/pmwiki/pmwiki.php?n=CMREP.Documentation}.
The first part of this parameter file contains the default parameters that control the values that you will see appearing on your terminal after launching this command (see Figure 6 and
the param\_output.txt in the demo folder provided with this tutorial). A few important facts should be retained. During the different iterations
you should control that the TOTAL (see Figure 6) is decreasing. Each of the values VOLOV to BNDTRI contribute to this TOTAL and are driven by the default parameters.
So you can adjust them by modifying the term weights of the parameter file.
\begin{itemize}
\item VOLOV translates the overlap between the model that is iteratively made and the binary
\item BNDJAC is driven by DefaultParameters.BoundaryJacobianEnergyTerm.Weight, \\
DefaultParameters.BoundaryJacobianEnergyTerm.PenaltyA and\\
DefaultParameters.BoundaryJacobianEnergyTerm.PenaltyB
\item GRAD-R corresponds to DefaultParameters.BoundaryGradRPenaltyTerm.Weight
\item RADIUS to DefaultParameters.RadiusPenaltyTerm.Weight
\item LOOPTN to DefaultParameters.LoopTangentSchemeValidityPenaltyTerm.Weight
\item MEDTRI and BNDTRI express the quality of the triangulation, hence how much your model deform

\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=3cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/default_iteration}
    \label{fig6}
\caption{Example of output after submitting the cmrep\_fit command. The total value decreases and each of the terms VOLOV to BNDTRI contribute to this decrease.}
  \end{center}
\end{figure}
 
The second part of the parameter file controls each step of the run, from the alignment stage (translation and rotation) to the deformation stage (fitting of the model). All the parameters are straightforward to
understand and thus to modify. One comment could be done about the blurring parameter, which can be tuned down if there are some finer structures to be preserved in the tract.
 

\begin{figure}[!h]
  \begin{center}
      \includegraphics[height=7cm] {/Users/caroline/work/DT-ITK/atlas_construction/documentation/work_flow}
    \label{fig7}
\caption{Pipeline illustrated on the CST}
  \end{center}
\end{figure}
 

 
\subsection{Checking your template}
In order to check the accuracy of the template, it is worth comparing it to the original binary file, through a Dice overlap for instance.
cmrep can be used to generate a binary file from the def3.med.vtk (cmrep\_fillmesh def3.med.vtk ref.nii.gz def3.nii.gz)
ref.nii.gz can be the binary image itself.
The binary def3.nii.gz obtained from the information of the medial representation is then compared to the initial binary model through
c3d -verbose def3.nii.gz tract\_binary.nii.gz -overlap 1 (if the foreground of the binary image is 1).

Such an atlas was already created using an aging population (65-83 yo) obtained from the ixi database (see in the example folder). This study was published in \cite{zhang2009}. Another one is in the process  of being created. The underlying database is the same but we selected subjects belonging to an adult population from age 18 to 60.
 

!!Creating the Surface Representation- 1st part- starting with DTI-TK}

\\Other factors can be added, such as 
\begin{itemize}
\item `-label' (default 1) - to be modified if the label of the seed (i.e., the white matter mask) is not 1
\item `-minFA' (default: 0.15) and `-maxAngle' (default: 45) which are stopping criteria
\item `-stepSize' (default: 0.5 mm)
\item  `-upsample' (default 1). This number can be changed when using DTIs with very low resolution. To get denser tracts, the value can be set to 2 (or other puissance of 2). It inserts additional point within a voxel.
\end{itemize}
\end{itemize}
 
\subsection{First Step: delineating the fibers corresponding to each tract}
\label{first_step}
If you are not familiar with brain white matter tracts in general, you can gather some information in \cite{mori2002}. This paper

The first task is to build a whole brain white matter atlas (see [[Documentation.HomePage|tutorial page]]. If you are already familiar with DTI-TK, you can skip the first points of the tutorial and directly go to [[Documentation.Registration|''Registration and Spatial normalization of DTI volumes'']].
At the end of this, you will have created a white matter template (see Figure 1), which is necessary to build the tract specific template.
 

!!{Main Goal
Now the whole brain DT atlas has been created from your population, the main point is to
delineate the tracts of interest and then create a medial (surface-based) representation for each one.
As of December 2010, these tracts of interest that have been considered so far are 
\begin{itemize}
\item the corpus callosum (CC)
\item the inferior longitudinal fasciculus (ILF)
\item the uncinate fasciculus (UNC)
\item the superior longitudinal fasciculus (SLF)
\item the cortico-spinal tract (CST)
\item the inferior fronto-occipital fasciculus (IFO)
\end{itemize}
 
Such an atlas was already created using an aging population (65-83 yo) obtained from the ixi database (see in the example folder). This study was published
in \cite{zhang2009}. Another one is in the process of being created. The underlying database is the same but we selected 
subjects belonging to an adult population from age 18 to 60.
 
Following the generation of this template, several applications are possible, such as the detection of white matter
differences between two populations in these particular tracts (an example is in the aforementioned Zhang paper, where
WM changes are identified between ALS and healthy subjects, based on the fractional anisotropy measure) or such as
longitudinal studies.
 
 
\section{Creating the Surface Representation- 1st part- starting with DTI-TK}
\subsection{What to start with?}
\label{prelim}