Skip to content

executable

Jump to bottom
Marc Modat edited this page Jul 10, 2023 · 6 revisions

Table of Content

RegAladin

Executable name reg_aladin

Scope: Run pairwise rigid or affine registration. The approach relies on a block matching approach following the algorithm of Ourselin et al.. The symmetric appoach is described in Modat et al..

As minimum requirement, a reference image $R$ and floating image $F$ in Nifti file format are to be specified, as follow:

reg_aladin -ref <input_ref_file> -flo <input_flo_file>

An affine transformation $A$ that maps a coordinate $x$ in the reference image to a position $x'$ in the floating image, such that $x \circ A = x'$. The transformation can then be used to resampling the floating image $F$ into the space of the reference image $R$ so that $F \circ A$ and $R$ are aligned in voxel space. By default, the affine matrix will be save in the current working directory as outputAffine.txt and the deformed floating image as outputResult.nii.gz. Those filenames can be specified by the user using the flag -aff and -res respectively.

Using the flag -help can be used to list all the available options without running any registration.

The list of option is:

-ref <filename> This is mandatory flag used to specify the reference image in Nifti format. Note that reference can also be called Fixed or Target in the litterature.

-flo <filename> This is mandatory flag used to specify the floating image in Nifti format. Note that floating can also be called Moving or Source in the litterature.

-noSym By default, the symmetric version of the algorithm is used by default. The symmetric version ensures that the output transformation is not impacted by the input image order. Internally, it optimise the transformation from $R$ to $F$ and from $F$ to $R$ concurrently while ensuring both transformations are the inverse of each other. Use this flag to disable it.

-rigOnly Use this flag to run a rigid registration only. By default, an initiale rigid step is used before an affine transformation is optimised.

-affDirect Use this flag to directly optimize a 12 DoF affine. By default a rigid step is optimise prior to running an affine transformation.

-aff <filename> Filename which contains the output affine transformation. The matrix is simply stored as a 4-by-4 matrix in a text file. The default value is outputAffine.txt. More information about how the transformation is used can be found on the transformation page.

-inaff <filename> This flag is used to specify an affine transformation to initialise the current optimisation. By default, the geometrical centre of the images are aligned.

-rmask <filename> This flag is used to specify a mask in the reference image space. The mask should have the same dimension as the reference image. The input reference image will not be multiply by the mask to avoid creating a strong contrast at the boundary but instead only voxel within the foreground of the mask will be considered for the optimisation. All values different from 0 will be considered as foreground.

-fmask <filename> This flag is used to specify a mask in the floating image space. The mask should have the same dimension as the floating image. All values different from 0 will be considered as foreground. This mask is only used when the symmetric scheme is used.

-res <filename> Filename of the resampled image. The input floating image is resampled in the space of the reference image given the obtained transformation. Cubic interpolation is used. If not specified, the value is set to outputResult.nii.gz and is saved in the current working directory.

-maxit <int> This corresponds to the maximal number of iterations of the trimmed least square approach to perform per level. The default value is 5.

-ln <int> Number of levels to use to in the pyramidal coarse-to-fine approach. By default, this value is set to 3. This corresponds to first optimising the transformation on a twice-downsampled by a ratio of 2 images, then on images downsampled one and finally on the original input sizes. In the downsampled process, the resolution is floored at 32 pixels along each axis.

-lp <int> Number of levels to use to run the registration once the image pyramids have been created. The default value is set to the number of level set by -ln. For example, if one specifies -ln 3 -lp 2, only the first lower resolution of the pyramids will be used for optimisation and the last level (full resolution) will be skipped.

-smooR <float> Apply an Gaussian kernel smoothing to the reference image. The specified value corresponds to the standard devhttps://github.com/KCL-BMEIS/niftyreg.wiki.gitiation in mm of the Gaussian kernel to apply. If a negative value is specified, the Gaussian kernel standard deviation is specified in voxel rather than mm. The default value is 0.

