Albumentations

The library is faster than other libraries on most of the transformations.
Based on numpy, OpenCV, imgaug picking the best from each of them.
Simple, flexible API that allows the library to be used in any computer vision pipeline.
Large, diverse set of transformations.
Easy to extend the library to wrap around other libraries.
Easy to extend to other tasks.
Supports transformations on images, masks, key points and bounding boxes.
Supports python 2.7-3.7
Easy integration with PyTorch.
Easy transfer from torchvision.
Was used to get top results in many DL competitions at Kaggle, topcoder, CVPR, MICCAI.
Written by Kaggle Masters.

How to use
Authors
Installation
- PyPI
- Conda
Documentation
Pixel-level transforms
Spatial-level transforms
Migrating from torchvision to albumentations
Benchmarking results
Contributing
- Adding new transforms
Building the documentation
Comments
Citing
Competitions won with the library
Industry users

How to use

All in one showcase notebook - showcase.ipynb

Classification - example.ipynb

Object detection - example_bboxes.ipynb

Non-8-bit images - example_16_bit_tiff.ipynb

Image segmentation example_kaggle_salt.ipynb

Keypoints example_keypoints.ipynb

Custom targets example_multi_target.ipynb

Weather transforms example_weather_transforms.ipynb

Serialization serialization.ipynb

Replay/Deterministic mode replay.ipynb

You can use this Google Colaboratory notebook to adjust image augmentation parameters and see the resulting images.

Authors

Alexander Buslaev

Alex Parinov

Vladimir I. Iglovikov

Evegene Khvedchenya

Mikhail Druzhinin

Installation

PyPI

You can use pip to install albumentations:

pip install albumentations

If you want to get the latest version of the code before it is released on PyPI you can install the library from GitHub:

pip install -U git+https://github.com/albu/albumentations

And it also works in Kaggle GPU kernels (proof)

!pip install albumentations > /dev/null

Conda

To install albumentations using conda we need first to install imgaug via conda-forge collection

conda install -c conda-forge imgaug
conda install albumentations -c albumentations

Documentation

The full documentation is available at albumentations.readthedocs.io.

Pixel-level transforms

Pixel-level transforms will change just an input image and will leave any additional targets such as masks, bounding boxes, and keypoints unchanged. The list of pixel-level transforms:

Spatial-level transforms

Spatial-level transforms will simultaneously change both an input image as well as additional targets such as masks, bounding boxes, and keypoints. The following table shows which additional targets are supported by each transform.

Transform	Image	Masks	BBoxes	Keypoints
CenterCrop	✓	✓	✓	✓
Crop	✓	✓	✓	✓
CropNonEmptyMaskIfExists	✓	✓	✓	✓
ElasticTransform	✓	✓
Flip	✓	✓	✓	✓
GridDistortion	✓	✓
HorizontalFlip	✓	✓	✓	✓
IAAAffine	✓	✓	✓	✓
IAACropAndPad	✓	✓	✓	✓
IAAFliplr	✓	✓	✓	✓
IAAFlipud	✓	✓	✓	✓
IAAPerspective	✓	✓	✓	✓
IAAPiecewiseAffine	✓	✓	✓	✓
Lambda	✓	✓	✓	✓
LongestMaxSize	✓	✓	✓	✓
NoOp	✓	✓	✓	✓
OpticalDistortion	✓	✓
PadIfNeeded	✓	✓	✓	✓
RandomCrop	✓	✓	✓	✓
RandomCropNearBBox	✓	✓	✓	✓
RandomGridShuffle	✓	✓
RandomResizedCrop	✓	✓	✓	✓
RandomRotate90	✓	✓	✓	✓
RandomScale	✓	✓	✓	✓
RandomSizedBBoxSafeCrop	✓	✓	✓
RandomSizedCrop	✓	✓	✓	✓
Resize	✓	✓	✓	✓
Rotate	✓	✓	✓	✓
ShiftScaleRotate	✓	✓	✓	✓
SmallestMaxSize	✓	✓	✓	✓
Transpose	✓	✓	✓	✓
VerticalFlip	✓	✓	✓	✓

