ShapeFormat and MedicalImage

For many operations, it is important to know what are the data dimensions, which dimension is the channel dimension, and whether there is a batch dimension in order to process the data. In the past, some transforms needed a parameter to specify the format of the data to be processed, but there was no standard way to do so. Furthermore, the shape format can change as the data passes through the transform chain and channels are added or data is batched.

In order to standardize the way that format data is passed and to keep it with the image data, the concepts of ShapeFormat and MedicalImage were introduced, and transforms in the components layer were rewritten to expect and deal with image data in a MedicalImage object that also contains the ShapeFormat data.

The goal is to move more towards data-driven data processing instead of requiring configurations for everything, and this requires self-descriptive data definitions. The introduction of MedicalImages that require ShapeFormat is a step in this direction. In the past, the data for fields in the transform context were stored directly as numpy arrays, but that was not self-descriptive because there was no information on what each dimension meant. Now, ShapeFormat provides an explanation of the data in MedicalImage, and there is even validation automatically performed to ensure that the number of data dimensions actually match the ShapeFormat. This makes it possible for transforms to properly manipulate the image data based on the ShapeFormat without further manual configuration.


The possible values for ShapeFormat are:

  • DHW

  • DHWC

  • CDHW

  • NDHW



  • HW

  • HWC

  • CHW

  • NHW

  • NHWC

  • NCHW

where N is for batch dimension, C is for channel dimension, and D is for depth, H is for height, and W is for width for the image data dimensions.

For a complete list of all the convenience methods offered, see ai4med.common.shape_format.


MedicalImage objects can be thought of as a wrapper containing:

  • the actual image data as a numpy array

  • the ShapeFormat

  • any additional properties that are desired stored as key value pairs

When data is set, validation is automatically performed to ensure that the data is in fact a numpy array, the ShapeFormat is valid, and number of data dimensions matches what is expected from the ShapeFormat.

Convenience methods are provided to easily get the batch size, number of channels, and spatial shape, and to set/get/remove properties. For details, see ai4med.common.medical_image.