-smooF <float> Apply an Gaussian kernel smoothing to the floating image. The specified value corresponds to the standard deviation in mm of the Gaussian kernel to apply. If a negative value is specified, the Gaussian kernel standard deviation is specified in voxel rather than mm. The default value is 0.

-refLowThr <float> A threshold is applied to the reference image. All values below the specified value are set to the threshold value. By default, no threshold is applied.

-refUpThr <float> An upper threshold is applied to the reference image. All values above the specified value are set to the threshold value. By default, no threshold is applied.

-floLowThr <float> A threshold is applied to the floating image. All values below the specified value are set to the threshold value. By default, no threshold is applied.

-floUpThr <float> An upper threshold is applied to the floating image. All values above the specified value are set to the threshold value. By default, no threshold is applied.

-pad <float> Specified the padding value to use during the resampling. By default NaN is used and the padded values are thus ignored during the optimisation.

-nac Specify to use the nifti header origin to initialise the transformation, in other words, the transformation is initialise with an identity matrix. nac stands for non-aligned-centres. Aligning the geometrical centres of the image is otherwise the default behaviour.

-comm Use the input masks centre of mass to initialise the transformation. comm stands for centre-of-mass-masks. Aligning the geometrical centres of the image is otherwise the default behaviour.

-comi Use the input images centre of mass to initialise the transformation. comm stands for centre-of-mass-images. Aligning the geometrical centres of the image is otherwise the default behaviour.

-interp Interpolation order to use internally during the optimisation to resample the floating image. By default, linear interpolation is used.

-iso Makes the floating and reference images isotropic as a pre-processing step. The deafult behaviour is to use the input image resolutions.

-pv <int> Percentage of blocks to use in the optimisation scheme. The default value is 50. The blocks are selected based on the standard deviation of their intensities. The blocks with the highest standard deviation are used.

-pi <int> Percentage of blocks to consider as inlier in the least-trimmed-sequare optimisation scheme. The default value is 50.

-speeeeed Only consider one block every two blocks along each axis. As a result, only 1/4 of the blocks are used in 2D and 1/8 in 3D. By default, all blocks are used.

-platf <uint> Specified the platform to use to run the program. Options are 0, 1 and 2 for CPU, CUDA, OpenCL respectively. By default, the CPU platform is used. Note that the code requires to be compiled with USE_CUDA and USE_OPENCL set to ON during the cmake configuration to use those platforms.

-gpuid <uint> When using a GPU paltform, CUDA or OpenCL, this is used to specified The index of the GPU which should be used. Please run reg_gpuinfo first to get platform information and their corresponding ids

-omp <int> Number of thread to use with OpenMP. By default, all available cores are used.

-voff Turns verbose off. By default, some information will be printed in the standard output stream.

--version Print the version of the executable and exit.

RegF3D

Executable name reg_f3d

Scope: Run pairwise non-linear registration

RegResample

Executable name reg_resample

Scope: Resample a floating image in the space of a reference image given a transformation file (generated by reg_aladin, reg_f3d or reg_transform).

Mandatory arguments are -ref and -flo to specify the reference and floating image filenames respectively. If no transformation is specified, an identity transformation is used.

Using the flag -help can be used to list all the available options without running any conversion.

The list of option is:

-ref <filename> Filename of the reference image.

-flo <filename> Filename of the floating image.

-trans <filename> Filename of the file containing the transformation parametrisation (from reg_aladin, reg_f3d or reg_transform)

-res <filename> Filename of the resampled floating image in the space of the reference image.

-blank <filename> Apply the transformation to a regular grid image with the same size and orientation as the floating image and save the warped image to the specified filename.

-inter <int> Interpolation order to use the resample the floatin image. The possible values are (0, 1, 3, 4) with (0=NN, 1=LIN; 3=CUB, 4=SINC). The default value is 3, that corresponds to cubic interpolation.

-pad <int> Padding value used to extrapolate outside of the floating image field of view. The default value is 0.

