Configuration API

Use numeric parameters when the pipeline needs no augmentation-backend objects. Use TransformSpec when the pipeline belongs in JSON, YAML, Hydra, or experiment configuration.

PyTorch remains a required runtime dependency in both cases.

Backend-free parameters

from fuse_augmentations import Compose

pipe = Compose.from_params(
    rotation=(-20.0, 20.0),
    scale=(0.85, 1.15),
    shear_x=(-5.0, 5.0),
    translate_x=(-8.0, 8.0),
    hflip_p=0.5,
    brightness=0.1,
    contrast=0.1,
)

The direct path supports rotation, uniform/per-axis scale, x/y shear, x/y pixel translation, H/V flips, brightness, and contrast. It samples direct geometric parameters independently per item; the randomness value is stored but does not change that direct sampling behavior.

brightness=0.1 and contrast=0.1 are active features: each describes a multiplicative factor range centered on 1.0. They are not reserved parameters.

Declarative specs

from fuse_augmentations import Compose, TransformSpec

specs = [
    TransformSpec(
        operation="rotation",
        params={"degrees": (-20.0, 20.0)},
        prob=0.8,
    ),
    TransformSpec(operation="hflip", params={}, prob=0.5),
]

torchvision_pipe = Compose.from_config(specs, backend="torchvision")
native_pipe = Compose.from_config(specs, backend="native")

TransformSpec freezes its parameter mapping and validates prob in [0, 1]. Use to_dict() and from_dict() for JSON/YAML round trips. from_dict() restores tuples for known numeric range keys; it does not convert every arbitrary list to a tuple.

Do not put prob inside params; use the dedicated field.

Capabilities are backend-specific

from fuse_augmentations import Compose

if "rotation90" in Compose.supported_ops("albumentations"):
    ...

The global operation vocabulary is larger than any one backend's coverage. See the exact declarative construction matrix.

By default, from_config validates all specs before constructing transforms and reports every unsupported item together. To explicitly build the supported subset:

pipe = Compose.from_config(
    specs,
    backend="torchvision",
    on_unsupported="warn_skip",
)

Skipping changes the requested pipeline, so use it only when a warning and partial pipeline are acceptable.

Canonical parameters and portability

The resolver translates a small canonical parameter vocabulary, including common rotation, scale, shear, translation, brightness, and contrast names. Unrecognized keys are passed to the backend constructor. A spec that contains backend-only keys is not portable merely because its operation name is canonical.

Treat backend swapping as validated reconstruction, not an assurance of identical random streams, interpolation numerics, defaults, or parameter semantics.

Default reordering

from_params and from_config default to ReorderPolicy.POINTWISE, unlike direct Compose(...), which defaults to NONE.

Use explicit ReorderPolicy.NONE when declaration order must be preserved:

from fuse_augmentations import Compose, ReorderPolicy

pipe = Compose.from_config(
    specs,
    backend="kornia",
    reorder=ReorderPolicy.NONE,
)

TransformSpec

TransformSpec dataclass

TransformSpec(operation: str, params: Mapping[str, object], prob: float = 1.0)

Declarative specification for a single augmentation transform.

A backend-agnostic, JSON-serialisable description of one augmentation operation. Used by :meth:FusedCompose.from_config <fuse_augmentations.compose.FusedCompose.from_config> and :meth:FusedCompose.from_params <fuse_augmentations.compose.FusedCompose.from_params> to build pipelines from configuration data rather than live transform objects.

Parameters:

Name	Type	Description	Default
operation	str	Canonical operation name (e.g. "rotation", "hflip").	required
params	Mapping[str, object]	Operation-specific parameters (e.g. {"degrees": (-30, 30)}). Range values (degrees, scale, etc.) must be 2-tuples, not lists. For JSON/YAML-deserialized configs use :meth:from_dict, which restores tuple semantics from any sequence type (list, OmegaConf ListConfig, etc.) automatically.	required
prob	float	Per-sample application probability. Default 1.0.	1.0

Examples:

>>> spec = TransformSpec(operation="rotation", params={"degrees": (-30.0, 30.0)}, prob=0.8)
>>> spec.operation
'rotation'
>>> spec.prob
0.8

to_dict

to_dict() -> dict[str, object]

Return a JSON-serialisable dict representation.

Returns:

Type	Description
dict[str, object]	Dict with keys "operation", "params", and "prob".

Examples:

>>> spec = TransformSpec(operation="hflip", params={}, prob=0.5)
>>> spec.to_dict()
{'operation': 'hflip', 'params': {}, 'prob': 0.5}

from_dict classmethod

from_dict(data_dict: dict[str, object]) -> TransformSpec

Construct a TransformSpec from a dict (e.g. parsed JSON).

Parameters:

Name	Type	Description	Default
data_dict	dict[str, object]	Dict with at least an "operation" key. "params" defaults to {} and "prob" defaults to 1.0 when absent.	required

Returns:

Type	Description
TransformSpec	A new TransformSpec instance.

Note

Tuple restoration applies to any sequence type (list, OmegaConf ListConfig, etc.) but only for canonical range-parameter keys ('degrees', 'factor', 'scale', 'pixels', etc. — the full set is :data:_RANGE_PARAM_KEYS). Backend-specific keys not in that set (e.g. Albumentations 'limit') are preserved as lists. OmegaConf DictConfig objects can be passed directly without calling OmegaConf.to_container() first. This is documented behaviour, not a bug.

Examples:

>>> import json
>>> spec = TransformSpec(operation="rotation", params={"degrees": (-30.0, 30.0)}, prob=0.8)
>>> restored = TransformSpec.from_dict(json.loads(json.dumps(spec.to_dict())))
>>> restored == spec  # list → tuple restored
True

Configuration policies

ReorderPolicy

Bases: Enum

Controls whether transforms are reordered before segmentation.

Attributes:

Name	Type	Description
NONE		No reordering; fuse only consecutive geometric ops as-is (v0.1 default).
POINTWISE		Move POINTWISE ops out of geometric chains (v0.2).
AGGRESSIVE		Alias of POINTWISE today; reserved for stronger reorder semantics later.

RandomnessPolicy

Bases: Enum

Controls how batch randomness is sampled by fused segments.

Attributes:

Name	Type	Description
BACKEND		Preserve each backend's native batch-randomness semantics.
PER_SAMPLE		Prefer one independent probability/parameter draw per batch item when the adapter exposes a canonical per-sample sampler.