albumentations.augmentations.transforms3d.functional
Module containing functional implementations of 3D transformations. This module provides a collection of utility functions for manipulating and transforming 3D volumetric data (such as medical imaging volumes). The functions here implement the core algorithms for operations like padding, cropping, rotation, and other spatial manipulations specifically designed for 3D data.
Members
- functionadjust_padding_by_position3d
- functioncreate_shape_groups_3d
- functioncrop3d
- functioncutout3d
- functionfilter_keypoints_in_holes3d
- functionkeypoints_rot90
- functionpad_3d_with_params
- functionshuffle_tiles_within_shape_groups_3d
- functionsplit_uniform_grid_3d
- functionswap_tiles_on_keypoints_3d
- functionswap_tiles_on_volume
- functiontransform_cube
- functiontransform_cube_keypoints
adjust_padding_by_position3dfunction
Adjust padding values based on desired position for 3D data.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| paddings | list[tuple[int, int]] | - | List of tuples containing padding pairs for each dimension [(d_pad), (h_pad), (w_pad)] |
| position | One of:
| - | Position of the image after padding. |
| py_random | random.Random | - | Random number generator |
Returns
- tuple[int, int, int, int, int, int]: Final padding values (d_front, d_back, h_top, h_bottom, w_left, w_right)
create_shape_groups_3dfunction
Groups 3D tiles by their shape and stores the indices for each shape.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| tiles | np.ndarray | - | - |
crop3dfunction
Crop 3D volume using coordinates.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | np.ndarray | - | Input volume with shape (z, y, x) or (z, y, x, channels) |
| crop_coords | tuple[int, int, int, int, int, int] | - | (z_min, z_max, y_min, y_max, x_min, x_max) coordinates for cropping |
Returns
- np.ndarray: Cropped volume with same number of dimensions as input
cutout3dfunction
Cut out holes in 3D volume and fill them with a given value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | np.ndarray | - | Input volume with shape (depth, height, width) or (depth, height, width, channels) |
| holes | np.ndarray | - | Array of holes with shape (num_holes, 6). Each hole is represented as [z1, y1, x1, z2, y2, x2] |
| fill | One of:
| - | Value to fill the holes |
Returns
- np.ndarray: Volume with holes filled with the given value
filter_keypoints_in_holes3dfunction
Filter out keypoints that are inside any of the 3D holes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. |
| holes | np.ndarray | - | Array of holes with shape (num_holes, 6). Each hole is represented as [z1, y1, x1, z2, y2, x2]. |
Returns
- np.ndarray: Array of keypoints that are not inside any hole.
keypoints_rot90function
Rotate keypoints 90 degrees k times around the specified axes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. |
| k | int | - | Number of times to rotate by 90 degrees. |
| axes | tuple[int, int] | - | Axes to rotate around. |
| volume_shape | tuple[int, int, int] | - | Shape of the volume (depth, height, width). |
Returns
- np.ndarray: Rotated keypoints with same shape as input.
pad_3d_with_paramsfunction
Pad 3D volume with given parameters.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | np.ndarray | - | Input volume with shape (depth, height, width) or (depth, height, width, channels) |
| padding | tuple[int, int, int, int, int, int] | - | Padding values in format: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) where: - depth_front/back: padding at start/end of depth axis (z) - height_top/bottom: padding at start/end of height axis (y) - width_left/right: padding at start/end of width axis (x) |
| value | One of:
| - | Value to fill the padding |
Returns
- np.ndarray: Padded volume with same number of dimensions as input
Notes
The padding order matches the volume dimensions (depth, height, width). For each dimension, the first value is padding at the start (smaller indices), and the second value is padding at the end (larger indices).
shuffle_tiles_within_shape_groups_3dfunction
Shuffles indices within each group of similar shapes and creates a list where each index points to the index of the tile it should be mapped to.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| shape_groups | dict[tuple[int, int, int], list[int]] | - | Dictionary mapping shapes to list of tile indices with that shape |
| random_generator | np.random.Generator | - | Random number generator for shuffling |
Returns
- : List where index i contains the new position for tile i
split_uniform_grid_3dfunction
Splits a 3D volume shape into a uniform grid specified by the grid dimensions.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume_shape | tuple[int, int, int] | - | The shape of the volume as (depth, height, width). |
| grid | tuple[int, int, int] | - | The grid size as (depth_slices, rows, columns). |
| random_generator | np.random.Generator | - | The random generator to use for shuffling the splits. |
Returns
- np.ndarray: An array containing the tiles' coordinates in the format
swap_tiles_on_keypoints_3dfunction
Swap the positions of 3D keypoints based on a tile mapping.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | A 2D numpy array of shape (N, 3+) where N is the number of keypoints. Each row represents a keypoint's (x, y, z) coordinates plus other data. |
| tiles | np.ndarray | - | A 2D numpy array of shape (M, 6) where M is the number of tiles. Each row represents a tile's (z_start, y_start, x_start, z_end, y_end, x_end). |
| mapping | np.ndarray | - | A 1D numpy array of shape (M,) where M is the number of tiles. Each element i contains the index of the tile that tile i should be swapped with. |
Returns
- np.ndarray: A 2D numpy array of the same shape as the input keypoints, containing the new positions
swap_tiles_on_volumefunction
Swap tiles on the 3D volume according to the mapping.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | np.ndarray | - | Input volume with shape (D, H, W) or (D, H, W, C). |
| tiles | np.ndarray | - | Array of tiles with each tile as [z_start, y_start, x_start, z_end, y_end, x_end]. |
| mapping | list[int] | - | List of new tile indices. Must have the same length as tiles. |
Returns
- np.ndarray: Output volume with tiles swapped according to the random shuffle.
Notes
This implementation uses a loop rather than vectorized operations because tiles may have variable sizes in the general case (e.g., when the volume dimensions aren't evenly divisible by the grid size). Advanced indexing with variable-sized slices isn't possible in NumPy, making this loop-based approach the most efficient solution.
transform_cubefunction
Transform cube by index (0-47)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| cube | np.ndarray | - | Input array with shape (D, H, W) or (D, H, W, C) |
| index | int | - | Integer from 0 to 47 specifying which transformation to apply |
Returns
- np.ndarray: Transformed cube with same shape as input
transform_cube_keypointsfunction
Transform keypoints according to the cube transformation specified by index.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. |
| index | int | - | Integer from 0 to 47 specifying which transformation to apply. |
| volume_shape | tuple[int, int, int] | - | Shape of the volume (depth, height, width). |
Returns
- np.ndarray: Transformed keypoints with same shape as input.