-tensor Force the last six timepoints of the floating image to be considered as a tensor with the timepoints corresponding to XX, XY, YY, XZ, YZ, ZZ. By default, all timepoints are considered independently as scalar.

-psf Perform the resampling in two steps to resample an image to a lower resolution by taking into account the point spread function. By default this is not used. More information about the implementation can be found in Cardoso, M.J., Modat, M., Vercauteren, T., Ourselin, S. (2015). Scale Factor Point Spread Function Matching: Beyond Aliasing in Image Resampling. In: Navab, N., Hornegger, J., Wells, W., Frangi, A. (eds) Medical Image Computing and Computer-Assisted Intervention -- MICCAI 2015. MICCAI 2015. Lecture Notes in Computer Science(), vol 9350. Springer, Cham. and on the version available on arxiv.

-psf_alg <0/1> Specify the type of algorithm used when estimating the point spread function. It can take the value 0 or 1, with 0: Minimise the matrix metric (0) and the determinant (1). By default, the method 0 is used.

-voff Use this flag to turn verbose off. By default, some information will be printed in the standard output stream.

-omp <int> Number of thread to use with OpenMP. By default, all available cores are used.

--version Print the version of the executable and exit.

RegTransform

Executable name reg_transform

Scope: Convert transformation file from one type to another, e.g. deformation field, displacement field, velocity field, ... It also enables to invert, half a transformation or compose two transformations.

NiftyReg relies on several means of encoding transformations. You can read more details about the different transformation parametrisation on the dedicated transformation page. The list of sopported transformation type is:

  • cubic B-Spline parametrised grid (reference image is required)
  • a dense deformation field
  • a dense displacement field
  • a cubic B-Spline parametrised stationary velocity field (reference image is required)
  • a stationary velocity deformation field
  • a stationary velocity displacement field
  • an affine matrix

Using the flag -help can be used to list all the available options without running any conversion.

The list of option is:

-ref <filename> This is used to specify the reference space in which the transformation has to be discretised. This option is required when an affine or a cubic B-Spline parametrised control point grid is used. For dense field (deformation, displacement, flow, ...) the dimension and space of the field is used.

-ref2 <filename> This is similar to the -ref option above but is used when a second transformation is specified when dealing with composition or two transformation.

-def <filename1> <filename2> Take a transformation of any recognised type and compute the corresponding deformation field.

  • filename1 - Input transformation file name (associated with -ref if required)
  • filename2 - Output deformation field file name

-disp <filename1> <filename2> Take a transformation of any recognised type and compute the corresponding displacement field.

  • filename1 - Input transformation file name (associated with -ref if required)
  • filename2 - Output displacement field file name

-flow <filename1> <filename2> Take a spline parametrised SVF and compute the corresponding flow field.

  • filename1 - Input transformation file name (associated with -ref if required)
  • filename2 - Output flow field file name

-comp <filename1> <filename2> <filename3> Compose two transformations of any recognised type and returns a deformation field such that Trans3(x) = Trans2(Trans1(x)).

  • filename1 - Input transformation 1 file name (Trans1) (associated with -ref if required)
  • filename2 - Input transformation 2 file name (Trans2) (associated with -ref2 if required)
  • filename3 - Output deformation field file name (Trans3)

-land <filename1> <filename2> <filename3> Apply a transformation to a set of landmark(s). Landmarks are encoded in a text file with one landmark position in mm per line:

  • key1_x key1_y key1_z
  • key2_x key2_y key2_z
  • ...

In the example of a 3D case. The expected inputs are:

  • filename1 - Input transformation ($T$) file name
  • filename2 - Input landmark file ($\vec{x}$) name.
  • filename3 - Output landmark file ($T(\vec{x})$) name

-updSform <filename1> <filename2> <filename3> Update the sform of an image using an affine transformation.

  • filename1 - Input image to be updated
  • filename2 - Affine transformation defined as Affine x Reference = Floating
  • filename3 - Updated image.

-invAff <filename1> <filename2> Invert an affine matrix.

  • filename1 - Input affine transformation file name.
  • filename2 - Output inverted affine transformation file name