Migrating from torchvision to albumentations

Migrating from torchvision to albumentations is simple - you just need to change a few lines of code. Albumentations has equivalents for common torchvision transforms as well as plenty of transforms that are not presented in torchvision. migrating_from_torchvision_to_albumentations.ipynb shows how one can migrate code from torchvision to albumentations.

Benchmarking results

To run the benchmark yourself follow the instructions in benchmark/README.md

Results for running the benchmark on first 2000 images from the ImageNet validation set using an Intel Xeon Gold 6140 CPU. For libraries that work with NumPy arrays, the uint8 data type is used to represent an image. The table shows how many images per second can be processed on a single core, higher is better.

	albumentations 0.4.0	imgaug 0.2.9	torchvision (Pillow backend) 0.4.0	torchvision (Pillow-SIMD backend) 0.4.0	keras 2.3.1	augmentor 0.2.6	solt 0.1.8
HorizontalFlip	961	754	1246	1251	669	1154	619
VerticalFlip	3941	2069	1105	1150	3884	1054	3540
Rotate	375	300	83	120	18	36	91
ShiftScaleRotate	664	454	75	116	23	-	-
Brightness	1806	1067	260	320	133	252	1694
Contrast	1701	1123	190	241	-	184	1699
BrightnessContrast	1749	577	114	143	-	112	880
ShiftRGB	1813	984	-	-	509	-	-
ShiftHSV	349	340	35	45	-	-	106
Gamma	1926	-	549	580	-	-	701
Grayscale	3688	307	487	574	-	872	2927
RandomCrop64	602010	2908	22398	33850	-	14267	38450
PadToSize512	2749	-	350	378	-	-	2370
Resize512	576	427	211	648	-	213	568
RandomSizedCrop_64_512	2223	715	334	1023	-	339	1949
Equalize	466	460	-	-	-	256	-

Python and library versions: Python 3.7.3, numpy 1.17.2, pillow 6.2.0, pillow-simd 6.0.0.post0, opencv-python 4.1.1.26, scikit-image 0.15.0, scipy 1.3.0.

Contributing

To create a pull request to the repository follow the documentation at docs/contributing.rst

Adding new transforms

If you are contributing a new transformation, make sure to update "Pixel-level transforms" or/and "Spatial-level transforms" sections of this file (README.md). To do this, simply run (with python3 only):

python3 tools/make_transforms_docs.py make

and copy/paste the results into the corresponding sections. To validate your modifications, you can run:

python3 tools/make_transforms_docs.py check README.md

Building the documentation

Go to docs/ directory
```
cd docs
```
Install required libraries
```
pip install -r requirements.txt
```
Build html files
```
make html
```
Open _build/html/index.html in browser.

Alternatively, you can start a web server that rebuilds the documentation automatically when a change is detected by running make livehtml

Competitions won with the library

Albumentations are widely used in Computer Vision Competitions at Kaggle an other platforms.

You can find their names and links to the solutions here.

Used by

Comments

In some systems, in the multiple GPU regime PyTorch may deadlock the DataLoader if OpenCV was compiled with OpenCL optimizations. Adding the following two lines before the library import may help. For more details pytorch/pytorch#1355

cv2.setNumThreads(0)
cv2.ocl.setUseOpenCL(False)

Citing

If you find this library useful for your research, please consider citing:

@article{2018arXiv180906839B,
    author = {A. Buslaev, A. Parinov, E. Khvedchenya, V.~I. Iglovikov and A.~A. Kalinin},
     title = "{Albumentations: fast and flexible image augmentations}",
   journal = {ArXiv e-prints},
    eprint = {1809.06839},
      year = 2018
}

You can find the full list of papers that cite Albumentations here.

cortwave/albumentations