Monday, May 18, 2015

resampling images with wb_command -volume-affine-resample

I often need to resample images without performing other calculations, for example, making a 3x3x3 mm voxel version of an anatomical image with 1x1x1 mm voxels for use as an underlay. This can be done with ImCalc in SPM, but that's a bit annoying, as it requires firing up SPM, and only outputs two-part NIfTI images (minor annoyances, but still).

The wb_command -volume-affine-resample program gets the resampling done at the command prompt with a single long command:

 wb_command -volume-affine-resample d:/temp/inImage.nii.gz d:/temp/affine.txt d:/temp/matchImage.nii CUBIC d:/temp/outImage.nii  

If the wb_command program isn't on the path, run this at the command prompt, from wherever wb_command.exe (or the equivalent for your platform) is installed. A lot of  things need to be specified:
  • inImage.nii.gz is the image you want to resample (for example, the 1x1x1 mm anatomical image)
  • affine.txt is a text file with the transformation to apply (see below)
  • matchImage.nii is the image with the dimensions you want the output image to have - what inImage should be transformed to match (for example, the 3x3x3 mm functional image)
  • CUBIC is how to do the resampling; other options are TRILINEAR and ENCLOSING_VOXEL
  • outImage.nii is the new image that will be written: inImage resampled to match matchImage; specifying a outImage.nii.gz will cause a gzipped NIfTI to be written.
The program writes outImage as a one-file (not a header-image pair) NIfTI. It takes input images as both compressed (i.e., .nii.gz) and uncompressed (i.e., .nii) one-file NIfTIs, but didn't like a header-image pair for input.

You need to specify an affine transform, but I don't want to warp anything so the matrix is all 1s and 0s; just put this matrix into a plain text file (I called it affine.txt):
 1 0 0 0  
 0 1 0 0  
 0 0 1 0  

UPDATE 24 May 2016: similar demo using afni 3dresample.
UPDATE 20 May 2015: Changed the resampling method to CUBIC and added a note that the program can output compressed images, as suggested by Tim Coalson.


  1. A few comments:

    1) It can output compressed nifti, just specify the output filename with a .nii.gz extension. No, it currently doesn't do hdr/img nifti (input nor output).

    2) I recommend CUBIC (which means cubic spline) for most resampling, other than ENCLOSING_VOXEL for label data. Yes, CUBIC can locally overshoot the input data, but it preserves more of the signal than other methods (resampling back to the original voxel grid will be more similar to the original than with other methods).

    3) Note that if you downsample a volume that isn't already as smooth as the lower resolution voxel grid, you may lose some signal. These resampling methods are point estimates at each new voxel center, so input voxels that are more than half the original voxel size away from any voxel center in the new voxel grid will be downweighted or ignored, depending on the method and how drastic a downsampling it is.

    1. Thanks for the tips and additional details, Tim!

      And you're right to point out that resampling (like from 1x1x1 mm to 3x3x3 mm voxels as in my example) loses information. In the example scenario this is fine, as the resampled image will only be used for low-resolution visualization. But great care must be taken when resizing images that will be used for analysis.