DOCSEARCHbyAlgolia
Submit Docs

imgaug: Image Augmentation for Machine Learning

repository·master·Indexed 12 days ago

https://github.com/aleju/imgaug

A high-performance Python library for image augmentation tailored for machine learning workflows. It allows for complex transformations of images and associated metadata, including bounding boxes, keypoints, segmentation maps, polygons, and line strings. Features include diverse augmentation categories (arithmetic, geometric, blur, color, and corruption), multi-target support, and advanced parameterization using probability distributions.

Tokens
39.9K
Snippets
70
Records
248
Agent score
96%

What's inside imgaug

  1. Overview of imgaug

    master

    imgaug is a Python library designed for augmenting images in machine learning projects. It allows you to transform a set of input images into a much larger dataset of slightly altered versions.

    Key capabilities include:

    • Diverse Augmentations: Supports affine and perspective transformations, contrast changes, Gaussian noise, cropping/padding, blurring, and more.
    • Multi-Target Support: Automatically aligns augmentations across different data types, including:
      • Images (full uint8 support)
      • Heatmaps (float32)
      • Segmentation Maps (int)
      • Masks (bool)
      • Keypoints/Landmarks (coordinates)
      • Bounding Boxes (coordinates)
      • Polygons (coordinates)
      • Line Strings (coordinates)
    • Advanced Parameterization: Supports using probability distributions (e.g., Gaussian, Beta) as parameters for augmentations.
    • Performance: Optimized for high performance and supports augmentation on multiple CPU cores.

  2. Explore imgaug augmentation techniques via examples

    master

    imgaug provides a wide variety of augmentation techniques categorized into several groups. You can use these to transform images for machine learning training.

    Categories of Augmenters:

    • Meta: Basic transformations like Identity or ChannelShuffle. Includes control structures like Sequential, OneOf, Sometimes, and Lambda to compose augmentations.
    • Arithmetic: Pixel-level operations such as Add, Multiply, AdditiveGaussianNoise, Dropout, Cutout, SaltAndPepper, Invert, Solarize, and JpegCompression.
    • Artistic: Stylistic transformations like Cartoon.
    • Blend: Blending techniques such as BlendAlpha, BlendAlphaSimplexNoise, and BlendAlphaFrequencyNoise.

    Note: When parameters are specified as (a, b), it denotes a uniform distribution where a value is randomly picked from the interval [a, b].

  3. How pooling augmenters affect Maps

    master

    In imgaug, pooling augmenters (such as those that reduce spatial resolution) now automatically pool map arrays (e.g., heatmap arrays and segmentation map arrays) to ensure consistency with the augmented image.

    Previously, pooling augmenters only updated the metadata (HeatmapsOnImage.shape or SegmentationMapsOnImage.shape) without resizing the actual map arrays. Now, the arrays themselves are pooled, provided that the keep_size parameter is set to False. This change ensures that pooling behavior is consistent across different types of augmenters, such as Crop.

  4. Explore pillike augmenters

    master

    The pillike category provides augmenters that mimic the behavior of the Python Imaging Library (PIL) for image enhancement and filtering.

    Key augmenters include:

    • Autocontrast: Automatically adjusts contrast.
    • EnhanceColor: Enhances color saturation.
    • EnhanceSharpness: Increases image sharpness.
    • FilterEdgeEnhanceMore: Enhances edges.
    • FilterContour: Extracts or enhances contours.

  5. Apply brightness augmentations via colorspaces

    master

    The imgaug.augmenters.color.WithBrightnessChannels augmenter is a core utility that converts images to specific colorspaces (like L*a*b*), extracts brightness-related channels, applies child augmenters to those channels, and converts back to RGB.

    Related brightness augmenters include:

    • imgaug.augmenters.color.MultiplyAndAddToBrightness
    • imgaug.augmenters.color.MultiplyBrightness
    • imgaug.augmenters.color.AddToBrightness

  7. Use blending augmenters with segmentation maps

    master

    The BlendAlpha... family of augmenters allows for conditional blending based on segmentation maps or specific colors.

    Key augmenters include:

    • BlendAlphaSegMapClassIds: Blends augmentations based on class IDs in a segmentation map. This must be called with all inputs at the same time (e.g., augmenters(images=..., segmentation_maps=...)).
    • BlendAlphaSomeColors: Applies blending to specific colors.
    • BlendAlphaRegularGrid / BlendAlphaCheckerboard: Can be used with Multiply(0.0) to achieve dropout effects.
    • BlendAlphaBoundingBoxes: Blends based on bounding box locations.
    • BlendAlphaHorizontalLinearGradient / BlendAlphaVerticalLinearGradient: Blends using linear gradients.

    Example usage for class-based blending: BlendAlphaSegMapClassIds(BlendAlphaSomeColors(AddToHueAndSaturation(...)))

  8. Preferred way to import augmenters

    master

    When using imgaug, the preferred way to access specific augmenters is to import them directly from the imgaug.augmenters namespace rather than through their specific sub-modules.

    Preferred Pattern: imgaug.augmenters.<AugmenterName>

    Avoid Pattern: imgaug.augmenters.<ModuleName>.<AugmenterName>

    While the previous restriction against importing from sub-modules has been lifted, using the direct namespace remains the recommended practice for stability and consistency.

  9. AlphaElementwise coordinate blending behavior

    master
    The AlphaElementwise augmenter (including SimplexNoiseAlpha and FrequencyNoiseAlpha) now blends coordinates (for keypoints, polygons, and line strings) on a point-by-point basis. It uses the image's average alpha value at each specific point's coordinate in the sampled alpha mask. Previously, it used a single average alpha value for the entire mask to choose between the first or second branch for all points.

  10. Use probability distributions as parameters

    master

    Most augmenters support using tuples (a, b) as a shortcut for uniform(a, b) or lists [a, b, c] for a set of allowed values. For complex distributions (Gaussian, Poisson, etc.), use imgaug.parameters (imported as iap).

    Common patterns:

    • iap.Uniform(a, b): Uniform distribution.
    • iap.Normal(mu, sigma): Gaussian distribution.
    • iap.Clip(dist, min, max): Clips a distribution's values to a range.
    import numpy as np
