1.0.0

Breaking changes

• imgaug dependency is now optional, and by default, Albumentations won't install it. This change was necessary to prevent simultaneous install of both opencv-python-headless and opencv-python (you can read more about the problem in this issue). If you still need imgaug as a dependency, you can use the pip install -U albumentations[imgaug] command to install Albumentations with imgaug.
• Deprecated augmentation ToTensor that converts NumPy arrays to PyTorch tensors is completely removed from Albumentations. You will get a RuntimeError exception if you try to use it. Please switch to ToTensorV2 in your pipelines.

New augmentations

• A.RandomToneCurve. See a notebook for examples of this augmentation (#839 by @aaroswings)
• SafeRotate. Safely Rotate Images Without Cropping (#888 by @deleomike)
• SomeOf transform that applies N augmentations from a list. Generalizing of OneOf (#889 by @henrique)
• We are deprecating imgaug transforms and providing Albumentations' implementations for them.
  (#786 by @KiriLev, #787 by @KiriLev, #790, #843, #844, #849, #885, #892)

By default, Albumentations doesn't require imgaug as a dependency. But if you need imgaug, you can install it along with Albumentations by running pip install -U albumentations[imgaug].

Here is a table of deprecated imgaug augmentations and respective augmentations from Albumentations that you should use instead:

Old deprecated augmentation	New augmentation
IAACropAndPad	CropAndPad
IAAFliplr	HorizontalFlip
IAAFlipud	VerticalFlip
IAAEmboss	Emboss
IAASharpen	Sharpen
IAAAdditiveGaussianNoise	GaussNoise
IAAPerspective	Perspective
IAASuperpixels	Superpixels
IAAAffine	Affine
IAAPiecewiseAffine	PiecewiseAffine

Major changes

• Serialization logic is updated. Previously, Albumentations used the full classpath to identify an augmentation (e.g. albumentations.augmentations.transforms.RandomCrop). With the updated logic, Albumentations will use only the class name for augmentations defined in the library (e.g., RandomCrop). For custom augmentations created by users and not distributed with Albumentations, the library will continue to use the full classpath to avoid name collisions (e.g., when a user creates a custom augmentation named RandomCrop and uses it in a pipeline).

  This new logic will allow us to refactor the code without breaking serialized augmentation pipelines created using previous versions of Albumentations. This change will also reduce the size of YAML and JSON files with serialized data.

  The new serialization logic is backward compatible. You can load serialized augmentation pipelines created in previous versions of Albumentations because Albumentations supports the old format.

Bugfixes

• Fixed a bug that prevented A.ReplayCompose to work with bounding boxes and keypoints correctly. (#748)
• A.GlassBlur now correctly works with float32 inputs (#826)
• MultiplicativeNoise now correctly works with gray images with shape [h, w, 1]. (#793)

Minor changes

• Code for geometric transforms moved to a standalone module albumentations.augmentations.geometric. (#784)
• Code for crop transforms moved to a standalone module albumentations.augmentations.crops. (#791)
• CI now runs tests under Python 3.9 as well (#830)
• Linters and code formatters for CI and pre-commit hooks are updated to the latest versions (#831)
• Logic in setup.py that detects existing installations of OpenCV now also looks for opencv-contrib-python and opencv-contrib-python-headless (#837 by @agchang-cgl)

0.5.2

Minor changes

• ToTensorV2 now automatically expands grayscale images with the shape [H, W] to the shape [H, W, 1]. PR #604 by @Ingwar.
• CropNonEmptyMaskIfExists now also works with multiple masks that are provided by the masks argument to the transform function. Previously this augmentation worked only with a single mask provided by the mask argument. PR #761

0.5.1

Breaking changes

• API for A.FDA is changed to resemble API of A.HistogramMatching. Now, both transformations expect to receive a list of reference images, a function to read those image, and additional augmentation parameters. (#734)
• A.HistogramMatching now usesread_rgb_image as a default read_fn. This function reads an image from the disk as an RGB NumPy array. Previously, the default read_fn was cv2.imread which read an image as a BGR NumPy array. (#734)

New transformations

• A.Sequential transform that can apply augmentations in a sequence. This transform is not intended to be a replacement for A.Compose. Instead, it should be used inside A.Compose the same way A.OneOf or A.OneOrOther. For instance, you can combine A.OneOf with A.Sequential to create an augmentation pipeline containing multiple sequences of augmentations and apply one randomly chosen sequence to input data. (#735)

Minor changes

• A.ShiftScaleRotate now has two additional optional parameters: shift_limit_x and shift_limit_y. If either of those parameters (or both of them) is set A.ShiftScaleRotate will use the set values to shift images on the respective axis. (#735)
• A.ToTensorV2 now supports an additional argument transpose_mask (False by default). If the argument is set to True and an input mask has 3 dimensions, A.ToTensorV2 will transpose dimensions of a mask tensor in addition to transposing dimensions of an image tensor. (#735)

Bugfixes

• A.FDA now correctly uses coordinates of the center of an image. (#730)
• Fixed problems with grayscale images for A.HistogramMatching. (#734)
• Fixed a bug that led to an exception when A.load() was called to deserialize a pipeline that contained A.ToTensor or A.ToTensorV2, but those transforms were not imported in the code before the call. (#735)

0.5.0

Breaking changes

• Albumentations now explicitly checks that all inputs to augmentations are named arguments and raise an exception otherwise. So if an augmentation receives input like aug(image) instead of aug(image=image), Albumentations will raise an exception. (#560)
• Dropped support of Python 3.5 (#709)
• Keypoints and bboxes are checked for visibility after each transform (#566)

New transformations

• A.FDA transform for Fourier-based domain adaptation. (#685)
• A.HistogramMatching transform that applies histogram matching. (#708)
• A.ColorJitter transform that behaves similarly to ColorJitter from torchvision (though there are some minor differences due to different internal logic for working with HSV colorspace in Pillow, which is used in torchvision and OpenCV, which is used in Albumentations). (#705)

Minor changes

• A.PadIfNeeded now accepts additional pad_width_divisor, pad_height_divisor (None by default) to ensure image has width & height that is dividable by given values. (#700)
• Added support to apply A.CoarseDropout to masks via mask_fill_value. (#699)
• A.GaussianBlur now supports the sigma parameter that sets standard deviation for Gaussian kernel. (#674, #673) .

Bugfixes

• Fixed bugs in A.HueSaturationValue for float dtype. (#696, #710)
• Fixed incorrect rounding error on bboxes in YOLO format. (#688)

0.4.6

Improvements

• Change the ImgAug dependency version from “imgaug>=0.2.5,<0.2.7” to “imgaug>=0.4.0". Now Albumentations won’t downgrade your existing ImgAug installation to the old version. PR #658.
• Do not try to resize an image if it already has the required height and width. That eliminates the redundant call to the OpenCV function that requires additional copying of the input data. PR #639.
  ReplayCompose is now serializable. PR #623 by IlyaOvodov
• Documentation fixes and updates.

Bug Fixes

• Fix a bug that causes some keypoints and bounding boxes to lie outside the visible part of the augmented image if an augmentation pipeline contained augmentations that increase the height and width of an image (such as PadIfNeeded). That happened because Albumentations checked which bounding boxes and keypoints lie outside the image only after applying all augmentations. Now Albumentations will check and remove keypoints and bounding boxes that lie outside the image after each augmentation. If, for some reason, you need the old behavior, pass check_each_transform=False in your KeypointParams or BboxParams. Issue #565 and PR #566.
• Fix a bug that causes an exception when Albumentations received images with the number of color channels that are even but are not multiples of 4 (such as 6, 10, etc.). PR #638.
• Fix the off-by-one error in applying steps for GridDistortion. Commit 9c225a9
• Fix bugs that prevent serialization of ImageCompression and GaussNoise. PR #569
• Fix a bug that causes errors with some values for label_fields in BboxParams. PR #504 by IlyaOvodov
• Fix a bug that prevents HueSaturationValue for working with grayscale images. PR #500.

0.4.0

Table of Contents

• New transforms

  • ISONoise
  • Solarize
  • Equilize
  • Posterize
  • ImageCompression
  • Downscale
  • RandomResizedCrop
  • RandomGridShuffle
  • CropNonEmptyMaskIfExists
  • ToTensorV2

• New features

  • Added YOLO format to bounding boxes
  • Deterministic / Replay mode

• Improvements

  • Added fill_value to Cutout
  • Separate fill_value for image and mask targets
  • Speedup in RGBShift transform
  • Speedup in HueSaturationValue
  • Speedup in RandomBrightnessContrast
  • Speedup in RandomGamma
  • Added support for images and masks with more than 3 channels
  • Added key points support to Crop, CropNonEmptyMaskIfExists, LongestMaxSize, RandomCropNearBBox, Resize, SmallestMaxSize, and Transpose
  • Add per channel transform composition

• Bug Fixes

  • Bugfix in GaussNoise
  • Bugfix in RandomGamma
  • Bugfix in RandomSizedBBoxSafeCrop

• Documentation Updated

  • Added page that lists pre-prints and papers that cite albumentations
  • Added page that contains competitions in which top teams used albumentations

New transforms

ISONoise

2e25667
Target: image

This transform mimics the noise that images will have if the ISO parameter of the camera is high. Wiki

Solarize

e365b52
Targets: image

Solarize inverts all pixels above some threshold. It is an essential part of the work AutoAugment: Learning Augmentation Policies from Data.

Equilize

9f71038
Target: image

Equalizes image histogram. It is an essential part of the work AutoAugment: Learning Augmentation Policies from Data.

Posterize

ad95fa0
Target: image

Reduce the number of bits for each pixel. It is an essential part of the work AutoAugment: Learning Augmentation Policies from Data.

ImageCompression

Target: image
b612786
Decrease Jpeg or WebP compression to the image.

Downscale

df831d6
Target: image

Decreases image quality by downscaling and upscaling back.

RandomResizedCrop

4dbe41e
Targets: image, mask, bboxes, keypoints

Crop the given Image to the random size and aspect ratio. This transform is an essential part of many image classification pipelines. Very popular for ImageNet classification.

It has the same API as RandomResizedCrop in torchvision.

RandomGridShuffle

4cf6c36
Targets: image, mask

Partition an image into tiles. Shuffle them and merge back.

CropNonEmptyMaskIfExists

Targets: image, mask, bboxes, keypoints

Crop area with a mask if the mask is non-empty, else make a random crop.

ToTensorV2

a502680
Targets: image, mask

Convert image and mask to torch.Tensor

New features

Added YOLO format to bounding boxes.

d05db9e

The Yolo format of a bounding box has a format [x, y, width, height], where values normalized to the size of the image. Ex: [0.3, 0.1, 0.05, 0.07]

Added Deterministic / Replay mode

9942689

Augmentations pipeline has a lot of randomnesses, which is hard to debug. We added Determentsic / Replay mode in which you can track what parameters were applied to the input and use precisely the same transform to another input if necessary.

Jupyter notebook with an example.

Added fill_value to the Cutout transform.

d85bab5

Separated fill_value for images and masks

2c1a148

One of the use cases is it to use mask_value, which is equal to the ignore_index of your loss. This will decrease the level of noise and may improve convergence.

Speedup in the RGBShift

c3cc277

3.2 times faster for uint8 images.

Speedup in HueSaturationValue

448761d

2 times faster for uint8 images.

Speedup in [RandomBrightnessContrast](https://albumentations.readthedocs.io/en/latest/api/augmentations.html#albumentations.augmentations.transforms.RandomBrightnessCont...

0.3.0 Release

Added serialization / deserialization

• Now we can define transformations in a python dictionary, json, yaml files and they will be deserialized and used in the code.
• Now we can define transformations in the code and serialize them in python dictionary, json and yaml files.

Jupyter notebook with an example

Special thanks to @creafz

Added new transformations

• Lambda
• GaussianBlur
• ChannelDropout
• CoarseDropout
• RandomSnow
• RandomRain
• RandomFog
• RandomSunFlare
• RandomShadow

Special thanks to @vfdev-5 @ternaus @BloodAxe @kirillbobyrev

Bugfixes and improvements

• Bugfix in ToGray
• Bugfix in ShiftScaleRotate
• Bugfix in GaussNoise
• Added fill_value parameter to CutOut
• SpeedUp in RandomBrightnessContrast

Special thanks to @qubvel @ternaus @albu @BloodAxe

0.2.0 Release

Added support for the keypoint transformations to

• CenterCrop
• Flip
• HorizontalFlip
• IAAAffine
• IAACropAndPad
• IAAFliplr
• IAAFlipud
• IAAPerspective
• IAAPiecewiseAffine
• PadIfNeeded
• RandomCrop
• RandomRotate90
• RandomScale
• RandomSizedCrop
• Rotate
• ShiftScaleRotate
• VerticalFlip

Notebook with an example

Special thanks to the Evegene Khvedchenya (@BloodAxe) for the work.

Added an option to apply the same transformation to the more than one target of the same type.

The possible use case are image2image or stereo-image pipelines.

Notebook with an example

Special thanks to Alexander Buslaev (@albu) for the work.

Added new transformations

• RandomCropNearBBox
• RandomSizedBBoxSafeCrop
• SmallestMaxSize

Speed up in

• Normalize
• Flip
• HorizontalFlip
• VerticalFlip
• ElasticTransform

Bug fixes

• Fix for Compose with multiprocessing DataLoaders.
• Fix in SmallestMaxSize for multiclass masks.
• Fix in RandomBrightness
• Fix in RandomContrast

And many others.

Additional

• Performance benchmark was extended to the Augmentor and Solt libraries.
• Added table to Readme that shows all implemented transformations with the set of possible targets: images, bounding boxes, masks, key points. (Special thanks to Alex Parinov @creafz )
• The library can be installed in anaconda.

Contributors

@BloodAxe @albu @creafz @ternaus @erikgaas @marcocaccin @libfun @DBusAI @alexobednikov @StrikerRUS @IlyaOvodov @ZFTurbo @Vcv85 @georgymironov @LinaShiryaeva @vfdev-5 @daisukelab @cdicle

Extended bounding boxes support. New transformations. New notebooks with examples. A lot of bugfixes.

Bounding boxes support

Transformations that support bounding boxes

The main change in this release is the addition of the operations on bounding boxes to the

• Flip
• VerticalFlip
• HorizontalFlip
• Transpose
• RandomRotate90
• LongestMaxSize
• Resize
• RandomScale
• Crop
• RandomCrop
• CenterCrop
• RandomSizedCrop
• IAAAffine

Supported formats

Currently supported the following formats for the bounding boxes:

1. COCO: [x_min, y_min, width, height], ex [97, 12, 150, 200]
2. Pascal VOC: [x_min, y_min, x_max, y_max], ex [97, 12, 247, 212]

Bounding box filtering

It may happen that after the transformation a big part of the bounding box was cropped and it is needed to exclude such boxes.

We support such a bounding box filtering based on the:

• Bounding box area, measured in pixels.
• Visible box area, measured in percent.

Smaller changes

• Added support for 8-bit images.
• We changed all np.random occurrences to random due to the numpy behavior reported in pytorch/pytorch#5059
• Multiple bugfixes.

Added notebooks with examples

• How to migrate from torchvision to albumentations.
• How to apply the transformation to the classification problems.
• How to apply transformations to the detection problems.
• How to apply transformations to the segmentation problems.
• How to apply transformations to the non 8-bit images
• All in one showcase