augmenters.color¶

WithColorspace¶

Apply child augmenters within a specific colorspace.

This augumenter takes a source colorspace A and a target colorspace B as well as children C. It changes images from A to B, then applies the child augmenters C and finally changes the colorspace back from B to A. See also ChangeColorspace() for more.

API link: WithColorspace

Example. Convert to HSV colorspace, add a value between 0 and 50 (uniformly sampled per image) to the Hue channel, then convert back to the input colorspace (RGB).

import imgaug.augmenters as iaa
aug = iaa.WithColorspace(
    to_colorspace="HSV",
    from_colorspace="RGB",
    children=iaa.WithChannels(
        0,
        iaa.Add((0, 50))
    )
)

WithHueAndSaturation¶

Apply child augmenters to hue and saturation channels.

This augumenter takes an image in a source colorspace, converts it to HSV, extracts the H (hue) and S (saturation) channels, applies the provided child augmenters to these channels and finally converts back to the original colorspace.

The image array generated by this augmenter and provided to its children is in int16 (sic! only augmenters that can handle int16 arrays can be children!). The hue channel is mapped to the value range [0, 255]. Before converting back to the source colorspace, the saturation channel’s values are clipped to [0, 255]. A modulo operation is applied to the hue channel’s values, followed by a mapping from [0, 255] to [0, 180] (and finally the colorspace conversion).

API link: WithHueAndSaturation

Example. Create an augmenter that will add a random value between 0 and 50 (uniformly sampled per image) hue channel in HSV colorspace. It automatically accounts for the hue being in angular representation, i.e. if the angle goes beyond 360 degrees, it will start again at 0 degrees. The colorspace is finally converted back to RGB (default setting).

import imgaug.augmenters as iaa
aug = iaa.WithHueAndSaturation(
    iaa.WithChannels(0, iaa.Add((0, 50)))
)

Using WithHueAndSaturation to add random values to the hue channel

Example. Create an augmenter that adds a random value sampled uniformly from the range [-30, 10] to the hue and multiplies the saturation by a random factor sampled uniformly from [0.5, 1.5]. It also modifies the contrast of the saturation channel. After these steps, the HSV image is converted back to RGB.

aug = iaa.WithHueAndSaturation([
    iaa.WithChannels(0, iaa.Add((-30, 10))),
    iaa.WithChannels(1, [
        iaa.Multiply((0.5, 1.5)),
        iaa.LinearContrast((0.75, 1.25))
    ])
])

Using WithHueAndSaturation to modify both the hue and saturation

MultiplyHueAndSaturation¶

Multipy hue and saturation by random values.

The augmenter first transforms images to HSV colorspace, then multiplies the pixel values in the H and S channels and afterwards converts back to RGB.

This augmenter is a wrapper around WithHueAndSaturation.

API link: MultiplyHueAndSaturation()

Example. Multiply hue and saturation by random values between 0.5 and 1.5 (independently per channel and the same value for all pixels within that channel). The hue will be automatically projected to an angular representation.

import imgaug.augmenters as iaa
aug = iaa.MultiplyHueAndSaturation((0.5, 1.5), per_channel=True)

Example. Multiply only the hue by random values between 0.5 and 1.5.

aug = iaa.MultiplyHueAndSaturation(mul_hue=(0.5, 1.5))

MultiplyHueAndSaturation, only applied to the hue

Example. Multiply only the saturation by random values between 0.5 and 1.5.

aug = iaa.MultiplyHueAndSaturation(mul_saturation=(0.5, 1.5))

MultiplyHue¶

Multiply the hue of images by random values.

The augmenter first transforms images to HSV colorspace, then multiplies the pixel values in the H channel and afterwards converts back to RGB.

This augmenter is a shortcut for MultiplyHueAndSaturation(mul_hue=...).

API link: MultiplyHue()

Example. Multiply the hue channel of images using random values between 0.5 and 1.5:

import imgaug.augmenters as iaa
aug = iaa.MultiplyHue((0.5, 1.5))

MultiplySaturation¶

Multiply the saturation of images by random values.

The augmenter first transforms images to HSV colorspace, then multiplies the pixel values in the H channel and afterwards converts back to RGB.

This augmenter is a shortcut for MultiplyHueAndSaturation(mul_saturation=...).

API link: MultiplySaturation()

Example. Multiply the saturation channel of images using random values between 0.5 and 1.5:

import imgaug.augmenters as iaa
aug = iaa.MultiplySaturation((0.5, 1.5))

AddToHueAndSaturation¶

Increases or decreases hue and saturation by random values.

The augmenter first transforms images to HSV colorspace, then adds random values to the H and S channels and afterwards converts back to RGB.

This augmenter is faster than using WithHueAndSaturation in combination with Add.

API link: AddToHueAndSaturation

Example. Add random values between -50 and 50 to the hue and saturation (independently per channel and the same value for all pixels within that channel):

import imgaug.augmenters as iaa
aug = iaa.AddToHueAndSaturation((-50, 50), per_channel=True)

AddToHue¶

Add random values to the hue of images.

The augmenter first transforms images to HSV colorspace, then adds random values to the H channel and afterwards converts back to RGB.

If you want to change both the hue and the saturation, it is recommended to use AddToHueAndSaturation as otherwise the image will be converted twice to HSV and back to RGB.

This augmenter is a shortcut for AddToHueAndSaturation(value_hue=...).

API link: AddToHue()

