Release 2.6.0

Summary

• Use float16 NumPy arrays and CPU PyTorch tensors for image and volume augmentation, including batches, masks, and reference data.
• Apply MixUp and input normalization after collation through albumentations.batch. Both operations run outside autograd and return tensors that can feed a trainable model.
• Configure ChannelDropout with an eligible channel set and a dropout ratio. Update older configurations that use channel_drop_range.
• Compose releases input storage promptly after successful calls and calls that raise. Custom samplers that accessed SamplingContext.invocation need the migration below.
• The release uses Albucore 0.3.5 for image kernels and raises the NumKong minimum to 7.8.7.

Breaking changes

ChannelDropout configuration

ChannelDropout replaces channel_drop_range with channels_to_drop and dropout_ratio. Omit channels_to_drop to make all channels eligible, or pass the channel indices that may be replaced. The ratio applies to the eligible set. The transform rounds half up and retains at least one input channel. Single-channel inputs pass through. The default ratio is 0.5, so set it explicitly when migrating a policy that relied on the old default of one dropped channel.

For an RGB input, both examples below select one of three channels. An old count range that sampled multiple possible counts requires a new policy choice because the ratio produces a fixed count for a given eligible set. Update saved configurations that contain the old constructor field. #589

import albumentations as A

# 2.5.1 used A.ChannelDropout(channel_drop_range=(1, 1), fill=0, p=0.5)
rgb_dropout = A.ChannelDropout(dropout_ratio=1 / 3, fill=0, p=0.5)

Custom sampling hooks

SamplingContext.invocation and the invocation= constructor argument have been removed. Read sampling.py_random and sampling.random_generator directly. Inspect inputs and target descriptors through the hook's data and targets arguments. For standalone tests or tools, use SamplingContext.from_seed() for an isolated stream or SamplingContext.from_owner() to draw from a configured transform. This keeps sampling state from holding input buffers after the call ends. Migration guide · #602

# Before
value = sampling.invocation.py_random.uniform(0, 1)

# After
value = sampling.py_random.uniform(0, 1)

Image type annotations and wavelength validation

• albumentations.core.type_definitions.ImageType has been removed. In custom transforms, annotate the dtypes that the operation accepts. For a NumPy operation that accepts all three image dtypes, use NDArray[np.uint8] | NDArray[np.float16] | NDArray[np.float32]. The pinned Albucore release also removes its ImageType alias and exposes convert_dtype for explicit conversions. #614
• WaterRefraction validates both endpoints of wavelength_range at construction. Fractions must lie in [0.001, 1.0]. Update older configurations outside this range. #612

New features

Batch operations for PyTorch training

The new albumentations.batch module operates on collated tensors such as (N, C, H, W) images and (N, C, D, H, W) volumes. It runs separately from per-sample Compose pipelines. Batch Augmentations guide · #618

• sample_mixup creates a seeded MixUpPlan with donor indices and weights. Apply the same plan to inputs and targets that can be interpolated, such as floating-point one-hot labels. The batch, plan, and generator use the same device.
• apply_mixup interpolates in FP32 and returns the input dtype. It writes FP32 results directly into the output and processes larger batches in blocks to limit temporary storage.
• InputNormalizer supports scaling and casting, fixed mean and standard deviation, per-sample normalization, and per-sample normalization over nonzero values. The nonzero mode preserves zero padding. It computes in FP32 and can return FP32, FP16, or BF16. Fixed statistics are copied at construction.

import torch
from albumentations.batch import InputNormalizer, apply_mixup, sample_mixup

images = torch.randint(0, 256, (8, 3, 32, 32), dtype=torch.uint8)
labels = torch.nn.functional.one_hot(torch.arange(8) % 4, num_classes=4).float()
normalizer = InputNormalizer("none", input_scale=255.0, output_precision="fp32")
plan = sample_mixup(
    batch_size=len(images),
    alpha=0.4,
    device=images.device,
    generator=torch.Generator(device=images.device).manual_seed(137),
)

mixed_images = apply_mixup(normalizer(images), plan)
mixed_labels = apply_mixup(labels, plan)

In the paired CPU measurements for #618, an FP32 MixUp batch of eight RGB 512 × 512 images took 1.64 ms with direct output writes, compared with 2.27 ms on the earlier implementation in that PR. Peak tensor allocations, including the result and excluding the existing input, fell from 72 to 48 MiB. Both runs used one thread on Apple M4 Max, Python 3.11.15, and PyTorch 2.15.0. Measurement details

Float16 image and volume pipelines

NumPy and eager CPU PyTorch routes accept float16 for supported image, volume, batch, and mask targets. Dtype-preserving transforms retain float16, and reference and donor inputs can use float16. Bounding boxes, keypoints, and geometric coordinates retain their existing precision contracts. #610

• Normalize preserves float16 output for float16 input, including per-image modes and explicit clipping.
• ToFloat preserves float16 and still scales uint8 inputs to float32. FromFloat accepts float16 and produces uint8.
• ToTensorV2 and ToTensor3D preserve float16 when converting from NumPy to PyTorch.

Bug fixes

• Compose releases input arrays and CPU tensors without waiting for cyclic garbage collection, including optional-channel images, masks, batches, and volumes. This also covers calls that raise exceptions. #596 · #602
• Instance binding realigns companion targets when a spatial operation filters out every bounding box. #591
• Grayscale operations preserve an explicit singleton channel throughout processing, including width-one collections and chained transforms. Compose restores the original rank when it adds a singleton axis for processing. #594
• NumPy fallback from CPU tensors handles read-only array storage safely. Regression tests cover direct and composed calls. #584 · #600
• PlasmaBrightnessContrast clips float16 batches and volumes, including byte-swapped floating arrays. #586
• WaterRefraction rejects invalid wavelengths before sampling a displacement map. The seeded map computation for supported wavelengths is unchanged. #605 · #612
• Normalize gains regression coverage for overflow in moments of large uint8 inputs. The NumKong 7.8.7 minimum supplies the runtime fix. #601 · #613

Misc

• The runtime pins Albucore 0.3.5 and requires NumKong 7.8.7 or later and StringZilla 5.3.2 or later. Albucore now supplies box blur, convolution, erosion, dilation, RGB linear transformations, and unsharp masking. The transform layer keeps its input validation and output contracts. #614
• ChannelDropout reuses its output buffer for eligible scalar fills. #592
• Type checks use the installed backend stubs. The lockfile, development dependencies, and GitHub Actions pins were refreshed. The benchmark guide distinguishes Core-only measurements from checks for changes to AX runtime paths. #610 · #616 · #617
• The release includes a wheel, source distribution, checksums, CycloneDX SBOM, and a Correctness & Compatibility Report. Release verification

Commits

Full changelog: 2.5.1…2.6.0