CubicSymmetry

Targets:

volume

mask3d

keypoints

Image Types:uint8, float32

Randomly reorient a 3D volume with one of 48 exact cubic symmetries, using only axis permutations and reflections for interpolation-free augmentation.

This transform is intended for augmentation. Use a transform with explicit deterministic parameters for TTA.

This transform is a 3D extension of D4. While D4 handles the 8 symmetries of a square (4 rotations x 2 reflections), CubicSymmetry handles all 48 symmetries of a cube. Like D4, this transform does not create any interpolation artifacts as it only remaps voxels from one position to another without any interpolation.

The 48 transformations consist of:

24 rotations (orientation-preserving):
- 4 rotations around each face diagonal (6 face diagonals x 4 rotations = 24)
24 rotoreflections (orientation-reversing):
- Reflection through a plane followed by any of the 24 rotations

For a cube, these transformations preserve:

All face centers (6)
All vertex positions (8)
All edge centers (12)

works with 3D volume data and masks of the shape (D, H, W) or (D, H, W, C)

Arguments

p

float

Probability of applying the transform. Default: 1.0

Examples

>>> import numpy as np
>>> import albumentations as A
>>> 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)
>>> transform = A.CubicSymmetry(p=1.0)
>>> transformed = transform(volume=volume, mask3d=mask3d)
>>> transformed_volume = transformed["volume"]
>>> transformed_mask3d = transformed["mask3d"]

Notes

This transform is particularly useful for data augmentation in 3D medical imaging, crystallography, and voxel-based 3D modeling where the object's orientation is arbitrary.
All transformations preserve the object's chirality (handedness) when using pure rotations (indices 0-23) and invert it when using rotoreflections (indices 24-47).