Population template: mrgrid crop -mask dilated and explicit mrtransform reorient

[maxpietsch]

changes to address issues with shrinking templates #1676

• mrcrop -mask reverted behaviour to pad by 1 voxel on all sides by default (new option -mask_margin).
• added mrtransform explicit reorient to population_template if the number of volumes matches SH series after mrtransform Jacobian modulation and explicit reorientation #1598
• mrmath: added -keep_unary_axes option and use that in population_template to avoid dimension mismatch between template and input data

[maxpietsch]

This reverts to the old mrcrop -mask behaviour to pad by 1 voxel around the mask. As discussed in #1676, this should avoid staircase patterns when transforming images that were cropped to the mask.

One difference is that cropping to a mask with a positive margin can now also extend the FOV of the cropped image if the mask + margin extends beyond the edge of the FOV. When interpolating at the very edge of the image, this can bias image intensities towards zero but allows using non-nearest interpolation. Any opinions on potentially padding beyond the FOV when cropping to a mask image?

[maxpietsch]

Can this be merged?

[maxpietsch]

On second thought and discussion with Daan, I think it is best to (550e93a):

• remove the -mask_margin option altogether as the -uniform option already allows changing the padding.
• revert the crop-to-mask behaviour to that of the original mrcrop command which does not pad beyond the original FOV. This restriction can be changed with the option -crop_unbound.
• default for all crop operations to be bound to within the original FOV with the exception of the -axis which still overrides all other extent options. This can be deactivated with -crop_unbound

To illustrate the difference that padding the FOV before rigid (rotation) transformation and regridding makes:

Given data and mask:

Cropping to mask and rigid transformation with regridding (linear interpolation) gives
for master (= pad by 1 to valid FOV):

and for "unbound padding" (before 550e93a, cropping with 1 voxel padding irrespective of FOV):

Regridded images are identical if nearest interpolation is used.

Difference between the two linearly interpolated images (mask is nearest-interpolated):

transformed mask without regridding:

Transforming the regridded images back without regridding to assess the mean squared difference to the original in scanner space inside the original mask or across the whole image using linear or nearest interpolation (mrmetric orig.mif orig_cropped_transformedandlinearlyregridded_transformedback<unbound,master>.mif -space image1 <-mask1 mask.mif> -interp <nearest,linear>):

MSE after cropping, transforming & regridding with linear interpolation, tranforming back, relative to original in voxel space of original
mrmetric: orig mask  (linear interp)  orig mask  (nearest interp)  all of orig (linear interp)   all of orig (nearest interp)
master:   0.00018643453489225402      0.0003085923725936925        4.9346885966807044e-05        7.5633275367555986e-05
unbound:  0.00018603586109253441      0.00030890752472299913       4.9261844688574506e-05        7.5696532084749933e-05
m/u:      1.00214                     0.99898                      1.00173                       0.999164

So, when evaluated in the original scanner space, padding at the edge of the FOV before transformation gives a lower error for evaluation using linear interpolation but higher error when evaluated with nearest interpolation. Or in other words, the bound padding behaviour is better if we care more about voxel space (voxel-wise average in population_template), the crop_unbound is better if we care about the scanner space after transformation.

Feel free to merge or object to any of the changes!

[Lestropie]

Pretty sure I understand. But the functionality is kinda funky and won't be easy to follow for many. I'm increasingly moving longer explanations to the DESCRIPTION section rather than trying to shove stuff into the option helps; I'm wondering if that might be useful here. I'd also considering renaming -crop_unbound to just -unbound; the option help can state that it applies only to the crop operation.

[thijsdhollander]

Given that the theme of this pull request is basically to make population_template work again (right?), it might make sense to add the fix for the dot product and load_transform as well...? Essentially 2a97a30 .

[thijsdhollander]

work again

• reproduce earlier behaviour again

[maxpietsch]

the functionality is kinda funky and won't be easy to follow for many

What part of the functionality do you mean? If you refer to the added restriction that crop operations do not pad unless explicitly specified, yes the lack of -crop_unbound can be a small hurdle for anyone stacking options and using signed extends such as

mrgrid in.mif crop -mask mask.mif -uniform -4 -axis 2 0,0 out.mif

This command crops to mask then extends the resulting FOV by 5 voxels (-1 around mask, -4 added) in all directions (up to the original FOV) then resets the extent of the z axis. So, the lack of -crop_unbound can be a small hurdle for anyone stacking options and using signed extends but will prevent less familiar users to be stumped by unexpected padding when explicitly cropping.

