Dimension mismatch between images can cause direction matrices to be wrong

[cookpa]

Thought I'd share some information I just figured out. Not necessarily a bug but a potential cause of user confusion.

If you have a call to ReadImage<ImageDimension> for some value of ImageDimension, and the user passes it a file SomeImage.ext of ImageDimension+1, the first ImageDimension dimensions will be read in, but the direction matrix is set to identity. I think this is done by ITK:

https://github.com/InsightSoftwareConsortium/ITK/blob/7299e5c59a2f63f5e3de7fcbc193259fc4a61873/Modules/IO/ImageBase/include/itkImageFileReader.hxx#L149-L157

An example of how this could cause problems at run time is using antsApplyTransforms. Let's say you have t1.nii.gz, and a time series boldTimeSeries.nii.gz. Then you might do something like:

antsMotionCorr [ ... ] -a averageBold.nii.gz

antsRegistration [ ... ] -m MI[ T1.nii.gz , averageBold.nii.gz , 1, 32, Regular, 0.25] -o boldToT1DistCorr_

Then

antsApplyTransforms -d 3 -i [some image in T1 space] -t [boldToT1DistCorr_0GenericAffine.mat, 1] -r averageBold.nii.gz -o [output in bold space]

works fine. But the unsuspecting user might attempt:

antsApplyTransforms -d 3 -i [some image in T1 space] -t [boldToT1DistCorr_0GenericAffine.mat, 1] -r boldTimeSeries.nii.gz -o [output in bold space]

the output dimension, size and voxel spacing will be correct, but the reference space direction matrix will be silently set to the identity transform.