### Building Pipelines Incrementally

Source: https://albumentations.ai/docs/2-core-concepts/pipelines

Shows a practical example of building a training pipeline by starting with basic geometric transforms and then adding color augmentations.

```python
import albumentations as A

# Start with basic geometric transforms
geometric_pipeline = A.Compose([
    A.RandomCrop(height=256, width=256),
    A.HorizontalFlip(p=0.5),
])

# Add color augmentations for training
training_pipeline = geometric_pipeline + [
    A.RandomBrightnessContrast(p=0.3),
    A.HueSaturationValue(p=0.3),
]
```

--------------------------------

### Mosaic Augmentation Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/mixing/transforms

Demonstrates how to use the Mosaic augmentation to combine a primary image with additional images specified in mosaic_metadata. This example includes setup for image, mask, bounding boxes, and keypoints, and configures the Mosaic transform with specific parameters. Ensure bbox_params and keypoint_params are correctly set in Compose.

```python
import numpy as np
import albumentations as A
import cv2

# Prepare primary data
primary_image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
primary_mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
primary_bboxes = np.array([[10, 10, 40, 40], [50, 50, 90, 90]], dtype=np.float32)
primary_bbox_classes = [1, 2]
primary_keypoints = np.array([[25, 25], [75, 75]], dtype=np.float32)
primary_keypoint_classes = ['eye', 'nose']

# Prepare additional images for mosaic.
# bbox_labels and keypoint_labels are dicts mapping field name -> list of values.
mosaic_metadata = [
    {
        'image': np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8),
        'mask': np.random.randint(0, 2, (100, 100), dtype=np.uint8),
        'bboxes': np.array([[20, 20, 60, 60]], dtype=np.float32),
        'bbox_labels': {'bbox_classes': [3]},
        'keypoints': np.array([[40, 40]], dtype=np.float32),
        'keypoint_labels': {'keypoint_classes': ['mouth']},
    },
    {
        'image': np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8),
        'mask': np.random.randint(0, 2, (100, 100), dtype=np.uint8),
        'bboxes': np.array([[30, 30, 70, 70]], dtype=np.float32),
        'bbox_labels': {'bbox_classes': [4]},
        'keypoints': np.array([[50, 50], [65, 65]], dtype=np.float32),
        'keypoint_labels': {'keypoint_classes': ['eye', 'eye']},
    },
]

transform = A.Compose([
    A.Mosaic(
        grid_yx=(2, 2),
        target_size=(200, 200),
        cell_shape=(120, 120),
        center_range=(0.4, 0.6),
        fit_mode="cover",
        p=1.0
    ),
], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_classes']),
   keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_classes']))

transformed = transform(
    image=primary_image,
    mask=primary_mask,
    bboxes=primary_bboxes,
    bbox_classes=primary_bbox_classes,
    keypoints=primary_keypoints,
    keypoint_classes=primary_keypoint_classes,
    mosaic_metadata=mosaic_metadata,
)

mosaic_image = transformed['image']
mosaic_bboxes = transformed['bboxes']
mosaic_bbox_classes = transformed['bbox_classes']
mosaic_keypoint_classes = transformed['keypoint_classes']
```

--------------------------------

### NoOp Transform Example

Source: https://albumentations.ai/docs/api-reference/albumentations/core/transforms_interface

Demonstrates how to use the NoOp transform within a Compose pipeline. This example includes setup for image, mask, bounding boxes, and keypoints, applies the NoOp transform, and verifies that the original data remains unchanged. It also shows a conditional usage pattern.

```python
>>> import numpy as np
>>> import albumentations as A
>>> 
>>> # Prepare sample data
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
>>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32)
>>> bbox_labels = [1, 2]
>>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32)
>>> keypoint_labels = [0, 1]
>>> 
>>> # Create transform pipeline with NoOp
>>> transform = A.Compose([
...     A.NoOp(p=1.0),  # Always applied, but does nothing
... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
...    keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))
>>> 
>>> # Apply the transform
>>> transformed = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels
... )
>>> 
>>> # Verify nothing has changed
>>> np.array_equal(image, transformed['image'])  # True
>>> np.array_equal(mask, transformed['mask'])  # True
>>> np.array_equal(bboxes, transformed['bboxes'])  # True
>>> np.array_equal(keypoints, transformed['keypoints'])  # True
>>> bbox_labels == transformed['bbox_labels']  # True
>>> keypoint_labels == transformed['keypoint_labels']  # True
>>> 
>>> # NoOp is often used as a placeholder or for testing
>>> # For example, in conditional transforms:
>>> condition = False  # Some condition
>>> transform = A.Compose([
...     A.HorizontalFlip(p=1.0) if condition else A.NoOp(p=1.0)
... ])
```

--------------------------------

### Install Dependencies

Source: https://albumentations.ai/docs/examples/face-landmarks-tutorial

