Stay updated

News & Insights
bbox_utilscache_utilscompositionhub_mixinkeypoints_utilslabel_managerpydanticserializationtransforms_interfacetype_definitionsutilsvalidation

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

get_shapefunction

get_shape(
    data: dict[str, Any]
)

Extract height and width dimensions from input data dictionary. 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

NameTypeDefaultDescription
datadict[str, Any]--

get_volume_shapefunction

get_volume_shape(
    data: dict[str, Any]
)

Extract depth, height, and width dimensions from volume data. 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

NameTypeDefaultDescription
datadict[str, Any]--

format_argsfunction

format_args(
    args_dict: dict[str, Any]
)

Format a dictionary of arguments into a string representation. 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

NameTypeDefaultDescription
args_dictdict[str, Any]--

Paramsclass

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

Base class for parameter handling in transforms. 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

NameTypeDefaultDescription
coord_formatAny--
label_fields
One of:
  • Sequence[str]
  • None
--

DataProcessorclass

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

Abstract base class for data processors. 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

NameTypeDefaultDescription
paramsParams--
additional_targets
One of:
  • dict[str, str]
  • None
--

validate_argsfunction

validate_args(
    low: float | Sequence[int] | Sequence[float] | None,
    bias: float | None
)

Validate that 'low' and 'bias' parameters are not used together. 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

NameTypeDefaultDescription
low
One of:
  • float
  • Sequence[int]
  • Sequence[float]
  • None
--
bias
One of:
  • float
  • None
--

process_sequencefunction

process_sequence(
    param: Sequence[Number]
)

Process a sequence and return it as a (min, max) tuple. 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

NameTypeDefaultDescription
paramSequence[Number]--

process_scalarfunction

process_scalar(
    param: Number,
    low: Number | None
)

Process a scalar value and optional low bound into a (min, max) tuple. 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

NameTypeDefaultDescription
paramNumber--
low
One of:
  • Number
  • None
--

apply_biasfunction

apply_bias(
    min_val: Number,
    max_val: Number,
    bias: Number
)

Apply a bias to both values in a range. 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

NameTypeDefaultDescription
min_valNumber--
max_valNumber--
biasNumber--

ensure_int_outputfunction

ensure_int_output(
    min_val: Number,
    max_val: Number,
    param: Number
)

Ensure output is of the same type (int or float) as the input parameter. 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

NameTypeDefaultDescription
min_valNumber--
max_valNumber--
paramNumber--

to_tuplefunction

to_tuple(
    param: int | tuple[int, int],
    low: int | tuple[int, int] | None,
    bias: float | None
)

Parameters

NameTypeDefaultDescription
param
One of:
  • int
  • tuple[int, int]
--
low
One of:
  • int
  • tuple[int, int]
  • None
--
bias
One of:
  • float
  • None
--

to_tuplefunction

to_tuple(
    param: float | tuple[float, float],
    low: float | tuple[float, float] | None,
    bias: float | None
)

Parameters

NameTypeDefaultDescription
param
One of:
  • float
  • tuple[float, float]
--
low
One of:
  • float
  • tuple[float, float]
  • None
--
bias
One of:
  • float
  • None
--

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 input argument to a min-max tuple. 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 (tuple[float, float] | float | tuple[int, int] | int): The primary input value. Can be: - A single int or float: Converted to a symmetric range around zero. - A tuple of two ints or two floats: Used directly as min and max values. low (tuple[float, float] | float | None, optional): A lower bound value. Used when param is a single value. If provided, the result will be (low, param) or (param, low), depending on which is smaller. Cannot be used together with 'bias'. Defaults to None. bias (float | int | None, optional): A value to be added to both elements of the resulting tuple. Cannot be used together with 'low'. Defaults to None. Returns: tuple[int, int] | tuple[float, float]: A tuple representing the processed range. - 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

NameTypeDefaultDescription
param
One of:
  • float
  • tuple[float, float]
  • tuple[int, int]
--
low
One of:
  • float
  • tuple[float, float]
  • tuple[int, int]
  • None
--
bias
One of:
  • float
  • None
--