AlbumentationsX 2.0.18 Release Notes

New Transform: PhotoMetricDistort

PhotoMetricDistort implements the photometric distortion pipeline from the SSD paper, matching the API and default parameters of torchvision's RandomPhotometricDistort.

Each of the five distortions — brightness, contrast, saturation, hue, and channel shuffle — is applied independently with probability distort_p. Contrast placement is randomized: it can appear either before or after the HSV-space adjustments (saturation + hue), mirroring the SSD paper's stochastic ordering.

import albumentations as A

transform = A.PhotoMetricDistort(
    brightness_range=(0.875, 1.125),  # multiplicative factor
    contrast_range=(0.5, 1.5),        # multiplicative factor
    saturation_range=(0.5, 1.5),      # multiplicative factor
    hue_range=(-0.05, 0.05),          # additive factor, range [-0.5, 0.5]
    distort_p=0.5,                    # probability per individual distortion
    p=0.5,                            # probability the whole transform runs
)

Key differences from torchvision:

• torchvision uses a single p that applies to each distortion; AlbumentationsX separates distort_p (per-distortion) from p (the overall transform gate), giving independent control.
• All default parameter values are identical to torchvision's RandomPhotometricDistort.

Supported targets: image, volume
Supported dtypes: uint8, float32
Channels: 1 (grayscale) and 3 (RGB) only — same constraint as torchvision

ColorJitter: Fused Brightness + Contrast

As part of the same PR, ColorJitter received a performance improvement. The four color operations are applied in a random order each call. When brightness and contrast happen to be adjacent in the shuffle (approximately 50% of calls, since 12 of the 24 possible orderings place them next to each other), they are now fused into a single operation:

• uint8: the two transforms are composed analytically into a single 256-entry LUT applied in one cv2.LUT call instead of two sequential passes
• float32: a single pre-allocated output buffer with in-place numpy ops avoids 4+ intermediate array allocations

The speedup is modest in the aggregate because the fusion only applies to the ~50% of calls where brightness and contrast are adjacent; the other ~50% are unchanged.

Performance: Multi-Channel Speedups (5+ Channels)

AlbumentationsX now requires OpenCV ≥ 4.13 and albucore ≥ 0.0.39. OpenCV 4.13 extended native multi-channel support for several operations. The previous code always split images with more than 4 channels into ≤4-channel chunks and processed them sequentially. The new code calls OpenCV directly when supported, falling back to chunking only when genuinely required.

All benchmarks: 512×512 images, 100 iterations, Apple M-series, macOS.

Blur (cv2.blur)

cv2.blur has always supported arbitrary channel counts natively — the chunking was unnecessary. The new code calls it directly with dst=img (in-place).

MedianBlur

OpenCV 4.13 added native multi-channel support for cv2.medianBlur when ksize is 3 or 5. For ksize ≥ 7, OpenCV's internal SIMD path still asserts channels ≤ 4, so chunking remains necessary there.

ksize = 5 — native multi-channel path (fast):

ksize = 7 — still chunked for >4 channels (no change expected):

Affine, Rotate, ShiftScaleRotate, SafeRotate (warp_affine)

These transforms now route through albucore.warp_affine, which calls cv2.warpAffine directly for multi-channel images when the interpolation mode is INTER_NEAREST, INTER_LINEAR, or INTER_AREA. For INTER_CUBIC, INTER_LANCZOS4, and INTER_LINEAR_EXACT, chunking is still required.

The default interpolation is INTER_LINEAR, so most users get the speedup automatically.

Affine (scale + rotate, INTER_LINEAR — default):

Affine (INTER_CUBIC — still chunked for >4 channels):

Rotate (INTER_LINEAR):

ShiftScaleRotate (INTER_LINEAR):

SafeRotate (INTER_LINEAR):

Perspective (warp_perspective)

Same interpolation-mode rules as warp_affine.

Perspective (INTER_LINEAR — default):

Perspective (INTER_CUBIC — still chunked for >4 channels):

ElasticTransform, GridDistortion, OpticalDistortion, ThinPlateSpline, PiecewiseAffine (remap)

All transforms that inherit from BaseDistortion route through albucore.remap. The native multi-channel path is available for INTER_NEAREST, INTER_LINEAR, INTER_AREA, and INTER_LINEAR_EXACT. For INTER_CUBIC and INTER_LANCZOS4, chunking remains necessary.

Note: ElasticTransform dominates its time on cv2.remap but also generates random displacement fields — the speedup for high channel counts reflects both the faster remap and that field generation is channel-independent. GridDistortion and OpticalDistortion show even larger speedups because their maps are smaller and the remap dominates.

ElasticTransform (INTER_LINEAR):

ElasticTransform (INTER_CUBIC — still chunked for >4 channels):

GridDistortion (INTER_LINEAR):

OpticalDistortion (INTER_LINEAR):

Pad, PadIfNeeded, CenterCrop, RandomCrop, Crop, CropAndPad (copy_make_border)

All padding operations now route through albucore.copy_make_border. For constant-value padding with a scalar fill (the most common case), cv2.copyMakeBorder supports arbitrary channel counts natively — no chunking needed. Per-channel fill with more than 4 distinct values still uses chunking.

PadIfNeeded (scalar fill, fill=0):

CenterCrop (pad when crop > image size):

CropAndPad:

Note: CropAndPad includes a resize step that still uses separate cv2 calls; the speedup is lower than pure pad transforms.

Summary of Affected Transforms

Requirements

• OpenCV ≥ 4.13.0.92 (previously ≥ 4.9.0.80)
• albucore == 0.0.39 (previously == 0.0.36)

Big thanks to @stark0908 for pointing the latests changes in OpenCV functionality that allowed to speed up multichannel transforms.