Use this command to install PyTorch, Albumentations-X, OpenCV, Matplotlib, TQDM, Segmentation Models PyTorch, and Kaggle. Ensure you have pip and Python installed.

```bash
pip install torch albumentationsx opencv-python matplotlib tqdm segmentation_models_pytorch kaggle

```

--------------------------------

### Install Libraries

Source: https://albumentations.ai/docs/examples/example-ultralytics

Installs the necessary Albumentations and Ultralytics libraries for custom augmentation integration.

```bash
!pip install albumentationsx ultralytics > /dev/null

```

--------------------------------

### Mosaic Augmentation Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/mixing/mosaic

Demonstrates how to use the Mosaic augmentation with primary image data and additional images for the mosaic. It includes setup for bounding boxes and keypoints, and shows how to apply the transform within a Compose pipeline.

```python
import numpy as np
import albumentations as A
import cv2

# Prepare primary data
primary_image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
primary_mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
primary_bboxes = np.array([[10, 10, 40, 40], [50, 50, 90, 90]], dtype=np.float32)
primary_bbox_classes = [1, 2]
primary_keypoints = np.array([[25, 25], [75, 75]], dtype=np.float32)
primary_keypoint_classes = ['eye', 'nose']

# Prepare additional images for mosaic.
# bbox_labels and keypoint_labels are dicts mapping field name -> list of values.
mosaic_metadata = [
    {
    'image': np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8),
    'mask': np.random.randint(0, 2, (100, 100), dtype=np.uint8),
    'bboxes': np.array([[20, 20, 60, 60]], dtype=np.float32),
    'bbox_labels': {'bbox_classes': [3]},
    'keypoints': np.array([[40, 40]], dtype=np.float32),
    'keypoint_labels': {'keypoint_classes': ['mouth']},
    },
    {
    'image': np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8),
    'mask': np.random.randint(0, 2, (100, 100), dtype=np.uint8),
    'bboxes': np.array([[30, 30, 70, 70]], dtype=np.float32),
    'bbox_labels': {'bbox_classes': [4]},
    'keypoints': np.array([[50, 50], [65, 65]], dtype=np.float32),
    'keypoint_labels': {'keypoint_classes': ['eye', 'eye']},
    },
]

transform = A.Compose([
    A.Mosaic(
grid_yx=(2, 2),
    target_size=(200, 200),
    cell_shape=(120, 120),
    center_range=(0.4, 0.6),
    fit_mode="cover",
    p=1.0
    ),
    ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_classes']),
    keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_classes']))

transformed = transform(
image=primary_image,
mask=primary_mask,
bboxes=primary_bboxes,
bbox_classes=primary_bbox_classes,
keypoints=primary_keypoints,
keypoint_classes=primary_keypoint_classes,
mosaic_metadata=mosaic_metadata,
)

mosaic_image = transformed['image']
mosaic_bboxes = transformed['bboxes']
mosaic_bbox_classes = transformed['bbox_classes']
mosaic_keypoint_classes = transformed['keypoint_classes']
```

--------------------------------

### Install Albumentations from GitHub

Source: https://albumentations.ai/docs/1-introduction/installation

Install the latest development version of Albumentations directly from its GitHub repository.

```bash
pip install -U git+https://github.com/albumentations-team/AlbumentationsX

```

--------------------------------

### Clone Benchmark Repository and Install Dependencies

Source: https://albumentations.ai/docs/benchmarks/benchmark-methodology

Clone the public benchmark repository and install its requirements using uv. This is the first step to reproducing benchmark results.

```bash
git clone https://github.com/albumentations-team/benchmark.git
cd benchmark
uv sync --all-extras
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://albumentations.ai/docs/contributing/coding-guidelines

Install the pre-commit package and set up the hooks for your local repository. These hooks automatically check and format code before each commit.

```bash
pip install pre-commit
pre-commit install
```

```bash
uv run pre-commit run --all-files
```

--------------------------------

### Manual OpenCV and Albumentations Installation

Source: https://albumentations.ai/docs/1-introduction/installation

Install a specific OpenCV variant manually, then install Albumentations. This provides full control over the OpenCV installation.

```bash
pip install opencv-python  # or opencv-python-headless, opencv-contrib-python, etc.
pip install -U albumentationsx

```

--------------------------------

### Install Dependencies

Source: https://albumentations.ai/docs/examples/example-tta-d4-aerial-segmentation

Installs the necessary libraries for running the TTA notebook, including albumentationsx, datasets, transformers, and PyTorch.

```bash
!pip install "albumentationsx[headless]" datasets transformers huggingface_hub torch torchvision tqdm -q

```

--------------------------------

### Install Albumentations

Source: https://albumentations.ai/docs/3-basic-usage/framework-integrations

Install the maintained albumentationsx package using pip.

```bash
pip install albumentationsx