from imgaug import augmenters as iaa
from imgaug import parameters as iap

images = np.random.randint(0, 255, (16, 128, 128, 3), dtype=np.uint8)

# Blur by a value sigma which is sampled from a uniform distribution
# of range 10.1 <= x < 13.0.
blurer = iaa.GaussianBlur(10 + iap.Uniform(0.1, 3.0))
images_aug = blurer(images=images)

# Blur by a value sigma which is sampled from a gaussian distribution
# N(1.0, 0.1), i.e. sample a value that is usually around 1.0.
# Clip the resulting value so that it never gets below 0.1 or above 3.0.
blurer = iaa.GaussianBlur(iap.Clip(iap.Normal(1.0, 0.1), 0.1, 3.0))
images_aug = blurer(images=images)

  11. Remove or clip coordinate-based augmentables outside the image plane

    master

    You can manage coordinate-based augmentables (Bounding Boxes, Polygons, Keypoints, LineStrings) that fall outside the image boundaries using specialized meta-augmenters or direct methods:

    Meta-Augmenters

    • imgaug.augmenters.meta.RemoveCBAsByOutOfImageFraction: Removes augmentables that have at least a specified fraction of their area outside the image plane.
    • imgaug.augmenters.meta.ClipCBAsToImagePlanes: Clips off all parts of augmentables that are outside the image boundaries.

    Direct Methods on *OnImage instances

    • remove_out_of_image_fraction(): Removes augmentables based on the fraction of area outside the image.
    • clip_out_of_image(): Clips the augmentables to the image boundaries.
    • remove_out_of_image(): Removes augmentables that are entirely outside the image.
    • clip_out_of_image_fraction(): Clips augmentables based on a fraction (in-place version: clip_out_of_image_fraction_()).

  12. Note on Augmenter class refactoring

    master
    In version 0.3.0, most augmenters were refactored from functions that returned instances into actual classes. While this change is designed to be non-breaking for existing code (arguments remain the same), it changes how augmenters behave when printed (e.g., print(A()) now prints the class name rather than a different class name). Affected modules include arithmetic, blend, blur, contrast, convolutional, meta, size, and weather.