Modules:ResampleScalarVectorDWIVolume-Documentation-3.6

Return to Slicer 3.6 Documentation

Gallery of New Features

Resample Scalar/Vector/DWI Volume

Module with panels expanded

Original Image [1]

Transformed Image

General Information

Module Type & Category

Type: CLI

Category: Filtering

Authors, Collaborators & Contact

• Francois Budin, NIRAL
• Sylvain Bouix, PNL
• Contact: Ryan Eckbo, PNL, reckbo[at]bwh[dot]harvard[dot]edu

Module Description

Resampling consists in applying a transformation to an image, usually to align it with other images to be able to compare them. This module implements image and vector-image resampling through the use of ITK Transforms. It supports any transform that is implemented in ITK (rigid, affine, non-rigid such as BSpline, etc). It can also handle diffusion weighted MRI image resampling. 'Resampling' is performed in space coordinates, not pixel/grid coordinates. It is quite important to ensure that image spacing is properly set on the images involved. The interpolator is required since the mapping from one space to the other will often require evaluation of the intensity of the image at non-grid positions.

Usage

Examples, Use Cases & Tutorials

• This module is especially appropriate when one needs to resample an image and already knows the transform to apply to it. Its principal advantages resides in the fact that one can apply any kind of transform supported by ITK (rigid, affine and non-rigid) and can choose between the most commonly used interpolators.
• The transform can be passed as an ITK Transform file using the command line, or directly as a transform node in Slicer3. In the latter case, the transform can only be rigid or affine.
• It also allows changing the spacing, the orientation, the size and the origin of the image.
• Be careful when applying multiple transforms contained in one file. Pay attention to the order of the transforms in the file. You may also not obtain the same result as other tools would give you. For example, if you register two images using BRAINSFit using an affine and a BSpline transform simultaneously, the output file will contain two transforms. However these two transforms are actually two components of the same transform and should be applied simultaneously. Resample Scalar/Vector/DWI Volume only applies transforms serially. You should therefore not use Resample Scalar/Vector/DWI Volume in this case.

Quick Tour of Features and Use

• Input/Output: Defines input and output files.
  • Input volume is the volume to resample. It can be either a scalar, a vector or a DW image. Be Careful: This module cannot resample DTI, use ResampleDTI instead
  • Reference Volume (optional) is the volume used to set the sampling parameters (origin, spacing, orientation and dimensions). If it is not set, the input volume will be taken for reference.
  • Output volume is the name of the output.
• Deformation Field: Allows the user to transform the input image using a deformation field. The deformation field is applied last in the case other transforms are given.
  • Displacement or H- field sets the type of deformation field. An H-field contains at each voxel the position in space of the transformed point. The displacement field contains at each voxel the displacement vector to apply to this point.
  • Deformation Field Volume sets the deformation field. It should be a 3-Dimensional vector image. Vectors should be of dimension 3.
• Resampling Parameters: Sets the number of threads used to perform the resampling.
• Transform Parameters:
  • Transform Node contains the transform(s) to apply to the image
  • Bulk Transform allows you, in the case the transform file contains an initialization transform and a BSpline transform, to specify that the initialization transform is part of the BSpline transform. This is, for example, to be used if your transform was computed with BRAINSFit or Deformable BSpline Registration. This option only works if the BSpline transform is of order 3 (restriction due to the templated implementation of ITK).
  • Transforms Order allows the user to tell the module in what order the transforms are stored in the node (or file). Transforms should be backward (from output space to input space). However, in Slicer3, the affine and rigid transform nodes are stored as forward transforms and are inverted when passed to the module.

Input Image <- Transform0 <- Transform1 <- ... <- Transform n <- Output Image (input-to-output)
Input Image <- Transform n <- Transform n-1 <- ... <- Transform0 <- Output Image (output-to-input)

