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

Start by comparing the init and call parameters of the listed spatial transforms, including Rotate, Affine, Resample, elastic, distortion, and grid transforms, against the table. Review related issue #5010 before deciding the shared parameter scope. Done means the inconsistencies have an agreed implementation and deprecation plan, including the omitted transforms and per-call parameters.