-invNrr <filename1> <filename2> <filename3> Invert a non-rigid transformation and save the result as a deformation field.

  • filename1 - Input transformation file name
  • filename2 - Input floating image where the inverted transformation will be discretised
  • filename3 - Output inverted transformation file name

Note that the cubic b-spline grid parametrisations can not be inverted without approximation, as a result, they are converted into deformation fields before inversion.

-half <filename1> <filename2> The input transformation is halfed and stored using the same transformation type.

  • filename1 - Input transformation file name
  • filename2 - Output transformation file name

-makeAff <rx> <ry> <rz> <tx> <ty> <tz> <sx> <sy> <$sz> <shx> <shy> <shz> <outputFilename> Create an affine transformation matrix

  • rx - Rotation along the x axis
  • ry - Rotation along the y axis
  • rz - Rotation along the z axis
  • tx - Translation along the x axis
  • ty - Translation along the y axis
  • tz - Translation along the z axis
  • sx - Scaling along the x axis
  • sy - Scaling along the y axis
  • sz - Scaling along the z axis
  • shx - Shearing along the x axis
  • shy - Shearing along the y axis
  • shz - Shearing along the z axis
  • outputFilename - Ouput affine transformation matrix filename

-aff2rig <filename1> <filename2> Extract the closest rigid transformation from an affine transformation matrix.

  • filename1 - Input transformation file name
  • filename2 - Output transformation file name

-flirtAff2NR <filename1> <filename2> <filename3> <filename4> Convert a flirt (FSL) affine transformation to a NiftyReg affine transformation.

  • filename1 - Input FLIRT (FSL) affine transformation file name
  • filename2 - Image used as a reference (-ref arg in FLIRT)
  • filename3 - Image used as a floating (-in arg in FLIRT)
  • filename4 - Output affine transformation file name

-omp <int> Number of thread to use with OpenMP. By default, all available cores are used.

--version Print the version of the executable and exit.

RegJacobian

Executable name reg_jacobian

Scope: Given a transformation file, it generates Jacobian determinant or Jacobian matrix images.

Using the flag -help can be used to list all the available options without running any conversion.

The list of option is:

-trans <filename> Input transformation file (generated by reg_f3d or reg_transform). This input argument is mandatory.

-ref <filename> Input filename of the reference image that will be used to discretise the output image. This argument is only required if the transformation is a control point grid based parametrisation. If a deformation or displacement field is specified as input transformation (-trans), the Jacobian output is discretised in the space of the field.

-jac <filename> Output filename of the Jacobian determinant map to generate. First compute the Jacobian matrix at every voxel location and save its determinant. A Jacobian determinant value greater than 1 indicates an expansion of the voxel size from the reference to the floating image, a value lower than 1 but greater than 0 indicates a compression and a value equal to 1 indicates no voxel volume change. A negative value indicates that the voxel dissapeared and thus that the topology of the input object has been broken.

-jacL <filename> Output filename of the Log of the Jacobian determinant map to generate. Same as jac except the Log of the determinant is saved.

-jacM <filename> Output filename of the Jacobian matrix map to generate (9 or 4 values are stored as a 5D nifti in 3D and 2D respectively). One matrix is computed per voxel.

-omp <int> Number of thread to use with OpenMP. By default, all available cores are used.

--version Print the version of the executable and exit.

RegAverage

Executable name reg_average

Scope: Compute average of images or affine matrices. If transformation files are specified, the input images are averaged in an average geometrical space (e.g. log-Euclidean).

RegMeasure

Executable name reg_measure

Scope: Compute similarity measure values between two input images. Note that the floating image is resampled in the space of the reference image prior to any computation.

RegTools

Executable name reg_tools

Scope: Set of operations on images that did not fit in the previous executable

RegGPUInfo

Executable name reg_gpuinfo

Scope: Display information about the GPU on the current computer. Note that this executable is compiled when CUDA or OpenCL are activated.

Clone this wiki locally