uTIlzReg is for research purposes only and has not been approved for clinical use.
uTIlzReg_GeoShoot is a program to perform geodesic shooting LDDMM registration between 2D/3D images.
Its main goal is to compare images with initial momenta.
The computations of uTIlzReg_GeoShoot are done in the source (= template) image coordinate system.
Geodesic shooting algorithm: Vialard F.X., Risser L., Rueckert D., Cotter C.J.: Diffeomorphic 3D Image Registration via Geodesic Shooting using an Efficient Adjoint Calculation. International Journal of Computer Vision, 2011
Multi-kernel registration: Risser L., Vialard F.X., Wolz R., Murgasova M., Holm D., Rueckert D., ADNI: Simultaneous Multiscale Registration using Large Deformation Diffeomorphic Metric Mapping. IEEE Transactions on Medical Imaging 30(10); 2011
Calling the function:
./uTIlzReg_GeoShoot [Source] [Target] <options>
where [Source] and [Target] are the source (moving/template) and target (fixed) images, and <options> are obviously the options.
<-iterations n> Number of iterations of the gradient descent (default n=10 but more iterations are often necessary)
<-subdivisions n> Number of time subdivisons between t=0 and t=1 (default n=10. If a message says that the CFL condition is not respected, it is better to increase the subdivisions number)
<-UnderSampleTpl n> Undersample the source/template image with a factor n (default n=1). All the computations are done in the template image space. Undersampling it allows to strongly speed up the computations at the expense of the registration accuracy (see multiresolution registration, at the bottom of this page, for a wise use of -UnderSampleTpl).
<-alpha n> Weight between the similarity energy and the deformation energy (default n=0.001)
Kernels in millimeters (Default: -Gauss 3):
<-Gauss n> Gaussian kernel of standard deviation S (n = S)
<-M_Gauss n> Sum of up to 7 Gaussian kernels (n = k W1 S1 ... Wk Sk , where k=[#kernels], W.=weight, S.=Sigma)
<-M_Gauss_easier n> Sum of 7 Gaussian kernels with linearly sampled standard deviations (assimilated to scales) and roughly similar deformation magnitudes at all scales. (n = Smax Smin , where Smax Smin are the maximum and minimum standard deviations in mm).
For the comparison of two natural images, we recommand to use this option with Smax similar to the spatial extent of the largest features to deform and Smin equals to the image resolution.
The weights and std dev will be shown at the beginning of the computations. When statistics are done from a template to several targets using initial momenta,
we however strongly recommend to use -M_Gauss with the same multi-kernel all the time. Typical parameters shown using the option -M_Gauss_easier can be used for instance.
Inputs (default: nothing):
<-PrefixInputs n> Prefix of the file containing the initial momentum (default="Null"). The initial momentum will be rescaled to the template image size if their sizes are different.
<-InputInitMomentum n> Initial Momentum to initiate the gradient descent (default="Null"). The initial momentum will be rescaled to the template image size if their sizes are different.
<-InputIniMoTxt n> Initial Momentum in an ascii file (instead of nifti) (default="Null")
<-affineT n> Affine transformation from the Target to the Template in the world domain. The 4*3 parameters are: r_xx r_xy r_xz t_x r_yx ... t_z
<-affineT_txt n> Affine transformation from the Target to the Template in the world domain. The 4*4 matrix (with 0 0 0 1 on the last row) is an ascii text file.
Outputs (default: initial momentum in a nifti file):
<-PrefixOutputs n> Prefix of the output files (default="Outputs")
<-OutFinalDef> Outputs the deformed template (Nothing by default)
<-OutDispField> Outputs the displacement field in mm (Nothing by default)
<-OutIniMoTxt n> Outputs the initial momentum in an ascii file (Nothing by default)
<-OutVeloField> Outputs the 3D+t velocity field in voxels (Nothing by default)
<-OutDistEnSim> Outputs the distance, enrgy and similarity measure (Nothing by default)
<-OutDeformation> Outputs the 3D+t deformation (Nothing by default)
<-MaxVeloUpdt n> Size of the maximum updates of the vector field (Default=0.5 voxels)
<-indicatorLimiter n> UpWind -> 0, MinMod -> 1 (default), SuperBee -> 2
<-indicatorRungeKutta n> Euler -> 0 (default), Runge-Kutta -> 1
<-margins n> Margin of the image where the calculations are reduced (default=3 voxels)
<-GreyLevAlign n> Grey level linear alignment of each channel -- n = [Padding Src] [Padding Trg]
Multiresolution (and not only multiscale which refers to the different kernel scales/standard deviatios here)
can be performed thanks to the options -PrefixOutputs, -PrefixInputs and -UnderSampleTpl.
To register an image template.nii on an image target.nii at 3 resolutions, use for instance:
uTIlzReg_GeoShoot template.nii target.nii -UnderSampleTpl 4 -PrefixOutputs out
uTIlzReg_GeoShoot template.nii target.nii -UnderSampleTpl 2 -PrefixOutputs out -PrefixInputs out
uTIlzReg_GeoShoot template.nii target.nii -UnderSampleTpl 1 -PrefixOutputs out -PrefixInputs out
or (with typical options):
uTIlzReg_GeoShoot template.nii target.nii -Gauss 10 -iterations 50 -UnderSampleTpl 4 -PrefixOutputs out
uTIlzReg_GeoShoot template.nii target.nii -Gauss 10 -iterations 20 -UnderSampleTpl 2 -PrefixOutputs out -PrefixInputs out
uTIlzReg_GeoShoot template.nii target.nii -Gauss 10 -iterations 10 -OutFinalDef -OutDispField -PrefixOutputs out -PrefixInputs out