```

--------------------------------

### Install Dependencies with pip Fallback

Source: https://albumentations.ai/docs/contributing/environment-setup

If uv is not available, manually create and activate a virtual environment, then install the project and development requirements using pip.

```bash
python3 -m venv env
source env/bin/activate
pip install -e .
pip install -r requirements-dev.txt
```

--------------------------------

### Install Dependencies with uv

Source: https://albumentations.ai/docs/contributing/environment-setup

Use uv to install the project dependencies, including development tools like Ruff, mypy, and pytest. This is the recommended method for setting up the development toolchain.

```bash
uv sync --group dev
```

--------------------------------

### Install Albumentations for Headless Environments

Source: https://albumentations.ai/docs/1-introduction/installation

Install Albumentations with headless OpenCV support, suitable for servers, Docker containers, and CI/CD pipelines where GUI is not needed.

```bash
pip install -U albumentationsx[headless]

```

--------------------------------

### Google-style Docstring Example

Source: https://albumentations.ai/docs/contributing/coding-guidelines

Example of a Google-style docstring for a transform's apply method. Includes a concise description, arguments, return type, and usage examples.

```python
def transform(self, image: np.ndarray) -> np.ndarray:
    """Apply brightness transformation to the image.

    Args:
        image: Input image in RGB format.

    Returns:
        Transformed image.

    Examples:
        >>> transform = Brightness(brightness_range=(-0.2, 0.2))
        >>> transformed = transform(image=image)
    """


```

--------------------------------

### Install Dependencies

Source: https://albumentations.ai/docs/examples/keras-cats-dogs-classification

Installs necessary libraries for the project, including TensorFlow, Keras, Albumentations, OpenCV, and Matplotlib.

```bash
# %pip install -q tensorflow keras tensorflow-datasets
# %pip install -q albumentationsx
# %pip install -q opencv-python-headless matplotlib
```

--------------------------------

### Basic Albumentations Transform Example

Source: https://albumentations.ai/docs/1-introduction/installation

A simple Python example demonstrating how to create a basic augmentation pipeline using Albumentations.

```python
import albumentations as A

transform = A.Compose([
    A.RandomCrop(width=256, height=256),
    A.HorizontalFlip(p=0.5),
    A.RandomBrightnessContrast(p=0.2),
])

```

--------------------------------

### Install AlbumentationsX

Source: https://albumentations.ai/docs/releases/2.0.9

Uninstall the original albumentations and install albumentationsx to use the new version. Your code remains unchanged.

```bash
pip uninstall albumentations
pip install albumentationsx
```

--------------------------------

### Verify Albumentations Installation

Source: https://albumentations.ai/docs/1-introduction/installation

Run this Python command to check if Albumentations is installed correctly and to display its version number.

```python
python -c "import albumentations as A; print(A.__version__)"

```

--------------------------------

### Get Crop Coordinates

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/crops/functional

Calculates the pixel coordinates for a crop region based on image shape, desired crop shape, and starting position.

```python
get_crop_coords(
    image_shape: tuple[int, int], 
    crop_shape: tuple[int, int], 
    h_start: float, 
    w_start: float
)
```

--------------------------------

### Object Detection Pipeline Setup

Source: https://albumentations.ai/docs/2-core-concepts/targets

Illustrates the initial setup for an object detection pipeline in Albumentations, including image preparation and defining bounding boxes with their corresponding labels. Remember to configure bbox_params within Compose for correct processing.

```python
import albumentations as A
import numpy as np

# Prepare data
image = np.random.randint(0, 256, (416, 416, 3), dtype=np.uint8)
bboxes = np.array([[50, 50, 150, 150], [200, 200, 350, 350]])
labels = ['person', 'car']
```

--------------------------------

### View Benchmark CLI Help

Source: https://albumentations.ai/docs/benchmarks/benchmark-methodology

Run the benchmark CLI with the --help flag to see available commands and scenarios for reproducing benchmark results.

```bash
uv run python -m benchmark.cli --help
```

--------------------------------

### Example Usage of GridMask

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/dropout/grid_mask

Demonstrates how to apply the GridMask augmentation to an image. Ensure albumentations and numpy are installed. The transform is applied with specific parameters and a probability of 1.0.

```python
import numpy as np
import albumentations as A
image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
transform = A.GridMask(num_grid_range=(3, 5), line_width_range=(0.2, 0.4), p=1.0)
result = transform(image=image)["image"]
```

--------------------------------

### Setup for Video Augmentation

Source: https://albumentations.ai/docs/3-basic-usage/video-augmentation

Import necessary libraries for video augmentation with Albumentations, OpenCV, and NumPy.

```python
import albumentations as A
import cv2
import numpy as np
```

--------------------------------

### Essential Starter Pipeline

Source: https://albumentations.ai/docs/3-basic-usage/choosing-augmentations

A basic pipeline demonstrating the recommended order of operations: size normalization, geometric transformations, dropout, and final normalization. Use this as a starting point and incrementally add more transforms.

```python
A.Compose([
    A.RandomCrop(height=224, width=224),      # Step 1: Size
    A.HorizontalFlip(p=0.5),                  # Step 2: Basic geometric
    A.CoarseDropout(num_holes_range=(3, 8),  # Step 3: Dropout
                    hole_height_range=(0.05, 0.15),
                    hole_width_range=(0.05, 0.15), p=0.5),
    A.Normalize(),                            # Step 7: Normalization
], seed=137)