Maybe better to change the INFO level message [INFO] -crop_unbound not specified, restricting FOV on axis 2 from A:B to C:D to a warning message?

moving longer explanations to the DESCRIPTION section

Feel free to modify as you see fit! I tried to:

• give a high-level overview of the most important features and differences between operations in the main description
• show concepts such as the symmetry of pad and crop via the -axis options, -fill values and padding to a reference image in the examples
• go into option-specific details that are only/mostly relevant to these options in the option descriptions

-crop_unbound to just -unbound

No strong preference but I think I prefer -crop_unbound as it explicitly states to what it applies without needing to look it up in the command help but admittedly the crop to mask option is also called -mask not -crop_mask.

cherry-pick 2a97a30

Not sure if I break the changes to testing/script_tests/population_template when I cherry-pick 2a97a30 here?

[Lestropie]

"funky" wasn't exactly my most articulate moment :-/ It can take a moment to wrap one's head around the concepts and therefore the consequences of different usages. Also, while -uniform definitely serves a very similar purpose for crop and pad operations, it's maybe not the first option name for which you would read the help text to determine how to control the spacing +/- of the mask extent. Not that I have a superior alternative to offer.

Maybe better to change the INFO level message [INFO] -crop_unbound not specified, restricting FOV on axis 2 from A:B to C:D to a warning message?

No, I don't think failing to specify an option should produce a warning if the only crime was providing a mask that runs all the way to the edge of the FoV. But maybe given the complexity we could add a CONSOLE level message that summarises what the practical effect of the operation will be after all options are interpreted?

Not sure if I break the changes to testing/script_tests/population_template when I cherry-pick 2a97a30 here?

I could resolve such if you want to. Otherwise just merge this first, and I'll shortly after merge #1614.

[maxpietsch]

Ok, I modified:

• -uniform overwrites mask padding instead of modifying it
• more verbose output

Example:

mrgrid im.mif crop -uniform -10 -mask mask.mif -axis 2 -5,5 -info - | mrinfo - > /dev/null 
mrgrid: [WARNING] Value "-5,5" is being used as one of the 2 expected arguments for option "-axis"; is this what you intended?
mrgrid: [INFO] reading config file "/home/mp14/.mrtrix.conf"...
mrgrid: [INFO] opening image "im.mif"...
mrgrid: [INFO] image "im.mif" opened with dimensions 100x100x64x45, voxel spacing 1.51515x1.51515x1.5x1, datatype Float32LE
mrgrid: [INFO] operation: crop
mrgrid: [INFO] cropping to mask
mrgrid: [INFO] opening image "mask.mif"...
mrgrid: [INFO] image "mask.mif" opened with dimensions 100x100x64x45, voxel spacing 1.51515x1.51515x1.5x1, datatype Bit
mrgrid: [INFO] cropping to mask changes axis 0 extent from 0:99 to 16:81
mrgrid: [INFO] cropping to mask changes axis 1 extent from 0:99 to 8:86
mrgrid: [INFO] uniformly cropping by -10 voxels
mrgrid: [INFO] operation: crop without -crop_unbound: restricting padding on axis 1 to valid FOV 0:96
mrgrid: changing axis 0 extent from 0:99 (n=100) to 6:91 (n=86)
mrgrid: changing axis 1 extent from 0:99 (n=100) to 0:96 (n=97)
mrgrid: changing axis 2 extent from 0:63 (n=64) to -5:58 (n=64)
mrgrid: [INFO] creating image "-"...
mrgrid: [INFO] image "/home/mp14/tmp13/mrtrix-tmp-JlLiaU.mif" created with dimensions 86x97x64x45, voxel spacing 1.51515x1.51515x1.5x1, datatype Float32LE
mrgrid: [100%] cropping image

Docs:

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

  -as reference image
     pad or crop the input image on the upper bound 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. Note that by default a gap of 1
     voxel is left at all edges of the image to allow valid trilinear
     interpolation. This gap can be modified with the -uniform option but by
     default it does not extend beyond the FOV unless -crop_unbound is used.

  -crop_unbound
     Allow padding beyond the original FOV when cropping.

  -axis index spec  (multiple uses permitted)
     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 delta_lower,delta_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). Negative delta specifier values trigger the
     inverse operation (pad instead of crop and vice versa) and negative range
     specifier trigger padding. Note that the deprecated commands 'mrcrop' and
     'mrpad' used range-based and delta-based -axis indices, respectively.

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

[thijsdhollander]

👍 Great stuff; looks like this fixes everything.