albumentations.core.utils

View Source on GitHub

Module containing utility functions and classes for the core Albumentations framework. This module provides a collection of helper functions and base classes used throughout the Albumentations library. It includes utilities for shape handling, parameter processing, data conversion, and serialization. The module defines abstract base classes for data processors that implement the conversion logic between different data formats used in the transformation pipeline.

Members

functionget_shape
functionget_image_data
functionget_volume_shape
functionformat_args
classParams
classDataProcessor

get_shapefunction

get_shape(
    data: dict[str, Any],
    additional_targets: dict[str, str] | None
)

Extract (height, width) from data dict. Keys: image, images, volume, volumes. Raises if no image/volume present. Call for spatial checks during pipeline. After grayscale preprocessing, all data has channel dimension at the end. Args: data (dict[str, Any]): Dictionary containing image or volume data with one of: - 'volume': 3D array of shape (D, H, W, C) - 'volumes': Batch of 3D arrays of shape (N, D, H, W, C) - 'image': 2D array of shape (H, W, C) - 'images': Batch of arrays of shape (N, H, W, C) additional_targets (dict[str, str] | None): Mapping of alias key -> canonical target name (e.g. {'custom_image_key': 'image'}). When provided, aliased keys are resolved to their canonical role. Returns: tuple[int, int]: (height, width) dimensions

Parameters

Name	Type	Default	Description
data	dict[str, Any]	-	-
additional_targets	One of: dict[str, str] None	-	-

get_image_datafunction

get_image_data(
    data: dict[str, Any],
    additional_targets: dict[str, str] | None
)

Extract image metadata (dtype, height, width, num_channels) from a data dict, resolving `additional_targets` aliases (priority: image, images, volume, volumes). Checks for image data under canonical keys in priority order: `'image'` > `'images'` > `'volume'` > `'volumes'`. When `additional_targets` is provided, keys aliased to one of those canonical targets are also resolved (e.g. `{'custom_image_key': 'image'}` makes `data['custom_image_key']` count as `'image'`). Height and width skip batch/depth dimensions according to the canonical role: - 'image': H, W from shape[0], shape[1] - 'images': H, W from shape[1], shape[2] (skip batch dim) - 'volume': H, W from shape[1], shape[2] (skip depth dim) - 'volumes': H, W from shape[2], shape[3] (skip batch + depth dims) Args: data (dict[str, Any]): Dictionary potentially containing image/volume arrays. additional_targets (dict[str, str] | None): Mapping of alias key -> canonical target name. When None, only canonical keys are checked. Returns: dict[str, Any]: Dictionary with 'dtype', 'height', 'width', 'num_channels' keys. Raises: ValueError: If no valid image/volume data keys are found in the dictionary.

Parameters

Name	Type	Default	Description
data	dict[str, Any]	-	-
additional_targets	One of: dict[str, str] None	-	-

get_volume_shapefunction

get_volume_shape(
    data: dict[str, Any],
    additional_targets: dict[str, str] | None
)

Extract (depth, height, width) from data containing 'volume' or 'volumes', honoring `additional_targets` aliases; returns None when no volume data is present. Handles PyTorch tensor layouts (CDHW, NCDHW) and numpy layouts (DHWC, NDHWC). Aliased volume keys resolve to their canonical role. Args: data (dict[str, Any]): Dictionary containing volume data additional_targets (dict[str, str] | None): Mapping of alias key -> canonical target name. When None, only canonical keys are checked. Returns: tuple[int, int, int] | None: (depth, height, width) dimensions if volume data exists, None otherwise

Parameters

Name	Type	Default	Description
data	dict[str, Any]	-	-
additional_targets	One of: dict[str, str] None	-	-

format_argsfunction

format_args(
    args_dict: dict[str, Any]
)

Format a dict of argument names and values as "key1='val1', key2=val2" for repr. Strings are quoted; other values passed through str(). For transform __repr__. Args: args_dict (dict[str, Any]): Dictionary of argument names and values. Returns: str: Formatted string of arguments in the form "key1='value1', key2=value2".

Parameters

Name	Type	Default	Description
args_dict	dict[str, Any]	-	-

Paramsclass

Params(
    coord_format: Any,
    label_fields: Sequence[str] | None
)

Base class for transform data params: coord_format and label_fields. BboxParams and KeypointParams subclass this. Serializable. Args: coord_format (Any): The coordinate format of the data this parameter object will process. label_fields (Sequence[str] | None): List of fields that are joined with the data, such as labels.

Parameters

Name	Type	Default	Description
coord_format	Any	-	-
label_fields	One of: Sequence[str] None	-	-

DataProcessorclass

DataProcessor(
    params: Params,
    additional_targets: dict[str, str] | None
)

Abstract base for data processors: convert, validate, filter. Subclasses: BboxProcessor, KeypointsProcessor. Uses Params. Data processors handle the conversion, validation, and filtering of data during transformations. Args: params (Params): Parameters for data processing. additional_targets (dict[str, str] | None): Dictionary mapping additional target names to their types.

Parameters

Name	Type	Default	Description
params	Params	-	-
additional_targets	One of: dict[str, str] None	-	-