Fuse compatible augmentations, once¶
fuse-augmentations is a PyTorch-based matrix-fusion engine for image augmentation pipelines. It recognizes a finite set of Kornia, TorchVision, and Albumentations transforms—or builds a pipeline directly from numeric ranges—then composes compatible transforms so a geometric chain can use fewer interpolation passes.
The strongest use case is a BCHW tensor pipeline with several consecutive, registered geometric transforms. Reducing repeated resampling can preserve more image detail, lower peak tensor memory, and accelerate long CPU chains.
This is not a general drop-in Compose replacement
Native PIL, CHW, Albumentations dictionary, target-processing, fill, center, random-number, and hook contracts are not preserved in general. Use the package as a tensor-first fusion engine and validate the exact pipeline you intend to ship.
Auxiliary targets require an allowlisted pipeline
With data_keys present, an unknown or unclassified spatial transform is rejected before any segment executes, preventing silent image/target divergence. Image-only calls may still use native passthrough; review every Unknown ... SPATIAL_KERNEL barrier warning. See Known limitations.
What is verified¶
- Registered consecutive affine transforms from one backend can be represented by a composed matrix and applied in one resampling pass.
- Exact discrete operations such as supported flips have lossless execution paths.
- Projective-to-projective chains, supported linear color chains, and some affine-to-crop paths have dedicated fusion strategies.
- Kornia, TorchVision, and Albumentations transforms can share one pipeline, with backend changes acting as hard fusion boundaries.
- A native builder supports rotation, scale, shear, translation, flips, brightness, and contrast without an optional augmentation backend.
- The pipeline exposes a structured fusion plan and per-call matrix access for inspection.
What is conditional¶
- Speed: long CPU geometric chains are the clearest win; single operations, mixed pipelines, and sampled TorchVision batch-8/32 workloads can be slower.
- Native parity: fewer resampling passes deliberately change numerics, and TorchVision center/fill/interpolation behavior is not generally pixel-equivalent.
- Targets: only registered and explicitly handled spatial operations are safe for multi-target routing.
- Reordering:
POINTWISEandAGGRESSIVEcan change pixels because border handling and clipping make operation order observable. - Accelerators: device execution is supported on torch paths. The published evidence includes a July 12, 2026 CPU run and a separate September 5, 2026 historical CUDA sweep; current-head CUDA/MPS measurements and runner availability remain unverified. See the benchmark record before making a device claim.
Choose your route¶
| Goal | Start here |
|---|---|
| Try the package with only its base dependencies | Quickstart |
| Bring an existing backend pipeline | Backend pipelines |
| Build one configuration for several backends | Declarative configuration |
| Route masks, boxes, or keypoints | Auxiliary targets |
| Evaluate image quality or performance | Research guide |
| Check an exact supported transform or restriction | Capabilities |
| Understand known unsafe or approximate behavior | Known limitations |
| Inspect signatures and docstrings | API reference |
Evidence standard¶
This documentation separates structural guarantees from measurements. Warp reduction follows from the fusion plan; speed and memory are measured properties of a particular backend, device, batch, shape, dtype, and transform mix. Benchmark pages publish losses and measurement blind spots alongside wins.
The package is currently classified Alpha. Treat advanced segment classes and the third-party adapter extension point as provisional.