```

--------------------------------

### GridDistortion Augmentation Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/distortion

Demonstrates how to apply GridDistortion to an image, mask, bounding boxes, and keypoints. Ensure you have albumentations and a backend like OpenCV installed. The same distortion is applied to all targets for consistency.

```python
>>> import albumentations as A
>>> transform = A.Compose([
...     A.GridDistortion(num_steps=5, distort_range=(-0.3, 0.3), p=1.0),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
>>> transformed_bboxes = transformed['bboxes']
>>> transformed_keypoints = transformed['keypoints']
```

--------------------------------

### Example Ultralytics Training with Custom Augmentations

Source: https://albumentations.ai/docs/examples/example-ultralytics

This snippet demonstrates a typical setup for training a model with custom spatial augmentations in Ultralytics. It includes data loading and augmentation pipeline configuration.

```python
from ultralytics import YOLO
from ultralytics.utils.ops import scale_boxes
import cv2

# Load a model
model = YOLO('yolov8n.yaml')  # build from YAML and transfer weights

# Train the model
results = model.train(data='coco128.yaml', epochs=100, imgsz=640)

# Load a custom model
model = YOLO('yolov8n.pt')

# Perform inference
results = model('https://ultralytics.com/images/bus.jpg')  # stream is True

# Process results
for r in results:
    im_array = r.plot()
    im = Image.fromarray(im_array[..., ::-1])  # bgr to rgb
    im.show()
    im.save('bus_pred.jpg')  # save prediction

# Export the model
path = model.export(format='onnx')

```

--------------------------------

### Import Libraries and Setup Environment

Source: https://albumentations.ai/docs/examples/keras-pretrained-segmentation

Imports essential libraries for deep learning, data handling, and visualization. Sets up environment variables to suppress warnings and ensure reproducibility by setting random seeds.

```python
import os
import platform
import warnings
from typing import Tuple
from dataclasses import dataclass

import numpy as np
import tensorflow as tf
import tensorflow_datasets as tfds
import keras
from keras import layers, models, optimizers, callbacks
import albumentations as A
import matplotlib.pyplot as plt
from tqdm.keras import TqdmCallback
from tqdm import tqdm

# Display plots inline
%matplotlib inline

# Suppress warnings for cleaner output
warnings.filterwarnings('ignore')
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '2'

# Set random seeds for reproducibility
np.random.seed(42)
tf.random.set_seed(42)

print("Versions:")
print(f"  TensorFlow: {tf.__version__}")
print(f"  Keras: {keras.__version__}")
print(f"  Albumentations: {A.__version__}")
print(f"  Platform: {platform.system()} {platform.processor()}")

```

--------------------------------

### Import Libraries and Setup

Source: https://albumentations.ai/docs/examples/face-landmarks-tutorial

Imports necessary libraries for PyTorch, Albumentations, and image processing. Sets up reproducibility with a fixed seed and configures the device (CUDA, MPS, or CPU).

```python
import torch
from torch import nn
from torch import optim
from torch.utils.data import Dataset, DataLoader
import albumentations as A
import numpy as np
import cv2
from pathlib import Path
from tqdm import tqdm
import matplotlib.pyplot as plt
import segmentation_models_pytorch as smp

# Reproducibility
SEED = 137
torch.manual_seed(SEED)
np.random.seed(SEED)
if torch.cuda.is_available():
    torch.cuda.manual_seed_all(SEED)

# Device setup
def get_device():
    if torch.cuda.is_available():
        device = torch.device("cuda")
        print(f"Using CUDA: {torch.cuda.get_device_name(0)}")
    elif torch.backends.mps.is_available():
        device = torch.device("mps")
        print("Using MPS (Apple Silicon)")
    else:
        device = torch.device("cpu")
        print("Using CPU")
    return device

device = get_device()

```

--------------------------------

### ModeFilter Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/blur/transforms

Demonstrates how to use ModeFilter for image augmentation. This snippet shows the setup for applying the transform with specified kernel range and probability, along with image, mask, bounding boxes, and keypoints.

```python
import numpy as np
import albumentations as A
image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
bboxes = np.array([[10, 10, 50, 50]], dtype=np.float32)
bbox_labels = [1]
keypoints = np.array([[20, 30]], dtype=np.float32)
keypoint_labels = [0]

transform = A.Compose([
    A.ModeFilter(kernel_range=(3, 7), p=1.0)
], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
   keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))

result = transform(
    image=image,
    mask=mask,
    bboxes=bboxes,
    bbox_labels=bbox_labels,
    keypoints=keypoints,
    keypoint_labels=keypoint_labels,
)
```

--------------------------------

### CoarseDropout Augmentation Examples

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/dropout/coarse_dropout

Demonstrates how to use CoarseDropout with random uniform fill and inpainting fill methods. Ensure numpy and albumentations are installed. The fill parameter can be set to 'random_uniform' or an inpainting method like 'inpaint_ns'.

```python
import numpy as np
import albumentations as A
image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
# Example with random uniform fill
aug_random = A.CoarseDropout(
    num_holes_range=(3, 6),
    hole_height_range=(10, 20),
    hole_width_range=(10, 20),
    fill="random_uniform",
    p=1.0
)
# Example with inpainting
aug_inpaint = A.CoarseDropout(
    num_holes_range=(3, 6),
    hole_height_range=(10, 20),
    hole_width_range=(10, 20),
    fill="inpaint_ns",
    p=1.0
)
transformed = aug_random(image=image, mask=mask)
transformed_image, transformed_mask = transformed["image"], transformed["mask"]
```

--------------------------------

### Initialize Model, Loss Function, and Optimizer

Source: https://albumentations.ai/docs/examples/pytorch-classification

Sets up the neural network model, the loss criterion (BCEWithLogitsLoss for binary classification), and the optimizer (Adam) based on defined parameters.

```python
model = getattr(models, params["model"])(pretrained=False, num_classes=1)
model = model.to(params["device"])
criterion = nn.BCEWithLogitsLoss().to(params["device"])
optimizer = torch.optim.Adam(model.parameters(), lr=params["lr"])
```

--------------------------------

### Albumentations ChromaticAberration Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/pixel/color

Applies lateral chromatic aberration by shifting red/blue channels relative to green. This transform is suitable for RGB images and simulates lens color fringing. Ensure OpenCV is installed for interpolation flags.

```python
import albumentations as A
import cv2
transform = A.ChromaticAberration(
    primary_distortion_range=(-0.05, 0.05),
    secondary_distortion_range=(-0.1, 0.1),
    mode='green_purple',
    interpolation=cv2.INTER_LINEAR,
    p=1.0,
)
transformed = transform(image=image)
aberrated_image = transformed['image']
```

--------------------------------

### ZoomBlur Augmentation Examples

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/blur/transforms

Demonstrates how to apply ZoomBlur with varying intensity levels and within a pipeline. The transform simulates zooming during exposure by averaging images at different zoom factors. Ensure you have numpy, albumentations, and cv2 installed.

```python
>>> import numpy as np
>>> import albumentations as A
>>> import cv2
>>> 
>>> # Create a sample image for demonstration
>>> image = np.zeros((300, 300, 3), dtype=np.uint8)
>>> # Add some shapes to visualize zoom blur effects
>>> cv2.rectangle(image, (100, 100), (200, 200), (255, 0, 0), -1)  # Red square
>>> cv2.circle(image, (150, 150), 30, (0, 255, 0), -1)  # Green circle
>>> cv2.line(image, (50, 150), (250, 150), (0, 0, 255), 5)  # Blue line
>>>
>>> # Example 1: Subtle zoom blur
>>> subtle_transform = A.Compose([
...     A.ZoomBlur(
...         max_factor_range=(1.05, 1.10),  # Small zoom range
...         step_factor_range=(0.01, 0.01), # Fine steps
...         p=1.0                           # Always apply
...     )
... ])
>>> 
>>> subtle_result = subtle_transform(image=image)
>>> subtle_blur = subtle_result["image"]
>>> # The image will have a subtle zoom blur effect, simulating a slight zoom during exposure
>>>
>>> # Example 2: Moderate zoom blur
>>> moderate_transform = A.Compose([
...     A.ZoomBlur(
...         max_factor_range=(1.15, 1.25),  # Medium zoom range
...         step_factor_range=(0.02, 0.02), # Medium steps
...         p=1.0
...     )
... ])
>>>
>>> moderate_result = moderate_transform(image=image)
>>> moderate_blur = moderate_result["image"]
>>> # The image will have a more noticeable zoom blur effect
>>>
>>> # Example 3: Strong zoom blur
>>> strong_transform = A.Compose([
...     A.ZoomBlur(
...         max_factor_range=(1.3, 1.5),    # Large zoom range
...         step_factor_range=(0.03, 0.05), # Larger steps (randomly chosen)
...         p=1.0
...     )
... ])
>>>
>>> strong_result = strong_transform(image=image)
>>> strong_blur = strong_result["image"]
>>> # The image will have a strong zoom blur effect, simulating fast zooming
>>>
>>> # Example 4: In a pipeline with other transforms
>>> pipeline = A.Compose([
...     A.RandomBrightnessContrast(brightness_range=(-0.2, 0.2), contrast_range=(-0.2, 0.2), p=0.7),
...     A.ZoomBlur(max_factor_range=(1.1, 1.3), step_factor_range=(0.02, 0.02), p=0.5),
...     A.HorizontalFlip(p=0.5)
... ])
>>>
>>> pipeline_result = pipeline(image=image)
>>> transformed_image = pipeline_result["image"]
>>> # The image may have zoom blur applied with 50% probability
```

--------------------------------

### Example Usage of RandomResizedCrop

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/crops/sized

Demonstrates how to use RandomResizedCrop within an Albumentations Compose pipeline. It includes setup for image, mask, bounding boxes, and keypoints, and applies the transform with specific parameters for size, scale, ratio, and interpolation.

```python
import numpy as np
import albumentations as A
import cv2

# Prepare sample data
image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32)
bbox_labels = [1, 2]
keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32)
keypoint_labels = [0, 1]

