albumentations.core.utils
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_volume_shape
- functionformat_args
- classParams
- classDataProcessor
- functionvalidate_args
- functionprocess_sequence
- functionprocess_scalar
- functionapply_bias
- functionensure_int_output
- functionto_tuple
- functionto_tuple
- functionto_tuple
get_shapefunction
get_shape(
data: dict[str, Any]
)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) Returns: tuple[int, int]: (height, width) dimensions
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| data | dict[str, Any] | - | - |
get_volume_shapefunction
get_volume_shape(
data: dict[str, Any]
)Extract (depth, height, width) from data containing 'volume' or 'volumes'. Returns None if no volume data. Handles PyTorch tensor layouts (CDHW, NCDHW). Args: data (dict[str, Any]): Dictionary containing volume data 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] | - | - |
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:
| - | - |
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:
| - | - |
validate_argsfunction
validate_args(
low: float | Sequence[int] | Sequence[float] | None,
bias: float | None
)Raise if both low and bias are set. Call from to_tuple and transform param helpers. Validates range or symmetric range params. Args: low (float | Sequence[int] | Sequence[float] | None): Lower bound value. bias (float | None): Bias value to be added to both min and max values. Raises: ValueError: If both 'low' and 'bias' are provided.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| low | One of:
| - | - |
| bias | One of:
| - | - |
process_sequencefunction
process_sequence(
param: Sequence[Number]
)Convert a two-element sequence to (min, max) tuple. Raises if len != 2. Returns (min(param), max(param)). Use from to_tuple and transform param parsing. Args: param (Sequence[Number]): Sequence of numeric values. Returns: tuple[Number, Number]: Tuple containing (min_value, max_value) from the sequence. Raises: ValueError: If the sequence doesn't contain exactly 2 elements.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | Sequence[Number] | - | - |
process_scalarfunction
process_scalar(
param: Number,
low: Number | None
)Convert scalar + optional low to (min, max). If low given: (low, param) or (param, low); else (-param, param). Use from to_tuple and param parsing. Args: param (Number): Scalar numeric value. low (Number | None): Optional lower bound. Returns: tuple[Number, Number]: Tuple containing (min_value, max_value) where: - If low is provided: (low, param) if low < param else (param, low) - If low is None: (-param, param) creating a symmetric range around zero
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | Number | - | - |
| low | One of:
| - | - |
apply_biasfunction
apply_bias(
min_val: Number,
max_val: Number,
bias: Number
)Shift a range by adding bias to both ends. Use with to_tuple for symmetric ranges from a single value. Min stays less than max. Args: min_val (Number): Minimum value. max_val (Number): Maximum value. bias (Number): Value to add to both min and max. Returns: tuple[Number, Number]: Tuple containing (min_val + bias, max_val + bias).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| min_val | Number | - | - |
| max_val | Number | - | - |
| bias | Number | - | - |
ensure_int_outputfunction
ensure_int_output(
min_val: Number,
max_val: Number,
param: Number
)Return (min_val, max_val) as ints if param is int, else floats. For to_tuple and transform params so pixel ranges stay int and float ranges stay float. Args: min_val (Number): Minimum value. max_val (Number): Maximum value. param (Number): Original parameter used to determine the output type. Returns: tuple[int, int] | tuple[float, float]: Tuple with values converted to int if param is int, otherwise values remain as float.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| min_val | Number | - | - |
| max_val | Number | - | - |
| param | Number | - | - |
to_tuplefunction
to_tuple(
param: int | tuple[int, int],
low: int | tuple[int, int] | None,
bias: float | None
)Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | One of:
| - | - |
| low | One of:
| - | - |
| bias | One of:
| - | - |
to_tuplefunction
to_tuple(
param: float | tuple[float, float],
low: float | tuple[float, float] | None,
bias: float | None
)Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | One of:
| - | - |
| low | One of:
| - | - |
| bias | One of:
| - | - |
to_tuplefunction
to_tuple(
param: float | tuple[float, float] | tuple[int, int],
low: float | tuple[float, float] | tuple[int, int] | None,
bias: float | None
)Convert param (scalar or (min, max)) to a min-max tuple. Optional low or bias. Handles int/float; use with validate_args (low and bias mutually exclusive). This function processes various input types and returns a tuple representing a range. It handles single values, sequences, and can apply optional low bounds or biases. Args: param (float | tuple[float, float] | tuple[int, int]): The primary input value. Can be: a single float (symmetric range around zero) or a tuple of two floats or two ints as min and max. low (float | tuple[float, float] | tuple[int, int] | None): Lower bound when param is a single value. Result will be (low, param) or (param, low). Cannot be used together with bias. bias (float | None): Value added to both elements of the resulting tuple. Cannot be used with low. Returns: tuple[float, float] | tuple[int, int]: Processed range; int-based input yields tuple[int, int]. - If input is int-based, returns tuple[int, int] - If input is float-based, returns tuple[float, float] Raises: ValueError: If both 'low' and 'bias' are provided. TypeError: If 'param' is neither a scalar nor a sequence of 2 elements. Examples: >>> to_tuple(5) (-5, 5) >>> to_tuple(5.0) (-5.0, 5.0) >>> to_tuple((1, 10)) (1, 10) >>> to_tuple(5, low=3) (3, 5) >>> to_tuple(5, bias=1) (-4, 6) Notes: - When 'param' is a single value and 'low' is not provided, the function creates a symmetric range around zero. - The function preserves the type (int or float) of the input in the output. - If a sequence is provided, it must contain exactly 2 elements.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | One of:
| - | - |
| low | One of:
| - | - |
| bias | One of:
| - | - |