---

name: imgaug description: "Use when working with imgaug image augmentation pipelines, aligned annotations, stochastic parameters, dtype/data utilities, or multicore augmentation for computer-vision data." disable-model-invocation: true metadata: disco-role: operating license: MIT

imgaug Repo Skill

Use this skill when a task involves the Python package imgaug: building image augmentation pipelines, applying identical transforms to annotations, choosing stochastic parameters, debugging dtype/shape issues, or running background augmentation for computer-vision training data.

This is a self-contained operating guide. Do not rely on the original repository checkout being available; use the bundled references and scripts in this skill.

First checks

For a fresh environment, install a compatible runtime before using examples:

python -m pip install "imgaug==0.4.0" "numpy<2" "opencv-python-headless<4.12"

If installing from a local clone of imgaug 0.4.0, modern build isolation can fail because setup.py imports pkg_resources. Use a private environment and, only when needed, install setuptools<81 before a no-build-isolation local install. Prefer the public package install above for ordinary use.

Run the bundled environment check whenever installation, imports, optional dependencies, or compatibility are uncertain:

python scripts/check_imgaug_env.py

Run a short end-to-end smoke that adapts imgaug's documented examples without display, network, or large data:

python scripts/smoke_imgaug_workflows.py

Route by task

Task signal	Read next
Build iaa.Sequential, SomeOf, OneOf, Sometimes, WithChannels, image-only augmentation, or choose augmenter families such as affine, blur, color, contrast, dropout, weather, superpixels, or PIL-like effects	sub-skills/augmentation-pipelines/SKILL.md
Apply one transform consistently to keypoints, bounding boxes, polygons, line strings, heatmaps, segmentation maps, or mixed Batch/UnnormalizedBatch objects	sub-skills/augmentables-and-batches/SKILL.md
Control random sampling, seeds, deterministic replay, stochastic parameter distributions, dtype conversion, example quokka data, image resizing, grids, or display helpers	sub-skills/parameters-random-and-utilities/SKILL.md
Speed up augmentation with augment_batches(..., background=True), Augmenter.pool(), imgaug.multicore.Pool, BatchLoader, or debug multiprocessing/performance issues	sub-skills/multicore-and-diagnostics/SKILL.md

Core usage pattern

Most workflows start with NumPy arrays in image shape (N, H, W, C) or a list of (H, W, C) arrays. Images should usually be RGB uint8 with values 0..255; convert BGR images loaded by OpenCV before color augmentations.

import numpy as np
import imgaug.augmenters as iaa

images = np.zeros((8, 64, 64, 3), dtype=np.uint8)
seq = iaa.Sequential([
    iaa.Fliplr(0.5),
    iaa.Affine(rotate=(-10, 10)),
    iaa.GaussianBlur(sigma=(0.0, 1.0)),
])
images_aug = seq(images=images)

When images have annotations, pass them in the same call so geometric parameters are sampled once and applied consistently:

images_aug, keypoints_aug = seq(images=images, keypoints=keypoints)

Use to_deterministic() when you must apply the same sampled transform in separate calls, but prefer a single call containing all aligned augmentables when possible.

Bundled references

• references/package-overview.md gives the package map, supported workflows, dependencies, and source-artifact replacement map.
• references/troubleshooting.md covers cross-cutting install/import, NumPy/OpenCV, dtype/shape, optional dependency, display, and multiprocessing failures.
• references/repo-provenance.md records the source snapshot used to build this skill; read it before deciding whether a checkout needs refresh-repo-skill.
• references/repo-routing-metadata.json is structured metadata for managed repo-skill routing.

What this skill does not cover

• It does not teach general computer-vision model training frameworks beyond preparing augmented arrays/batches for them.
• It does not run long visual/performance checks from the source repository; bundled scripts use tiny deterministic fixtures.
• It does not verify optional imagecorruptions or numba acceleration unless the current task explicitly requires them.