# Define transform with parameters as tuples
transform = A.Compose([
    A.RandomResizedCrop(
        size=(64, 64),
        scale=(0.5, 0.9), # Crop size will be 50-90% of original image
        ratio=(0.75, 1.33), # Aspect ratio will vary from 3:4 to 4:3
        interpolation=cv2.INTER_LINEAR,
        mask_interpolation=cv2.INTER_NEAREST,
        area_for_downscale="image", # Use INTER_AREA for image downscaling
        p=1.0
    ),
], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
 keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))

# Apply the transform
transformed = transform(
    image=image,
    mask=mask,
    bboxes=bboxes,
    bbox_labels=bbox_labels,
    keypoints=keypoints,
    keypoint_labels=keypoint_labels
)

# Get the transformed data
transformed_image = transformed['image'] # Shape: (64, 64, 3)
transformed_mask = transformed['mask'] # Shape: (64, 64)
```

--------------------------------

### ShiftScaleRotate Transformation Example

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/geometric/transforms

Demonstrates how to apply the ShiftScaleRotate transformation with custom ranges for shift, scale, and rotation. It shows the setup for image, mask, bounding boxes, and keypoints, and how to retrieve the transformed data. Uses Pascal VOC format for bounding boxes and 'xy' for keypoints.

```python
>>> import numpy as np
>>> import albumentations as A
>>> import cv2
>>> 
>>> # Prepare sample data
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
>>> bboxes = np.array([[10, 10, 50, 50], [40, 40, 80, 80]], dtype=np.float32)
>>> bbox_labels = [1, 2]
>>> keypoints = np.array([[20, 30], [60, 70]], dtype=np.float32)
>>> keypoint_labels = [0, 1]
>>> 
>>> # Define transform with parameters as tuples when possible
>>> transform = A.Compose([
...     A.ShiftScaleRotate(
...         shift_range=(-0.0625, 0.0625),
...         scale_range=(-0.1, 0.1),
...         rotate_range=(-45, 45),
...         interpolation=cv2.INTER_LINEAR,
...         border_mode=cv2.BORDER_CONSTANT,
...         rotate_method="largest_box",
...         p=1.0
...     ),
... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
...    keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))
>>> 
>>> # Apply the transform
>>> transformed = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels
... )
>>> 
>>> # Get the transformed data
>>> transformed_image = transformed['image']      # Shifted, scaled and rotated image
>>> transformed_mask = transformed['mask']        # Shifted, scaled and rotated mask
>>> transformed_bboxes = transformed['bboxes']    # Shifted, scaled and rotated bounding boxes
>>> transformed_bbox_labels = transformed['bbox_labels']  # Labels for transformed bboxes
>>> transformed_keypoints = transformed['keypoints']  # Shifted, scaled and rotated keypoints
>>> transformed_keypoint_labels = transformed['keypoint_labels']  # Labels for transformed keypoints
>>>
```

--------------------------------

### D4-based TTA Example with Albumentations (2.0.19+)

Source: https://albumentations.ai/docs/4-advanced-guides/test-time-augmentation

Demonstrates TTA for object detection or segmentation using the D4 symmetry group with Albumentations. It iterates through D4 group elements, applies transformations, gets model predictions, and maps them back to the original coordinate system using the inverse transform.

```python
import numpy as np
import torch
import albumentations as A
from albumentations.core.type_definitions import d4_group_elements
from albumentations.pytorch import ToTensorV2

