PadIfNeeded3D

Targets:

volume

mask3d

keypoints

Image Types:uint8, float32

Pads the sides of a 3D volume if its dimensions are less than specified minimum dimensions. If the pad_divisor_zyx is specified, the function additionally ensures that the volume dimensions are divisible by these values.

Arguments

min_zyx

tuple[int, int, int] | None

Minimum desired size as (depth, height, width). Ensures volume dimensions are at least these values. If not specified, pad_divisor_zyx must be provided.

pad_divisor_zyx

tuple[int, int, int] | None

If set, pads each dimension to make it divisible by corresponding value in format (depth_div, height_div, width_div). If not specified, min_zyx must be provided.

position

center | random

center

Position where the volume is to be placed after padding. Default is 'center'.

fill

tuple[float, ...] | float

Value to fill the border voxels for volume. Default: 0

fill_mask

tuple[float, ...] | float

Value to fill the border voxels for masks. Default: 0

p

float

Probability of applying the transform. Default: 1.0

Examples

>>> import numpy as np
>>> import albumentations as A
>>>
>>> # Prepare sample data
>>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8)  # (D, H, W)
>>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8)    # (D, H, W)
>>> keypoints = np.array([[20, 30, 5], [60, 70, 8]], dtype=np.float32)  # (x, y, z)
>>> keypoint_labels = [1, 2]  # Labels for each keypoint
>>>
>>> # Create a transform with both min_zyx and pad_divisor_zyx
>>> transform = A.Compose([
...     A.PadIfNeeded3D(
...         min_zyx=(16, 128, 128),        # Minimum size (depth, height, width)
...         pad_divisor_zyx=(8, 16, 16),   # Make dimensions divisible by these values
...         position="center",              # Center the volume in the padded space
...         fill=0,                         # Fill value for volume
...         fill_mask=1,                    # Fill value for mask
...         p=1.0
...     )
... ], keypoint_params=A.KeypointParams(coord_format='xyz', label_fields=['keypoint_labels']))
>>>
>>> # Apply the transform
>>> transformed = transform(
...     volume=volume,
...     mask3d=mask3d,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels
... )
>>>
>>> # Get the transformed data
>>> padded_volume = transformed["volume"]           # Shape: (16, 128, 128)
>>> padded_mask3d = transformed["mask3d"]           # Shape: (16, 128, 128)
>>> padded_keypoints = transformed["keypoints"]     # Keypoints shifted by padding
>>> padded_keypoint_labels = transformed["keypoint_labels"]  # Labels remain unchanged

Notes

Input volume should be a numpy array with dimensions ordered as (z, y, x) or (depth, height, width), with optional channel dimension as the last axis.