add mrgrid

[maxpietsch]

Adding mrgrid as a replacement to mrcrop, mrpad and mrresize (#364).

The syntax follows closely what @jdtournier suggested in this comment with the exception of the distinction between -template and -as options. As in mrtransform, the former indicates that interpolation is performed (regrid operation), the latter doesn't ( crop or pad).

The added Regrid adapter as a generalisation of the Subset adapter that allows padding with fill values. However, the bounds checks in move_index and value feel clunky. Is there a better way?

Are we happy with the interface?

Shall I remove the existing commands?

The help page:

MRtrix 3.0_RC3-642-g9efee35d         mrgrid                          Apr 23 2019

     mrgrid: part of the MRtrix3 package

SYNOPSIS

     Modify the grid of an image without interpolation (cropping or padding) or
     by regridding to an image grid with modified orientation, location and or
     resolution. The image content remains in place in real world coordinates.

USAGE

     mrgrid [ options ] input operation output

        input        input image to be regridded.

        operation    the operation to be performed, one of: regrid, crop, pad.

        output       the output image.


DESCRIPTION

     The 'regrid' operation performs changes of the voxel grid that require
     interpolation of the image such as changing the resolution or location and
     orientation of the voxel grid. If the image is down-sampled, the
     appropriate smoothing is automatically applied using Gaussian smoothing
     unless nearest neighbour interpolation is selected or oversample is
     changed explicitly. The resolution can only be changed for spatial
     dimensions. 

     The image extent after cropping, can be specified either manually for each
     axis dimensions, or via a mask or reference image. If using a mask, a gap
     of 1 voxel will be left at all edges of the image such that trilinear
     interpolation upon the resulting images is still valid. This is useful for
     axially-acquired brain images, where the image size can be reduced by a
     factor of 2 by removing the empty space on either side of the brain. 

     Analogously, 'pad' increases the FOV of an image. Pad and crop can be
     performed simultaneously by specifying signed specifier argument values to
     the -axis option.

     This command encapsulates and extends the functionality of the superseded
     commands 'mrpad', 'mrcrop' and 'mrresize'. Note the difference in -axis
     convention used for 'mrcrop' and 'mrpad' (see -axis option description).

EXAMPLE USAGES

     Crop and pad the first axis:
       $ mrgrid in.mif crop -axis 0 10,-5 out.mif
     This removes 10 voxels on the lower and pads with 5 on the upper bound,
     which is equivalent to padding with the negated specifier (mrgrid in.mif
     pad -axis 0 -10,5 out.mif)

     Right-pad the image to the number of voxels of a reference image:
       $ mrgrid in.mif pad -as ref.mif -nd -axis 3 0,0 out.mif -fill nan
     This pads the image on the upper bound of all axes except for the volume
     dimension. The headers of in.mif and ref.mif are ignored and the output
     image uses NAN values to fill in voxels outside the original range of
     in.mif.

     Regrid and interpolate to match the voxel grid of a reference image:
       $ mrgrid in.mif regrid -template ref.mif -scale 1,1,0.5 out.mif -fill nan
     The -template instructs to regrid in.mif to match the voxel grid of
     ref.mif (voxel size, grid orientation and voxel centres) The -scale option
     overwrites the voxel scaling factor yielding voxel sizes in the third
     dimension that are twice as coarse as those of the template image.

Regridding options (involves image interpolation, applied to spatial axes only)

  -template image
     match the input image grid (voxel spacing, image size, header
     transformation) to that of a reference image. The image resolution
     relative to the template image can be changed with one of -size, -voxel,
     -scale.

  -size dims
     define the size (number of voxels) in each spatial dimension for the
     output image. This should be specified as a comma-separated list.

  -voxel size
     define the new voxel size for the output image. This can be specified
     either as a single value to be used for all spatial dimensions, or as a
     comma-separated list of the size for each voxel dimension.

  -scale factor
     scale the image resolution by the supplied factor. This can be specified
     either as a single value to be used for all dimensions, or as a
     comma-separated list of scale factors for each dimension.

  -interp method
     set the interpolation method to use when reslicing (choices: nearest,
     linear, cubic, sinc. Default: cubic).

  -oversample factor
     set the amount of over-sampling (in the target space) to perform when
     regridding. This is particularly relevant when downsamping a
     high-resolution image to a low-resolution image, to avoid aliasing
     artefacts. This can consist of a single integer, or a comma-separated list
     of 3 integers if different oversampling factors are desired along the
     different axes. Default is determined from ratio of voxel dimensions
     (disabled for nearest-neighbour interpolation).

Pad and crop options (no image interpolation is performed, header transformation is adjusted)

  -as reference image
     right-pad or right-crop the input image to match the specified reference
     image grid. This operation ignores differences in image transformation
     between input and reference image.

  -uniform number
     pad or crop the input image by a uniform number of voxels on all sides

  -mask image
     crop the input image according to the spatial extent of a mask image. The
     mask must share a common voxel grid with the input image but differences
     in image transformations are ignored. Note that even though only 3
     dimensions are cropped when using a mask, the bounds are computed by
     checking the extent for all dimensions.

  -axis index spec
     pad or crop the input image along the provided axis (defined by index).
     The specifier argument defines the number of voxels added or removed on
     the lower or upper end of the axis (-axis index lower,upper) or acts as a
     voxel selection range (-axis index start:stop). In both modes, values are
     relative to the input image (overriding all other extent-specifying
     options) and negative values trigger the inverse operation. Note that the
     deprecated commands 'mrcrop' and 'mrpad' used range-based and delta-based
     -axis indices, respectively.

  -nd
     Crop or pad all, not just spatial axes.

General options

  -fill number
     Use number as the out of bounds value (Default: 0.0)

  -nan
     Fill with not-a-number as out of bounds value. Convenience option for
     -fill NAN.

Stride options

  -strides spec
     specify the strides of the output data in memory; either as a
     comma-separated list of (signed) integers, or as a template image from
     which the strides shall be extracted and used. The actual strides produced
     will depend on whether the output image format can support it.

Data type options

  -datatype spec
     specify output image data type. Valid choices are: float32, float32le,
     float32be, float64, float64le, float64be, int64, uint64, int64le,
     uint64le, int64be, uint64be, int32, uint32, int32le, uint32le, int32be,
     uint32be, int16, uint16, int16le, uint16le, int16be, uint16be, cfloat32,
     cfloat32le, cfloat32be, cfloat64, cfloat64le, cfloat64be, int8, uint8,
     bit.

[thijsdhollander]

Looks very good to me; I'm very happy with the choices made, and also fully support separate -template and -as options: even though they're both supplying the image that serves as a "reference", there's an important difference in what aspects are used (or ignored) as reference information.

One thing that I picked up from the help/interface (and didn't fully anticipate) is that -as will perform a right pad or crop. I think what I'd naturally had been expecting first would be more of a "centered" pad or crop. But in saying that, I now realise that'll introduce the necessity to deal with an ambiguity if the input image and -as reference image differ by an uneven number along a(ny) dimension... So taking that then into account, I think right pad or crop is probably fine.

Happy to delete the commands that this effectively replaces: no functionality is lost (I think).

[Lestropie]

• Description could do with better clarity as to which paragraph corresponds to which operation; e.g. as dot points with having the name of the operation as the first word in the paragraph.

• For cropping based on a mask, I kind of regretted implementing it the way I did in mrcrop. I'd rather crop strictly to retain all ROI voxels within the FoV, and in cases where valid trilinear interpolation is required, recommend to the user that the mask should be dilated via maskfilter before being provided to mrgrid -mask.

• Does the interpreted sign of crop and pad operations using the -axis option change? Your current example uses:
  crop -axis 0 10,-5
  , which removes voxels from the lower bound and adds them on the upper bound; would:
  pad -axis 0 10,-5
  add voxels at the lower bound and remove them from the upper bound? This probably requires greater description.

• Some areas talk about "lower" and "upper" bounds, whereas others refer to as "right". Might be better for this to be consistent throughout; the meanings behind these terms could even be made explicitly in the Description if need be.

• -as option looks like it takes two arguments rather than one because of the space in "reference image".

• The naming of the -nd option isn't immediately intuitive; I get the intent, but it didn't come to me straight away. Maybe something like "-all_axes"?

• Personally I'd remove the -nan option; maybe just instead clarify in the -fill option description that nan, inf and -inf are valid values.

• What's an intended use case of the -as option? In any case where you're wanting your image to have the same number of voxels as some other image, right-padding is almost certainly going to result in a spatial misalignment between the image contents, at which point, what benefit are you gaining by having the same number of voxels? Obviously it's something that you can do, I'm just struggling to envisage a case where it would actually serve a valid purpose.

[maxpietsch]

• Description could do with better clarity as to which paragraph corresponds to which operation; e.g. as dot points with having the name of the operation as the first word in the paragraph.

done.

-mask crop strictly without padding

done, documented the change in the -mask option and the general command description, amended all scripts where I found it except for the initial mask in population_template where I don't think it'll make a difference.

Does the interpreted sign of crop and pad operations using the -axis option change?

Yes, the operation can be inverted (pad instead of crop and vice versa) by flipping the sign in the delta specifier. I made that more explicit in the -axis description.

remove the -nan option

done, added description of nan, inf and -inf as valid fill values, removed the -nan option (I added it originally as mrtransform has it).

-intended use case of the -as option

To concatenate multiple SH images with varying lmax in the 4th dimension. This requires zero-padding to the largest lmax prior to concatenation.

right-padding is almost certainly going to result in a spatial misalignment between the image contents

All operations in mrgrid preseve the location in scanner reference frame. Another reason for right-padding is that it also preserves the image transformation.

[thijsdhollander]

All operations in mrgrid preseve the location in scanner reference frame. Another reason for right-padding is that it also preserves the image transformation.

Yep, thought that was part of the intention behind that choice. I'm happy with it; it makes sense, I reckon.

-intended use case of the -as option

To concatenate multiple SH images with varying lmax in the 4th dimension. This requires zero-padding to the largest lmax prior to concatenation.

Yep, was thinking of the same. I have a few other uses in mind, but don't wish to elaborate on those here. There's definitely some uses, and I'm sure users will find their own. Fully support having the option; having options is a good thing.

[thijsdhollander]

Review-refresh: all still good.

[thijsdhollander]

Just comes to mind now: when removing the older commands, you'll have to fix up the tests, I suppose. But as the new command basically allows for the same functionality, you could re-write the tests as such that the test data doesn't have to be touched. That itself would be a good test indeed.

[maxpietsch]

I converted all mrpad, mrcrop and mrresize tests to a single mrpad test in 9efee35, and modified the -mask crop test in 5e5b53d. The test data is unchanged.