albumentations.augmentations.medical.transforms

Simulate thicker or lower-resolution volume acquisition by degrading selected spatial axes and restoring the original grid for 3D model robustness training. The transform samples a subset from `axes` and one downsampling factor for every selected axis. Both NumPy and CPU Tensor routes delegate spatial resizing to Albucore `resize3d`. PyTorch does not currently provide antialiasing for 5D trilinear interpolation, so Tensor input remains non-antialiased when `antialias=True`. `mask3d` remains unchanged because this is an image-acquisition artifact, not a geometry transform.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> volume = np.random.default_rng(137).integers(0, 256, (32, 128, 128, 1), dtype=np.uint8)
>>> transform = A.Compose([
...     A.Anisotropy3D(
...         axes=(0,),
...         num_axes_range=(1, 1),
...         downscale_factor_range=(2.0, 2.0),
...         p=1.0,
...     ),
... ])
>>> result = transform(volume=volume)
>>> result["volume"].shape
(32, 128, 128, 1)

Simulate smooth MRI intensity inhomogeneity by multiplying images and volumes by a positive field sampled on a coarse spatial grid. The transform samples zero-mean Gaussian log-gain coefficients, interpolates them across all spatial axes, and exponentiates the result. The field changes tissue intensity across space while preserving anatomy labels.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> volume = np.full((16, 64, 96, 1), 0.25, dtype=np.float32)
>>> mask3d = np.zeros((16, 64, 96), dtype=np.uint8)
>>> pipeline = A.Compose([
...     A.BiasField(std_range=(0.1, 0.3), scale_range=(0.02, 0.04), p=1),
... ], seed=137, strict=True)
>>> result = pipeline(volume=volume, mask3d=mask3d)
>>> result["volume"].shape
(16, 64, 96, 1)

Notes

- Images use bilinear interpolation over `(H, W)`; volumes use trilinear interpolation over `(D, H, W)`. Singleton axes remain singleton. Batch elements and aligned additional targets share sampled coefficients. - The coarse axis length is `min(size, max(2, int(size * scale)))`. The standard deviation describes the coarse coefficients; interpolation generally reduces the final log-field variance. - The positive gain is `exp(interpolated_log_gain)`. Results are clipped to `[0, 1]` for float32 and rounded back into `[0, 255]` for uint8. Clipping can change contrast near the intensity maximum. - TorchIO uses `std=0.5` and `scale=0.025` as reference MRI settings. The default range samples up to that strength. Strong fields can obscure tissue contrast or alter clinical semantics; inspect augmented examples for the intended anatomy and task. - Parameters use voxel dimensions. Physical spacing and scanner-specific coil sensitivity are not modelled.

References

• [{'description': 'TorchIO BiasField', 'source': 'https://docs.torchio.org/2.0/reference/transforms/bias_field/'}]

Simulate repeated MRI ghost replicas along one spatial axis by attenuating periodic k-space planes while protecting central frequencies. Periodic frequency loss creates displaced copies of anatomy in the reconstructed magnitude volume. The same acquisition parameters apply to every channel and collection item; anatomy annotations stay unchanged.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> volume = np.random.default_rng(137).random((16, 64, 96, 1), dtype=np.float32)
>>> mask3d = np.zeros((16, 64, 96), dtype=np.uint8)
>>> pipeline = A.Compose([
...     A.GhostingArtifact(num_ghosts_range=(2, 4), intensity_range=(0.2, 0.5), axis=1, p=1),
... ], seed=137, strict=True)
>>> result = pipeline(volume=volume, mask3d=mask3d)
>>> result["volume"].shape
(16, 64, 96, 1)

Notes

