Data transforms and augmentations

Here is a list of built-in data transformation functions. If you need additional transformation functions, please contact us at the TLT user forum: http://devtalk.nvidia.com.

LoadNifty

Load NIfTI data. The value of each key (specified by fields) in input "dict" can be a string (a path to a single NIfTI file) or a list of strings (several paths to multiple NIfTI files, if there are several channels saved as separate files).

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

Returns:

- Each field of "dict" is substituted by a 4D numpy array.

VolumeTo4dArray

Transforms the value of each key (specified by fields) in input "dict" from 3D to 4D numpy array by expanding one channel, if needed.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

Returns:

- Each field of "dict" is substituted by a 4D numpy array.

ScaleIntensityRange

Scale the Intensity range with optional clipping of the of the numpy array.

init_args:

- field: string

one key_value to apply, e.g. "image".

- a_min: float

- a_max: float

Range of the original image

- b_min: float

- b_max: float

Target range of the image.

- Clip = False: bool

Flag controls whether to clip the intensity out of the target range.

ScaleIntensityOscillation

Randomly shift scale level for image.
Args:
field: key string, e.g. "image". ‣ magnitude: scale shift is a random value random between 0 and magnitude.

Returns
Data with an offset on intensity scale.

CropSubVolumeBatchPosNegRatio

Randomly crop the foreground and background ROIs from both the image and mask for training. The sampling ratio between positive and negative samples is adjusted with the epoch number.

‣ init_args:

- image_field: string

one key_value to apply, e.g. "image".

- label_field: string

one key_value to apply, e.g. "label".

- size: list of ints

cropped ROI size, e.g., [96, 96, 96].

- pos/neg: float

Positive numbers to determine the ratio between positive and negative samples.

- batch_size: int

A positive integer to determine how many patches are cropped from the single volume.

- data_format: string

”channels_first” (by default) or ”channels_last”.

- fast_crop: binary

True or False to determine whether to enable the fast cropping algorithm.

‣ Returns:

- Updated dictionary with cropped ROI image and mask

NPResize3D

Resize 3D volume with a given shape

‣ init_args:

- applied_keys: list of strings

key_values to apply, e.g. ["image", “label”].

- output_shape: list of ints

output size, e.g., [96, 96, 96].

- nearest: binary

True for nearest interpolation (for segmentation labels, etc.), and False for linear interpolation (for images, etc.).

‣ Returns:

- 3D volume with the given shape

TransformVolumeCropROIFastPosNegRatio

Fast 3D data augmentation method (CPU based) by combining 3D morphological transforms (rotation, elastic deformation, and scaling) and ROI cropping. The sampling ratio is specified by pos/neg.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- size: list of int

cropped ROI size, e.g., [96, 96, 96].

- deform: boolean

whether to apply 3D deformation.

- rotation: boolean

whether to apply 3D rotation.

- rotation_degree: float

the degree of rotation, e.g., 15 means randomly rotate the image/label in a range [-15, +15].

- scale: boolean

whether to apply 3D scaling.

- scale_factor: float

the percentage of scaling, e.g., 0.1 means randomly scaling the image/label in a range [-0.1, +0.1].

- pos: float

the factor controlling the ratio of positive ROI sampling.

- neg: float

the factor controlling the ratio of negative ROI sampling.

Returns:

- Updated dictionary with cropped ROI image and mask after data augmentation.

AdjustContrast

Randomly adjust the contrast of the field in input "dict".

init_args:

- field: string

one key_value to apply, e.g. "image".

AddGaussianNoise

Randomly add Gaussian noise to the field in input "dict".

init_args:

- field: string

one key_value to apply, e.g. "image".

LoadPng

Load png image and the label. The value of "image" must be a string (a path to a single png file) while the value of the "label" must be a list of labels.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

Returns:

- "image" of "dict" is substituted by a 3D numpy array while the "label" of "dict" is substituted by a numpy list

CropRandomSubImageInRange

Randomly crop 2D image. The crop size is randomly selected between lower_size and image size.

init_args:

- lower_size: int or float

lower limit of crop size, if float, then must be fraction <1

- max_displacement: float

max displacement from center to crop

- keep_aspect: boolean

if true, then original aspect ratio is kept

Returns:

- The "image" field of input "dict" is substituted by cropped ROI image.

NPResizeImage

Resize the 2D numpy array (channel x rows x height) as an image.

init_args:

- applied_keys: string

one key_value to apply, e.g. "image".

- output_shape: list of int with length 2

e.g., [256,256].

- data_format: string

''channels_first', 'channels_last', or 'grayscale'.

NP2DRotate

