Consolidation of spatial transform parameters

Introduction

Before we hit 1.0, it may be worth looking across the set of transforms that we have and making parameters consistent where we can do so. Below is a list of transforms (columns) and their construction parameters.

In general:

• Any parameters that we add can be done so without issue
• Any renamed parameters should be kept for 1.0 and the old ones deprecated for future removal

What is still missing

This table considers the __init__ methods of the various spatial transforms. There are also some inconsistencies across the __call__ methods, in terms of what can be modified on a per call basis, which can also potentially be added.

See also

#5010 as adding / consolidating parameters is closely tied to the idea of unifying the back-end resample operation across spatial transforms

Table details

The table is split up into transform specific parameters and general parameters that apply to many or all spatial transforms.

Entries are as follows:

• i: parameter is on __init__ only
• c: parameter is on __call__ only
• x: parameter is on both __init__ and __call__
• ?: parameter is not present but perhaps should be

                       S O F R R Z R R R R R R   R A R   A R R   R R G R
                       p r l e o o o a a a a a   e f a   f a a   a a r a
                       a i i s t o t n n n n n   s f n   f n n   n n i n
                       c e p i a m a d d d d d   a i d   i d d   d d d d
                       i n   z t   t R R F A Z   m n A   n A D   2 3 D G
                       n t   e e   e o o l x o   p e f   e f e   D D i r
                       g a         9 t t i i o   l   f   G f f   E E s i
                         t         0 a a p s m   e   i   r i o   l l t d
                         i           t t   F         n   i n r   a a o D
                         o           e e   l         e   d e m   s s r i
                         n           9     i               G G   t t t s
                                     0     p               r r   i i i t
                                                           i i   c c o o
                                                           d d       n r
                                                                       t
                                                                       i
                                                                       o
                                                                       n

don't transform images                                   x x x

------------------------------------------------------------------------
pixdim                 i
output_spatial_shape   c
diagonal               i
axcodes                  i
as_closest_canonical     i
labels                   i
spatial_axis               i             i
size_mode                    i
angle                          i
zoom                             i
k                                  i
spatial_axes                       i i
max_k                                i
range_x                                i
range_y                                i
range_z                                i
min_zoom                                     i
max_zoom                                     i
rotate_params                                      i     i
shear_params                                       i     i
translate_params                                   i     i
scale_params                                       i     i
rotate_range                                         i     i     i i
shear_range                                          i     i     i i
translate_range                                      i     i     i i
scale_range                                          i     i     i i
spacing                                                      i   i ?
magnitude_range                                              i   i i
sigma_range                                                      ? i
num_cells                                                            i i
distort_steps                                                        x
distort_limit                                                          i

mode                   x     x x x ? ? x     x   x x x   . . .   x x x x
padding_mode           x       x x ? ? x     x   x x x   . . .   x x x x
align_corners          x     x x x     x     x   ? ? ?           ? ? ? ?
keep_size                      i i ? ? i     x   ? ? ?           ? ? ? ?
spatial_size                 i                     c c   c c c   x x
anti_aliasing                x                   ? ? ?           ? ? ? ?
anti_aliasing_sigma          x                   ? ? ?           ? ? ? ?
dtype                  x       x       x         x i     i ? ?

affine                                             i     i
as_tensor_output                                 i i i   i i i   i i
normalized                                         i ?
norm_coords                                      x i ?
device                                           x i     i i i   i i i i
cache_grid                                           i
grid                                             c   c   c c

randomize                            c c c c c             c     c c   c
prob                                 i i i i i             ?     i i   i

General parameters

keep_size: keep_size should be added to any transform that has the potential to alter the image size:

• Rotate90, RandRotate90, Resample, Affine, RandAffine, Rand2DElastic, Rand3DElastic, RandDistortion, RandGridDistortion

align_corners: align_corners should be added to any transform that has the potential to alter the image size:

• Resample, Affine, RandAffine, Rand2DElastic, Rand3DElastic, RandDistortion, RandGridDistortion

mode: mode should be added to any transform with the potential to have to resample off pixel / voxel centers. Rotate90 and RandRotate90 both have this potential when dealing with anisotropic pixels / voxels

• Rotate90, RandRotate90
• Note: Making Rotate90 and RandRotate90 perform resampling changes the current behavior It could be argued that, although these methods generate grids rather than preprocessing images, mode could also be defined for them as it might then be subsequently passed to lazy resampling once that feature is implemented:
• AffineGrid, RandAffineGrid, RandDeformGrid

padding_mode: padding_mode should be added to any transform that has the potential to sample outside of the existing volume

• Rotate90, RandRotate90
• Note: Making Rotate90 and RandRotate90 perform resampling changes the current behavior

anti_aliasing / anti_aliasing_sigma: anti_aliasing / anti_aliasing_sigma should be applicable to transforms that support mode, particularly if The resampling backend method is consolidated across most spatial transforms.

• Spacing, Zoom, RandZoom, Resample, Affine, RandAffine, GridDistortion, RandGridDistortion
• See also Rand2DElastic, Rand3DElastic, the former of which appears to be missing sigma_range

norm_coords:

• deprecated on Affine but not Resample

Specific parameters

There are a number of transforms with slight naming inconsistencies in their transform-specific parameter names:

• Flip and RandFlip use spatial_axis, whereas Rotate90 and RandRotate90 use spatial_axes
  • Flip and RandFlip could move to spatial_axes, as multiple axes can be specified
• Rotate uses angle whereas RandRotate uses range_x, range_y and range_z
  • Although RandRotate does need to take ranges instead of scalars, they could still be handled in the way angle is handled, depending on the dimensionality of the data vs the number of ranges specified
• anti_aliasing_sigma vs sigma_range: Resize has anti_aliasing_sigma (and a few other transforms should probably have it if we enable this kind of resampling in general), but Rand3DElastic has sigma_range (and Rand2DElastic should probably have it). This should probably become anti_aliasing_sigma_range

Omitted:

• SpatialResample
• ResampleToMatch
• GridSplit
• GridPatch
• RandGridPatch

[atbenmurray]

@ericspod @mingxin-zheng @Nic-Ma @rijobro @wyli I’m going to pick up the following:

• self.__call__ additional args from init method
• Move internal transforms constructed during __call__ to __init__ Unless anyone objects or is already working on it

[wyli]

• review backends update docstrings
• review arg names spatial_axis, spatial_axes
• keep size=True Rotate90 RandRotate90
• self.__call__ additional args from __init__ method
• Move internal transforms constructed during __call__ to __init__
• review arg names: angle vs range_x, range_y, range_z