- Inputs are real magnitude volumes. `Compose` supplies canonical NumPy `(D, H, W, C)` layouts and restores optional singleton channel dimensions. Complex input is unsupported. - The comb is anchored at DC: positive and negative frequencies that are multiples of `num_ghosts` are multiplied by `1 - intensity` outside the protected band. This preserves conjugate symmetry. - FFT/IFFT use backward normalization. A real FFT along the selected spatial axis is mathematically equivalent to a full 3D FFT with this plane mask; batch and channel axes are never transformed. - Reconstruction takes the absolute value and clips to `[0, 1]` for float32, or rounds back into `[0, 255]` for uint8. Magnitude and clipping can change the mean despite preserving central coefficients. - Non-divisible axis lengths give sampled, broadened replicas. If no affected frequency fits outside the protected band, the transform is an exact identity. This includes a singleton selected axis. - Physical spacing and scanner trajectories are not modelled. Select the axis for the input layout and inspect strong artifacts for the intended anatomy and task.

References

• [{'description': 'TorchIO Ghosting', 'source': 'https://docs.torchio.org/2.0/reference/transforms/ghosting/'}]

Simulate Gibbs ringing near sharp intensity boundaries by truncating high-frequency k-space in an image or a whole 3D volume. A hard rectangular frequency cutoff creates oscillations and reduces spatial resolution. Use it to model finite Cartesian acquisition bandwidth; it is a generic artifact simulation, not a correction algorithm.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> image = np.zeros((64, 96, 1), dtype=np.float32)
>>> image[16:48, 24:72] = 0.75
>>> transform = A.GibbsRinging(retained_fraction_range=(0.4, 0.8), p=1)
>>> augmented = transform(image=image)["image"]
>>> volume = np.zeros((16, 64, 96, 1), dtype=np.float32)
>>> volume[4:12, 16:48, 24:72] = 0.75
>>> pipeline = A.Compose([transform], seed=137, strict=True)
>>> result = pipeline(volume=volume)["volume"]
>>> result.shape
(16, 64, 96, 1)

Notes

- `Compose` normalizes optional channel axes. Direct calls use explicit channel-last `(H, W, C)` images or `(D, H, W, C)` volumes. - FFT/IFFT operate over `(H, W)` for images and `(D, H, W)` for volumes, including singleton depth. Channels and collection items are independent signals with one shared sampled cutoff fraction. - On an axis of length `N`, retain signed frequency indices with `abs(k) <= floor(retained_fraction * N / 2)`. DC is always included. Even-length Nyquist bins are retained only when the cutoff reaches `N / 2`; odd lengths use their actual signed bins. - The retained region is a rectangle in 2D and a rectangular box in 3D. The fraction describes bandwidth along each axis, not the fraction of all Fourier coefficients or physical voxel spacing. - FFT normalization is backward. The symmetric mask gives a real inverse reconstruction; no magnitude operation is applied. Fourier boundaries are periodic, so image-border jumps can ring. - Inputs must be finite real uint8, float16 or float32 arrays; floating inputs are expected in `[0, 1]`. Floating reconstruction is clipped to `[0, 1]`; uint8 is processed in float32 and rounded back into `[0, 255]`. Clipping can change the mean. - Cutoffs are discrete. Nearby fractions can select the same bins, and sufficiently small arrays can retain their entire spectrum. Removing more frequencies does not guarantee a larger local overshoot.

References

• [{'description': 'Gibbs Ringing in Diffusion MRI', 'source': 'https://pmc.ncbi.nlm.nih.gov/articles/PMC4915073/'}]