image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
device = next(model.parameters()).device
predictions = []

for element in d4_group_elements:
    D4_transform = A.D4(group_element=element, p=1.0)
    transform = A.Compose([
        D4_transform,
        A.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
        ToTensorV2(),
    ])

    input_tensor = transform(image=image)("image").unsqueeze(0).to(device)
    with torch.no_grad():
        pred_tensor = model(input_tensor)  # [1, C, H, W]

    # Map prediction back to original orientation (convert to numpy for inverse)
    pred_np = pred_tensor.squeeze(0).permute(1, 2, 0).cpu().numpy()
    prediction = D4_transform.inverse()(image=pred_np)("image")
    predictions.append(prediction)

# Average predictions (e.g., for segmentation logits or density maps)
final_prediction = np.stack(predictions).mean(axis=0)

```

--------------------------------

### Set Up Pre-commit Hooks with uv

Source: https://albumentations.ai/docs/contributing/environment-setup

Install pre-commit hooks using uv to automatically check code quality before each commit. This ensures code adheres to project standards.

```bash
uv run pre-commit install
```

--------------------------------

### require_huggingface_hub

Source: https://albumentations.ai/docs/api-reference/albumentations/core/hub_mixin

Decorator that raises ImportError if huggingface_hub is not installed. Use it on Hub methods that require the package. Required for push_to_hub. This decorator ensures that the `huggingface_hub` package is installed before executing the decorated function. If the package is not installed, it raises an ImportError with instructions on how to install it.

```APIDOC
## require_huggingface_hub

