Stay updated
News & Insightsalbumentations.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
- functionpad_3d_with_params
- functioncrop3d
- functioncutout3d
- functiontransform_cube
- functionfilter_keypoints_in_holes3d
- functionkeypoints_rot90
- functiontransform_cube_keypoints
- functionsplit_uniform_grid_3d
- functioncreate_shape_groups_3d
- functionshuffle_tiles_within_shape_groups_3d
- functionswap_tiles_on_volume
- functionswap_tiles_on_keypoints_3d
adjust_padding_by_position3dfunction
adjust_padding_by_position3d(
paddings: list[tuple[int, int]],
position: Literal['center', 'random'],
py_random: random.Random
)Adjust padding values based on desired position for 3D data. Args: paddings (list[tuple[int, int]]): List of tuples containing padding pairs for each dimension [(d_pad), (h_pad), (w_pad)] position (Literal["center", "random"]): 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)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| paddings | list[tuple[int, int]] | - | - |
| position | One of:
| - | - |
| py_random | random.Random | - | - |
pad_3d_with_paramsfunction
pad_3d_with_params(
volume: ImageType,
padding: tuple[int, int, int, int, int, int],
value: tuple[float, ...] | float
)Pad 3D volume with given parameters. Args: 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 (tuple[float, ...] | float): Value to fill the padding Returns: np.ndarray: Padded volume with same number of dimensions as input Note: 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).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| padding | tuple[int, int, int, int, int, int] | - | - |
| value | One of:
| - | - |
crop3dfunction
crop3d(
volume: ImageType,
crop_coords: tuple[int, int, int, int, int, int]
)Crop 3D volume using coordinates. Args: 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
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| crop_coords | tuple[int, int, int, int, int, int] | - | - |
cutout3dfunction
cutout3d(
volume: ImageType,
holes: np.ndarray,
fill: tuple[float, ...] | float
)Cut out holes in 3D volume and fill them with a given value. Args: 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 (tuple[float, ...] | float): Value to fill the holes Returns: np.ndarray: Volume with holes filled with the given value
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| holes | np.ndarray | - | - |
| fill | One of:
| - | - |
transform_cubefunction
transform_cube(
cube: np.ndarray,
index: int
)Transform cube by index (0-47) Args: 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
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| cube | np.ndarray | - | - |
| index | int | - | - |
filter_keypoints_in_holes3dfunction
filter_keypoints_in_holes3d(
keypoints: np.ndarray,
holes: np.ndarray
)Filter out keypoints that are inside any of the 3D holes. Args: 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| holes | np.ndarray | - | - |
keypoints_rot90function
keypoints_rot90(
keypoints: np.ndarray,
k: int,
axes: tuple[int, int],
volume_shape: tuple[int, int, int]
)Rotate keypoints 90 degrees k times around the specified axes. Args: 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| k | int | - | - |
| axes | tuple[int, int] | - | - |
| volume_shape | tuple[int, int, int] | - | - |
transform_cube_keypointsfunction
transform_cube_keypoints(
keypoints: np.ndarray,
index: int,
volume_shape: tuple[int, int, int]
)Transform keypoints according to the cube transformation specified by index. Args: 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| index | int | - | - |
| volume_shape | tuple[int, int, int] | - | - |
split_uniform_grid_3dfunction
split_uniform_grid_3d(
volume_shape: tuple[int, int, int],
grid: tuple[int, int, int],
random_generator: np.random.Generator
)Splits a 3D volume shape into a uniform grid specified by the grid dimensions. Args: 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 (z_start, y_start, x_start, z_end, y_end, x_end).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume_shape | tuple[int, int, int] | - | - |
| grid | tuple[int, int, int] | - | - |
| random_generator | np.random.Generator | - | - |
create_shape_groups_3dfunction
create_shape_groups_3d(
tiles: np.ndarray
)Groups 3D tiles by their shape and stores the indices for each shape.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| tiles | np.ndarray | - | - |
shuffle_tiles_within_shape_groups_3dfunction
shuffle_tiles_within_shape_groups_3d(
shape_groups: dict[tuple[int, int, int], list[int]],
random_generator: np.random.Generator
)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. Args: shape_groups: Dictionary mapping shapes to list of tile indices with that shape random_generator: Random number generator for shuffling Returns: List where index i contains the new position for tile i
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| shape_groups | dict[tuple[int, int, int], list[int]] | - | - |
| random_generator | np.random.Generator | - | - |
swap_tiles_on_volumefunction
swap_tiles_on_volume(
volume: ImageType,
tiles: np.ndarray,
mapping: list[int]
)Swap tiles on the 3D volume according to the mapping. Args: 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. Note: 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| tiles | np.ndarray | - | - |
| mapping | list[int] | - | - |
swap_tiles_on_keypoints_3dfunction
swap_tiles_on_keypoints_3d(
keypoints: np.ndarray,
tiles: np.ndarray,
mapping: np.ndarray
)Swap the positions of 3D keypoints based on a tile mapping. Args: 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 of the keypoints after the tile swap.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| tiles | np.ndarray | - | - |
| mapping | np.ndarray | - | - |