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
- classDataProcessor
- classParams
- functionapply_bias
- functionensure_contiguous_output
- functionensure_int_output
- functionformat_args
- functionget_image_shape
- functionget_shape
- functionget_volume_shape
- functionprocess_scalar
- functionprocess_sequence
- functionto_tuple
- functionvalidate_args
DataProcessorclass
DataProcessor(
params: Params,
additional_targets: dict[str, str] | None = None
)Abstract base class for data processors. Data processors handle the conversion, validation, and filtering of data during transformations.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| params | Params | - | Parameters for data processing. |
| additional_targets | One of:
| None | Dictionary mapping additional target names to their types. |
Paramsclass
Params(
format: Any,
label_fields: Sequence[str] | None
)Base class for parameter handling in transforms.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| format | Any | - | The format of the data this parameter object will process. |
| label_fields | One of:
| - | List of fields that are joined with the data, such as labels. |
apply_biasfunction
apply_bias(
min_val: Number,
max_val: Number,
bias: Number
)Apply a bias to both values in a range.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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).
ensure_contiguous_outputfunction
ensure_contiguous_output(
arg: np.ndarray | Sequence[np.ndarray]
)Ensure that numpy arrays are contiguous in memory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| arg | One of:
| - | A numpy array or sequence of numpy arrays. |
Returns
- np.ndarray | list[np.ndarray]: Contiguous array(s) with the same data.
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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,
format_argsfunction
format_args(
args_dict: dict[str, Any]
)Format a dictionary of arguments into a string representation.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| args_dict | dict[str, Any] | - | Dictionary of argument names and values. |
Returns
- str: Formatted string of arguments in the form "key1='value1', key2=value2".
get_image_shapefunction
get_image_shape(
img: np.ndarray | torch.Tensor
)Extract height and width dimensions from an image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | One of:
| - | Image as either numpy array (HWC format) or torch tensor (CHW format). |
Returns
- tuple[int, int]: Image dimensions as (height, width).
get_shapefunction
get_shape(
data: dict[str, Any]
)Extract spatial dimensions from input data dictionary containing image or volume.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| data | dict[str, Any] | - | Dictionary containing image or volume data with one of: - 'volume': 3D array of shape (D, H, W, C) [numpy] or (C, D, H, W) [torch] - 'image': 2D array of shape (H, W, C) [numpy] or (C, H, W) [torch] - 'images': Batch of arrays of shape (N, H, W, C) [numpy] or (N, C, H, W) [torch] |
Returns
- dict[Literal["depth", "height", "width"], int]: Dictionary containing spatial dimensions
get_volume_shapefunction
get_volume_shape(
vol: np.ndarray | torch.Tensor
)Extract depth, height, and width dimensions from a volume.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vol | One of:
| - | Volume as either numpy array (DHWC format) or torch tensor (CDHW format). |
Returns
- tuple[int, int, int]: Volume dimensions as (depth, height, width).
process_scalarfunction
process_scalar(
param: Number,
low: Number | None
)Process a scalar value and optional low bound into a (min, max) tuple.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | Number | - | Scalar numeric value. |
| low | One of:
| - | Optional lower bound. |
Returns
- tuple[Number, Number]: Tuple containing (min_value, max_value) where:
process_sequencefunction
process_sequence(
param: Sequence[Number]
)Process a sequence and return it as a (min, max) tuple.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | Sequence[Number] | - | Sequence of numeric values. |
Returns
- tuple[Number, Number]: Tuple containing (min_value, max_value) from the sequence.
to_tuplefunction
to_tuple(
param: float | tuple[float, float] | tuple[int, int],
low: float | tuple[float, float] | tuple[int, int] | None = None,
bias: float | None = 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| param | One of:
| - | 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 | One of:
| None | 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 | One of:
| None | 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.
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.
validate_argsfunction
validate_args(
low: float | Sequence[int] | Sequence[float] | None,
bias: float | None
)Validate that 'low' and 'bias' parameters are not used together.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| low | One of:
| - | Lower bound value. |
| bias | One of:
| - | Bias value to be added to both min and max values. |