### Description
Decorator that raises ImportError if huggingface_hub is not installed. Use it on Hub methods that require the package. Required for push_to_hub. This decorator ensures that the `huggingface_hub` package is installed before executing the decorated function. If the package is not installed, it raises an ImportError with instructions on how to install it.

### Parameters

#### Path Parameters

* **func** (Callable[..., Any]) - Required - The function to decorate.

### Returns

* **Callable[..., Any]** - The decorated function.
```

--------------------------------

### Sequential Example Usage in Compose

Source: https://albumentations.ai/docs/api-reference/albumentations/core/composition

Demonstrates how to use Sequential within Compose, combined with OneOf, to create a pipeline with multiple augmentation sequences.

```python
import albumentations as A
transform = A.Compose([
A.OneOf([
A.Sequential([
A.HorizontalFlip(p=0.5),
A.ShiftScaleRotate(p=0.5),
]),
A.Sequential([
A.VerticalFlip(p=0.5),
A.RandomBrightnessContrast(p=0.5),
]),
], p=1)
])
```

--------------------------------

### Set Up Pre-commit Hooks with pip Fallback

Source: https://albumentations.ai/docs/contributing/environment-setup

If using the pip fallback method, install pre-commit hooks directly after activating the virtual environment.

```bash
pre-commit install
```

--------------------------------

### Install Pillow

Source: https://albumentations.ai/docs/examples/example-overlayelements

Installs or upgrades the Pillow library, which is required for image manipulation.

```bash
!pip install -U pillow
```

--------------------------------

### End-to-End OBB Pipeline Example

Source: https://albumentations.ai/docs/3-basic-usage/oriented-bounding-boxes

Demonstrates a complete Albumentations pipeline for Oriented Bounding Boxes (OBB). This example includes image loading, OBB definition, random cropping, affine transformations, pixel-level adjustments, and OBB label filtering based on area and visibility.

```python
import albumentations as A
import cv2
import numpy as np

image = cv2.imread("image.jpg")
image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

bboxes = np.array(
    [
        [94.9, 35.1, 45.0, 138.5, -44.2],
        [256.0, 210.0, 96.0, 38.0, 12.0],
    ],
    dtype=np.float32,
)
labels = ["ship", "vehicle"]

transform = A.Compose(
    [
        A.RandomCrop(width=512, height=512, p=1.0),
        A.Affine(scale=(0.9, 1.1), rotate=(-20, 20), shear=(-5, 5), p=0.9),
        A.RandomBrightnessContrast(p=0.2),
    ],
    bbox_params=A.BboxParams(
        coord_format="cxcywh",
        bbox_type="obb",
        label_fields=["labels"],
        filter_invalid_bboxes=True,
        min_area=16,
        min_visibility=0.2,
    ),
    seed=137,
)

result = transform(image=image, bboxes=bboxes, labels=labels)

augmented_image = result["image"]
augmented_bboxes = result["bboxes"]
augmented_labels = result["labels"]

```

--------------------------------

### Install Required Packages

Source: https://albumentations.ai/docs/examples/keras-pretrained-segmentation

Installs the necessary Python packages for the semantic segmentation project, including albumentationsx, tensorflow, tensorflow-datasets, keras, matplotlib, and tqdm. The '--upgrade' flag ensures the latest versions are installed.

```bash
# Install required packages
%pip install -q --upgrade albumentationsx tensorflow tensorflow-datasets keras matplotlib tqdm jupytext

```

--------------------------------

### Setup Training Callbacks

Source: https://albumentations.ai/docs/examples/keras-pretrained-segmentation

This code configures essential callbacks for model training, including saving the best model weights, early stopping to prevent overfitting, learning rate reduction, and a progress bar for monitoring training progress.

```python
# Setup callbacks
os.makedirs(config.checkpoint_dir, exist_ok=True)

checkpoint = callbacks.ModelCheckpoint(
    filepath=os.path.join(config.checkpoint_dir, f'best_{config.backbone}_unet.keras'),
    monitor='val_dice_coefficient',
    mode='max',
    save_best_only=True,
    verbose=0
)

