imgaug - Image Augmentation Library

0.4.0 · active · verified Sun Apr 12

imgaug is a Python library for image augmentation in machine learning experiments, particularly for deep neural networks. It supports a wide range of augmentation techniques for images, keypoints/landmarks, bounding boxes, heatmaps, and segmentation maps. The library allows for easy combination of augmenters into sequences, execution in random order or on multiple CPU cores, and provides a powerful stochastic interface. The current stable version is 0.4.0, with releases historically every few months, though the last release was in early 2020.

Warnings

breaking Version 0.3.0 introduced breaking changes to segmentation map augmentation. The class name `SegmentationMapOnImage` was changed to `SegmentationMapsOnImage` (plural). Methods like `get_arr_int()` were renamed to `get_arr()`, and arguments `nb_classes` and `background_threshold` were removed. Segmentation map arrays are now expected to be `int32` instead of floats.
Fix: Update class names (singular to plural), method calls, and ensure segmentation maps are `int32` arrays. Refer to official documentation for `SegmentationMapsOnImage`.
gotcha Augmenters expect input images as NumPy arrays of shape `(N, height, width, channels)` for batches, or a list of `(height, width, channels)` arrays for single images. Grayscale images should have a channel dimension (e.g., `(height, width, 1)`). All images should have `uint8` dtype with values in the range `0-255`. Incorrect shapes or dtypes can lead to unexpected behavior or errors.
Fix: Ensure image data conforms to the expected NumPy array shape and dtype. For a single image, wrap it in a list: `seq(images=[my_image])`.
gotcha Using `augment_image()` with an array shape like `(H, W, C)` where `C` is large (e.g., `C >= 32` for masks/segmentation maps) can trigger a `SuspiciousSingleImageShapeWarning`. This happens when imgaug interprets a multi-image input (`N, H, W`) as a single image (`H, W, C`), leading to incorrect augmentation.
Fix: If you intend to augment a batch of single-channel images (e.g., masks), use `augment_images()` (plural form) instead of `augment_image()`.
gotcha While `imgaug` can accept raw lists of tuples for annotations like keypoints or bounding boxes, it is highly recommended to use `imgaug`'s dedicated augmentable classes (e.g., `imgaug.augmentables.kps.KeypointsOnImage`, `imgaug.augmentables.bbs.BoundingBoxesOnImage`). This helps avoid parsing misunderstandings and ensures correct handling during complex augmentations.
Fix: Wrap your keypoints, bounding boxes, etc., in the appropriate `imgaug.augmentables` classes before passing them to the augmenter sequence.
gotcha Keypoints or bounding box coordinates may be augmented to lie outside the image boundaries. This behavior is intentional, allowing users to decide how to handle out-of-bounds annotations (e.g., clip them, drop them, or project them back).
Fix: Implement custom logic to clip, drop, or adjust keypoints/bounding boxes that fall outside the image dimensions after augmentation, based on your specific application requirements.

Install

pip install imgaug Install latest stable version
pip install git+https://github.com/aleju/imgaug.git Install latest development version from GitHub

Imports

ia
```
import imgaug as ia
```
iaa
```
import imgaug.augmenters as iaa
```
SegmentationMapsOnImage
```
from imgaug.augmentables.segmaps import SegmentationMapsOnImage
```
The class name changed from singular `SegmentationMapOnImage` to plural `SegmentationMapsOnImage` in version 0.3.0.

Quickstart

This quickstart demonstrates how to define a simple augmentation sequence using `iaa.Sequential` and apply it to an image. It includes common transformations like flipping, blurring, and affine transformations. Images are expected as NumPy arrays (H, W, C) for a single image or (N, H, W, C) for a batch, typically with `uint8` dtype and pixel values in `0-255` range.

import numpy as np
import imageio.v3 as iio
import imgaug as ia
import imgaug.augmenters as iaa

# Fix seed to make examples reproducible
ia.seed(1)

# Example image (replace with your actual image loading)
image = iio.imread('https://upload.wikimedia.org/wikipedia/commons/8/8c/Default_pfp.jpg')
image = ia.quokka(size=(64, 64)) # Fallback if direct imageio fails or for testing

# Define an augmentation sequence
seq = iaa.Sequential([
    iaa.Fliplr(0.5), # horizontally flip 50% of all images
    iaa.Sometimes(0.5, # apply to 50% of images
        iaa.GaussianBlur(sigma=(0, 1.0)) # blur images with a sigma of 0 to 1.0
    ),
    iaa.Affine( # apply affine transformations to images
        scale={"x": (0.8, 1.2), "y": (0.8, 1.2)},
        translate_percent={"x": (-0.2, 0.2), "y": (-0.2, 0.2)},
        rotate=(-25, 25),
        shear=(-8, 8)
    )
], random_order=True) # apply augmenters in random order

# Augment a batch of images (or a single image wrapped in a list)
# `image` should be (H, W, C) for single, or (N, H, W, C) for batch
images_aug = seq(images=[image]) # Pass a list for a single image, imgaug expects batches

# Display the original and augmented image (requires matplotlib)
import matplotlib.pyplot as plt
fig, axes = plt.subplots(1, 2)
axes[0].imshow(image)
axes[0].set_title('Original')
axes[1].imshow(images_aug[0])
axes[1].set_title('Augmented')
plt.show()

view raw JSON →