Rotate 2D numpy array, or channelled 2D array. If random is set to true, then rotate within the range of [ -angle, angle]

init_args:

- applied_keys: string

one key_value to apply, e.g. "image".

- angle: float

e.g. 7.

- random: boolean

default is false.

NPExpandDims

Add a singleton dimension to the selected axis of the numpy array.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- expand_axis: int

axis to expand, default is 0

NPRepChannels

Repeat a numpy array along specified axis, e.g., turn a grayscale image into a 3-channel image.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- channel_axis: int

the axis along which to repeat values.

- repeat: int

the number of repetitions for each element.

CenterData

Center numpy array's value by subtracting a subtrahend and dividing by a divisor.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- subtrahend: float

subtrahend. If None, it is computed as the mean of dict[key_value].

- divisor: float

divisor. If None, it is computed as the std of dict[key_value]

NPRandomFlip3D

Flip the 3D numpy array along random axes with the provided probability.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- probability: float

probability to apply the flip, value between 0 and 1.0.

NPRandomZoom3D

Apply a random zooming to the 3D numpy array.

init_args:

- applied_keys: string or list of strings

key_values to apply, e.g. ["image", "label"].

- lower_limits: list of float

lower limit of the zoom along each dimension.

- upper_limits: list of float

upper limit of the zoom along each dimension.

- data_format: string

'channels_first' or "channels_last".

- use_gpu: boolean

whether to use cupy for GPU acceleration. Default is false.

- keep_size: boolean

default is false which means this function will change the size of the data array after zooming. Setting keep_size to True will result in an output of the same size as the input.

CropForegroundObject

Crop the 4D numpy array and resize the forground. The numpy array must have foreground voxels.

init_args:

- size: list of int

resized size.

- image_field: string

"image".

- label_field: string

"label".

- pad: int number of voxels for addinga margin around the object)- foreground_only: boolean whetherto treat all foreground labels as onebinary label (default) or whether toselect foreground label at random.
- keep_classes : boolean; if true, keep original label indices in label image (no thresholding), useful for multi-class tasks.
- pert: int; random perturbation in each dimension added to padding (in voxels).

NPRandomRot90_XY

Rotate the 4D numpy array along random axes on XY plane (axis = (1, 2)).

init_args:

- applied_keys: string

one key_value to apply, e.g. "image".

- probability: float

probability to utilize the transform, between 0 and 1.0.

AddExtremePointsChannel

Add and additional channel to 4D numpy array where the extreme points of the foreground labels are modeled as Gaussians.

init_args:

- image_field: string

"image".

- label_field: string

"label".

- sigma: float

size of Gaussian.

- pert: boolean

random perturbation added to the extreme points.

NormalizeNonzeroIntensities

Normalize 4D numpy array to zero mean and unit std, based on non-zero elements only for each input channel individually.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

SplitAcrossChannels

Splits the 4D numpy array across channels to create new dict entries. New key_values shall be applied_key+channel number, e.g. "image1".

init_args:

- applied_key: string

one key_value to apply, e.g. "image".

LoadResolutionFromNifty

Get the image resolution from an NifTI image

init_args:
- applied_key: string

one key_value to apply, e.g. "image".

Returns:

- "dict" has a new key-value pair: dict[applied_key+"_resolution"]: resolution of the NIfTI image

Load3DShapeFromNumpy

Get the image shape from an NifTI image

init_args:
- applied_key: string

one key_value to apply, e.g. "image".

Returns:

- "dict" has a new key-value pair: dict[applied_key+"_shape"]: shape of the NIfTI image

ResampleVolume

Resample the 4D numpy array from current resolution to a specific resolution

init_args:
- applied_key: string

one key_value to apply, e.g. "image".

- resolution: list of float

input image resolution.

- target_resolution: list of float

target resolution.

BratsConvertLabels

Brats data specific. Convert input labels format (indices 1,2,4) into proper format.

init_args:
- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

CropSubVolumeRandomWithinBounds

Crops a random subvolume from within the bounds of 4D numpy array.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

- size: list of int

the size of the crop region e.g. [224,224,128].

FlipAxisRandom

Flip the numpy array along its dimensions randomly.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

- axis : list of ints

which axes to attempt to flip (e.g. [0,1,2] - for all 3 dimensions) - the axis indices must be provided only for spatial dimensions.

CropSubVolumeCenter

Crops a center subvolume from within the bounds of 4D numpy array.

init_args:

- fields: string or list of strings

key_values to apply, e.g. ["image", "label"].

- size: list of int

the size of the crop region e.g. [224,224,128] (similar to CropSubVolumeRandomWithinBounds, but crops the center)