Advanced API¶

Most applications should use Compose. The objects on this page expose implementation-level building blocks for research, inspection, and controlled integrations. Their contracts are narrower and more likely to evolve than the core pipeline API.

Stability levels¶

Level	Surface	Guidance
Public	`Compose`, `TransformSpec`, descriptors, converters, target functions, enums	Preferred application API
Advanced	Segment classes, adapter/converter protocols, `build_segments`	Use when the low-level contract is understood and pinned by tests
Experimental/internal	`_backend.register_adapter`, entry-point loading, private segment subclasses	Do not treat as stable production extension API

Segment objects are torch.nn.Module implementations, but the top-level pipeline directly dispatches their forward methods for speed. Forward hooks registered on individual segment modules are therefore bypassed; register hooks on the pipeline or execute the segment directly when hook observation is required.

Geometric segments¶

`FusedAffineSegment`¶

Composes one compatible affine/exact run. Its adapter must classify transforms, sample canonical parameters, and build forward pixel matrices.

FusedAffineSegment ¶

FusedAffineSegment(transforms: list[object], adapter: TransformAdapter, interpolation: InterpolationStr | None = None, padding_mode: PaddingModeStr | None = None, randomness: RandomnessPolicy = BACKEND, *, compile_warp: bool = False, mask_interpolation: MaskInterpolationStr = 'nearest')

Bases: _BaseAffineSegment

Fused affine segment that composes geometric transforms into one grid_sample call.

Accumulates per-sample (B, 3, 3) forward affine matrices for every transform in the segment, inverts the composed matrix once, and applies a single grid_sample warp. All operations are vectorised over the batch dimension -- no Python loop per sample.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	List of geometric transform objects to fuse.	required
`adapter`	`TransformAdapter`	A `TransformAdapter` that bridges the transforms to canonical parameters and matrices.	required
`interpolation`	`InterpolationStr \| None`	Optional interpolation mode override (`"bilinear"`, `"nearest"`, `"bicubic"`). Defaults to `"bilinear"` when `None`.	`None`
`padding_mode`	`PaddingModeStr \| None`	Optional padding mode override (`"zeros"`, `"border"`, `"reflection"`). Defaults to `"zeros"` when `None`.	`None`
`mask_interpolation`	`MaskInterpolationStr`	Sampling mode for auxiliary masks. `"nearest"` preserves hard labels; `"bilinear"` supports float soft masks.	`'nearest'`

Initialize FusedAffineSegment.

forward ¶

forward(image: Tensor, aux_targets: dict[str, Tensor] | None = None) -> Tensor | tuple[Tensor, dict[str, Tensor]]

Apply the fused affine transform chain via a single grid_sample call.

Parameters:

Name	Type	Description	Default
`image`	`Tensor`	`(batch_size, channels, height, width)` float input tensor.	required
`aux_targets`	`dict[str, Tensor] \| None`	Optional dict of auxiliary targets to transform alongside the image (`"mask"`, `"bbox_xyxy"`, `"bbox_xywh"`, `"keypoints"`). When `None`, returns a bare tensor for backward compatibility.	`None`

Returns:

Type	Description
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	Bare `image` tensor when `aux_targets` is `None`;
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	`(image, aux_targets)` tuple otherwise.

`ExactAffineSegment`¶

Executes an exact-only run without interpolation. Supported discrete operations and auxiliary-target behavior depend on the adapter.

ExactAffineSegment ¶

ExactAffineSegment(transforms: list[object], adapter: TransformAdapter, randomness: RandomnessPolicy = BACKEND)

Bases: Module

Lossless segment for GEOMETRIC_EXACT-only chains.

Used when a run of consecutive geometric transforms consists entirely of GEOMETRIC_EXACT operations, such as flips and other discrete, lossless image-space transforms supported by the active adapter (for example 90-degree rotations or transpose-like ops). Applies each transform via :meth:TransformAdapter.exact_apply instead of grid_sample, introducing zero interpolation error.

Per-sample probability masking is implemented by sampling a boolean mask of shape (B,) from each transform's application probability and applying the exact transform only to active samples. The fused engine prefers a prob attribute when present and falls back to backend p for native transform objects.

