albumentations.augmentations.transforms3d.transforms
Module containing 3D transformation classes for volumetric data augmentation. This module provides a collection of transformation classes designed specifically for 3D volumetric data (such as medical CT/MRI scans). These transforms can manipulate properties such as spatial dimensions, apply dropout effects, and perform symmetry operations on 3D volumes, masks, and keypoints. Each transformation inherits from a base transform interface and implements specific 3D augmentation logic.
Members
- classBaseCropAndPad3D
- classBasePad3D
- classCenterCrop3D
- classCoarseDropout3D
- classCubicSymmetry
- classPad3D
- classPadIfNeeded3D
- classRandomCrop3D
BaseCropAndPad3Dclass
BaseCropAndPad3D(
pad_if_needed: bool,
fill: tuple[float, ...] | float,
fill_mask: tuple[float, ...] | float,
pad_position: Literal['center', 'random'],
p: float = 1.0
)Base class for 3D transforms that need both cropping and padding.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| pad_if_needed | bool | - | - |
| fill | One of:
| - | - |
| fill_mask | One of:
| - | - |
| pad_position | One of:
| - | - |
| p | float | 1.0 | - |
BasePad3Dclass
BasePad3D(
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Base class for 3D padding transforms.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| fill | One of:
| 0 | - |
| fill_mask | One of:
| 0 | - |
| p | float | 1.0 | - |
CenterCrop3Dclass
CenterCrop3D(
size: tuple[int, int, int],
pad_if_needed: bool = False,
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Crop the center of 3D volume.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| size | tuple[int, int, int] | - | Desired output size of the crop in format (depth, height, width) |
| pad_if_needed | bool | False | Whether to pad if the volume is smaller than desired crop size. Default: False |
| fill | One of:
| 0 | Padding value for image if pad_if_needed is True. Default: 0 |
| fill_mask | One of:
| 0 | Padding value for mask if pad_if_needed is True. Default: 0 |
| p | float | 1.0 | probability of applying the transform. Default: 1.0 |
Notes
If you want to perform cropping only in the XY plane while preserving all slices along the Z axis, consider using CenterCrop instead. CenterCrop will apply the same XY crop to each slice independently, maintaining the full depth of the volume.
CoarseDropout3Dclass
CoarseDropout3D(
num_holes_range: tuple[int, int] = (1, 1),
hole_depth_range: tuple[float, float] = (0.1, 0.2),
hole_height_range: tuple[float, float] = (0.1, 0.2),
hole_width_range: tuple[float, float] = (0.1, 0.2),
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float | None = None,
p: float = 0.5
)CoarseDropout3D randomly drops out cuboid regions from a 3D volume and optionally, the corresponding regions in an associated 3D mask, to simulate occlusion and varied object sizes found in real-world volumetric data.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| num_holes_range | tuple[int, int] | (1, 1) | Range (min, max) for the number of cuboid regions to drop out. Default: (1, 1) |
| hole_depth_range | tuple[float, float] | (0.1, 0.2) | Range (min, max) for the depth of dropout regions as a fraction of the volume depth (between 0 and 1). Default: (0.1, 0.2) |
| hole_height_range | tuple[float, float] | (0.1, 0.2) | Range (min, max) for the height of dropout regions as a fraction of the volume height (between 0 and 1). Default: (0.1, 0.2) |
| hole_width_range | tuple[float, float] | (0.1, 0.2) | Range (min, max) for the width of dropout regions as a fraction of the volume width (between 0 and 1). Default: (0.1, 0.2) |
| fill | One of:
| 0 | Value for the dropped voxels. Can be: - int or float: all channels are filled with this value - tuple: tuple of values for each channel Default: 0 |
| fill_mask | One of:
| None | Fill value for dropout regions in the 3D mask. If None, mask regions corresponding to volume dropouts are unchanged. Default: None |
| p | float | 0.5 | Probability of applying the transform. Default: 0.5 |
Example
>>> 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)
>>> aug = A.CoarseDropout3D(
... num_holes_range=(3, 6),
... hole_depth_range=(0.1, 0.2),
... hole_height_range=(0.1, 0.2),
... hole_width_range=(0.1, 0.2),
... fill=0,
... p=1.0
... )
>>> transformed = aug(volume=volume, mask3d=mask3d)
>>> transformed_volume, transformed_mask3d = transformed["volume"], transformed["mask3d"]Notes
- The actual number and size of dropout regions are randomly chosen within the specified ranges. - All values in hole_depth_range, hole_height_range and hole_width_range must be between 0 and 1. - If you want to apply dropout only in the XY plane while preserving the full depth dimension, consider using CoarseDropout instead. CoarseDropout will apply the same rectangular dropout to each slice independently, effectively creating cylindrical dropout regions that extend through the entire depth of the volume.
CubicSymmetryclass
CubicSymmetry(
p: float = 1.0
)Applies a random cubic symmetry transformation to a 3D volume. 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 volumes and masks of the shape (D, H, W) or (D, H, W, C)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| p | float | 1.0 | Probability of applying the transform. Default: 1.0 |
Example
>>> 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).
Pad3Dclass
Pad3D(
padding: int | tuple[int, int, int] | tuple[int, int, int, int, int, int],
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Pad the sides of a 3D volume by specified number of voxels.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| padding | One of:
| - | Padding values. Can be: * int - pad all sides by this value * tuple[int, int, int] - symmetric padding (depth, height, width) where each value is applied to both sides of the corresponding dimension * tuple[int, int, int, int, int, int] - explicit padding per side in order: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) |
| fill | One of:
| 0 | Padding value for image |
| fill_mask | One of:
| 0 | Padding value for mask |
| p | float | 1.0 | probability of applying the transform. Default: 1.0. |
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.
PadIfNeeded3Dclass
PadIfNeeded3D(
min_zyx: tuple[int, int, int] | None = None,
pad_divisor_zyx: tuple[int, int, int] | None = None,
position: Literal['center', 'random'] = center,
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| min_zyx | One of:
| 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 | One of:
| 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 | One of:
| center | Position where the volume is to be placed after padding. Default is 'center'. |
| fill | One of:
| 0 | Value to fill the border voxels for volume. Default: 0 |
| fill_mask | One of:
| 0 | Value to fill the border voxels for masks. Default: 0 |
| p | float | 1.0 | Probability of applying the transform. Default: 1.0 |
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.
RandomCrop3Dclass
RandomCrop3D(
size: tuple[int, int, int],
pad_if_needed: bool = False,
fill: tuple[float, ...] | float = 0,
fill_mask: tuple[float, ...] | float = 0,
p: float = 1.0
)Crop random part of 3D volume.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| size | tuple[int, int, int] | - | Desired output size of the crop in format (depth, height, width) |
| pad_if_needed | bool | False | Whether to pad if the volume is smaller than desired crop size. Default: False |
| fill | One of:
| 0 | Padding value for image if pad_if_needed is True. Default: 0 |
| fill_mask | One of:
| 0 | Padding value for mask if pad_if_needed is True. Default: 0 |
| p | float | 1.0 | probability of applying the transform. Default: 1.0 |
Notes
If you want to perform random cropping only in the XY plane while preserving all slices along the Z axis, consider using RandomCrop instead. RandomCrop will apply the same XY crop to each slice independently, maintaining the full depth of the volume.