early_stop = callbacks.EarlyStopping(
    monitor='val_dice_coefficient',
    mode='max',
    patience=7,
    restore_best_weights=True,
    verbose=0
)

reduce_lr = callbacks.ReduceLROnPlateau(
    monitor='val_dice_coefficient',
    mode='max',
    factor=0.5,
    patience=3,
    min_lr=1e-7,
    verbose=0
)

# Create tqdm callback for progress bars
tqdm_callback = TqdmCallback(verbose=2, leave=True)

```

--------------------------------

### CopyAndPaste with Instance Binding Example

Source: https://albumentations.ai/docs/examples/example-instance-binding

Demonstrates how to use CopyAndPaste to paste instances from a donor image onto a primary image. It shows how to prepare donor metadata, apply the transform with instance binding, and visualize the output. Ensure that donor images are tight-cropped to their masks or bounding boxes.

```python
DONOR_PATH = next(p for p in image_paths if p != PRIMARY_PATH and len(load_sample(p)[1]) >= 3)
donor_image, donor_instances = load_sample(DONOR_PATH)

donors = [
    {
        "image": donor_image,
        "mask": inst["mask"],
        "bbox_labels": {"class_name": inst["bbox_labels"]["class_name"]},
    }
    for inst in donor_instances[:3]
]

transform_cp = A.Compose(
    [
        A.HorizontalFlip(p=0.5),
        A.CopyAndPaste(
            scale_range=(0.4, 1.0),
            blend_mode="gaussian",
            blend_sigma_range=(1.0, 2.0),
            min_visibility_after_paste=0.1,
            p=1.0,
        ),
    ],
    bbox_params=A.BboxParams(coord_format="pascal_voc", label_fields=["class_name"]),
    instance_binding=["masks", "bboxes"],
    seed=42,
)

out_cp = transform_cp(
    image=primary_image,
    instances=primary_instances,
    copy_paste_metadata=donors,
)

print(f"primary: {len(primary_instances)}  donors offered: {len(donors)}  output instances: {len(out_cp['instances'])}")
for inst in out_cp["instances"]:
    print("  ", inst["bbox_labels"]["class_name"], "bbox", inst["bbox"].round(1).tolist())

fig, axes = plt.subplots(1, 3, figsize=(20, 7))
draw_instances(axes[0], primary_image, primary_instances, title=f"Primary ({len(primary_instances)})")
draw_instances(axes[1], donor_image, donor_instances, title=f"Donor pool ({len(donor_instances)})")
draw_instances(axes[2], out_cp["image"], out_cp["instances"], title=f"CopyAndPaste result ({len(out_cp['instances'])})")
plt.tight_layout()
plt.show()

```

```text
primary: 8  donors offered: 3  output instances: 11
   bowl bbox [26.0, 188.0, 639.0, 475.0]
   bowl bbox [8.0, 4.0, 328.0, 234.0]
   broccoli bbox [73.0, 229.0, 390.0, 475.0]
   bowl bbox [205.0, 14.0, 640.0, 390.0]
   orange bbox [187.0, 40.0, 264.0, 88.0]
   orange bbox [115.0, 39.0, 174.0, 87.0]
   orange bbox [169.0, 74.0, 254.0, 145.0]
   orange bbox [180.0, 2.0, 276.0, 75.0]
   horse bbox [104.0, 377.0, 174.0, 476.0]
   horse bbox [558.0, 346.0, 603.0, 431.0]
   person bbox [604.0, 44.0, 640.0, 84.0]

```

--------------------------------

### GaussianBlur Examples

Source: https://albumentations.ai/docs/api-reference/albumentations/augmentations/blur/transforms

Examples demonstrating the usage of GaussianBlur with different configurations for sigma, blur range, and within a pipeline.

```APIDOC
## GaussianBlur

### Description
Applies Gaussian blur to an image. This is useful for reducing image noise and detail.

### Parameters
Name| Type| Default| Description  
---|---|---|---  
sigma_range| tuple[float, float] | (0.5, 3.0) | Range of sigma values for the Gaussian kernel. A larger sigma results in more blur. Default: (0.5, 3.0)
blur_range| tuple[int, int] | (0, 0) | Range of kernel sizes for the Gaussian kernel. If (0, 0), the kernel size is computed from sigma. Otherwise, it must be an odd integer. Default: (0, 0)
p| float| 0.5| Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5

### Notes
- When `blur_range=(0, 0)` (default), this implementation exactly matches PIL's GaussianBlur.

### References
  * [{'description': 'OpenCV Gaussian Blur', 'source': 'https://docs.opencv.org/master/d4/d86/group__imgproc__filter.html#gaabe8c836e97159a9193fb0b11ac52cf1'}, {'description': 'PIL GaussianBlur', 'source': 'https://pillow.readthedocs.io/en/stable/reference/ImageFilter.html#PIL.ImageFilter.GaussianBlur'}]
```