augmenters.segmentation

Superpixels

Completely or partially transform images to their superpixel representation.

Note

This augmenter is fairly slow. See Performance.

API link: Superpixels

Example. Generate about 64 superpixels per image. Replace each one with a probability of 50% by its average pixel color.

import imgaug.augmenters as iaa
aug = iaa.Superpixels(p_replace=0.5, n_segments=64)

Example. Generate 16 to 128 superpixels per image. Replace each superpixel with a probability between 10 and 100% (sampled once per image) by its average pixel color.

aug = iaa.Superpixels(p_replace=(0.1, 1.0), n_segments=(16, 128))

Example. Effect of setting n_segments to a fixed value of 64 and then increasing p_replace from 0.0 and 1.0:

Example. Effect of setting p_replace to a fixed value of 1.0 and then increasing n_segments from 1*16 to 9*16=144:

Voronoi

Average colors of an image within Voronoi cells.

This augmenter performs the following steps:

1. Query points_sampler to sample random coordinates of cell centers. On the image.
2. Estimate for each pixel to which voronoi cell (i.e. segment) it belongs. Each pixel belongs to the cell with the closest center coordinate (euclidean distance).
3. Compute for each cell the average color of the pixels within it.
4. Replace the pixels of p_replace percent of all cells by their average color. Do not change the pixels of (1 - p_replace) percent of all cells. (The percentages are average values over many images. Some images may get more/less cells replaced by their average color.)

API link: Voronoi

Example. Create an augmenter that places a 20x40 (HxW) grid of cells on the image and replaces all pixels within each cell by the cell’s average color. The process is performed at an image size not exceeding 128px on any side. If necessary, the downscaling is performed using linear interpolation.

import imgaug.augmenters as iaa
points_sampler = iaa.RegularGridPointsSampler(n_cols=20, n_rows=40)
aug = iaa.Voronoi(points_sampler)

Example. Create a voronoi augmenter that generates a grid of cells dynamically adapted to the image size. Larger images get more cells. On the x-axis, the distance between two cells is w * W pixels, where W is the width of the image and w is always 0.1. On the y-axis, the distance between two cells is h * H pixels, where H is the height of the image and h is sampled uniformly from the interval [0.05, 0.2]. To make the voronoi pattern less regular, about 20 percent of the cell coordinates are randomly dropped (i.e. the remaining cells grow in size). In contrast to the first example, the image is not resized (if it was, the sampling would happen after the resizing, which would affect W and H). Not all voronoi cells are replaced by their average color, only around 90 percent of them. The remaining 10 percent’s pixels remain unchanged.

points_sampler = iaa.DropoutPointsSampler(
    iaa.RelativeRegularGridPointsSampler(
        n_cols_frac=(0.05, 0.2),
        n_rows_frac=0.1),
    0.2)
aug = iaa.Voronoi(points_sampler, p_replace=0.9, max_size=None)

UniformVoronoi

Uniformly sample Voronoi cells on images and average colors within them.

This augmenter is a shortcut for the combination of Voronoi with UniformPointsSampler. Hence, it generates a fixed amount of N random coordinates of voronoi cells on each image. The cell coordinates are sampled uniformly using the image height and width as maxima.

API link: UniformVoronoi

Example. Sample for each image uniformly the number of voronoi cells N from the interval [100, 500]. Then generates N coordinates by sampling uniformly the x-coordinates from [0, W] and the y-coordinates from [0, H], where H is the image height and W the image width. Then uses these coordinates to group the image pixels into voronoi cells and averages the colors within them. The process is performed at an image size not exceeding 128px on any side. If necessary, the downscaling is performed using linear interpolation.

import imgaug.augmenters as iaa
aug = iaa.UniformVoronoi((100, 500))

Example. Same as above, but always samples N=250 cells, replaces only 90 percent of them with their average color (the pixels of the remaining 10 percent are not changed) and performs the transformation at the original image size.

aug = iaa.UniformVoronoi(250, p_replace=0.9, max_size=None)

RegularGridVoronoi

Sample Voronoi cells from regular grids and color-average them.

This augmenter is a shortcut for the combination of Voronoi, RegularGridPointsSampler and DropoutPointsSampler. Hence, it generates a regular grid with R rows and C columns of coordinates on each image. Then, it drops p percent of the R*C coordinates to randomize the grid. Each image pixel then belongs to the voronoi cell with the closest coordinate.

API link: RegularGridVoronoi

Example. Place a regular grid of 10x20 (height x width) coordinates on each image. Randomly drop on average 20 percent of these points to create a less regular pattern. Then use the remaining coordinates to group the image pixels into voronoi cells and average the colors within them. The process is performed at an image size not exceeding 128px on any side. If necessary, the downscaling is performed using linear interpolation.

import imgaug.augmenters as iaa
aug = iaa.RegularGridVoronoi(10, 20)

Example. Same as above, generates a grid with randomly 10 to 30 rows, drops none of the generated points, replaces only 90 percent of the voronoi cells with their average color (the pixels of the remaining 10 percent are not changed) and performs the transformation at the original image size.

aug = iaa.RegularGridVoronoi(
    (10, 30), 20, p_drop_points=0.0, p_replace=0.9, max_size=None)

RelativeRegularGridVoronoi

Sample Voronoi cells from image-dependent grids and color-average them.

This augmenter is a shortcut for the combination of Voronoi, RegularGridPointsSampler and DropoutPointsSampler. Hence, it generates a regular grid with R rows and C columns of coordinates on each image. Then, it drops p percent of the R*C coordinates to randomize the grid. Each image pixel then belongs to the voronoi cell with the closest coordinate.

Note

In contrast to the other Voronoi augmenters, this one uses None as the default value for max_size, i.e. the color averaging is always performed at full resolution. This enables the augmenter to make most use of the added points for larger images. It does however slow down the augmentation process.

API link: RelativeRegularGridVoronoi

Example. Place a regular grid of R x C coordinates on each image, where R is the number of rows and computed as R=0.1*H with H being the height of the input image. C is the number of columns and analogously estimated from the image width W as C=0.25*W. Larger images will lead to larger R and C values. On average, 20 percent of these grid coordinates are randomly dropped to create a less regular pattern. Then, the remaining coordinates are used to group the image pixels into voronoi cells and the colors within them are averaged.

import imgaug.augmenters as iaa
aug = iaa.RelativeRegularGridVoronoi(0.1, 0.25)

Example. Same as above, generates a grid with randomly R=r*H rows, where r is sampled uniformly from the interval [0.03, 0.1] and C=0.1*W rows. No points are dropped. The augmenter replaces only 90 percent of the voronoi cells with their average color (the pixels of the remaining 10 percent are not changed). Images larger than 512px are temporarily downscaled (before sampling the grid points) so that no side exceeds 512px. This improves performance, but degrades the quality of the resulting image.

aug = iaa.RelativeRegularGridVoronoi(
    (0.03, 0.1), 0.1, p_drop_points=0.0, p_replace=0.9, max_size=512)