Auxiliary-target routing: masks route for every exact op (a non-flip op's mask is transformed by the same lossless rotation applied to the image, sharing its per-sample sampling); boxes/keypoints route for flips via :meth:TransformAdapter.exact_flip_dims. A geometric run that combines a non-flip exact op with box/keypoint targets is built as a :class:FusedAffineSegment (grid path) instead, so those targets are always routed -- build_segments receives that hint via its route_coords_via_grid flag.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	List of `GEOMETRIC_EXACT` transform objects.	required
`adapter`	`TransformAdapter`	A `TransformAdapter` providing `exact_apply` for image updates and, when auxiliary targets are used, `exact_flip_dims` for flip-compatible target routing.	required
`randomness`	`RandomnessPolicy`	Batch randomness policy. `BACKEND` preserves native backend semantics; `PER_SAMPLE` draws probability masks per item.	`BACKEND`

Examples:

>>> import torch
>>> import kornia.augmentation as K
>>> from fuse_augmentations.affine.segment import ExactAffineSegment
>>> from fuse_augmentations.adapters.kornia import KorniaAdapter
>>> t = K.RandomHorizontalFlip(p=1.0)
>>> seg = ExactAffineSegment([t], KorniaAdapter())
>>> out = seg(torch.zeros(1, 3, 8, 8))
>>> out.shape
torch.Size([1, 3, 8, 8])

Initialize ExactAffineSegment.

last_matrix `property` ¶

last_matrix: Tensor | None

Return None always (ExactAffineSegment does not compute a matrix).

forward ¶

forward(image: Tensor, aux_targets: dict[str, Tensor] | None = None) -> Tensor | tuple[Tensor, dict[str, Tensor]]

Apply exact transforms losslessly with per-sample masking.

For each transform, draws a per-sample boolean mask from the transform's prob probability, applies :meth:TransformAdapter.exact_apply only to active samples, and scatters the transformed subset back into the batch. Auxiliary-target routing is currently supported only for flip-compatible exact ops exposed through :meth:TransformAdapter.exact_flip_dims.

Parameters:

Name	Type	Description	Default
`image`	`Tensor`	Input image batch. Shape: `(batch_size, channels, height, width)`, dtype: float32. Value range and channel convention follow the calling pipeline.	required
`aux_targets`	`dict[str, Tensor] \| None`	Optional dict of auxiliary targets to transform alongside the image (`"mask"`, `"bbox_xyxy"`, `"bbox_xywh"`, `"keypoints"`). When `None`, returns a bare tensor for backward compatibility.	`None`

Returns:

Type	Description
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	Bare `image` tensor when `aux_targets` is `None`;
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	`(image, aux_targets)` tuple otherwise.

`ProjectiveSegment`¶

Composes consecutive projective homographies. It is a separate segment from adjacent affine geometry.

ProjectiveSegment ¶

ProjectiveSegment(transforms: list[object], adapter: TransformAdapter, interpolation: InterpolationStr | None = None, padding_mode: PaddingModeStr | None = None, randomness: RandomnessPolicy = BACKEND, *, compile_warp: bool = False, mask_interpolation: MaskInterpolationStr = 'nearest')

Bases: _BaseAffineSegment

Fused projective segment that composes homography matrices into one grid_sample call.

Identical to :class:FusedAffineSegment in accumulation and auxiliary-target handling -- both share the :class:_BaseAffineSegment composition engine -- but overrides :meth:_apply_grid to use :func:~fuse_augmentations.affine.matrix.perspective_grid instead of F.affine_grid so the full 3x3 homography (including perspective division) is applied correctly.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	List of projective transform objects to fuse.	required
`adapter`	`TransformAdapter`	A `TransformAdapter` that bridges the transforms to canonical parameters and matrices.	required
`interpolation`	`InterpolationStr \| None`	Optional interpolation mode override (`"bilinear"`, `"nearest"`, `"bicubic"`). Defaults to `"bilinear"` when `None`.	`None`
`padding_mode`	`PaddingModeStr \| None`	Optional padding mode override (`"zeros"`, `"border"`, `"reflection"`). Defaults to `"zeros"` when `None`.	`None`

forward ¶

forward(image: Tensor, aux_targets: dict[str, Tensor] | None = None) -> Tensor | tuple[Tensor, dict[str, Tensor]]

Apply the fused projective transform chain via a single grid_sample call.

Parameters:

Name	Type	Description	Default
`image`	`Tensor`	`(B, C, H, W)` float input tensor.	required
`aux_targets`	`dict[str, Tensor] \| None`	Optional dict of auxiliary targets to transform alongside the image (`"mask"`, `"bbox_xyxy"`, `"bbox_xywh"`, `"keypoints"`). When `None`, returns a bare tensor for backward compatibility.	`None`

Returns:

Type	Description
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	Bare `image` tensor when `aux_targets` is `None`;
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	`(image, aux_targets)` tuple otherwise.

`CropResizeSegment`¶

Runs a standalone fixed-output crop-resize. On torch paths, an immediately preceding affine run may instead be represented by a private combined geo-crop segment; that private implementation is intentionally not an API object.

CropResizeSegment ¶

CropResizeSegment(transform: object, adapter: TransformAdapter, interpolation: InterpolationStr | None = None, padding_mode: PaddingModeStr | None = None, randomness: RandomnessPolicy = BACKEND, *, antialias: bool = False, mask_interpolation: MaskInterpolationStr = 'nearest')

Bases: Module

Segment for a single CROP_RESIZE_FIXED transform.

Samples the random crop region, builds the forward affine matrix, normalizes it via :func:~fuse_augmentations.affine.matrix.normalize_matrix_io (which accounts for different input and output spatial dimensions), and applies exactly one grid_sample call at the target (H_out, W_out) dimensions.

Unlike :class:FusedAffineSegment, the output shape is (batch_size, channels, height_out, width_out) which generally differs from the input shape (batch_size, channels, height_in, width_in).

.. note:: Per-sample probability prob is not applied: shape-changing transforms must produce a consistent output size for all batch elements, so the crop is always applied. Use prob=1.0 (the standard default) when constructing RandomResizedCrop transforms.

.. note:: Auxiliary targets ("mask", "bbox_xyxy", "bbox_xywh", "keypoints") are warped through the crop affine matrix at the target output size. Masks use nearest-neighbour sampling to preserve integer class labels; boxes and keypoints are transformed via the forward affine matrix.

Parameters:

Name	Type	Description	Default
`transform`	`object`	A single `CROP_RESIZE_FIXED` transform object.	required
`adapter`	`TransformAdapter`	A `TransformAdapter` providing `sample_params` and `build_matrix` for the transform.	required
`interpolation`	`InterpolationStr \| None`	Interpolation mode (`"bilinear"`, `"nearest"`, `"bicubic"`). Defaults to `"bilinear"` when `None`.	`None`
`padding_mode`	`PaddingModeStr \| None`	Padding mode (`"zeros"`, `"border"`, `"reflection"`). Defaults to `"zeros"` when `None`.	`None`
`mask_interpolation`	`MaskInterpolationStr`	Sampling mode for auxiliary masks. `"nearest"` preserves hard labels; `"bilinear"` supports float soft masks.	`'nearest'`

Initialize CropResizeSegment.

forward ¶

forward(image: Tensor, aux_targets: dict[str, Tensor] | None = None) -> Tensor | tuple[Tensor, dict[str, Tensor]]

Apply the crop-resize via a single grid_sample call at target output size.

Parameters:

Name	Type	Description	Default
`image`	`Tensor`	`(batch_size, channels, height_in, width_in)` float input tensor.	required
`aux_targets`	`dict[str, Tensor] \| None`	Optional dict of auxiliary targets to transform alongside the image. Supported keys: `"mask"`, `"bbox_xyxy"`, `"bbox_xywh"`, `"keypoints"`. Masks are warped with nearest-neighbour sampling to the target size; boxes and keypoints are transformed via the forward affine matrix.	`None`

Returns:

Type	Description
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	`(batch_size, channels, height_out, width_out)` tensor when `aux_targets` is `None`;
`Tensor \| tuple[Tensor, dict[str, Tensor]]`	`(tensor, aux_targets)` tuple otherwise.

Color segments¶

FusedColorSegment accepts transforms that the adapter can express as homogeneous (4 \times 4) color matrices. It cannot represent nonlinear saturation/hue or arbitrary intermediate clamps.

FusedColorSegment ¶

FusedColorSegment(transforms: list[object], adapter: TransformAdapter, clip_output: bool = True, randomness: RandomnessPolicy = BACKEND, clip_policy: ClipPolicyStr = 'final', *, compile_color: bool = False)

Bases: Module

Fused colour-space segment that composes POINTWISE_LINEAR transforms into one matrix multiply.

Accumulates per-sample (B, 4, 4) homogeneous colour-space affine matrices for every transform in the segment, multiplies all pixels by the composed matrix, and clamps the result to [0, 1]. All operations are vectorised over the batch dimension.

Colour transforms do not affect spatial layout, so auxiliary targets (masks, bounding boxes, keypoints) are returned unchanged.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	List of `POINTWISE_LINEAR` transform objects to fuse.	required
`adapter`	`TransformAdapter`	A `TransformAdapter` providing `sample_params` and `build_color_matrix` for each transform.	required
`clip_output`	`bool`	When `True` (default), the fused output is clamped to `[0, 1]` after the matrix multiply, matching the typical behaviour of individual colour transforms. Set to `False` only when the pipeline intentionally produces values outside this range (e.g. transforms configured with `clip_output=False` in the underlying library).	`True`

Initialize FusedColorSegment.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	`POINTWISE_LINEAR` transforms to fuse.	required
`adapter`	`TransformAdapter`	Adapter providing `sample_params` and `build_color_matrix`.	required
`clip_output`	`bool`	Whether to clamp the final output to `[0, 1]`.	`True`
`randomness`	`RandomnessPolicy`	Batch randomness policy.	`BACKEND`
`clip_policy`	`ClipPolicyStr`	`"final"` (default) fuses the whole chain into one matmul and clamps once; `"per_op_parity"` clamps at each op whose intermediate could leave `[0, 1]`, matching a native per-op clamped chain.	`'final'`
`compile_color`	`bool`	Compile only the pure color matrix application on non-CPU devices.	`False`

transforms `property` ¶

transforms: list[object]

Return the list of transforms in this segment.

forward ¶

forward(image: Tensor, aux_targets: dict[str, Any] | None = None) -> Tensor | tuple[Tensor, dict[str, Any]]

Apply the fused colour matrix to the image batch.

Parameters:

Name	Type	Description	Default
`image`	`Tensor`	`(batch_size, channels, height, width)` float input tensor with values in `[0, 1]`.	required
`aux_targets`	`dict[str, Any] \| None`	Optional dict of auxiliary targets. Colour transforms do not affect spatial layout, so these are returned unchanged.	`None`

Returns:

Type	Description
`Tensor \| tuple[Tensor, dict[str, Any]]`	Bare `image` tensor when `aux_targets` is `None`;
`Tensor \| tuple[Tensor, dict[str, Any]]`	`(image, aux_targets)` tuple otherwise.

Segmentation helper¶

build_segments is exported for advanced use but is an implementation-oriented planner. It expects an adapter instance and returns a heterogeneous list of segment modules and passthrough transforms. Prefer Compose unless a custom planner is being tested directly.

build_segments ¶

build_segments(transforms: list[object], adapter: TransformAdapter, interpolation: InterpolationStr | None = None, padding_mode: PaddingModeStr | None = None, randomness: RandomnessPolicy = BACKEND, *, use_numpy: bool = False, route_coords_via_grid: bool = False, route_crop_aux: bool = False, execution: ExecutionStr = 'cv2', compile_warp: bool = False, per_transform_padding: bool = False, antialias: bool = False, clip_policy: ClipPolicyStr = 'final', mask_interpolation: MaskInterpolationStr = 'nearest') -> list[object]

Split a transform list into fused segments and passthrough transforms.

Walks the transforms left to right and groups consecutive geometric transforms (GEOMETRIC_INTERP or GEOMETRIC_EXACT) into a single segment. Any SPATIAL_KERNEL, POINTWISE, or POINTWISE_LINEAR transform breaks the current geometric group and is returned as-is.

After grouping, each accumulated geometric run is classified:

EXACT-only - if the run contains only GEOMETRIC_EXACT ops (e.g. flips, 90-degree rotations, transpose-like discrete ops), it becomes an :class:ExactAffineSegment that uses adapter-provided exact image operations with zero interpolation error.
Mixed / INTERP - if any op in the run is GEOMETRIC_INTERP, the whole run becomes a :class:FusedAffineSegment that composes matrices and applies one grid_sample call.

When ReorderPolicy.POINTWISE is active in :class:~fuse_augmentations.compose.FusedCompose, reorder_pointwise is called first to bubble pointwise ops out of geometric chains, and build_segments then classifies the reordered list.

Parameters:

Name	Type	Description	Default
`transforms`	`list[object]`	List of transform objects (already reordered if a reorder policy applies).	required
`adapter`	`TransformAdapter`	A `TransformAdapter` for category lookup and matrix building.	required
`interpolation`	`InterpolationStr \| None`	Interpolation mode override forwarded to each :class:`FusedAffineSegment` (`"bilinear"`, `"nearest"`, `"bicubic"`).	`None`
`padding_mode`	`PaddingModeStr \| None`	Padding mode override forwarded to each :class:`FusedAffineSegment` (`"zeros"`, `"border"`, `"reflection"`).	`None`
`use_numpy`	`bool`	When `True`, produce :class:`AlbuFusedAffineSegment` instances (Albumentations/scipy backend) instead of the PyTorch :class:`FusedAffineSegment`. Used for the Albumentations backend.	`False`
`randomness`	`RandomnessPolicy`	Batch randomness policy for fused PyTorch segments.	`BACKEND`
`route_coords_via_grid`	`bool`	When `True` (set by the caller when the pipeline carries box/keypoint auxiliary targets), route an all-exact geometric run through :class:`FusedAffineSegment` instead of :class:`ExactAffineSegment`. An all-exact run always composes to a D4 element, so the fused segment's exact-dispatch still applies it losslessly while routing boxes/keypoints through the composed pixel matrix — avoiding the `ExactAffineSegment` box/keypoint limitation without an interpolation penalty. Torch path only.	`False`
`route_crop_aux`	`bool`	When `True` (set by the caller when the pipeline carries any auxiliary target), emit a :class:`CropResizeSegment` for a `CROP_RESIZE_FIXED` op on the `use_numpy` (Albumentations) path instead of an image-only passthrough, so masks/boxes/keypoints route to the crop's output size. Without it the numpy-path crop resizes the image only, silently desyncing aux targets. No effect on the PyTorch backends (they always build `CropResizeSegment`).	`False`
`execution`	`ExecutionStr`	Execution strategy forwarded to the Albumentations fused segments (`use_numpy=True` path). `"cv2"` (default) warps each sample with OpenCV; `"torch"` opts into one batched `grid_sample` for the whole batch. Ignored for the PyTorch backends.	`'cv2'`
`compile_warp`	`bool`	When `True` (and torch is new enough), the torch warp core (matrix normalize -> `affine_grid` -> `grid_sample`) of each fused geometric or projective segment runs under `torch.compile`. Off by default and a no-op on CPU or older torch — the eager output is unchanged. Crop-resize segments (:class:`CropResizeSegment`, :class:`_FusedGeoCropSegment`) build their warp inline and do not honor this flag.	`False`
`per_transform_padding`	`bool`	When `True`, partition geometric runs by each transform's compatible border mode instead of applying `padding_mode` to the entire run. Opaque modes remain native passthrough boundaries.	`False`
`antialias`	`bool`	When `True`, crop-resize segments prefilter the input before an aggressive downscale so the single warp does not alias. Off by default and a no-op unless the scale drops past the threshold — the output is unchanged.	`False`
`clip_policy`	`ClipPolicyStr`	Clamp policy forwarded to each :class:`FusedColorSegment`. `"final"` (default) fuses the color chain into one matmul and clamps once; `"per_op_parity"` clamps at each op that could leave `[0, 1]`.	`'final'`
`mask_interpolation`	`MaskInterpolationStr`	Sampling mode for routed masks. `"nearest"` preserves the historical hard-label behavior; `"bilinear"` supports float soft masks.	`'nearest'`

Returns:

Name	Type	Description
	`list[object]`	Flat list where each element is a :class:`FusedAffineSegment`
	`list[object]`	(mixed/INTERP geometric run), an :class:`ExactAffineSegment`
	`list[object]`	(EXACT-only geometric run; auxiliary targets remain flip-only),
`a`	`list[object]`	class:`CropResizeSegment` (`CROP_RESIZE_FIXED` op on the
	`list[object]`	PyTorch path), a :class:`FusedColorSegment` (`POINTWISE_LINEAR`
	`list[object]`	run where the adapter supports `build_color_matrix`), or the
	`list[object]`	original transform object (passthrough for `SPATIAL_KERNEL`,
	`list[object]`	`POINTWISE`, `CROP_RESIZE_FIXED` on the numpy path, and
	`list[object]`	unsupported `POINTWISE_LINEAR` transforms).

Protocols¶

Transform adapters¶

The protocol describes classification, parameter sampling, matrix building, exact execution, color-matrix building, and native passthrough. Conformance alone does not register an adapter with Compose.

TransformAdapter ¶

Bases: Protocol

Adapter between a backend transform and the fused affine engine.

Implementations bridge framework-specific transforms (Kornia, Albumentations, TorchVision) to the canonical parameter representation used by FusedAffineSegment.

Optional descriptive members (read via fuse_augmentations._backend.adapter_capabilities and direct getattr, so absence is tolerated for backwards compatibility):

capabilities: frozenset[str] — canonical op names (see :data:~fuse_augmentations.resolver.SUPPORTED_OPS) the adapter can build.
sampling_semantics: SamplingSemantics — whether the adapter draws one parameter set per sample or one per batch.

These are intentionally not declared as Protocol members: doing so would make @runtime_checkable isinstance require them, breaking adapters that predate the attributes. Instead they are read defensively via fuse_augmentations._backend.adapter_capabilities and getattr, so absence is tolerated. isinstance therefore continues to check only the methods below.

category ¶

category(transform: object) -> TransformCategory

Return the TransformCategory of the given transform.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object.	required

Returns:

Type	Description
`TransformCategory`	The category classification for the transform.

sample_params ¶

sample_params(transform: object, input_shape: tuple[int, int, int, int], device: device) -> dict[str, Tensor]

Sample random parameters for a batch of images.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object.	required
`input_shape`	`tuple[int, int, int, int]`	(batch_size, channels, height, width) tuple.	required
`device`	`device`	Target device for parameter tensors.	required

Returns:

Type	Description
`dict[str, Tensor]`	Dict mapping canonical parameter names to (batch_size,) tensors.

build_matrix ¶

build_matrix(transform: object, params: dict[str, Tensor], height: int, width: int) -> Tensor

Build a (batch_size, 3, 3) pixel-space forward affine matrix from sampled params.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object.	required
`params`	`dict[str, Tensor]`	Canonical-unit parameter dict from sample_params().	required
`height`	`int`	Image height in pixels.	required
`width`	`int`	Image width in pixels.	required

Returns:

Type	Description
`Tensor`	Tensor of shape (batch_size, 3, 3).

exact_flip_dims ¶

exact_flip_dims(transform: object) -> list[int]

Return the tensor dimensions to flip for a GEOMETRIC_EXACT transform.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object (must be GEOMETRIC_EXACT category).	required

Returns:

Type	Description
`list[int]`	List of dimension indices passed to `tensor.flip(dims=...)`,
`list[int]`	e.g. `[3]` for a horizontal flip, `[2]` for a vertical flip.

Raises:

Type	Description
`NotImplementedError`	If the adapter does not support ExactAffineSegment.

exact_apply ¶

exact_apply(transform: object, image: Tensor) -> Tensor

Apply a GEOMETRIC_EXACT transform losslessly to an image batch.

Implementers must provide this method for adapters that are used with :class:ExactAffineSegment. A typical implementation flips the image along the dims returned by :meth:exact_flip_dims. Adapters that support non-flip discrete ops (e.g. 90-degree rotations, transposes) can instead dispatch via torch.rot90, .permute, etc.

Warning

Implementations for stochastic discrete ops (RandomRotate90, D4) draw their own random parameters internally, independent of :meth:sample_params. Never combine an exact_apply image path with a :meth:sample_params-derived matrix for the SAME transform in one forward — the two draws are unrelated and image vs coordinate outputs would diverge. Current segments keep these paths mutually exclusive.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object (GEOMETRIC_EXACT category).	required
`image`	`Tensor`	`(batch_size, channels, height, width)` input tensor.	required

Returns:

Type	Description
`Tensor`	Transformed `(batch_size, channels, height, width)` tensor.

call_nonfused ¶

call_nonfused(transform: object, image: Tensor, **kwargs: object) -> Tensor

Apply a non-fusible transform directly via its native backend.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object.	required
`image`	`Tensor`	Input image tensor.	required
`**kwargs`	`object`	Additional keyword arguments forwarded to the transform.	`{}`

Returns:

Type	Description
`Tensor`	Transformed image tensor.

build_color_matrix ¶

build_color_matrix(transform: object, params: dict[str, Tensor], mean: Tensor | None = None) -> Tensor

Build a (batch_size, 4, 4) homogeneous color-space affine matrix from sampled params.

Adapters that support POINTWISE_LINEAR fusion must override this method to return a (batch_size, 4, 4) matrix encoding the per-channel linear colour transform (3x3 colour matrix + 3-element bias in homogeneous form). The default implementation raises NotImplementedError so that adapters without colour-fusion support fall back to passthrough segmentation automatically.

Accuracy caveats vs native backends (inherent to single-matrix fusion):

No intermediate clamping: native backends clamp to [0, 1] after EACH op; a fused matrix cannot represent clamping between ops, so out-of-gamut intermediates diverge from native. :class:~fuse_augmentations.affine.segment.FusedColorSegment clamps only the FINAL result (clip_output=True default). See clip_policy on :class:~fuse_augmentations.compose.FusedCompose for a per-op-parity split option.
Contrast midpoint: TorchVision/Kornia ColorJitter contrast is relative to the per-image mean luminance (c' = cf*c + (1-cf)*luma_mean). When mean is provided (the fused segment supplies the per-image luminance of the transform's input), that mean is used, matching native. When mean is None (a bare, out-of-context call), a fixed midpoint of 0.5 is used so the returned matrix is well-defined without an image.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object (`POINTWISE_LINEAR` category).	required
`params`	`dict[str, Tensor]`	Canonical parameter dict from :meth:`sample_params`.	required
`mean`	`Tensor \| None`	Optional per-image luminance of the image reaching this transform, shape `(batch_size,)`. Used only by contrast-like ops with a mean-relative midpoint (`ColorJitter` contrast). `None` falls back to the fixed `0.5` midpoint.	`None`

Returns:

Type	Description
`Tensor`	Tensor of shape `(batch_size, 4, 4)`.

Raises:

Type	Description
`NotImplementedError`	If the adapter does not support colour-space matrix fusion for this transform.

build_lut ¶

build_lut(transform: object, params: dict[str, Tensor], values: Tensor) -> Tensor

Apply a POINTWISE_LUT transform's per-channel intensity map to a grid of values.

Adapters that support static POINTWISE_LUT fusion (gamma, solarize, posterize) must override this to evaluate the transform's pointwise, per-channel scalar map on values using its own backend function (never a re-derived formula), returning the mapped intensities. The default implementation raises NotImplementedError so adapters without lookup-fusion support fall back to passthrough segmentation automatically.

:class:~fuse_augmentations.affine.segment.FusedLUTSegment composes a contiguous run of such ops by threading a domain grid through each op in order: values starts as a uniform grid over [0, 1] and each op maps it in place, so after the run values holds the composed function sampled on that grid — one lookup table applied once. Because each op is evaluated exactly on the running values (not re-interpolated between ops), the composition itself introduces no error.

Accuracy caveats vs native backends:

uint8 / 256-entry path (exact). When the segment enumerates the map over all 256 byte values, the composed table is bit-exact against a native sequential chain: each op is a deterministic 0..255 -> 0..255 map and integer composition loses nothing.
float / K-entry interp path (approximate). For a floating image the composed table is sampled on a uniform K-point grid (default K = 1024) and applied by gather + linear interpolation. This is exact-ish only for smooth maps: a steep region (e.g. gamma < 1 near black) can differ from native by ~2 uint8 levels, and a discontinuous map (solarize threshold, posterize step) uses a detected sharp step instead of a linear ramp, but its inferred breakpoint can still differ by part of a grid cell. Do not claim the float path beats native precision; gate float-path parity at a documented interpolation tolerance, never as >= native.

Parameters:

Name	Type	Description	Default
`transform`	`object`	The backend transform object (`POINTWISE_LUT` category).	required
`params`	`dict[str, Tensor]`	Canonical parameter dict from :meth:`sample_params`.	required
`values`	`Tensor`	`(batch_size, channels, num_points)` float tensor of input intensities in `[0, 1]` to map. The per-sample leading dim lets per-sample parameters (a random gamma per image) produce a per-sample lookup table.	required

Returns:

Type	Description
`Tensor`	Tensor of shape `(batch_size, channels, num_points)`: `values` after the
`Tensor`	transform's per-channel intensity map, clamped to `[0, 1]` as the native op does.

Raises:

Type	Description
`NotImplementedError`	If the adapter does not support lookup-table fusion for this transform.

Backend converters¶

Converters translate the pipeline's primary output representation. Coordinate-target conversion is deliberately separate from image layout conversion.

BackendConverter ¶

Bases: Protocol

Protocol for output format converters used with output_backend=.

Implementations convert the pipeline's native torch.Tensor output to a target backend format (e.g. NumPy ndarray).

target_backend `property` ¶

target_backend: str

Target backend identifier (e.g. 'numpy', 'torch').

convert ¶

convert(tensor: Any) -> Any

Convert tensor to target backend format.

Parameters:

Name	Type	Description	Default
`tensor`	`Any`	The input tensor to convert.	required

Returns:

Type	Description
`Any`	Converted object in the target backend format.

Experimental adapter registration¶

The private fuse_augmentations._backend module contains register_adapter and lazy loading for the fuse_augmentations.adapters entry-point group. This surface is explicitly experimental.

The current registry provides detection metadata. A default third-party adapter registered as Backend.UNKNOWN is not yet an end-to-end Compose execution path: composition dispatch only constructs one of the three built-in adapters. A production plugin should wait for a public contract with an integration test covering registration, construction, forward execution, and serialization.

Do not map a third-party adapter to a built-in backend enum as a workaround. Composition would retrieve the built-in adapter, not the registered third-party instance.

When to stay at the core API¶

Use Compose instead of direct segments when any of these are needed:

mixed-backend routing;
output conversion;
data_keys validation and assembly;
passthrough safety checks;
structured plan descriptors;
serialization compatibility;
stable handling of future segment implementations.

Advanced API¶

Stability levels¶

Geometric segments¶

FusedAffineSegment¶

FusedAffineSegment ¶

forward ¶

ExactAffineSegment¶

ExactAffineSegment ¶

last_matrix property ¶

forward ¶

ProjectiveSegment¶

ProjectiveSegment ¶

forward ¶

CropResizeSegment¶

CropResizeSegment ¶

forward ¶

Color segments¶

FusedColorSegment ¶

transforms property ¶

forward ¶

Segmentation helper¶

build_segments ¶

Protocols¶

Transform adapters¶

TransformAdapter ¶

category ¶

sample_params ¶

build_matrix ¶

exact_flip_dims ¶

exact_apply ¶

call_nonfused ¶

build_color_matrix ¶

build_lut ¶

Backend converters¶

BackendConverter ¶

target_backend property ¶

convert ¶

Experimental adapter registration¶

When to stay at the core API¶

`FusedAffineSegment`¶

`ExactAffineSegment`¶

last_matrix `property` ¶

`ProjectiveSegment`¶

`CropResizeSegment`¶

transforms `property` ¶

target_backend `property` ¶