Example. Sample random values from the discrete uniform range [-50..50], convert them to angular representation and add them to the hue, i.e. to the H channel in HSV colorspace:

import imgaug.augmenters as iaa
aug = iaa.AddToHue((-50, 50))

AddToSaturation¶

Add random values to the saturation of images.

The augmenter first transforms images to HSV colorspace, then adds random values to the S channel and afterwards converts back to RGB.

If you want to change both the hue and the saturation, it is recommended to use AddToHueAndSaturation as otherwise the image will be converted twice to HSV and back to RGB.

This augmenter is a shortcut for AddToHueAndSaturation(value_saturation=...).

API link: AddToSaturation()

Example. Sample random values from the discrete uniform range [-50..50], and add them to the saturation, i.e. to the S channel in HSV colorspace:

import imgaug.augmenters as iaa
aug = iaa.AddToSaturation((-50, 50))

ChangeColorspace¶

Augmenter to change the colorspace of images.

API link: ChangeColorspace

Example. The following example shows how to change the colorspace from RGB to HSV, then add 50-100 to the first channel, then convert back to RGB. This increases the hue value of each image.

import imgaug.augmenters as iaa
aug = iaa.Sequential([
    iaa.ChangeColorspace(from_colorspace="RGB", to_colorspace="HSV"),
    iaa.WithChannels(0, iaa.Add((50, 100))),
    iaa.ChangeColorspace(from_colorspace="HSV", to_colorspace="RGB")
])

Grayscale¶

Augmenter to convert images to their grayscale versions.

API link: Grayscale

Example. Change images to grayscale and overlay them with the original image by varying strengths, effectively removing 0 to 100% of the color:

import imgaug.augmenters as iaa
aug = iaa.Grayscale(alpha=(0.0, 1.0))

Example. Visualization of increasing alpha from 0.0 to 1.0 in eight steps:

KMeansColorQuantization¶

Quantize colors using k-Means clustering.

This “collects” the colors from the input image, groups them into k clusters using k-Means clustering and replaces the colors in the input image using the cluster centroids.

This is slower than UniformColorQuantization, but adapts dynamically to the color range in the input image.

Note

This augmenter expects input images to be either grayscale or to have 3 or 4 channels and use colorspace from_colorspace. If images have 4 channels, it is assumed that the 4th channel is an alpha channel and it will not be quantized.

API link: KMeansColorQuantization

Example. Create an augmenter to apply k-Means color quantization to images using a random amount of colors, sampled uniformly from the interval [2..16]. It assumes the input image colorspace to be RGB and clusters colors randomly in RGB or Lab colorspace.

import imgaug.augmenters as iaa
aug = iaa.KMeansColorQuantization()

Example. Create an augmenter that quantizes images to (up to) eight colors:

aug = iaa.KMeansColorQuantization(n_colors=8)

KMeansColorQuantization with eight colors

Example. Create an augmenter that quantizes images to (up to) n colors, where n is randomly and uniformly sampled from the discrete interval [4..32]:

aug = iaa.KMeansColorQuantization(n_colors=(4, 16))

KMeansColorQuantization with random n_colors

Example. Create an augmenter that quantizes input images that are in BGR colorspace. The quantization happens in RGB or Lab colorspace, into which the images are temporarily converted.

aug = iaa.KMeansColorQuantization(
    from_colorspace=iaa.ChangeColorspace.BGR)

KMeansColorQuantization with input images in BGR colorspace

Example. Create an augmenter that quantizes images by clustering colors randomly in either RGB or HSV colorspace. The assumed input colorspace of images is RGB.

aug = iaa.KMeansColorQuantization(
    to_colorspace=[iaa.ChangeColorspace.RGB, iaa.ChangeColorspace.HSV])

KMeansColorQuantization with quantization in RGB or HSV

UniformColorQuantization¶

Quantize colors into N bins with regular distance.

For uint8 images the equation is floor(v/q)*q + q/2 with q = 256/N, where v is a pixel intensity value and N is the target number of colors after quantization.

This augmenter is faster than KMeansColorQuantization, but the set of possible output colors is constant (i.e. independent of the input images). It may produce unsatisfying outputs for input images that are made up of very similar colors.

Note

This augmenter expects input images to be either grayscale or to have 3 or 4 channels and use colorspace from_colorspace. If images have 4 channels, it is assumed that the 4th channel is an alpha channel and it will not be quantized.

API link: UniformColorQuantization

Example. Create an augmenter to apply uniform color quantization to images using a random amount of colors, sampled uniformly from the discrete interval [2..16]:

import imgaug.augmenters as iaa
aug = iaa.UniformColorQuantization()

Example. Create an augmenter that quantizes images to (up to) eight colors:

aug = iaa.UniformColorQuantization(n_colors=8)

UniformColorQuantization with eight colors

Example. Create an augmenter that quantizes images to (up to) n colors, where n is randomly and uniformly sampled from the discrete interval [4..32]:

aug = iaa.UniformColorQuantization(n_colors=(4, 16))

UniformColorQuantization with random n_colors

Example. Create an augmenter that uniformly quantizes images in either RGB or HSV colorspace (randomly picked per image). The input colorspace of all images has to be BGR.

aug = iaa.UniformColorQuantization(
    from_colorspace=iaa.ChangeColorspace.BGR,
    to_colorspace=[iaa.ChangeColorspace.RGB, iaa.ChangeColorspace.HSV])

UniformColorQuantization in RGB or HSV colorspace with BGR inputs