...

GridShuffle3D

Targets:
volume
mask3d
keypoints

Randomly shuffles the grid's cells on a 3D volume, mask3d, or keypoints, effectively rearranging patches within the volume.

This transformation divides the volume into a 3D grid and then permutes these grid cells based on a random mapping. Unlike the 2D version, this does not support bounding boxes as 3D bounding boxes are not yet implemented.

Arguments
grid_zyx
tuple[int, int, int]
[2,2,2]

Size of the grid for splitting the volume into cells along (Z, Y, X) axes, corresponding to (depth, height, width) dimensions. Each cell is shuffled randomly. For example, (2, 3, 3) will divide the volume into 2 slices along Z, 3 along Y, and 3 along X, resulting in 18 cells to be shuffled. Default: (2, 2, 2)

p
float
0.5

Probability that the transform will be applied. Should be in the range [0, 1]. Default: 0.5

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
>>>
>>> # Define transform with grid_zyx as a tuple (Z, Y, X)
>>> transform = A.Compose([
...     A.GridShuffle3D(grid_zyx=(2, 3, 3), 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
>>> transformed_volume = transformed['volume']           # Grid-shuffled volume
>>> transformed_mask3d = transformed['mask3d']           # Grid-shuffled mask
>>> transformed_keypoints = transformed['keypoints']     # Grid-shuffled keypoints
>>> transformed_keypoint_labels = transformed['keypoint_labels']  # Labels remain unchanged
Notes
  • This transform maintains consistency across all targets. If applied to a volume and its corresponding mask3d or keypoints, the same shuffling will be applied to all.
  • The number of cells in the grid should be at least 2 (i.e., grid_zyx should be at least (1, 1, 2), (1, 2, 1), (2, 1, 1) or larger) for the transform to have any effect.
  • Keypoints are moved along with their corresponding grid cell.
  • The grid_zyx parameter corresponds to volume dimensions: Z (depth), Y (height), X (width).