• Manual Transform: if no tranform is set in previous panel, one can enter his own transform
  • Transform Matrix: a 12-parameter affine transformation manually. The first 9 numbers represent a linear transformation matrix in column-major order (where the column index varies the fastest), the last 3 are a translation.
  • Transform: forces the transform to be of rigid or affine type (affine is default)
  • Space: It should normally not be modified when using this module directly in Slicer3 with a transform node. It does not specify whether the matrix is expressed in LPS or RAS coordinate space but rather if everything is expressed in the same coordinate space. LPS means that everything is in the same space and RAS means that it is not the case. This option can be set to RAS if the given transform is in RAS coordinate space (respectively LPS) and the input volume is in LPS coordinate space (respectively RAS). Be careful: When passing manually the transform, the coordinate space modification is directly applied on the given transform. However, when passing the transform through a file or a transform node, it is the input volume coordinate space that is modified and the transform is left unchanged (so that any kind of transform supported by ITK is also supported by this module). If one sets the output volume parameters manually, one has to pay attention to the fact that in that case the given parameters are considered to be in the transform coordinate space!!!
• Rigid/Affine Parameters:
  • Rotation Point: uses a fiducial to set a point around which the rotation defined in the transform needs to be performed.
  • Centered Transform: sets the center of the transformation to the center of the input image.
  • Inverse ITK Transformation: inverses the transformation before applying it to the image. The transform given to the module is from the output image to the input one. If one wants to specify a transform from the input image to the output image, one should use this flag. This option can only be used if the transform is rigid or affine.
• Interpolation Type: sets the type of interpolation kernel to either linear, nearest neighbor (nn), windowed sinc (ws), or b-spline (bs).
• Windowed Sinc Interpolate Function Parameters: selects the type window function for the sinc interpolation h=hamming, c=cosine, w=welch, l=lanczos, b=blackman. This is only relevant if one selects ws as the interpolation type.
• BSpline Interpolate Function Parameters: The spline order (only relevant if the selected interpolator is bs).
• Output Parameters: One can overwrite the reference volume parameters by setting manually the spacing, size, origin (as a fiducial), and direction matrix (also known as space directions) in column-major order.

Development

Dependencies

The module uses some source code present in the ResampleDTI module repository.

Known bugs

Follow this link to the Slicer3 bug tracker.

Usability issues

Follow this link to the Slicer3 bug tracker. Please select the usability issue category when browsing or contributing.

Source code & documentation

Source code:

• ResampleVolume2.cxx
• ResampleVolume2.xml

Source code from ResampleDTI used in this module too:

• itkWarpTransform3D.h
• itkWarpTransform3D.txx
• itkTransformDeformationFieldFilter.h
• itkTransformDeformationFieldFilter.txx
• deformationfieldio.h
• deformationfieldio.cxx
• dtitypes.h
• itkHFieldToDeformationFieldImageFilter.h
• itkHFieldToDeformationFieldImageFilter.txx

Doxygen documentation:

• WarpTransform3D
• TransformDeformationFieldFilter
• HFieldToDeformationFieldImageFilter

More Information

When Using the module in command line

• Warning : When using this module in Microsoft Windows, the flag -c which centers the transform might cause problems. Please use the long flag --centered_transform instead in that case.
• The Transform can be given through an ITK Transform file. An example is given below.

#Insight Transform File V1.0
# Transform 0
Transform: AffineTransform_double_3_3
Parameters: 1.73205080756880 0.5 0 -0.5 .8660254037844 0 0 0 1.5 15 32 27
FixedParameters: 40 35 20

• Be Careful : The transform file must have an empty line after the fixed parameters
• The Fixed Parameters are the coordinates of the center of rotation
• The Parameters are written in the following format:
  • The first 9 numbers represent a linear transformation matrix in column-major order (where the column index varies the fastest)
  • The last 3 are a translation.
• A transform file may contain multiple transforms. The transforms are all merged together before being applied to the image. Therefore the interpolation operation is performed only once per voxel which improves the quality of the output image compared to applying each transform separatly.

Acknowledgment

This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on the National Centers for Biomedical Computing can be obtained from http://nihroadmap.nih.gov/bioinformatics.

References

ITK software guide. Sections "6.9 Geometric Transformations", "8.8 Transforms" and "8.9 Interpolators".

[1] BrainWeb: Simulated Brain Database