AlbumentationsX vs Legacy Albumentations
On this page
- What changes when you switch
- Pass CPU tensors directly into Compose
- Keep floating images and volumes in FP16
- Mix and normalize collated batches
- Select video frames with their annotations
- Keep object annotations and labels consistent
- Build policies that operate in three dimensions
- Inspect a sample at each step
- Recent additions for imaging workloads
- Performance
- Migrate an existing pipeline
- Versioned sources
Choose AlbumentationsX for a pipeline that needs ongoing library development, FP16 images or volumes, CPU torch.Tensor input, oriented bounding boxes, linked per-object annotations, or more extensive 3D augmentation. It keeps the familiar Compose workflow and import albumentations as A.
The legacy albumentations package remains available under MIT. Its repository is archived, and its last release is 2.0.8. Keeping that version can make sense when reproducing an existing experiment or maintaining an environment whose dependencies must stay fixed.
This page compares AlbumentationsX 2.6.0 with legacy Albumentations 2.0.8, verified on November 7, 2026. The latest main source was also checked at fbba9b7. Post-release changes are identified below. The migration steps cover installation and the behavior to check before switching.
What changes when you switch
Both libraries already synchronize images with built-in annotation targets, support custom transforms, and provide ReplayCompose and pipeline serialization. Those are shared capabilities. The differences below are reasons to evaluate AX for an existing workload.
| Your requirement | Legacy Albumentations 2.0.8 | AlbumentationsX 2.6.0 |
|---|---|---|
| Receive upstream fixes and new features | Archived repository; last release May 2025 | Maintained release line |
| Augment data already stored as PyTorch tensors | NumPy pipeline input; conversion to Tensor follows augmentation | CPU Tensor input and output; NumPy and Tensor can be mixed across targets |
| Keep floating images and volumes in half precision | Documented uint8/float32 image path; no FP16 pipeline contract | NumPy and CPU Tensor FP16, including collections and reference/donor inputs |
| Mix collated training examples or normalize on the model device | No albumentations.batch module | sample_mixup, apply_mixup, and InputNormalizer outside Compose |
| Select video frames together with their annotations | Shared spatial augmentation across frames | Adds UniformTemporalSubsample and explicit frame_binding |
| Keep one object's mask, box, and pose together when filtering | Separate target arrays | instance_binding removes the bound annotations together |
| Train with oriented bounding boxes (OBB) | Axis-aligned boxes | bbox_type="obb" with validation of the transforms in the pipeline |
| Preserve left/right annotation semantics after a reflection | Application code handles semantic label changes | Configured mappings for keypoint labels and semantic-mask class IDs |
| Apply geometry in three dimensions | 3D crops, padding, dropout, and cubic symmetry | Adds affine transforms, resizing, elastic deformation, and more discrete 3D operations |
| Inspect intermediate results and sampled choices | Replay and applied-parameter logging | Adds execution traces, optional snapshots and timings, and applied-configuration reconstruction |
| Choose license terms | MIT | Commercial license with agreed coverage, or AGPL-3.0-only at no charge under its terms |
A commercial agreement can cover proprietary integration and customer delivery for the teams and products you name. Request a quote or email [email protected]. Compare both options in the license guide. The AGPL permits commercial use subject to its terms; migration itself does not create a payment requirement. The 2.6.0 licensing notice records the license for the version compared here.
Pass CPU tensors directly into Compose
If your decoder or dataset already returns a CPU torch.Tensor, pass it directly to Compose. Image tensors use channel-first layout. A Tensor input returns as a Tensor, so the pipeline does not need a terminal conversion transform.
NumPy and Tensor containers are independent for each target. This example crops and flips a Tensor image with a NumPy segmentation mask. Each result keeps its input container, and the mask follows the image geometry.
import albumentations as A
import numpy as np
import torch
image = torch.arange(72, dtype=torch.uint8).reshape(3, 4, 6)
mask = np.zeros((4, 6), dtype=np.uint8)
mask[1:3, 1:3] = 1
transform = A.Compose(
[A.CenterCrop(height=2, width=4), A.HorizontalFlip(p=1.0)],
seed=137,
)
result = transform(image=image, mask=mask)
assert isinstance(result["image"], torch.Tensor)
assert result["image"].shape == (3, 2, 4)
assert isinstance(result["mask"], np.ndarray)
torch.testing.assert_close(result["image"], image[:, 1:3, 1:5].flip(-1))
np.testing.assert_array_equal(result["mask"], mask[1:3, 1:5][:, ::-1])
Accepted Tensor shapes and dtypes
N is the number of images, masks, or annotation rows; C is channels; D, H, and W are depth, height, and width.
| Target | Tensor shape accepted by Compose | Tensor dtypes |
|---|---|---|
image | (C, H, W) or grayscale (H, W) | uint8, float16, float32 |
images | (N, C, H, W) | uint8, float16, float32 |
volume | (C, D, H, W) | uint8, float16, float32 |
volumes | (N, C, D, H, W) | uint8, float16, float32 |
mask | (C, H, W) or (H, W) | uint8, int16, float16, float32 |
masks | (N, C, H, W) or (N, H, W) | uint8, int16, float16, float32 |
mask3d | (C, D, H, W) or (D, H, W) | uint8, int16, float16, float32 |
masks3d | (N, C, D, H, W) or (N, D, H, W) | uint8, int16, float16, float32 |
bboxes, keypoints | (N, K), where K follows the configured coordinate format | float32 |
For video passed as images, N is the frame count. The Tensor layout is (T, C, H, W); ordinary DataLoader collation adds a batch axis to produce (B, T, C, H, W).
Inputs must be plain CPU torch.Tensor values with torch.strided layout and requires_grad=False. CUDA and MPS tensors, Tensor subclasses, and unlisted dtypes are outside this input contract. Image values use uint8 in [0, 255] or float16/float32 in [0, 1]. Image normalization is an explicit transform in the policy.
When an input omits a supported channel axis, Compose restores that shape if the output still has one channel. NumPy inputs keep their channel-last convention, including (D, H, W) or (D, H, W, C) for a volume.
How Tensor support affects your pipeline
- Remove terminal converters for Tensor input. ToTensorV2 and ToTensor3D accept NumPy input only. If any supplied target is a Tensor, either converter anywhere in the selectable pipeline causes an error, even if its probability is zero.
- CPU augmentation works with GPU training. Run augmentation in your dataset or DataLoader, then transfer the resulting batch to the model's device.
- Execution depends on each applied transform. Tensor-aware handlers run directly. Other transforms convert the Tensor targets they use to NumPy and restore them afterward. This fallback occurs per transform; adjacent transforms can each perform a conversion. A skipped transform performs none.
The NumPy and Tensor input guide for 2.6.0 covers additional targets, annotation processing, and conversion behavior.
Keep floating images and volumes in FP16
AX 2.6.0 accepts NumPy float16 and eager CPU torch.float16 for images, volumes, their collections, supported masks, and reference/donor data. Dtype-preserving transforms retain FP16. This halves the stored bytes per value relative to float32; wider temporary arithmetic means peak memory and runtime still need measurement on your policy.
import albumentations as A
import numpy as np
import torch
image = np.linspace(0, 1, 4 * 6 * 3, dtype=np.float16).reshape(4, 6, 3)
transform = A.Compose([A.HorizontalFlip(p=1.0), A.ToFloat()], seed=137)
array_result = transform(image=image)["image"]
tensor_image = torch.from_numpy(image).permute(2, 0, 1)
tensor_result = transform(image=tensor_image)["image"]
assert array_result.dtype == np.float16
assert tensor_result.dtype == torch.float16
np.testing.assert_array_equal(array_result, image[:, ::-1])
torch.testing.assert_close(tensor_result, tensor_image.flip(-1))
Normalize returns FP16 for FP16 input, including per-image modes. ToFloat preserves FP16 input and converts uint8 to float32; FromFloat produces uint8. ToTensorV2 and ToTensor3D preserve FP16 when converting NumPy targets. Bboxes, keypoints, and geometry keep their existing precision contracts. Keep categorical mask IDs in an integer dtype when exact IDs matter.
FP16 input does not enable CUDA/MPS execution or autograd in Compose. For a collated batch on the model device, use the separate batch API below. The target guide covers dtype and layout choices.
Mix and normalize collated batches
The albumentations.batch module runs after collation. sample_mixup creates a reusable plan of donor indices and weights; apply_mixup applies that plan to images or volumes and floating targets that can validly be interpolated. InputNormalizer scales, normalizes, and casts channel-first image or volume batches, with FP32 arithmetic and FP32, FP16, or BF16 output.
These operations run outside autograd and return inputs for the model's trainable step. They use the batch device, independently of the CPU-only Compose boundary. See Batch Augmentations for a complete example and target constraints.
Select video frames with their annotations
UniformTemporalSubsample(num_frames=...) selects evenly spaced frames, repeating frames when the requested clip is longer than the input. frame_binding=["images", "masks"] keeps one semantic mask attached to each selected frame; frame_binding=["images", "frame_annotations"] supports per-frame annotation dictionaries. This adds temporal selection to the shared spatial augmentation already available in legacy. See Video Augmentation.
Keep object annotations and labels consistent
Filter all annotations belonging to one object together
An instance-segmentation sample can contain one box and mask per object. A crop may remove a box while leaving the corresponding mask entry in a separately managed array. Pose data adds another set of rows that must stay attached to the same object.
With instance_binding, each object is supplied as a dictionary in instances. Configure the fields that belong together, such as instance_binding=["masks", "bboxes"]. If bbox filtering removes an object, its bound fields are removed too. When a mask and bbox are bound, an empty transformed mask also removes the object. This relationship is maintained through crops and mixing operations such as Mosaic and CopyAndPaste.
Use this for per-object masks, boxes, and pose groups. A single semantic-segmentation mask containing class IDs uses the ordinary mask target. The instance segmentation guide gives the input structure and filtering rules.
Describe rotated objects with oriented bounding boxes
For aerial objects, text regions, or other objects whose orientation matters, set bbox_type="obb" in BboxParams. The box representation includes an angle. Compose checks geometric transforms when the pipeline is constructed and rejects operations without OBB support.
Support is specific to the transform. The oriented bounding boxes guide lists coordinate formats and shows a complete pipeline.
Remap left/right labels after a reflection
A geometric flip moves pixels and coordinates. It also changes the meaning of a label such as left_eye or a semantic-mask class representing the left side of an organ. Configure that relationship with KeypointParams.label_mapping or semantic_mask_label_mappings.
Mappings run when the relevant orientation-changing event occurs. The library needs an explicit mapping; it cannot infer the meaning of class IDs or label names. For paired 2D landmarks, remapping can reorder complete keypoint records to preserve the landmark index convention. Three-dimensional keypoint remapping changes label values while retaining transformed row order.
For the mapping fields and examples, see the 2.6.0 KeypointParams reference in source and Compose semantic-mask options.
Build policies that operate in three dimensions
AX expands the geometry you can apply to a volume and its annotations:
| What you want to simulate or change | AX transforms |
|---|---|
| Rotation, scaling, and translation in 3D | Affine3D |
| Resampling depth, height, and width | Resize3D |
| Smooth nonrigid volume deformation | ElasticTransform3D, added in 2.4.4 |
| Reflections, right-angle rotations, or shuffled volume blocks | Flip3D, RandomRotate90_3D, GridShuffle3D |
| Lower acquisition resolution along selected axes | Anisotropy3D |
Check each transform's target support when combining a volume, mask3d, and xyz keypoints. For example, acquisition degradation with Anisotropy3D changes the volume while leaving annotations unchanged. Physical spacing, orientation, and imaging affines remain your data layer's responsibility; array augmentation does not update that metadata.
See volumetric augmentation for layouts and example policies.
Inspect a sample at each step
When an augmented sample looks wrong, AX can show the decisions and intermediate data that produced it. run_with_trace records applied and skipped steps. TraceOptions can request snapshots of selected targets and per-transform timings; tracing is off by default.
Three tools answer different debugging questions:
| Your question | API to use |
|---|---|
| Which step changed this sample? | run_with_trace, optionally with TraceOptions(snapshot_targets=("image", "bboxes")) |
| Which constructor choices were realized? | save_applied_params=True and Compose.from_applied_transforms(...) |
| How do I repeat the sampled crop coordinates, dropout mask, and other runtime parameters? | ReplayCompose |
Legacy already has ReplayCompose. AX's applied-configuration reconstruction is an additional inspection tool: it makes a runnable policy from realized constructor settings, but those settings alone do not preserve every random array or sampled coordinate. Use Replay and Applied-Parameter Debugging to choose the appropriate mechanism.
Recent additions for imaging workloads
These examples highlight additions and extensions available in 2.6.0. Each transform's Explore page describes its parameters and supported targets.
| Workload | Capability |
|---|---|
| MRI acquisition artifacts | BiasField, GhostingArtifact, GibbsRinging, and MotionArtifact add intensity inhomogeneity and k-space artifact policies. |
| MRI spikes and magnitude noise | KSpaceSpikeNoise adds Fourier-domain spikes to images or volumes; introduced in 2.4.4. RicianNoise provides magnitude-MRI noise simulation. |
| Appearance variation through random filtering | StochasticConvolution applies randomly perturbed convolution kernels; introduced in 2.4.4. |
| Uneven lighting with several illuminated regions | Illumination supports multiple Gaussian spots in 2.4.4. |
| Histology with a known stain basis | HEStain extends custom stain-matrix support to complete (3, 3) bases. |
| Detection with constrained crops or pasted objects | BBoxSubsetSafeRandomCrop, LetterBox, and CopyAndPaste |
Performance
If augmentation cannot prepare the next batch in time, the GPU waits. For training workloads, measure the complete DataLoader pipeline with your worker count, batch size, image sizes, and transform sequence. A faster individual transform helps only to the extent that it reduces the bottleneck in that pipeline.
The RGB benchmark includes DataLoader pipelines and individual-transform measurements. The multichannel and video results cover other input shapes. Read the package versions, hardware, execution route, and methodology alongside each result.
To measure the benefit of migrating from legacy, run both pinned versions on equivalent inputs and policies in separate environments. The published RGB benchmark does not establish a legacy-to-AX speedup unless both versions appear in the same measured workload. Tensor input support also does not guarantee a faster policy: the applied transforms may use NumPy fallback.
Migrate an existing pipeline
Install the runtime and package
Use a separate environment for AX while keeping the legacy environment available for comparison. Both distributions install the albumentations Python namespace; do not install them together.
First install the PyTorch build appropriate for your operating system and CPU, CUDA, or MPS setup using the PyTorch installation selector. AX requires PyTorch at import time even when you pass NumPy arrays or train with TensorFlow, Keras, or JAX. The package does not install or select a PyTorch build for you.
Then install AX with an OpenCV variant. For a server or container without GUI support, this command installs the version reviewed on this page:
python -m pip install "albumentationsx[headless]==2.6.0"
Choose gui, contrib, or contrib-headless instead when those OpenCV capabilities are needed. If you already manage OpenCV separately, install albumentationsx==2.6.0 without an OpenCV extra.
The Python import stays the same:
import albumentations as A
assert A.__version__ == "2.6.0"
Check the policy on representative samples
- Start with your existing augmentation policy. Check constructor parameters and warnings against the selected AX release. Coordinate processors use
coord_format, and range arguments use current names such asRotate.angle_rangeandBlur.blur_range.ChannelDropoutuseschannels_to_dropanddropout_ratioinstead ofchannel_drop_range; for one dropped RGB channel, setdropout_ratio=1 / 3. Keeping the import name does not guarantee identical behavior across versions. - Check the data boundary. Compare output shapes, dtypes, value ranges, bbox formats, keypoint labels, and any filtered objects. For Tensor input, use the shapes above and remove terminal Tensor converters.
- Check annotations visually. Include small objects, partly cropped objects, left/right labels, and 3D samples if they occur in your dataset. A matching image shape alone cannot establish annotation correctness.
- Add capabilities where your data needs them. Introduce instance binding, semantic remapping, or OBB processing with samples that exercise the corresponding behavior.
- Measure the workload you intend to run. Compare loader throughput and training step time with the same inputs and resources. Use a fixed evaluation protocol to assess model quality; the same random seed need not produce identical augmentations across library versions.
Changes already merged after 2.6.0
The checked main revision adds guarantees and fixes beyond the release compared above:
- Root validation runs before probability and sampling draws, including
p=0and traced calls; rejected root inputs do not advance the configured stream. - Geometry fixes cover OBB refitting under unequal resize scales, perspective and remap geometry, and annotation mapping when replaying resize operations on a different frame size.
ReplayComposerecords ordered and repeated visits throughSomeOfandRandomOrder. Older records remain readable, but cannot recover visit information they never saved.
Use the development revision for those changes, or wait for a release that contains it. See the validation, geometry, and determinism contracts for the current behavior.
Versioned sources
- Legacy 2.0.8 release and archived source repository.
- AX 2.6.0 release notes.
- AX 2.6.0 source, including the Tensor contract and tracing contract.