{"id":4574,"library":"imgaug","title":"imgaug - Image Augmentation Library","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/aleju/imgaug","tags":["image augmentation","deep learning","computer vision","machine learning","data augmentation"],"install":[{"cmd":"pip install imgaug","lang":"bash","label":"Install latest stable version"},{"cmd":"pip install git+https://github.com/aleju/imgaug.git","lang":"bash","label":"Install latest development version from GitHub"}],"dependencies":[{"reason":"Core dependency for numerical operations and image data handling.","package":"numpy"},{"reason":"Used for various scientific computing tasks, often by augmenters.","package":"scipy"},{"reason":"Image processing functionality, especially for loading/saving images.","package":"Pillow"},{"reason":"Default image loading/saving utility in many examples and for general use.","package":"imageio"},{"reason":"For drawing and visualization of augmented images and annotations.","package":"matplotlib"},{"reason":"Provides image processing algorithms.","package":"scikit-image"},{"reason":"Recommended for server environments; imgaug uses OpenCV functionality. Note: 'opencv-python' may be installed by default, but 'opencv-python-headless' is generally preferred to avoid GUI dependencies.","package":"opencv-python-headless","optional":true},{"reason":"Required for some operations involving line strings or polygons.","package":"Shapely","optional":true},{"reason":"Required for using augmenters in `imgaug.augmenters.imgcorruptlike` module.","package":"imagecorruptions","optional":true}],"imports":[{"symbol":"ia","correct":"import imgaug as ia"},{"symbol":"iaa","correct":"import imgaug.augmenters as iaa"},{"note":"The class name changed from singular `SegmentationMapOnImage` to plural `SegmentationMapsOnImage` in version 0.3.0.","wrong":"from imgaug.augmentables.segmaps import SegmentationMapOnImage","symbol":"SegmentationMapsOnImage","correct":"from imgaug.augmentables.segmaps import SegmentationMapsOnImage"}],"quickstart":{"code":"import numpy as np\nimport imageio.v3 as iio\nimport imgaug as ia\nimport imgaug.augmenters as iaa\n\n# Fix seed to make examples reproducible\nia.seed(1)\n\n# Example image (replace with your actual image loading)\nimage = iio.imread('https://upload.wikimedia.org/wikipedia/commons/8/8c/Default_pfp.jpg')\nimage = ia.quokka(size=(64, 64)) # Fallback if direct imageio fails or for testing\n\n# Define an augmentation sequence\nseq = iaa.Sequential([\n    iaa.Fliplr(0.5), # horizontally flip 50% of all images\n    iaa.Sometimes(0.5, # apply to 50% of images\n        iaa.GaussianBlur(sigma=(0, 1.0)) # blur images with a sigma of 0 to 1.0\n    ),\n    iaa.Affine( # apply affine transformations to images\n        scale={\"x\": (0.8, 1.2), \"y\": (0.8, 1.2)},\n        translate_percent={\"x\": (-0.2, 0.2), \"y\": (-0.2, 0.2)},\n        rotate=(-25, 25),\n        shear=(-8, 8)\n    )\n], random_order=True) # apply augmenters in random order\n\n# Augment a batch of images (or a single image wrapped in a list)\n# `image` should be (H, W, C) for single, or (N, H, W, C) for batch\nimages_aug = seq(images=[image]) # Pass a list for a single image, imgaug expects batches\n\n# Display the original and augmented image (requires matplotlib)\nimport matplotlib.pyplot as plt\nfig, axes = plt.subplots(1, 2)\naxes[0].imshow(image)\naxes[0].set_title('Original')\naxes[1].imshow(images_aug[0])\naxes[1].set_title('Augmented')\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Update class names (singular to plural), method calls, and ensure segmentation maps are `int32` arrays. Refer to official documentation for `SegmentationMapsOnImage`.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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])`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"If you intend to augment a batch of single-channel images (e.g., masks), use `augment_images()` (plural form) instead of `augment_image()`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Wrap your keypoints, bounding boxes, etc., in the appropriate `imgaug.augmentables` classes before passing them to the augmenter sequence.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}