Perturb stain concentrations in histology images to simulate color variation across laboratories, scanners, protocols, and staining panels. Use this transform to train pathology models against expected staining variation. It converts RGB values to optical density, separates the stain concentrations with the selected basis, perturbs the configured components, and reconstructs the RGB image.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>>
>>> image = np.zeros((300, 300, 3), dtype=np.uint8)
>>> image[50:150, 50:150] = np.array([120, 140, 180], dtype=np.uint8)  # Hematoxylin-rich region
>>> image[150:250, 150:250] = np.array([140, 160, 120], dtype=np.uint8)  # Eosin-rich region
>>>
>>> # Example 1: Map HEDJitter(theta) to a full H&E+DAB basis
>>> theta = 0.05
>>> hed_basis = np.array(
...     [
...         [0.65, 0.70, 0.29],  # Hematoxylin
...         [0.07, 0.99, 0.11],  # Eosin
...         [0.27, 0.57, 0.78],  # DAB
...     ],
...     dtype=np.float32,
... )
>>> transform = A.HEStain(
...     method="custom",
...     stain_matrix=hed_basis,
...     residual_mode="augment",
...     intensity_scale_range=(1 - theta, 1 + theta),
...     intensity_shift_range=(-theta, theta),
...     augment_background=True,
...     p=1.0,
... )
>>> transformed_image = transform(image=image)["image"]
>>>
>>> # Example 2: Using a specific preset stain matrix
>>> transform = A.HEStain(
...     method="preset",
...     preset="standard",
...     intensity_scale_range=(0.8, 1.2),
...     intensity_shift_range=(-0.1, 0.1),
...     augment_background=False,
...     p=1.0,
... )
>>> transformed_image = transform(image=image)["image"]
>>>
>>> # Example 3: Using random preset selection
>>> transform = A.HEStain(
...     method="random_preset",
...     intensity_scale_range=(0.7, 1.3),
...     intensity_shift_range=(-0.15, 0.15),
...     p=1.0,
... )
>>> transformed_image = transform(image=image)["image"]
>>>
>>> # Example 4: Using Vahadane extraction (requires an H&E stained input)
>>> transform = A.HEStain(
...     method="vahadane",
...     intensity_scale_range=(0.7, 1.3),
...     p=1.0,
... )
>>> transformed_image = transform(image=image)["image"]
>>>
>>> # Example 5: Using Macenko extraction (requires an H&E stained input)
>>> transform = A.HEStain(
...     method="macenko",
...     intensity_scale_range=(0.7, 1.3),
...     intensity_shift_range=(-0.2, 0.2),
...     p=1.0,
... )
>>> transformed_image = transform(image=image)["image"]
>>>
>>> # Example 6: Combining stain and brightness variation in one pipeline
>>> transform = A.Compose([
...     A.HEStain(method="preset", preset="high_contrast", p=1.0),
...     A.RandomBrightnessContrast(p=0.5),
... ])
>>> transformed_image = transform(image=image)["image"]

Notes

- Let `M` be the stain matrix and `C` the per-pixel concentrations. `"project"` solves `OD ~= C @ M`, perturbs H&E, and reconstructs `RGB = exp(-(C * scale + shift) @ M)`. - For a `(2, 3)` matrix, `"preserve"` and `"augment"` derive `R = normalize(cross(H, E))` and solve the full H&E+R basis. A `(3, 3)` matrix uses its third row directly. - A custom matrix is fixed for the lifetime of the transform. Per-image callable extraction is not supported.

References

• [{'description': 'A. C. Ruifrok and D. A. Johnston, "Quantification of histochemical"', 'source': 'Analytical and quantitative cytology and histology, 2001.'}, {'description': 'M. Macenko et al., "A method for normalizing histology slides for', 'source': '2009 IEEE International Symposium on quantitative analysis," 2009 IEEE International Symposium on Biomedical Imaging, 2009.'}, {'description': 'D. Tellez et al., "H&E stain augmentation improves generalization of convolutional networks for histopathological mitosis detection"', 'source': 'Medical Imaging, 2018.'}]

Inject point spikes into the MRI k-space spectrum and reconstruct the image or volume, producing structured stripes typical of acquisition failures. K-space spike artifacts arise from isolated high-energy points in the Fourier representation of MRI data (e.g. scanner spikes, radio-frequency interference). Each sampled spike adds a real amplitude at its frequency and at the conjugate mirror, keeping the spectrum Hermitian so the reconstruction is real.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)
>>> transform = A.Compose(
...     [A.KSpaceSpikeNoise(num_spikes_range=(2, 4), intensity_range=(0.1, 0.3), p=1.0)],
...     seed=137,
... )
>>> spiked = transform(image=image)["image"]

Notes

- Fourier frequencies refer to spatial axes only; batch and channel dimensions are excluded. Shared float32 volume spikes can be reconstructed analytically. Float32 results may differ from FFT reconstruction by roundoff; uint8 retains FFT reconstruction and its rounding. - Each spike injects a real amplitude `intensity * max|F|` at the sampled bin and at its conjugate mirror, so the half-spectrum stays Hermitian and the reconstruction is real without discarding imaginary parts. Self-conjugate bins (DC and the Nyquist bin of even axes) are injected once. - Spikes are uniform over the full frequency grid, including DC. A spike at DC shifts the global mean rather than creating stripes; this is intentional and documented. - A spike of relative amplitude `i` turns a flat field of value `c` into a cosine pattern of amplitude `2 * i * c` along the spike's frequency direction. - One spike realization is sampled per transform invocation and reused across all channels (shared mode), all images in a batch, and the whole volume as a single 3D transform. - uint8 inputs are processed as float32 in [0, 1] and converted back with rounding, so outputs stay within [0, 255]; float32 outputs are clipped to [0, 1]. - This differs from image-space impulse noise (SaltAndPepper), which replaces individual pixels, and from RingingOvershoot, which convolves in the image domain.

References

• [{'description': 'TorchIO RandomSpike', 'source': 'https://docs.torchio.org/2.0/reference/transforms/spike/'}, {'description': 'TorchIO paper', 'source': 'https://www.sciencedirect.com/science/article/pii/S0169260721003102'}]

Simulate motion artifacts in 3D MRI volumes by combining k-space from successive rigid movement states during image acquisition. The transform acquires consecutive planes of centred k-space along one selected axis. The initial segment uses the original volume; each subsequent segment uses an independently sampled absolute rotation and translation of that volume. A magnitude inverse FFT reconstructs the corrupted image. Anatomy annotations stay unchanged.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> volume = np.random.default_rng(137).random((16, 64, 96, 1), dtype=np.float32)
>>> transform = A.Compose([A.MotionArtifact(num_events_range=(1, 2), p=1)], seed=137, strict=True)
>>> result = transform(volume=volume)
>>> result["volume"].shape
(16, 64, 96, 1)

Notes

- Inputs are real magnitude volumes `(D, H, W)` or `(D, H, W, C)`. Every spatial axis must have at least two voxels. Complex-valued input is unsupported. - Event boundaries are sampled uniformly without replacement from the interior acquisition-plane boundaries. The event time is the boundary index divided by the selected axis length. - Channels, collection items, and additional volumes share the same event times and motion states. FFTs operate over `(D, H, W)` only, independently for each channel and collection item. - Resampling uses zero padding. FFT/IFFT use backward normalization; the magnitude of the complex reconstruction is clipped to `[0, 1]` for float32 or converted back to `[0, 255]` for uint8. - Rotations and translations use voxel coordinates. Physical spacing and scanner acquisition trajectories are not modelled. Parameter strength must be chosen for the anatomy and task. - Runtime grows with the number of events. Moved volumes and spectra are processed one at a time.

References

• [{'description': 'TorchIO Motion', 'source': 'https://docs.torchio.org/2.0/reference/transforms/motion/'}, {'description': 'Shaw et al., 2019', 'source': 'https://proceedings.mlr.press/v102/shaw19a.html'}]

Simulate MRI magnitude reconstruction with Gaussian real and imaginary components, yielding Rician noise and a positive low-signal noise floor. The transform computes sqrt((signal + n_real)^2 + n_imag^2). Unlike additive Gaussian noise, this model remains biased upward at low signal-to-noise ratios, matching magnitude MRI reconstruction.

Parameters

Examples

>>> import albumentations as A
>>> import numpy as np
>>> image = np.random.default_rng(137).integers(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.RicianNoise(std_range=(0.05, 0.15), p=1.0)
>>> noisy_image = transform(image=image)["image"]

Notes

- Volumes receive one independently sampled full-depth field rather than a slice-wise image batch. - A sampled standard deviation of zero is an exact identity.

References

• [{'description': 'Gudbjartsson & Patz (1995)', 'source': 'https://doi.org/10.1002/mrm.1910340618'}]