Difference between revisions of "Reg f3d"

Fast Free-Form Deformation algorithm for non-rigid registration.
This implementation is a re-factoring of Daniel Rueckert' 99 TMI work.
The code is presented in Modat et al., "Fast Free-Form Deformation using
graphics processing units", CMPB, 2010
Cubic B-Spline are used to deform a source image in order to optimise a objective function
based on the Normalised Mutual Information and a penalty term. The penalty term could
be either the bending energy or the squared Jacobian determinant log.
This code has been written by Marc Modat (m.modat@ucl.ac.uk), for any comment,
please contact him.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Usage:	reg_f3d -ref <filename> -flo <filename> [OPTIONS].
	-ref <filename>	Filename of the reference image (mandatory)
	-flo <filename>	Filename of the floating image (mandatory)

***************
*** OPTIONS ***
***************
*** Initial transformation options (One option will be considered):
	-aff <filename>		Filename which contains an affine transformation (Affine*Reference=Floating)
	-incpp <filename>	Filename ofloatf control point grid input
				The coarse spacing is defined by this file.

*** Output options:
	-cpp <filename>		Filename of control point grid [outputCPP.nii]
	-res <filename> 	Filename of the resampled image [outputResult.nii]

*** Input image options:
	-rmask <filename>		Filename of a mask image in the reference space
	-smooR <float>			Smooth the reference image using the specified sigma (mm) [0]
	-smooF <float>			Smooth the floating image using the specified sigma (mm) [0]
	--rLwTh <float>			Lower threshold to apply to the reference image intensities [none]. Identical value for every timepoint.*
	--rUpTh <float>			Upper threshold to apply to the reference image intensities [none]. Identical value for every timepoint.*
	--fLwTh <float>			Lower threshold to apply to the floating image intensities [none]. Identical value for every timepoint.*
	--fUpTh <float>			Upper threshold to apply to the floating image intensities [none]. Identical value for every timepoint.*
	-rLwTh <timepoint> <float>	Lower threshold to apply to the reference image intensities [none]*
	-rUpTh <timepoint> <float>	Upper threshold to apply to the reference image intensities [none]*
	-fLwTh <timepoint> <float>	Lower threshold to apply to the floating image intensities [none]*
	-fUpTh <timepoint> <float>	Upper threshold to apply to the floating image intensities [none]*
	* The scl_slope and scl_inter from the nifti header are taken into account for the thresholds

*** Spline options:
	-sx <float>		Final grid spacing along the x axis in mm (in voxel if negative value) [5 voxels]
	-sy <float>		Final grid spacing along the y axis in mm (in voxel if negative value) [sx value]
	-sz <float>		Final grid spacing along the z axis in mm (in voxel if negative value) [sx value]

*** Regularisation options:
	-be <float>		Weight of the bending energy penalty term [0.005]
	-le <float> <float>	Weights of linear elasticity penalty term [0.0 0.0]
	-l2 <float>		Weights of L2 norm displacement penalty term [0.0]
	-jl <float>		Weight of log of the Jacobian determinant penalty term [0.0]
	-noAppJL		To not approximate the JL value only at the control point position

*** Measure of similarity options:
*** NMI with 64 bins is used expect if specified otherwise
	--nmi			NMI. Used NMI even when one or several other measures are specified.
	--rbn <int>		NMI. Number of bin to use for the reference image histogram. Identical value for every timepoint.
	--fbn <int>		NMI. Number of bin to use for the floating image histogram. Identical value for every timepoint.
	-rbn <tp> <int>		NMI. Number of bin to use for the reference image histogram for the specified time point.
	-rbn <tp> <int>		NMI. Number of bin to use for the floating image histogram for the specified time point.
	--lncc <float>		LNCC. Standard deviation of the Gaussian kernel. Identical value for every timepoint
	-lncc <tp> <float>	LNCC. Standard deviation of the Gaussian kernel for the specified timepoint
	--ssd			SSD. Used for all time points
	-ssd <tp>		SSD. Used for the specified timepoint
	--kld			KLD. Used for all time points
	-kld <tp>		KLD. Used for the specified timepoint
	* For the Kullback–Leibler divergence, reference and floating are expected to be probabilities
	-amc			To use the additive NMI for multichannel data (bivariate NMI by default)

*** Optimisation options:
	-maxit <int>		Maximal number of iteration per level [300]
	-ln <int>		Number of level to perform [3]
	-lp <int>		Only perform the first levels [ln]
	-nopy			Do not use a pyramidal approach
	-noConj			To not use the conjuage gradient optimisation but a simple gradient ascent
	-pert <int>		To add perturbation step(s) after each optimisation scheme

*** F3D2 options:
	-vel 			Use a velocity field integration to generate the deformation
	-fmask <filename>	Filename of a mask image in the floating space

*** OpenMP-related options:
	-omp <int>		Number of thread to use with OpenMP. [8]

*** GPU-related options:
	-mem			Display an approximate memory requierment and exit
	-gpu 			To use the GPU implementation [no]

*** Other options:
	-smoothGrad <float>	To smooth the metric derivative (in mm) [0]
	-pad <float>		Padding value [nan]
	-voff			To turn verbose off

	--version		Print current source code git hash key and exit
				(3d24c3580a0cd227f30540578b3f84eca9d01e4a)
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
For further description of the penalty term, use: reg_f3d -helpPenalty
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *