Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

docs(augmentation): adopt choose-then-use docstrings and catalogs (#6560)

Dmytro Mishkin60b06181deba
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1b9284caa..c69f4ad7c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -111,7 +111,7 @@ A docstring is how a reader, human or agent, decides which function to call, so
- Write each entry as `` - :func:`name`: how it differs. ``; the explanation is required.
- Spell targets as Sphinx registers them: a short name for an object documented under the same module, the documented path (`~kornia.geometry.camera.perspective.unproject_points`) for the rest. A shorter import alias renders as plain text, with no warning.
- List kornia objects only, with no self-links or private names; mention torch and Python functions in the contract paragraph instead. Link true siblings both ways (v1 and v2, 2D and 3D); reviewers check that, no test does.
-- **Module docstrings** open with a title line, then the conventions the module's functions share, then "Which function to use", grouped by task, one line each, naming every entry of the `__all__` of the namespace users import from as a role (`` :func:`name` ``) or a literal (``` ``name`` ```). A namespace without `__all__` (`kornia.geometry`, `kornia.geometry.transform`) catalogs its subpackages and main entry points instead; a defining file without `__all__` gets no catalog.
+- **Module docstrings** open with a title line, then the conventions the module's functions share, then "Which function to use" (or "Which class to use" for a catalog of classes), grouped by task, one line each, naming every entry of the `__all__` of the namespace users import from as a role (`` :func:`name` ``) or a literal (``` ``name`` ```). A namespace without `__all__` (`kornia.geometry`, `kornia.geometry.transform`) catalogs its subpackages and main entry points instead; a defining file without `__all__` gets no catalog.
- **Shapes** are literals such as ``` ``(B, 1, H, W)`` ```. Keep `:math:` for formulas, and for a tuple that is a value, such as a point's `` :math:`(X, Y, Z)` ``; write a value range as an interval, `` :math:`[0, 1]` ``.
Enforcement, rollout tables, and reference-resolution rules are in [Docstring checks](TESTING.md#docstring-checks).
diff --git a/benchmarks/augmentation/README.md b/benchmarks/augmentation/README.md
index fce2fdb34..8ad228614 100644
--- a/benchmarks/augmentation/README.md
+++ b/benchmarks/augmentation/README.md
@@ -100,7 +100,7 @@ misleading. What each one operates on:
| Library | Data | Batch | Device | Differentiable |
| --- | --- | --- | --- | --- |
| **kornia** | `float` `BCHW` tensor | βœ… batched | CPU **or GPU** | βœ… yes |
-| **torchvision v2** | `float` `BCHW` tensor | βœ… batched | CPU or GPU | ❌ no |
+| **torchvision v2** | `float` `BCHW` tensor | βœ… batched | CPU or GPU | ⚠️ 5 of the 8 benchmark transforms |
| **albumentations** | `uint8` `HWC` numpy | ❌ per-image loop | CPU only | ❌ no |
| **OpenCV** (`cv2`) | `uint8` `HWC` numpy | ❌ per-image loop | CPU only | ❌ no |
| **PIL** (Pillow) | `uint8` `HWC` image | ❌ per-image loop | CPU only | ❌ no |
@@ -112,8 +112,9 @@ Two distinct races follow:
the classic data-loader regime, and the SIMD/native backends win it. kornia's `float` path is
*not* built for this and should not be expected to lead.
- **GPU / `float` / batched / differentiable** β€” kornia's home turf. torchvision v2 competes on
- raw speed but is not differentiable; nothing else runs here at all. This is the regime kornia
- is designed to lead, and where `torch.compile` fusion pays off.
+ raw speed, but its backward pass raises for `RandomAffine`, `RandomPerspective` and `ColorJitter`
+ with hue; nothing else runs here at all. This is the regime kornia is designed to lead, and where
+ `torch.compile` fusion pays off.
## Historical sample results (all_libraries.py, superseded 2026-08-08)
diff --git a/docs/source/augmentation.auto.rst b/docs/source/augmentation.auto.rst
index da6ec6055..b0f7dd009 100644
--- a/docs/source/augmentation.auto.rst
+++ b/docs/source/augmentation.auto.rst
@@ -9,7 +9,14 @@ Automatic Augmentation Methods
Augmentation Policy
-------------------
-This module contains common data augmentation policies that can improve the accuracy of image classification models.
+The three policies differ in how they pick operations:
+
+- :class:`AutoAugment` picks one sub-policy from a searched dataset preset, or from a list you supply.
+- :class:`RandAugment` picks ``n`` distinct operations and sets every magnitude from ``m``.
+- :class:`TrivialAugment` picks one operation and draws its magnitude, if it has one, per image.
+
+One call picks one operation sequence for the whole batch; each operation then applies its own probability and
+parameters. To chain transforms of your own choice, use :class:`~kornia.augmentation.container.ImageSequential`.
.. autoclass:: AutoAugment
@@ -51,6 +58,33 @@ This module contains common data augmentation policies that can improve the accu
.. automethod:: forward
+Policy operations
+-----------------
+
+The operations the policies above sample. Use them directly to define a custom policy.
+
+.. currentmodule:: kornia.augmentation.auto.operations.ops
+
+.. autoclass:: AutoContrast
+.. autoclass:: Brightness
+.. autoclass:: Contrast
+.. autoclass:: Equalize
+.. autoclass:: Gray
+.. autoclass:: HorizontalFlip
+.. autoclass:: Hue
+.. autoclass:: Invert
+.. autoclass:: Posterize
+.. autoclass:: Rotate
+.. autoclass:: Saturate
+.. autoclass:: Sharpness
+.. autoclass:: ShearX
+.. autoclass:: ShearY
+.. autoclass:: Solarize
+.. autoclass:: SolarizeAdd
+.. autoclass:: TranslateX
+.. autoclass:: TranslateY
+.. autoclass:: VerticalFlip
+
Augmentation Search Methods
---------------------------
diff --git a/docs/source/augmentation.base.rst b/docs/source/augmentation.base.rst
index 00ed4bd21..1ccd477b2 100644
--- a/docs/source/augmentation.base.rst
+++ b/docs/source/augmentation.base.rst
@@ -104,7 +104,7 @@ value in `apply_transform`:
super().__init__(p=p, same_on_batch=same_on_batch, keepdim=keepdim)
# A PlainUniformGenerator sampler is a 4-tuple ``(range, name, center, bound)``:
# sample a value inside ``range`` and expose it as ``params[name]``. ``center`` and
- # ``bound`` (``None`` here) are optional constraints for centred/bounded ranges.
+ # ``bound`` (``None`` here) are optional constraints for centered/bounded ranges.
self._param_generator = rg.PlainUniformGenerator((add_range, "add", None, None))
def apply_transform(
diff --git a/docs/source/augmentation.container.rst b/docs/source/augmentation.container.rst
index 02b278686..fc753a2fb 100644
--- a/docs/source/augmentation.container.rst
+++ b/docs/source/augmentation.container.rst
@@ -6,16 +6,22 @@ Augmentation Containers
.. currentmodule:: kornia.augmentation.container
-The classes in this section are containers for augmenting different data formats (e.g. images, videos).
+Containers chain augmentations into one pipeline. Use :class:`AugmentationSequential` when masks, boxes or keypoints
+must follow the image, and :class:`ImageSequential` for images alone. :class:`VideoSequential` applies image
+transforms to every frame of a video, and :class:`PatchSequential` to every patch of an image grid. The dispatchers
+run several pipelines, either all on one input or each on its own input.
Augmentation Sequential
-----------------------
-Kornia augmentations provide a simple on-device augmentation framework with a number of conveniences
-(e.g. returning the transformation matrix, or inverting a geometric transform). On top of that, we provide an
-advanced augmentation container to ease the pain of building augmentation pipelines. This API also provides
-predefined routines that automate the processing of masks, bounding boxes, and keypoints.
+``AugmentationSequential`` samples its parameters once per call and applies them to every input named in
+``data_keys``: images, masks, boxes and keypoints. It records the draw for replay, composes the matrices of its
+geometric steps, and undoes the 2D matrix-based ones with ``inverse()``. Keypoints and
+:class:`~kornia.geometry.boxes.Boxes` come back to their input coordinates. Tensor boxes are refit to axis-aligned
+boxes, so a rotation can enlarge them: a 12 Γ— 8 box rotated by 45Β° comes back 20 Γ— 20. A 3D geometric child raises
+``NotImplementedError``, and a mix child raises ``RuntimeError``. Inversion does not restore the pixels lost to
+cropping or resampling, and it leaves color changes and non-rigid warps in place.
.. autoclass:: AugmentationSequential
@@ -158,6 +164,18 @@ data formats.
.. automethod:: forward
+Container building blocks
+-------------------------
+
+Base classes and parameter records for writing a custom container. To build a pipeline, use the containers above.
+
+.. autoclass:: kornia.augmentation.container.base.BasicSequentialBase
+.. autoclass:: kornia.augmentation.container.base.SequentialBase
+.. autoclass:: kornia.augmentation.container.base.ImageSequentialBase
+.. autoclass:: kornia.augmentation.container.params.ParamItem
+.. autoclass:: kornia.augmentation.container.params.PatchParamItem
+
+
Data keys
---------
diff --git a/docs/source/augmentation.geometric.rst b/docs/source/augmentation.geometric.rst
index 4508a474f..abe9ded97 100644
--- a/docs/source/augmentation.geometric.rst
+++ b/docs/source/augmentation.geometric.rst
@@ -3,12 +3,16 @@
.. currentmodule:: kornia.augmentation
-Spatial transformations and erasing operations. Matrix, inverse and annotation support depend on the class
-and configuration. The non-rigid `RandomElasticTransform`, `RandomThinPlateSpline` and `RandomFisheye` cannot
-move boxes and keypoints with the image, so a forward call with either raises; ``.inverse()`` leaves these steps
-applied (`#4420 <https://github.com/kornia/kornia/issues/4420>`_). `RandomErasing` changes image
-and mask values without moving coordinates. See
-:class:`~kornia.augmentation.AugmentationSequential` for the supported data-key paths and their limitations.
+Spatial transforms, plus ``RandomErasing``, which changes image and mask values without moving coordinates. The
+non-rigid ``RandomElasticTransform``, ``RandomThinPlateSpline`` and ``RandomFisheye`` cannot move boxes or
+keypoints, so a container call that passes them raises; the last two raise for masks too. ``.inverse()`` leaves
+these steps applied (`#4420 <https://github.com/kornia/kornia/issues/4420>`_). See
+:class:`~kornia.augmentation.AugmentationSequential` for the supported data-key paths.
+
+``RandomAffine`` combines rotation, translation, scale and shear in one warp; ``RandomPerspective`` warps
+projectively. ``RandomCrop`` cuts a fixed-size patch at a random position, ``RandomResizedCrop`` cuts a patch of
+random size and aspect ratio and resizes it, and ``CenterCrop`` always cuts the center. ``RandomRotation90``
+rotates by multiples of 90 degrees.
.. autoclass:: CenterCrop
.. autoclass:: PadTo
diff --git a/docs/source/augmentation.intensity.rst b/docs/source/augmentation.intensity.rst
index b6c08d568..e7fb11bbc 100644
--- a/docs/source/augmentation.intensity.rst
+++ b/docs/source/augmentation.intensity.rst
@@ -4,7 +4,12 @@
.. currentmodule:: kornia.augmentation
Transforms that change pixel values but keep every pixel where it is, so masks, boxes and keypoints pass through
-unchanged.
+unchanged. With default arguments, 24 of the 37 transforms on this page clamp their output to ``[0, 1]``. These 13
+do not: the four blurs, ``RandomGaussianNoise``, ``RandomSaltAndPepperNoise``, ``RandomGrayscale``, ``RandomInvert``,
+``RandomChannelShuffle``, ``RandomChannelDropout``, ``RandomRain``, ``Normalize`` and ``Denormalize``.
+
+``ColorJiggle`` and ``ColorJitter`` both jitter brightness, contrast, saturation and hue; ``ColorJitter`` uses
+torchvision's formulas. ``RandomEqualize`` equalizes whole channels, ``RandomClahe`` local tiles.
.. autoclass:: ColorJiggle
.. autoclass:: ColorJitter
diff --git a/docs/source/augmentation.mix.rst b/docs/source/augmentation.mix.rst
index 1165bbe8e..c7b48fb73 100644
--- a/docs/source/augmentation.mix.rst
+++ b/docs/source/augmentation.mix.rst
@@ -6,6 +6,11 @@
Transforms that combine samples or rearrange patches within an image. Supported label, box and mask keys
vary by class; mixing does not imply support for every annotation type.
+``RandomMixUpV2`` blends each image with a paired batch image, and ``RandomCutMixV2`` pastes in a rectangle from
+it. ``RandomMosaic`` replaces an image by a crop of a mosaic of batch images; ``RandomJigsaw`` shuffles the tiles of
+each image. ``RandomTransplantation`` copies the region of one mask label, together with its mask, from the previous
+image in the batch.
+
.. autoclass:: PatchMix
.. autoclass:: RandomCutMixV2
.. autoclass:: RandomJigsaw
diff --git a/docs/source/augmentation.module.rst b/docs/source/augmentation.module.rst
index 573a74afe..4696b57cf 100644
--- a/docs/source/augmentation.module.rst
+++ b/docs/source/augmentation.module.rst
@@ -8,9 +8,13 @@ Image Augmentations
.. currentmodule:: kornia.augmentation
-The augmentation operators, grouped by what they change. All of them accept ``(B, C, H, W)`` float tensors in
-``[0, 1]`` (``(B, C, D, H, W)`` for the 3D transforms), sample independent parameters per batch element, and can
-be combined with :class:`~kornia.augmentation.AugmentationSequential`.
+The augmentation operators, grouped by what they change. They take float tensors of shape ``(B, C, H, W)``, or
+``(B, C, D, H, W)`` for the 3D transforms; color transforms expect values in ``[0, 1]``. Each operator applies
+with probability ``p``, drawn per sample, except the crops, the resizes, ``RandomMixUpV2``, ``RandomCutMixV2``,
+``PatchMix``, ``Normalize``, ``Denormalize`` and ``RandomDissolving``, which transform the whole batch or none of
+it. ``same_on_batch=True`` makes any other operator use one draw for the whole batch. In the class descriptions,
+"selected" samples are the ones ``p`` picked. Combine operators with
+:class:`~kornia.augmentation.container.AugmentationSequential`.
.. list-table::
:widths: 30 70
diff --git a/docs/source/augmentation.rst b/docs/source/augmentation.rst
index 8c3742286..3b3b223af 100644
--- a/docs/source/augmentation.rst
+++ b/docs/source/augmentation.rst
@@ -4,17 +4,18 @@ kornia.augmentation
.. meta::
:description: The Augmentation module in Kornia provides high-level data augmentation functionalities for computer vision tasks, including random rotations, affine transformations, color intensities, image noise distortion, and more. It supports batch processing, device compatibility, and backpropagation. Additionally, users can retrieve transformation details for more flexibility in complex pipelines.
-This module implements data augmentation at a high level of abstraction. Like the rest of the library,
-it performs augmentation routines in batch mode, on any supported device, and every operation is
-differentiable, so it can take part in backpropagation. Among the available functionalities are random rotations;
-affine and perspective transformations; several random color and intensity transformations; image noise;
-motion blur; and many differentiable data augmentation policies such as AutoAugment and RandAugment.
-
-In addition, the module includes a feature that is not found in other augmentation frameworks: after each
-call, the user can retrieve the applied transformation, or the chain of transformations, e.g. the sampled
-random rotation matrix. That matrix can later be used to undo the image transformation, or to apply the same
-transformation to additional data such as segmentation masks, bounding boxes or landmark keypoints. This gives
-the user the flexibility to build complex data augmentation pipelines.
+This module applies random augmentations to batches of float tensors on the CPU or the GPU: spatial transforms,
+color and intensity changes, blur and noise, image mixing, 3D volume transforms, and the AutoAugment, RandAugment
+and TrivialAugment policies. Most operators are differentiable with respect to their input.
+
+Every call records what it sampled. In eager mode, ``aug._params`` holds the last draw, and
+``aug(image, params=aug._params)`` replays it; matrix-based geometric transforms also expose the draw as
+``aug.transform_matrix``. :class:`~kornia.augmentation.container.AugmentationSequential` uses this record to apply
+one draw to an image and its masks, boxes and keypoints, and its ``inverse()`` undoes the 2D matrix-based geometric
+steps; 3D geometric and mix children raise. Inversion cannot restore pixels lost to cropping or resampling, and it
+leaves color changes in place.
+For images alone, chain transforms with :class:`~kornia.augmentation.container.ImageSequential`; for video, apply
+them to every frame with :class:`~kornia.augmentation.container.VideoSequential`.
.. code-block:: python
@@ -32,43 +33,45 @@ the user the flexibility to build complex data augmentation pipelines.
img_out, mask_out, kpts_out = aug(image, mask, keypoints) # same random parameters for all three
img_back, mask_back, kpts_back = aug.inverse(img_out, mask_out, kpts_out)
- matrix = aug.transform_matrix # (B, 3, 3) matrix of the last geometric transform
+ matrix = aug.transform_matrix # (B, 3, 3) composed matrix for the geometric steps
.. note::
- **Input format.** Kornia augmentations expect **float tensors with values in** ``[0, 1]`` and shape
- ``(B, C, H, W)`` β€” the same format produced by ``torchvision.transforms.v2.ToDtype(torch.float32, scale=True)``
- (or the legacy ``ToTensor``). A ``uint8`` tensor raises a clear error, but a **float tensor already in the**
- ``[0, 255]`` **range does not raise** β€” it is silently treated as ``[0, 1]`` and the output clips at ``1.0``,
- which shows up later as degraded model accuracy rather than an exception. Scale first, e.g. ``img.float() / 255``.
+ **Input format.** Pass float tensors of shape ``(B, C, H, W)`` for images and ``(B, C, D, H, W)`` for
+ volumes. Color transforms expect values in ``[0, 1]``, so convert 8-bit images with ``img.float() / 255``;
+ a cast alone does not rescale. A ``uint8`` tensor raises ``TypeError``, but a float tensor in ``[0, 255]``
+ raises nothing: most color transforms, such as :class:`~kornia.augmentation.ColorJiggle`, clamp it to
+ ``[0, 1]`` and the image comes out nearly white. For the same reason, apply color transforms before
+ :class:`~kornia.augmentation.Normalize`.
Benchmark
---------
-Kornia is **GPU-batched and differentiable** β€” that is the regime it is built to lead, and it is
-not the regime the other libraries target. A fair comparison holds the batch size and device fixed
-across libraries; comparing kornia at a large batch against a single-image library is not meaningful.
+Kornia is built for batches of float tensors on the GPU, with gradients through most operators. albumentations,
+OpenCV, PIL and kornia-rs transform one ``uint8`` image at a time on the CPU. torchvision v2 also runs batched on the
+GPU. In the benchmark's settings, gradients reach the input through five of its eight transforms, and the backward
+pass raises for ``RandomAffine``, ``RandomPerspective`` and ``ColorJitter`` with hue. Kornia passes a gradient through
+all eight.
-Reproducible, honestly-framed benchmarks live under
-`benchmarks/augmentation/ <https://github.com/kornia/kornia/tree/main/benchmarks/augmentation>`_ and
-print their git commit, platform, and device so results are auditable:
+The scripts under
+`benchmarks/augmentation/ <https://github.com/kornia/kornia/tree/main/benchmarks/augmentation>`_ print their git
+commit, platform and device with every result:
-- ``vs_torchvision.py`` β€” per-op kornia (eager / ``torch.compile``) vs torchvision v2, with a
- ``best/tv`` ratio and verdict per op.
-- ``flagship.py`` β€” the flagship suite: augmentations through each library's random-transform
- class API (parameter sampling included) vs torchvision v2, albumentations, OpenCV, and PIL,
- with machine-readable JSON export.
-- ``pipeline.py`` β€” end-to-end multi-op pipeline throughput (the shape a training loop runs),
- including a compiled and an ``--half`` (fp16/AMP) path.
+- ``flagship.py`` β€” each library's random-transform classes, parameter sampling included, against torchvision v2,
+ albumentations, OpenCV and PIL, with JSON export.
+- ``vs_torchvision.py`` β€” each kornia op, eager and compiled, against torchvision v2.
+- ``pipeline.py`` β€” a multi-op training pipeline end to end, with compiled and ``--half`` (fp16/AMP) paths.
-Reading them honestly: on a **GPU-batched, differentiable, compiled** pipeline kornia is the fastest
-option (torchvision v2 is not differentiable; albumentations is CPU/``uint8``/single-image). On
-**CPU single-image** throughput, SIMD/NumPy libraries such as albumentations are faster β€” that is
-their regime, not kornia's. See ``benchmarks/augmentation/README.md`` for the per-regime breakdown.
+In the RTX 4090 snapshot in ``benchmarks/augmentation/README.md`` (256 Γ— 256 float32 images, batch 32), compiled
+kornia on the GPU is 2.2–19.4Γ— faster than the fastest CPU ``uint8`` library on all eight operations, and faster than
+torchvision v2 on three of them: ``ColorJiggle`` (1.20Γ—), Gaussian blur (1.32Γ—) and perspective (1.15Γ—). Eager kornia
+on the GPU is 2.0–6.7Γ— faster than the fastest CPU library on seven operations, reaches 0.52Γ— of albumentations on
+``RandomResizedCrop``, and is slower than torchvision v2 on all eight. On the CPU at batch 1, albumentations or OpenCV
+is faster than both kornia modes on all eight.
Deployment: torch.export, torch.compile, ONNX
---------------------------------------------
-Kornia augmentations are plain ``nn.Module`` s and are exportable for deployment:
+Augmentations are ``nn.Module`` subclasses, so the PyTorch capture tools apply to them, within these limits:
- **torch.export.** Deterministic transforms β€” ``Normalize``, ``Denormalize``, ``Resize``,
``CenterCrop``, ``PadTo`` β€” and an ``AugmentationSequential`` pipeline of them capture cleanly
@@ -89,16 +92,20 @@ Kornia augmentations are plain ``nn.Module`` s and are exportable for deployment
is skipped during an export capture; the captured output is unchanged. Random augmentations and
bounding-box/keypoint propagation through an exported graph are not covered.
-- **torch.compile.** Most augmentations run fullgraph (0 graph breaks); a compiled
- ``AugmentationSequential`` fuses the pointwise chain end to end. See the per-op ``test_dynamo``
- tests for the compile-clean set.
-
-- **ONNX.** :class:`~kornia.onnx.sequential.ONNXSequential` chains ONNX graphs; it does not take an augmentation
- module. The :ref:`export survey <export-support>` records which individual augmentations exported. Without
- ``dynamic_shapes``, a pipeline exported with ``torch.onnx.export(..., dynamo=True)`` gets a graph of the input shape
- it was exported with, and some augmentations (``Resize``, for one) keep that shape fixed even with it, or fail to
- export with it on torch 2.5.1. Some augmentations fail to export. The exported file can be chained with
- ``ONNXSequential``. Pre-built ONNX models are published under the ``kornia/ONNX_models`` Hugging Face repo.
+- **torch.compile.** In the :ref:`augmentation export survey <export-support-kornia-augmentation>` (torch 2.9.1,
+ CPU), 60 of the 82 augmentation classes compile into one graph in every surveyed configuration, ``VideoSequential``
+ included. The other 22 break the graph, fail to compile, or give results that differ from eager in at least one
+ configuration: the other five containers, the three policies, the six mix transforms,
+ ``RandomTransplantation3D``, ``ColorJiggle``, ``ColorJitter``, ``RandomRain``, ``RandomSnow``, ``RandomClahe``,
+ ``RandomDissolving``, and ``RandomCrop`` with ``p=0.5``. Compiling is not always faster: in the benchmark snapshot
+ it slows CPU ``RandomAffine`` to 0.45Γ— of eager at batch 32, and speeds it up 1.55Γ— at batch 1.
+
+- **ONNX.** Export with ``torch.onnx.export(..., dynamo=True)`` and chain the file with
+ :class:`~kornia.onnx.sequential.ONNXSequential`, which takes ONNX graphs, not augmentation modules. Without
+ ``dynamic_shapes`` the graph is fixed to the input shape used for export; some augmentations, such as ``Resize``,
+ stay fixed even with it, or fail to export with it on torch 2.5.1. The :ref:`export survey <export-support>`
+ records which augmentations export. Pre-built ONNX models are published under the ``kornia/ONNX_models``
+ Hugging Face repo.
.. currentmodule:: kornia.augmentation
@@ -114,13 +121,13 @@ Where to find things
perspective, resize), :doc:`mix <augmentation.mix>` (CutMix, MixUp, Mosaic) and
:doc:`3D <augmentation.transforms3d>`.
* - :doc:`Containers <augmentation.container>`
- - :class:`AugmentationSequential` applies one sampled transform to images, masks, boxes and
- keypoints and can invert it; plus ``ImageSequential``, ``PatchSequential``, ``VideoSequential``
- and the dispatchers.
+ - :class:`~kornia.augmentation.container.AugmentationSequential` applies one draw to images, masks, boxes
+ and keypoints and can invert it; ``ImageSequential`` chains image-only transforms, ``VideoSequential``
+ applies them per frame, ``PatchSequential`` per grid patch, and the dispatchers run several pipelines.
* - :doc:`Automatic augmentation <augmentation.auto>`
- - The learned policies: :class:`~kornia.augmentation.auto.AutoAugment`,
- :class:`~kornia.augmentation.auto.RandAugment` and
- :class:`~kornia.augmentation.auto.TrivialAugment`.
+ - The policies :class:`~kornia.augmentation.auto.AutoAugment`,
+ :class:`~kornia.augmentation.auto.RandAugment` and :class:`~kornia.augmentation.auto.TrivialAugment`,
+ and the operations they sample.
* - :doc:`Base classes <augmentation.base>`
- Subclass ``IntensityAugmentationBase2D`` or ``GeometricAugmentationBase2D`` to write your own
augmentation, with worked examples.
diff --git a/docs/source/augmentation.transforms3d.rst b/docs/source/augmentation.transforms3d.rst
index 43fbe24cb..b5e55695c 100644
--- a/docs/source/augmentation.transforms3d.rst
+++ b/docs/source/augmentation.transforms3d.rst
@@ -3,7 +3,11 @@
.. currentmodule:: kornia.augmentation
-Operators for volumetric ``(B, C, D, H, W)`` tensors, e.g. medical volumes or video treated as 3D data.
+Operators for volumetric ``(B, C, D, H, W)`` tensors, such as medical volumes. For video, apply 2D transforms
+frame by frame with :class:`~kornia.augmentation.container.VideoSequential`. The geometric transforms order voxel
+coordinates ``(x, y, z)``, the reverse of the tensor's ``(D, H, W)``. Inside
+:class:`~kornia.augmentation.container.AugmentationSequential`, use :class:`RandomTransplantation3D` for volumes;
+:class:`RandomTransplantation` handles volumes only when called directly.
Geometric
---------
diff --git a/kornia/augmentation/_2d/base.py b/kornia/augmentation/_2d/base.py
index 87f2da21d..a1b6c56ae 100644
--- a/kornia/augmentation/_2d/base.py
+++ b/kornia/augmentation/_2d/base.py
@@ -59,11 +59,13 @@ _LazyMatrixArgs = Tuple[Union[torch.Tensor, _InputMetadata], Dict[str, torch.Ten
class AugmentationBase2D(_AugmentationBase):
- r"""Base class for custom 2D augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a custom 2D augmentation, applied per sample with probability ``p`` (default 0.5).
- AugmentationBase2D aims at offering a generic base class for a greater level of customization.
- If the subclass contains routined matrix-based transformations, `RigidAffineAugmentationBase2D`
- might be a better fit.
+ ``output = MyAugmentation(...)(input)`` processes images of shape ``(B, C, H, W)`` once a subclass
+ implements ``apply_transform`` and supplies any parameter generation it needs. This generic base supports
+ custom operations, including matrix-free warps such as :class:`RandomElasticTransform` and
+ :class:`RandomThinPlateSpline`. Use :class:`IntensityAugmentationBase2D` for value-only operations or
+ :class:`GeometricAugmentationBase2D` for matrix-based coordinate transforms.
This class is the anchor for the contract the 2D augmentations of ``kornia.augmentation`` inherit.
Mix and 3D augmentations have their own bases and contracts.
@@ -83,9 +85,9 @@ class AugmentationBase2D(_AugmentationBase):
and never drops a real batch dimension. The dtype guard accepts ``float16``, ``bfloat16``, ``float32``
and ``float64`` and raises ``TypeError`` on an integer tensor. The output keeps the input's device.
- a wrong input rank raises :class:`~kornia.core.exceptions.InputRankError` with the same message from
- every entry point, the class, :meth:`validate_tensor` and the containers. It is a ``ValueError`` and also a
+ every entry point, the class, ``validate_tensor()`` and the containers. It is a ``ValueError`` and also a
``RuntimeError`` and an ``AssertionError``, the types those entry points raised before
- (`#4424 <https://github.com/kornia/kornia/issues/4424>`_). :meth:`validate_tensor` accepts the ranks
+ (`#4424 <https://github.com/kornia/kornia/issues/4424>`_). ``validate_tensor()`` accepts the ranks
``forward`` accepts.
- this base samples ``p`` per sample and uses ``p_batch`` as a call-wide gate. ``same_on_batch=True``
shares applicable sampled values across the batch. Concrete constructors need not expose ``p_batch``;
@@ -119,6 +121,9 @@ class AugmentationBase2D(_AugmentationBase):
- ``torch.jit.script`` is not supported; ``torch.compile(fullgraph=True)`` works for some augmentations
and flags only.
+ See Also:
+ - :class:`GeometricAugmentationBase2D`: adds coordinate-aware geometric transform hooks.
+
"""
def validate_tensor(self, input: torch.Tensor) -> None:
@@ -141,12 +146,14 @@ class AugmentationBase2D(_AugmentationBase):
class RigidAffineAugmentationBase2D(AugmentationBase2D):
- r"""Base class for 2D rigid/affine augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Record a matrix for a custom 2D transform, applied per sample with probability ``p`` (default 0.5).
- See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
+ ``output = MyAugmentation(...)(input)`` records a ``(B, 3, 3)`` matrix once a subclass implements
+ ``compute_transformation`` and ``apply_transform``. This base manages matrix sampling and storage;
+ use :class:`GeometricAugmentationBase2D` for coordinate transforms or :class:`IntensityAugmentationBase2D`
+ for value-only operations.
- RigidAffineAugmentationBase2D manages transformation matrices. Further subclasses supply the
- handlers for different data types like masks, boxes, and keypoints.
+ See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
Args:
p: probability for applying an augmentation. This param controls the augmentation probabilities
@@ -170,6 +177,9 @@ class RigidAffineAugmentationBase2D(AugmentationBase2D):
or ``identity_matrix``, in which case the input is kept until the matrix is read or replaced.
- this base does not implement an inverse operation.
+ See Also:
+ - :class:`GeometricAugmentationBase2D`: applies and records 2D geometric transformations.
+
"""
_transform_matrix: Optional[torch.Tensor] = None
diff --git a/kornia/augmentation/_2d/geometric/affine.py b/kornia/augmentation/_2d/geometric/affine.py
index b0cb2a7f7..90bde38be 100644
--- a/kornia/augmentation/_2d/geometric/affine.py
+++ b/kornia/augmentation/_2d/geometric/affine.py
@@ -30,9 +30,10 @@ from kornia.geometry.transform import get_affine_matrix2d, warp_affine
class RandomAffine(GeometricAugmentationBase2D):
r"""Warp images by a random 2D affine transformation, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomAffine.png
+ ``output = RandomAffine(degrees, ...)(input)`` warps each image of shape ``(B, C, H, W)`` with one sampled
+ affine transform about its center.
- The transformation is computed so that the image center is kept invariant.
+ .. image:: _static/img/RandomAffine.png
.. note::
Unlike torchvision's ``RandomAffine``, which transforms every image, this class transforms each sample with
@@ -75,7 +76,7 @@ class RandomAffine(GeometricAugmentationBase2D):
move content right and down.
- a positive ``degrees`` rotates the displayed image clockwise, unlike :class:`RandomRotation`
(:doc:`/get-started/conventions`, `#4408 <https://github.com/kornia/kornia/issues/4408>`_).
- - ``shear`` draws degrees, converted to radians and applied about the image centre with the sign and the
+ - ``shear`` draws degrees, converted to radians and applied about the image center with the sign and the
x-then-y order of :func:`~kornia.geometry.transform.get_shear_matrix2d`, as
:class:`~kornia.geometry.transform.Affine` applies its ``shear``.
- in :class:`~kornia.augmentation.container.AugmentationSequential`, a ``fill_value`` with more than one
@@ -85,6 +86,11 @@ class RandomAffine(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.warp_affine`.
+ See Also:
+ - :class:`RandomRotation`: samples rotation without translation, scaling or shear.
+ - :class:`RandomPerspective`: samples a projective four-corner warp.
+ - :class:`RandomAffine3D`: applies the corresponding sampled transform to volumes.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/geometric/base.py b/kornia/augmentation/_2d/geometric/base.py
index 45adcb854..12f4c474b 100644
--- a/kornia/augmentation/_2d/geometric/base.py
+++ b/kornia/augmentation/_2d/geometric/base.py
@@ -29,7 +29,11 @@ from kornia.geometry.keypoints import Keypoints
class GeometricAugmentationBase2D(RigidAffineAugmentationBase2D):
- r"""Base class for custom 2D geometric augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a 2D coordinate transform, applied per sample with probability ``p`` (default 0.5).
+
+ ``output = MyAugmentation(...)(input)`` warps images of shape ``(B, C, H, W)`` once a subclass implements
+ ``compute_transformation`` and ``apply_transform``. Implement ``inverse_transform`` to support image inversion.
+ Use :class:`IntensityAugmentationBase2D` for an augmentation that changes values without moving coordinates.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
@@ -43,8 +47,8 @@ class GeometricAugmentationBase2D(RigidAffineAugmentationBase2D):
to the batch form ``False``.
Convention:
- - pixel coordinates are ``(x, y)`` at integer pixel centres, with corners ``(0, 0)`` and
- ``(W - 1, H - 1)`` (see :doc:`/get-started/conventions`); rotations, shears and affine maps are centred
+ - pixel coordinates are ``(x, y)`` at integer pixel centers, with corners ``(0, 0)`` and
+ ``(W - 1, H - 1)`` (see :doc:`/get-started/conventions`); rotations, shears and affine maps are centered
at ``((W - 1) / 2, (H - 1) / 2)``, and ``transform_matrix`` maps input pixel coordinates to output pixel
coordinates.
- the resampling classes, including the non-rigid :class:`RandomElasticTransform` and
@@ -76,11 +80,15 @@ class GeometricAugmentationBase2D(RigidAffineAugmentationBase2D):
Note:
Masks are resampled with nearest neighbour whatever ``resample`` the augmentation uses for images,
- unless ``resample`` is passed explicitly to :meth:`transform_masks` or :meth:`inverse_masks` --
+ unless ``resample`` is passed explicitly to ``transform_masks()`` or ``inverse_masks()`` --
which is what ``extra_args[DataKey.MASK]`` does in a container. An explicit value is honoured in
both directions. Antialiasing is disabled for masks by default, even when it is enabled for images.
- Pass ``antialias=True`` explicitly to :meth:`transform_masks` or through ``extra_args[DataKey.MASK]``
- to filter soft masks.
+ Only :class:`Resize` and its subclasses, :class:`LongestMaxSize` and :class:`SmallestMaxSize`, read the
+ flag: pass ``antialias=True`` explicitly to ``transform_masks()`` or through ``extra_args[DataKey.MASK]`` to
+ filter soft masks. Other geometric augmentations ignore it.
+
+ See Also:
+ - :class:`AugmentationBase2D`: base class for general 2D augmentations.
"""
@@ -157,7 +165,7 @@ class GeometricAugmentationBase2D(RigidAffineAugmentationBase2D):
"""Process masks corresponding to the inputs that are transformed.
Note:
- Uses ``flags["resample"]`` as given; :meth:`transform_masks` supplies "nearest" when the caller
+ Uses ``flags["resample"]`` as given; ``transform_masks()`` supplies "nearest" when the caller
did not choose one.
Treats ``align_corners=None`` as the module's own ``align_corners``, so a mask is resampled on the
same grid as its input.
diff --git a/kornia/augmentation/_2d/geometric/center_crop.py b/kornia/augmentation/_2d/geometric/center_crop.py
index 399c38a4c..42c78a7b1 100644
--- a/kornia/augmentation/_2d/geometric/center_crop.py
+++ b/kornia/augmentation/_2d/geometric/center_crop.py
@@ -28,9 +28,10 @@ from kornia.geometry.transform.crop2d import _crop_inverse_by_transform_mat, _cr
class CenterCrop(GeometricAugmentationBase2D):
- r"""Crop a given image torch.Tensor at the center.
+ r"""Crop the centered patch of each image, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/CenterCrop.png
+ ``output = CenterCrop(size)(input)`` extracts a centered patch of size ``size`` from images of shape
+ ``(B, C, H, W)``. Use :class:`RandomCrop` to sample the crop position instead.
Args:
size: Desired output size (out_h, out_w) of the crop.
@@ -48,7 +49,7 @@ class CenterCrop(GeometricAugmentationBase2D):
Shape:
- Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``
- - Output: :math:`(B, C, out_h, out_w)`
+ - Output: ``(B, C, out_h, out_w)``
.. note::
This function internally uses :func:`kornia.geometry.transform.crop_by_boxes`.
@@ -60,10 +61,16 @@ class CenterCrop(GeometricAugmentationBase2D):
``cropping_mode="slice"`` indexes the input and returns a copy, so writing to the result leaves the input
unchanged. ``cropping_mode="resample"`` warps with the configured ``resample`` and ``align_corners``. Both
- modes support :meth:`inverse`, which warps the crop back onto the original canvas with the inverse of
+ modes support ``inverse()``, which warps the crop back onto the original canvas with the inverse of
``transform_matrix`` (zero padding unless the call passes ``padding_mode``) and cannot restore discarded
data.
+ .. image:: _static/img/CenterCrop.png
+
+ See Also:
+ - :class:`RandomCrop`: samples a crop position for each selected image.
+ - :class:`CenterCrop3D`: extracts a centered subvolume.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/geometric/crop.py b/kornia/augmentation/_2d/geometric/crop.py
index dc6b1352b..374b2bb0d 100644
--- a/kornia/augmentation/_2d/geometric/crop.py
+++ b/kornia/augmentation/_2d/geometric/crop.py
@@ -54,9 +54,10 @@ def _remove_padding(
class RandomCrop(GeometricAugmentationBase2D):
- r"""Crop random patches of a torch.Tensor image on a given size.
+ r"""Crop random image patches to a requested size, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/RandomCrop.png
+ ``output = RandomCrop(size, ...)(input)`` chooses crop positions in images of shape ``(B, C, H, W)`` and returns
+ patches of ``size``. Use :class:`RandomResizedCrop` to resize the sampled patch.
Args:
size: Desired output size (out_h, out_w) of the crop.
@@ -86,7 +87,7 @@ class RandomCrop(GeometricAugmentationBase2D):
Shape:
- Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``
- - Output: :math:`(B, C, out_h, out_w)`
+ - Output: ``(B, C, out_h, out_w)``
Note:
Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.
@@ -118,7 +119,7 @@ class RandomCrop(GeometricAugmentationBase2D):
Slice mode uses :func:`~kornia.geometry.transform.crop_by_indices` with its own defaults and ignores this
class's ``resample`` and ``align_corners``. Resample mode uses the configured interpolation and
``align_corners`` and maps constant, replicate and reflect pre-padding to zero, border and reflection
- sampler padding. Both modes support :meth:`inverse`, for images, masks, boxes and keypoints: it warps with
+ sampler padding. Both modes support ``inverse()``, for images, masks, boxes and keypoints: it warps with
the inverse of the mode's ``transform_matrix``, removes the pre-crop padding, and cannot restore cropped or
interpolated content.
For an empty batch, ``forward_input_shape`` records the original, unpadded canvas for inverse replay.
@@ -128,6 +129,13 @@ class RandomCrop(GeometricAugmentationBase2D):
not bitwise. Eager execution retains native slicing and resizing for performance;
the tensorized compiled path avoids recompilation as crop coordinates change.
+ .. image:: _static/img/RandomCrop.png
+
+ See Also:
+ - :class:`CenterCrop`: extracts the deterministic centered patch.
+ - :class:`RandomResizedCrop`: samples a crop and resizes it to the requested output size.
+ - :class:`RandomCrop3D`: samples a fixed-size subvolume.
+
Examples:
>>> import torch
>>> _ = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/geometric/elastic_transform.py b/kornia/augmentation/_2d/geometric/elastic_transform.py
index bf610afd5..f19db8c73 100644
--- a/kornia/augmentation/_2d/geometric/elastic_transform.py
+++ b/kornia/augmentation/_2d/geometric/elastic_transform.py
@@ -29,6 +29,26 @@ from kornia.geometry.transform import elastic_transform2d
class RandomElasticTransform(AugmentationBase2D):
r"""Warp images with a random elastic displacement field, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomElasticTransform(kernel_size, sigma, alpha, ...)(input)`` displaces pixels in selected images
+ of shape ``(B, C, H, W)``.
+
+ Args:
+ kernel_size: the size of the Gaussian kernel, in the y and x directions, respectively.
+ sigma: The standard deviation of the Gaussian in the y and x directions,
+ respectively. Larger sigma results in smaller pixel displacements.
+ alpha: The scaling factor that controls the intensity of the deformation
+ in the x and y directions, respectively -- the opposite order to ``kernel_size`` and ``sigma``.
+ align_corners: Interpolation flag used by `grid_sample`.
+ resample: Interpolation mode used by `grid_sample`. Either 'nearest' (0) or 'bilinear' (1).
+ padding_mode: The padding used by ``grid_sample``. Either 'zeros', 'border' or 'reflection'.
+ same_on_batch: apply the same transformation across the batch.
+ p: probability of applying the transformation to each sample.
+ keepdim: whether to keep the output shape the same as input (True) or broadcast it
+ to the batch form (False).
+
+ .. note::
+ This function internally uses :func:`kornia.geometry.transform.elastic_transform2d`.
+
.. image:: _static/img/RandomElasticTransform.png
.. note::
@@ -47,22 +67,8 @@ class RandomElasticTransform(AugmentationBase2D):
the ``align_corners`` split across classes (`#4412 <https://github.com/kornia/kornia/issues/4412>`_) are
listed on :class:`~kornia.augmentation.GeometricAugmentationBase2D`.
- Args:
- kernel_size: the size of the Gaussian kernel, in the y and x directions, respectively.
- sigma: The standard deviation of the Gaussian in the y and x directions,
- respectively. Larger sigma results in smaller pixel displacements.
- alpha: The scaling factor that controls the intensity of the deformation
- in the x and y directions, respectively -- the opposite order to ``kernel_size`` and ``sigma``.
- align_corners: Interpolation flag used by `grid_sample`.
- resample: Interpolation mode used by `grid_sample`. Either 'nearest' (0) or 'bilinear' (1).
- padding_mode: The padding used by ``grid_sample``. Either 'zeros', 'border' or 'reflection'.
- same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation to each sample.
- keepdim: whether to keep the output shape the same as input (True) or broadcast it
- to the batch form (False).
-
- .. note::
- This function internally uses :func:`kornia.geometry.transform.elastic_transform2d`.
+ See Also:
+ - :class:`RandomThinPlateSpline`: warps from sampled thin-plate-spline control points.
Examples:
>>> import torch
diff --git a/kornia/augmentation/_2d/geometric/fisheye.py b/kornia/augmentation/_2d/geometric/fisheye.py
index d789038ef..f611fc786 100644
--- a/kornia/augmentation/_2d/geometric/fisheye.py
+++ b/kornia/augmentation/_2d/geometric/fisheye.py
@@ -30,17 +30,7 @@ from kornia.geometry.transform import remap
class RandomFisheye(AugmentationBase2D):
r"""Add a random radial (fisheye) distortion, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomFisheye.png
-
- Convention:
- Coordinates are normalized to ``[-1, 1]`` with corner pixel centres at the endpoints.
- At output coordinate ``(x, y)``, let ``r`` be its distance from the sampled centre.
- The input sampling coordinate is ``(x * (1 + r**gamma), y * (1 + r**gamma))``:
- the centre changes the distance, but scaling is about the coordinate origin.
- Sampling is bilinear with zero padding and ``align_corners=True``; these settings are fixed.
- There is no ``transform_matrix`` or ``inverse``. A ``mask``, keypoint or box data key raises
- ``NotImplementedError`` identifying this augmentation, even at ``p=0``
- (`#4420 <https://github.com/kornia/kornia/issues/4420>`_).
+ ``output = RandomFisheye(...)(input)`` radially distorts each selected image of shape ``(B, C, H, W)``.
Args:
center_x: Ranges to sample respect to x-coordinate center with shape (2,).
@@ -51,6 +41,21 @@ class RandomFisheye(AugmentationBase2D):
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
+ .. image:: _static/img/RandomFisheye.png
+
+ Convention:
+ Coordinates are normalized to ``[-1, 1]`` with corner pixel centers at the endpoints.
+ At output coordinate ``(x, y)``, let ``r`` be its distance from the sampled center.
+ The input sampling coordinate is ``(x * (1 + r**gamma), y * (1 + r**gamma))``:
+ the center changes the distance, but scaling is about the coordinate origin.
+ Sampling is bilinear with zero padding and ``align_corners=True``; these settings are fixed.
+ There is no ``transform_matrix`` or ``inverse``. A ``mask``, keypoint or box data key raises
+ ``NotImplementedError`` identifying this augmentation, even at ``p=0``
+ (`#4420 <https://github.com/kornia/kornia/issues/4420>`_).
+
+ See Also:
+ - :class:`RandomPerspective`: samples a projective rather than radial warp.
+
Examples:
>>> import torch
>>> img = torch.ones(1, 1, 2, 2)
diff --git a/kornia/augmentation/_2d/geometric/horizontal_flip.py b/kornia/augmentation/_2d/geometric/horizontal_flip.py
index 849a65f20..48067ee06 100644
--- a/kornia/augmentation/_2d/geometric/horizontal_flip.py
+++ b/kornia/augmentation/_2d/geometric/horizontal_flip.py
@@ -30,13 +30,7 @@ from kornia.geometry.transform import hflip
class RandomHorizontalFlip(GeometricAugmentationBase2D):
r"""Flip images horizontally, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomHorizontalFlip.png
-
- Input should be a torch.Tensor of shape (C, H, W) or a batch of tensors ``(B, C, H, W)``.
- If Input is a tuple it is assumed that the first element contains the aforementioned tensors and the second,
- the corresponding transformation matrix that has been applied to them. In this case the module
- will Horizontally flip the tensors and torch.cat the corresponding transformation matrix to the
- previous one. This is especially useful when using this functionality as part of an ``nn.Sequential`` module.
+ ``output = RandomHorizontalFlip(...)(input)`` reverses the width axis of images of shape ``(B, C, H, W)``.
Args:
p: probability of applying the transformation to each sample.
@@ -56,6 +50,12 @@ class RandomHorizontalFlip(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.hflip`.
+ .. image:: _static/img/RandomHorizontalFlip.png
+
+ See Also:
+ - :class:`RandomHorizontalFlip3D`: reverses the width axis of a volume.
+ - :class:`RandomVerticalFlip`: reflects across the horizontal center line.
+
Examples:
>>> import torch
>>> input = torch.tensor([[[[0., 0., 0.],
diff --git a/kornia/augmentation/_2d/geometric/pad.py b/kornia/augmentation/_2d/geometric/pad.py
index f6fabaa0e..4de6152e2 100644
--- a/kornia/augmentation/_2d/geometric/pad.py
+++ b/kornia/augmentation/_2d/geometric/pad.py
@@ -24,9 +24,11 @@ from kornia.augmentation._2d.geometric.base import GeometricAugmentationBase2D
class PadTo(GeometricAugmentationBase2D):
- r"""Pad the given sample to a specific size. Always occurs (p=1.0).
+ r"""Pad or crop an image batch to a requested size. Always occurs (p=1.0).
- .. image:: _static/img/PadTo.png
+ ``output = PadTo(size)(input)`` pads or crops the right and bottom edges of an image batch
+ ``(B, C, H, W)`` to ``size``. Set ``crop_if_exceeds=False`` to keep oversized axes unchanged;
+ use :class:`Resize` when the content itself should be resampled.
Args:
size: a tuple of ints in the format (height, width) that give the spatial
@@ -53,11 +55,16 @@ class PadTo(GeometricAugmentationBase2D):
default ``crop_if_exceeds=True``, a target smaller than the input crops that axis instead, so a target can pad
one axis while cropping the other. With ``crop_if_exceeds=False``, that axis passes through unchanged.
- :meth:`inverse` restores the prior input shape on every axis. It exactly removes right/bottom padding, and it
+ ``inverse()`` restores the prior input shape on every axis. It exactly removes right/bottom padding, and it
regrows a cropped axis at the right/bottom with zeros, as the crop augmentations' inverses do: the discarded
pixels cannot be recovered. The transformation matrix is identity, because every kept pixel keeps its
coordinates, so keypoints and boxes are neither moved nor clipped when cropping puts them outside the canvas.
+ .. image:: _static/img/PadTo.png
+
+ See Also:
+ - :class:`Resize`: resamples an image to a requested size.
+
Examples:
>>> import torch
>>> img = torch.tensor([[[[0., 0., 0.],
diff --git a/kornia/augmentation/_2d/geometric/perspective.py b/kornia/augmentation/_2d/geometric/perspective.py
index e8cc5f0db..c47cd82bd 100644
--- a/kornia/augmentation/_2d/geometric/perspective.py
+++ b/kornia/augmentation/_2d/geometric/perspective.py
@@ -29,7 +29,8 @@ from kornia.geometry.transform import get_perspective_transform, warp_perspectiv
class RandomPerspective(GeometricAugmentationBase2D):
r"""Warp images with a random perspective transformation, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomPerspective.png
+ ``output = RandomPerspective(distortion_scale, ...)(input)`` applies a projective warp to selected images of
+ shape ``(B, C, H, W)``.
Args:
distortion_scale: the degree of distortion, ranged from 0 to 1.
@@ -51,7 +52,7 @@ class RandomPerspective(GeometricAugmentationBase2D):
Convention:
- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.
The source corners are ``(0, 0)``, ``(W - 1, 0)``, ``(W - 1, H - 1)`` and ``(0, H - 1)``;
- :attr:`transform_matrix` maps them to the sampled destination corners.
+ ``transform_matrix`` maps them to the sampled destination corners.
- ``basic`` samples each corner inward by at most ``distortion_scale * (W, H) / 2``. ``area_preserving``
samples each coordinate in both directions over the same extent.
- with ``distortion_scale=0`` and ``H > 1``, ``W > 1``, the warp is an identity up to numerical precision
@@ -63,6 +64,12 @@ class RandomPerspective(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.warp_perspective`.
+ .. image:: _static/img/RandomPerspective.png
+
+ See Also:
+ - :class:`RandomAffine`: samples an affine rather than projective transform.
+ - :class:`RandomPerspective3D`: applies a projective warp to volumes.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs= torch.tensor([[[[1., 0., 0.],
diff --git a/kornia/augmentation/_2d/geometric/resize.py b/kornia/augmentation/_2d/geometric/resize.py
index a870436f3..070652ce7 100644
--- a/kornia/augmentation/_2d/geometric/resize.py
+++ b/kornia/augmentation/_2d/geometric/resize.py
@@ -30,7 +30,9 @@ from kornia.geometry.transform.affwarp import _side_to_image_size
class Resize(GeometricAugmentationBase2D):
- """Resize to size.
+ """Resample images to a requested spatial size, applied to a batch with probability ``p`` (default 1.0).
+
+ ``output = Resize(size, ...)(input)`` resamples images of shape ``(B, C, H, W)`` to ``size``.
Args:
size: Size (h, w) in pixels of the resized region or just one side.
@@ -38,7 +40,7 @@ class Resize(GeometricAugmentationBase2D):
resample: Resampling mode.
align_corners: interpolation flag.
antialias: if True, then image will be filtered with Gaussian before downscaling. No effect for upscaling.
- p: probability of the augmentation been applied.
+ p: probability of resizing the batch; one draw decides for every sample.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
@@ -52,10 +54,13 @@ class Resize(GeometricAugmentationBase2D):
This class uses :func:`kornia.geometry.transform.resize`; ``align_corners`` is forwarded for bilinear and
bicubic sampling, and ``transform_matrix`` follows the grid they sample: at ``align_corners=False`` it is
the half-pixel map ``x' = (x + 0.5) * W_out / W_in - 0.5`` (likewise for ``y``), and at ``True`` it maps
- the corner pixel centres onto each other. Nearest sampling uses the half-pixel grid and PyTorch's
+ the corner pixel centers onto each other. Nearest sampling uses the half-pixel grid and PyTorch's
``nearest-exact`` interpolation.
- :meth:`inverse` resamples to the prior canvas and cannot recover
- values discarded by a resize.
+ ``inverse()`` resamples to the prior canvas and cannot recover values discarded by a resize.
+
+ See Also:
+ - :class:`LongestMaxSize`: bounds the longest image side while preserving aspect ratio.
+ - :class:`SmallestMaxSize`: sets the shortest image side while preserving aspect ratio.
"""
@@ -165,10 +170,16 @@ class Resize(GeometricAugmentationBase2D):
class LongestMaxSize(Resize):
- """Rescale an image so that maximum side is equal to max_size, keeping the aspect ratio of the initial image.
+ """Resize so the longest side equals ``max_size``, applied to a batch with probability ``p`` (default 1.0).
+
+ ``output = LongestMaxSize(max_size)(input)`` resizes images while preserving their aspect ratio.
+ Use :class:`SmallestMaxSize` to set the shortest side instead.
Args:
- max_size: maximum size of the image after the transformation.
+ max_size: length of the longest output side.
+ resample: Resampling mode, as in :class:`Resize`.
+ align_corners: interpolation flag, as in :class:`Resize`.
+ p: probability of resizing the batch; one draw decides for every sample.
Convention:
See :class:`Resize` for the common resize conventions. This behaves like
@@ -176,6 +187,10 @@ class LongestMaxSize(Resize):
are not accepted constructor arguments. Its longest output side equals ``max_size`` and the other
side is truncated while preserving aspect ratio.
+ See Also:
+ - :class:`SmallestMaxSize`: makes the shortest side equal to its bound.
+ - :class:`Resize`: resamples to an explicit output size.
+
"""
def __init__(
@@ -190,10 +205,16 @@ class LongestMaxSize(Resize):
class SmallestMaxSize(Resize):
- """Rescale an image so that minimum side is equal to max_size, keeping the aspect ratio of the initial image.
+ """Resize so the shortest side equals ``max_size``, applied to a batch with probability ``p`` (default 1.0).
+
+ ``output = SmallestMaxSize(max_size)(input)`` resizes images while preserving their aspect ratio.
+ Use :class:`LongestMaxSize` to bound the longest side instead.
Args:
- max_size: maximum size of the image after the transformation.
+ max_size: length of the shortest output side.
+ resample: Resampling mode, as in :class:`Resize`.
+ align_corners: interpolation flag, as in :class:`Resize`.
+ p: probability of resizing the batch; one draw decides for every sample.
Convention:
See :class:`Resize` for the common resize conventions. This behaves like
@@ -201,6 +222,10 @@ class SmallestMaxSize(Resize):
are not accepted constructor arguments. Its shortest output side equals ``max_size`` and the other
side is truncated while preserving aspect ratio.
+ See Also:
+ - :class:`LongestMaxSize`: makes the longest side equal to its bound.
+ - :class:`Resize`: resamples to an explicit output size.
+
"""
def __init__(
diff --git a/kornia/augmentation/_2d/geometric/resized_crop.py b/kornia/augmentation/_2d/geometric/resized_crop.py
index 9c9ce0811..963068891 100644
--- a/kornia/augmentation/_2d/geometric/resized_crop.py
+++ b/kornia/augmentation/_2d/geometric/resized_crop.py
@@ -46,9 +46,10 @@ def _one_pixel_axes(box: torch.Tensor, device: torch.device) -> torch.Tensor:
class RandomResizedCrop(GeometricAugmentationBase2D):
- r"""Crop random patches in an image torch.Tensor and resizes to a given size.
+ r"""Crop random image patches and resize them, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/RandomResizedCrop.png
+ ``output = RandomResizedCrop(size, scale, ratio, ...)(input)`` samples regions from images of shape
+ ``(B, C, H, W)`` and resamples them to ``size``. Use :class:`RandomCrop` to preserve the sampled patch size.
Args:
size: Desired output size (out_h, out_w) of each edge.
@@ -58,7 +59,7 @@ class RandomResizedCrop(GeometricAugmentationBase2D):
resample: the interpolation mode.
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of the augmentation been applied.
+ p: probability of applying the transformation for the whole batch.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
cropping_mode: The used algorithm to crop. ``slice`` will use advanced slicing to extract the torch.Tensor based
@@ -68,7 +69,7 @@ class RandomResizedCrop(GeometricAugmentationBase2D):
Shape:
- Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``
- - Output: :math:`(B, C, out_h, out_w)`
+ - Output: ``(B, C, out_h, out_w)``
Note:
Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.
@@ -86,25 +87,29 @@ class RandomResizedCrop(GeometricAugmentationBase2D):
width (input narrower than ``min(ratio)``) or its full height (wider than ``max(ratio)``). So
``scale=(1.0, 1.0)`` keeps an input within ``ratio`` whole, except that a candidate rounded a pixel or two
short on the longer side also fits (8x6 gives 7x6 in about 18% of draws, as in torchvision). Unlike
- torchvision, which centres the fallback crop, it is placed at a random position like any other crop.
+ torchvision, which centers the fallback crop, it is placed at a random position like any other crop.
Both cropping modes use the configured interpolation and ``align_corners``. Slice mode ignores
``align_corners`` for ``resample="nearest"``. With bilinear or bicubic interpolation, each mode's image
follows its ``transform_matrix``, and at ``align_corners=False`` the two modes give different images: slice
mode resizes the crop on the half-pixel grid, ``x' = (x - x0 + 0.5) * W_out / W_crop - 0.5`` for a crop
- starting at column ``x0`` (likewise for ``y``), while resample mode maps the crop's corner pixel centres
- onto the output's. Nearest sampling in slice mode uses the half-pixel grid and PyTorch's
- ``nearest-exact`` interpolation. With corner alignment, an axis where the output is one pixel long samples
- the crop's first row or column, and one where the crop is one pixel long repeats it, as ``F.interpolate``
- does, in both modes. Both modes support
- :meth:`inverse`, which warps the output back onto the original canvas with the inverse of the mode's
- ``transform_matrix`` and cannot recover discarded information.
+ starting at column ``x0`` (likewise for ``y``), while resample mode maps the crop's corner pixel centers onto
+ the output's. Nearest sampling in slice mode uses the half-pixel grid and PyTorch's ``nearest-exact``
+ interpolation. With corner alignment, an axis where the output is one pixel long samples the crop's first row
+ or column, and one where the crop is one pixel long repeats it, as ``F.interpolate`` does, in both modes. Both
+ modes support ``inverse()``, which warps the output back onto the original canvas with the inverse of the
+ mode's ``transform_matrix`` and cannot recover discarded information.
Note:
Compiled slice-mode interpolation matches eager execution to floating-point tolerance,
not bitwise. Eager execution retains native slicing and resizing for performance;
the tensorized compiled path avoids recompilation as crop coordinates change.
+ See Also:
+ - :class:`RandomCrop`: samples a fixed-size patch without resizing it.
+
+ .. image:: _static/img/RandomResizedCrop.png
+
Example:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.tensor([[[0., 1., 2.],
diff --git a/kornia/augmentation/_2d/geometric/rotation.py b/kornia/augmentation/_2d/geometric/rotation.py
index 562be4df1..6668603b9 100644
--- a/kornia/augmentation/_2d/geometric/rotation.py
+++ b/kornia/augmentation/_2d/geometric/rotation.py
@@ -31,6 +31,9 @@ from kornia.geometry.transform.affwarp import _compute_rotation_matrix, _compute
class RandomRotation(GeometricAugmentationBase2D):
r"""Rotate images by a random angle in degrees, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomRotation(degrees, ...)(input)`` rotates selected images of shape ``(B, C, H, W)``
+ about their centers. Use :class:`RandomRotation90` when only quarter turns are wanted.
+
.. image:: _static/img/RandomRotation.png
.. note::
@@ -61,6 +64,10 @@ class RandomRotation(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.affine`.
+ See Also:
+ - :class:`RandomRotation90`: samples only multiples of 90 degrees.
+ - :class:`RandomRotation3D`: rotates volumes by a sampled 3D axis-angle vector.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.tensor([[1., 0., 0., 2.],
@@ -162,6 +169,9 @@ def _range_allows_odd_turns(low: float, high: float) -> bool:
class RandomRotation90(GeometricAugmentationBase2D):
r"""Rotate images by a random multiple of 90 degrees, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomRotation90(times, ...)(input)`` rotates selected images of shape ``(B, C, H, W)``
+ by quarter turns. Use :class:`RandomRotation` to sample arbitrary angles.
+
Args:
times: the range of n times 90 degree rotation needs to be applied. A range of whole numbers is closed:
every whole number from the lower to the upper bound is drawn with the same probability.
@@ -193,6 +203,9 @@ class RandomRotation90(GeometricAugmentationBase2D):
This function internally uses :func:`kornia.geometry.transform.affine`. This version is relatively
slow as it operates based on affine transformations.
+ See Also:
+ - :class:`RandomRotation`: samples an arbitrary angle in degrees.
+
Examples:
>>> rng = torch.manual_seed(1)
>>> input = torch.tensor([[1., 0., 0., 2.],
diff --git a/kornia/augmentation/_2d/geometric/shear.py b/kornia/augmentation/_2d/geometric/shear.py
index 5de60c570..3d61a9c36 100644
--- a/kornia/augmentation/_2d/geometric/shear.py
+++ b/kornia/augmentation/_2d/geometric/shear.py
@@ -32,12 +32,8 @@ from kornia.geometry.transform import get_shear_matrix2d, warp_affine
class RandomShear(GeometricAugmentationBase2D):
r"""Shear images by random angles in degrees, applied per sample with probability ``p`` (default 0.5).
- The transformation is computed so that the image center is kept invariant.
-
- .. note::
- Unlike torchvision's ``RandomAffine(degrees=0, shear=...)``, which shears every image, this class shears each
- sample with probability ``p``, 0.5 by default; with ``same_on_batch=True`` one draw decides for the whole batch.
- Pass ``p=1.0`` to shear every sample.
+ ``output = RandomShear(shear, ...)(input)`` shears images of shape ``(B, C, H, W)`` about their centers by
+ sampled angles.
Args:
shear: Range of degrees to select from.
@@ -64,6 +60,14 @@ class RandomShear(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.warp_affine`.
+ .. note::
+ Unlike torchvision's ``RandomAffine(degrees=0, shear=...)``, which shears every image, this class shears each
+ sample with probability ``p``, 0.5 by default; with ``same_on_batch=True`` one draw decides for the whole batch.
+ Pass ``p=1.0`` to shear every sample.
+
+ See Also:
+ - :class:`RandomAffine`: samples a combined affine transformation.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/geometric/thin_plate_spline.py b/kornia/augmentation/_2d/geometric/thin_plate_spline.py
index 5d7d6470f..19f48379e 100644
--- a/kornia/augmentation/_2d/geometric/thin_plate_spline.py
+++ b/kornia/augmentation/_2d/geometric/thin_plate_spline.py
@@ -30,6 +30,21 @@ from kornia.geometry.transform import get_tps_transform, warp_image_tps
class RandomThinPlateSpline(AugmentationBase2D):
r"""Warp images with a random thin plate spline, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomThinPlateSpline(...)(input)`` deforms selected images of shape ``(B, C, H, W)`` using a sampled
+ thin-plate spline.
+
+ Args:
+ scale: the non-negative scale factor to apply to the destination points.
+ Zero leaves the control points unchanged.
+ align_corners: Interpolation flag used by ``grid_sample``.
+ padding_mode: Padding used by ``grid_sample``: 'zeros', 'border' or 'reflection'.
+ same_on_batch: apply the same transformation across the batch.
+ p: probability of applying the transformation to each sample.
+ keepdim: whether to keep the output shape the same as input (True) or broadcast it
+ to the batch form (False).
+ .. note::
+ This function internally uses :func:`kornia.geometry.transform.warp_image_tps`.
+
.. image:: _static/img/RandomThinPlateSpline.png
Convention:
@@ -44,17 +59,8 @@ class RandomThinPlateSpline(AugmentationBase2D):
(`#4412 <https://github.com/kornia/kornia/issues/4412>`_) are listed on
:class:`~kornia.augmentation.GeometricAugmentationBase2D`.
- Args:
- scale: the non-negative scale factor to apply to the destination points.
- Zero leaves the control points unchanged.
- align_corners: Interpolation flag used by ``grid_sample``.
- padding_mode: Padding used by ``grid_sample``: 'zeros', 'border' or 'reflection'.
- same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation to each sample.
- keepdim: whether to keep the output shape the same as input (True) or broadcast it
- to the batch form (False).
- .. note::
- This function internally uses :func:`kornia.geometry.transform.warp_image_tps`.
+ See Also:
+ - :class:`RandomElasticTransform`: samples a smooth pixel displacement field.
Examples:
>>> img = torch.ones(1, 1, 2, 2)
diff --git a/kornia/augmentation/_2d/geometric/translate.py b/kornia/augmentation/_2d/geometric/translate.py
index 842eae15f..b8f68a24b 100644
--- a/kornia/augmentation/_2d/geometric/translate.py
+++ b/kornia/augmentation/_2d/geometric/translate.py
@@ -29,10 +29,8 @@ from kornia.geometry.transform import get_translation_matrix2d, warp_affine
class RandomTranslate(GeometricAugmentationBase2D):
r"""Translate images by a random 2D shift, applied per sample with probability ``p`` (default 0.5).
- .. note::
- Unlike torchvision's ``RandomAffine(degrees=0, translate=...)``, which translates every image, this class
- translates each sample with probability ``p``, 0.5 by default; with ``same_on_batch=True`` one draw decides for
- the whole batch. Pass ``p=1.0`` to translate every sample.
+ ``output = RandomTranslate(translate_x, translate_y, ...)(input)`` shifts selected images of shape
+ ``(B, C, H, W)``.
Args:
translate_x: tuple of maximum absolute fraction for horizontal translations.
@@ -60,6 +58,14 @@ class RandomTranslate(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.warp_affine`.
+ .. note::
+ Unlike torchvision's ``RandomAffine(degrees=0, translate=...)``, which translates every image, this class
+ translates each sample with probability ``p``, 0.5 by default; with ``same_on_batch=True`` one draw decides for
+ the whole batch. Pass ``p=1.0`` to translate every sample.
+
+ See Also:
+ - :class:`RandomAffine`: samples a combined affine transformation.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/geometric/vertical_flip.py b/kornia/augmentation/_2d/geometric/vertical_flip.py
index a4bda18d1..39ae2e868 100644
--- a/kornia/augmentation/_2d/geometric/vertical_flip.py
+++ b/kornia/augmentation/_2d/geometric/vertical_flip.py
@@ -29,7 +29,8 @@ from kornia.geometry.transform import vflip
class RandomVerticalFlip(GeometricAugmentationBase2D):
r"""Flip images vertically, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomVerticalFlip.png
+ ``output = RandomVerticalFlip(...)(input)`` reverses the height axis of selected images of shape
+ ``(B, C, H, W)``.
Args:
p: probability of applying the transformation to each sample.
@@ -49,6 +50,12 @@ class RandomVerticalFlip(GeometricAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.geometry.transform.vflip`.
+ .. image:: _static/img/RandomVerticalFlip.png
+
+ See Also:
+ - :class:`RandomVerticalFlip3D`: reverses the height axis of a volume.
+ - :class:`RandomHorizontalFlip`: reflects across the vertical center line.
+
Examples:
>>> import torch
>>> input = torch.tensor([[[[0., 0., 0.],
diff --git a/kornia/augmentation/_2d/intensity/auto_contrast.py b/kornia/augmentation/_2d/intensity/auto_contrast.py
index 9b09e91c1..89e047706 100644
--- a/kornia/augmentation/_2d/intensity/auto_contrast.py
+++ b/kornia/augmentation/_2d/intensity/auto_contrast.py
@@ -38,7 +38,9 @@ def _warn_clip_output_deprecated(clip_output: Optional[bool]) -> None:
class RandomAutoContrast(IntensityAugmentationBase2D):
- r"""Apply a random auto-contrast of a torch.Tensor image.
+ r"""Rescale each selected image channel from its own minimum to maximum.
+
+ ``output = RandomAutoContrast()(input)`` maps each selected channel into ``[0, 1]`` from its observed extrema.
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -61,6 +63,10 @@ class RandomAutoContrast(IntensityAugmentationBase2D):
a clamp, so an input outside ``[0, 1]`` is mapped into range rather than clipped, and a constant
channel comes back as zeros. Empty batches preserve their shape, dtype and device.
+ See Also:
+ - :class:`RandomContrast`: applies a sampled multiplicative factor instead of input-dependent rescaling.
+ - :class:`Normalize`: applies supplied channel statistics instead of observed extrema.
+
"""
def __init__(
diff --git a/kornia/augmentation/_2d/intensity/base.py b/kornia/augmentation/_2d/intensity/base.py
index 047e70955..2bc33c543 100644
--- a/kornia/augmentation/_2d/intensity/base.py
+++ b/kornia/augmentation/_2d/intensity/base.py
@@ -53,7 +53,11 @@ class _PicklableCompileMixin:
class IntensityAugmentationBase2D(RigidAffineAugmentationBase2D):
- r"""Base class for custom 2D intensity augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a 2D value augmentation, per sample with probability ``p`` (default 0.5).
+
+ ``output = MyAugmentation(...)(input)`` changes pixel values once a subclass implements ``apply_transform``.
+ The base supplies the probability gate, parameter replay and identity geometric transform. Use
+ :class:`~kornia.augmentation.GeometricAugmentationBase2D` for an augmentation that moves pixels.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
@@ -95,11 +99,15 @@ class IntensityAugmentationBase2D(RigidAffineAugmentationBase2D):
``(1, C, H, W)`` and the plasma classes store an expanded view that shares one map across the batch.
- where a class documents bounds for a parameter, a range outside them usually raises at construction;
the class page states a bound it does not enforce, or checks only on the forward pass. A scalar
- magnitude ``x`` usually means ``center Β± x`` around a centre the class fixes -- the neutral value, for a
+ magnitude ``x`` usually means ``center Β± x`` around a center the class fixes -- the neutral value, for a
factor such as ``contrast`` -- with its lower end floored at the bound, so ``contrast=1.5`` reads as
``[0, 2.5]``, while an upper end past the bound raises. :class:`RandomSharpness` reads a scalar as
``[0, x]`` and :class:`RandomPosterize` as ``[x, 8]``.
+ See Also:
+ - :class:`~kornia.augmentation.GeometricAugmentationBase2D`: base class for transforms that move pixels.
+ - :class:`~kornia.augmentation.AugmentationBase2D`: common base for all 2D augmentations.
+
"""
# Intensity augmentations are pointwise: apply_transform ignores the transform matrix and
diff --git a/kornia/augmentation/_2d/intensity/box_blur.py b/kornia/augmentation/_2d/intensity/box_blur.py
index 80402aa55..274d5a5d2 100644
--- a/kornia/augmentation/_2d/intensity/box_blur.py
+++ b/kornia/augmentation/_2d/intensity/box_blur.py
@@ -28,6 +28,9 @@ from kornia.filters import box_blur
class RandomBoxBlur(IntensityAugmentationBase2D):
"""Blur images with a box filter, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomBoxBlur(kernel_size, ...)(input)`` replaces every pixel in each selected image of shape
+ ``(B, C, H, W)`` with a rectangular-window mean.
+
.. image:: _static/img/RandomBoxBlur.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -65,6 +68,9 @@ class RandomBoxBlur(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.filters.box_blur`.
+ See Also:
+ - :class:`RandomGaussianBlur`: uses Gaussian rather than uniform filter weights.
+
Examples:
>>> img = torch.ones(1, 1, 24, 24)
>>> out = RandomBoxBlur((7, 7))(img)
diff --git a/kornia/augmentation/_2d/intensity/brightness.py b/kornia/augmentation/_2d/intensity/brightness.py
index cf4c14bcc..3ece46654 100644
--- a/kornia/augmentation/_2d/intensity/brightness.py
+++ b/kornia/augmentation/_2d/intensity/brightness.py
@@ -27,11 +27,11 @@ from kornia.enhance.adjust import adjust_brightness
class RandomBrightness(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the brightness of a torch.Tensor image.
+ r"""Shift brightness by an additive random offset.
- The shift is additive: the output is ``input + (factor - 1)``, before the default clamp. torchvision's and
- PIL's brightness is multiplicative (``input * factor``); :class:`ColorJitter`'s brightness step is that
- formula.
+ ``output = RandomBrightness(brightness)(input)`` computes ``input + (factor - 1)`` for each selected image
+ using a sampled brightness factor, with clamping enabled by default. Use :class:`ColorJitter` for
+ torchvision-compatible multiplicative brightness, ``input * factor``.
.. image:: _static/img/RandomBrightness.png
@@ -52,7 +52,7 @@ class RandomBrightness(IntensityAugmentationBase2D):
- with ``clip_output=True``, input values are clamped into ``[0, 1]`` before the operation
as well as afterwards. With ``clip_output=False``, the arithmetic is range-independent:
neither input nor output is clamped.
- - ``brightness`` is centred on ``1.0``: the drawn factor is re-based to ``factor - 1`` before it reaches
+ - ``brightness`` is centered on ``1.0``: the drawn factor is re-based to ``factor - 1`` before it reaches
:func:`kornia.enhance.adjust_brightness`, whose own identity is ``0.0``, so the same number passed
straight to the primitive means something else.
- at the default ``clip_output=True`` the result is clamped into ``[0, 1]``; with ``clip_output=False``
@@ -61,6 +61,11 @@ class RandomBrightness(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.adjust_brightness`
+ See Also:
+ - :class:`RandomContrast`: scales values instead of adding an offset.
+ - :class:`ColorJiggle`: combines this additive brightness step with color adjustments.
+ - :class:`ColorJitter`: uses torchvision-compatible multiplicative brightness.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/channel_dropout.py b/kornia/augmentation/_2d/intensity/channel_dropout.py
index 0dacd5581..6c13c5dce 100644
--- a/kornia/augmentation/_2d/intensity/channel_dropout.py
+++ b/kornia/augmentation/_2d/intensity/channel_dropout.py
@@ -28,6 +28,9 @@ from kornia.core.utils import _to_device_nonblocking
class RandomChannelDropout(IntensityAugmentationBase2D):
r"""Set random channels to ``fill_value`` (channel dropout) per sample with probability ``p`` (default 0.5).
+ ``output = RandomChannelDropout(num_drop_channels, fill_value, ...)(input)`` replaces selected channels of each
+ selected image ``(B, C, H, W)`` with a constant.
+
.. image:: _static/img/RandomChannelDropout.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -61,6 +64,10 @@ class RandomChannelDropout(IntensityAugmentationBase2D):
If num_drop_channels is set to 3, it means that for each image in the batch,
we will randomly choose three channels to drop (all image).
+ See Also:
+ - :class:`RandomChannelShuffle`: permutes channels instead of replacing them.
+ - :class:`RandomGrayscale`: computes grayscale instead of removing channels.
+
Examples:
>>> rng = torch.manual_seed(1)
>>> img = torch.ones(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/channel_shuffle.py b/kornia/augmentation/_2d/intensity/channel_shuffle.py
index 278923632..6c2f3d057 100644
--- a/kornia/augmentation/_2d/intensity/channel_shuffle.py
+++ b/kornia/augmentation/_2d/intensity/channel_shuffle.py
@@ -27,6 +27,9 @@ from kornia.core.utils import _to_device_nonblocking
class RandomChannelShuffle(IntensityAugmentationBase2D):
r"""Randomly permute the channels of images, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomChannelShuffle(...)(input)`` reorders the channels of every selected image ``(B, C, H, W)``
+ without changing its values.
+
.. image:: _static/img/RandomChannelShuffle.png
.. note::
@@ -50,6 +53,9 @@ class RandomChannelShuffle(IntensityAugmentationBase2D):
permutation across the batch.
- values are only reordered, never recomputed, so the input's value range is carried through.
+ See Also:
+ - :class:`RandomChannelDropout`: replaces channels instead of permuting them.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.arange(1*2*2*2.).view(1,2,2,2)
diff --git a/kornia/augmentation/_2d/intensity/clahe.py b/kornia/augmentation/_2d/intensity/clahe.py
index f009adf6b..05fb1ff86 100644
--- a/kornia/augmentation/_2d/intensity/clahe.py
+++ b/kornia/augmentation/_2d/intensity/clahe.py
@@ -30,6 +30,10 @@ from kornia.enhance.equalization import _equalize_clahe
class RandomClahe(IntensityAugmentationBase2D):
r"""Equalize local contrast with CLAHE, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomClahe(clip_limit, grid_size, ...)(input)`` equalizes each selected image through local tiles.
+ It accepts ``(B, C, H, W)`` images and clamps the selected inputs and outputs to ``[0, 1]``. Use
+ :class:`RandomEqualize` for one global histogram per channel.
+
.. image:: _static/img/equalize_clahe.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -61,6 +65,9 @@ class RandomClahe(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.equalize_clahe`.
+ See Also:
+ - :class:`RandomEqualize`: equalizes each whole channel rather than local tiles.
+
Examples:
>>> img = torch.rand(1, 10, 20)
>>> aug = RandomClahe()
diff --git a/kornia/augmentation/_2d/intensity/color_jiggle.py b/kornia/augmentation/_2d/intensity/color_jiggle.py
index 05b07bb92..fae21a64b 100644
--- a/kornia/augmentation/_2d/intensity/color_jiggle.py
+++ b/kornia/augmentation/_2d/intensity/color_jiggle.py
@@ -120,7 +120,10 @@ def _apply_cond(order: Tuple[int, ...], input: torch.Tensor, factors: Tuple[torc
class ColorJiggle(IntensityAugmentationBase2D):
- r"""Randomly shift brightness, scale contrast and HSV saturation, and rotate the hue of an image.
+ r"""Jiggle color with Kornia's additive-brightness and HSV formulas.
+
+ ``output = ColorJiggle(brightness, contrast, saturation, hue)(input)`` applies a sampled order of enabled color
+ steps. Use :class:`ColorJitter` when reproducing torchvision's multiplicative and grayscale-blend formulas.
.. image:: _static/img/ColorJiggle.png
@@ -169,6 +172,11 @@ class ColorJiggle(IntensityAugmentationBase2D):
:func:`kornia.enhance.adjust_contrast`. :func:`kornia.enhance.adjust_saturation`,
:func:`kornia.enhance.adjust_hue`.
+ See Also:
+ - :class:`ColorJitter`: torchvision-compatible alternative with different brightness, contrast and saturation.
+ - :class:`RandomBrightness`: applies only the additive brightness step.
+ - :class:`RandomHue`: applies only an HSV hue rotation.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.ones(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/color_jitter.py b/kornia/augmentation/_2d/intensity/color_jitter.py
index dfd804c10..01947f466 100644
--- a/kornia/augmentation/_2d/intensity/color_jitter.py
+++ b/kornia/augmentation/_2d/intensity/color_jitter.py
@@ -62,10 +62,11 @@ def _apply_cond(order: Tuple[int, ...], input: torch.Tensor, factors: Tuple[torc
class ColorJitter(_PicklableCompileMixin, IntensityAugmentationBase2D):
r"""Randomly adjust brightness, contrast, saturation and hue using torchvision-compatible formulas.
- The four steps are torchvision's formulas -- brightness multiplies the image by the factor, contrast blends it
- with its grayscale mean, saturation with its grayscale, and hue is torchvision's ``adjust_hue`` shift -- so this
- is the class to port ``torchvision.transforms.ColorJitter`` code to. It is not actively maintained; prefer
- :class:`ColorJiggle` for new code.
+ ``output = ColorJitter(brightness, contrast, saturation, hue)(input)`` applies four sampled adjustments in a
+ sampled or fixed order using torchvision's formulas. Brightness multiplies the image by a factor, contrast
+ blends it with its grayscale mean, saturation blends it with its grayscale, and hue uses torchvision's
+ ``adjust_hue`` shift. Use this class to port ``torchvision.transforms.ColorJitter`` code; it is not actively
+ maintained, so prefer :class:`ColorJiggle` for new code.
.. image:: _static/img/ColorJitter.png
@@ -106,6 +107,11 @@ class ColorJitter(_PicklableCompileMixin, IntensityAugmentationBase2D):
:func:`kornia.enhance.adjust_saturation_with_gray_subtraction`,
:func:`kornia.enhance.adjust_hue`.
+ See Also:
+ - :class:`ColorJiggle`: Kornia's alternative with additive brightness and raw-value contrast.
+ - :class:`RandomBrightness`: applies Kornia's additive brightness alone.
+ - :class:`RandomSaturation`: applies HSV saturation scaling alone.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.ones(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/contrast.py b/kornia/augmentation/_2d/intensity/contrast.py
index c994e3127..2f0b065f7 100644
--- a/kornia/augmentation/_2d/intensity/contrast.py
+++ b/kornia/augmentation/_2d/intensity/contrast.py
@@ -27,11 +27,11 @@ from kornia.enhance.adjust import adjust_contrast
class RandomContrast(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the contrast of a torch.Tensor image.
+ r"""Scale pixel values by a random contrast factor.
- The factor scales the raw values: the output is ``input * factor``. torchvision's and PIL's contrast blends
- the image with its grayscale mean instead (``factor * input + (1 - factor) * mean``); :class:`ColorJitter`'s
- contrast step is that formula.
+ ``output = RandomContrast(contrast)(input)`` computes ``input * factor`` for each selected image using a sampled
+ contrast factor, with clamping enabled by default. Use :class:`ColorJitter` for torchvision-compatible contrast,
+ which blends the image with its grayscale mean, ``factor * input + (1 - factor) * mean``.
.. image:: _static/img/RandomContrast.png
@@ -61,6 +61,11 @@ class RandomContrast(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.adjust_contrast`
+ See Also:
+ - :class:`RandomBrightness`: adds an offset instead of scaling values.
+ - :class:`ColorJiggle`: combines this raw-value scaling with color adjustments.
+ - :class:`ColorJitter`: blends with the grayscale mean as torchvision does.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/denormalize.py b/kornia/augmentation/_2d/intensity/denormalize.py
index 5267a2cc8..d10ab52bd 100644
--- a/kornia/augmentation/_2d/intensity/denormalize.py
+++ b/kornia/augmentation/_2d/intensity/denormalize.py
@@ -25,7 +25,9 @@ from kornia.enhance import denormalize
class Denormalize(IntensityAugmentationBase2D):
- r"""Denormalize tensor images with mean and standard deviation.
+ r"""Restore image channels with supplied mean and standard deviation.
+
+ ``output = Denormalize(mean, std)(input)`` returns ``input * std + mean``.
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -48,13 +50,17 @@ class Denormalize(IntensityAugmentationBase2D):
- this operation is range-independent: it does not clamp the input into ``[0, 1]``.
- the ``mean`` and ``std`` forms, the batch-wide ``p`` gate and the storage in ``flags`` are those of
:class:`Normalize`.
- - this class inverts :class:`Normalize` built with the same ``mean`` and ``std``, up to float rounding,
- when both apply -- each draws its own ``p`` gate.
+ - this class inverts :class:`Normalize` built with the same ``mean`` and nonzero ``std``, up to
+ floating-point rounding, when both transforms apply and their intermediate values remain finite.
- the result is not clamped: it is ``input * std + mean`` whatever range the input is in.
.. note::
This function internally uses :func:`kornia.enhance.denormalize`.
+ See Also:
+ - :class:`Normalize`: subtracts mean and divides by standard deviation.
+ - :class:`RandomAutoContrast`: derives a rescaling from each image's extrema.
+
Examples:
>>> norm = Denormalize(mean=torch.zeros(1, 4), std=torch.ones(1, 4))
>>> x = torch.rand(1, 4, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/dissolving.py b/kornia/augmentation/_2d/intensity/dissolving.py
index b5df1d785..27fe5fa2b 100644
--- a/kornia/augmentation/_2d/intensity/dissolving.py
+++ b/kornia/augmentation/_2d/intensity/dissolving.py
@@ -28,6 +28,9 @@ from kornia.filters import StableDiffusionDissolving
class RandomDissolving(IntensityAugmentationBase2D):
r"""Dissolve images with a Stable Diffusion model, applied to the whole batch with probability ``p`` (default 0.5).
+ ``output = RandomDissolving(step_range, version, ...)(input)`` applies one sampled reverse-diffusion step to the
+ selected batch of images. It needs the optional ``diffusers`` dependency and a compatible Stable Diffusion model.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Based on :cite:`shi2024dissolving`, the dissolving transformation is essentially applying one-step
@@ -71,6 +74,9 @@ class RandomDissolving(IntensityAugmentationBase2D):
downloads a Stable Diffusion checkpoint at that point -- the ``from_pretrained`` call is in that
class's own constructor, not on the first forward.
+ See Also:
+ - :class:`RandomErasing`: removes a rectangle without a diffusion model.
+
"""
def __init__(
diff --git a/kornia/augmentation/_2d/intensity/equalize.py b/kornia/augmentation/_2d/intensity/equalize.py
index bb0484226..6be010973 100644
--- a/kornia/augmentation/_2d/intensity/equalize.py
+++ b/kornia/augmentation/_2d/intensity/equalize.py
@@ -27,6 +27,9 @@ from kornia.enhance import equalize
class RandomEqualize(IntensityAugmentationBase2D):
r"""Equalize the histogram of each image channel, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomEqualize(...)(input)`` equalizes every selected channel of an image ``(B, C, H, W)`` after
+ clamping it to ``[0, 1]``. Use :class:`RandomClahe` to equalize local tiles with contrast limiting.
+
.. image:: _static/img/RandomEqualize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -50,6 +53,10 @@ class RandomEqualize(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.equalize`.
+ See Also:
+ - :class:`RandomEqualize3D`: equalizes volume intensities.
+ - :class:`RandomClahe`: uses local contrast-limited histogram equalization.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/erasing.py b/kornia/augmentation/_2d/intensity/erasing.py
index 313a09779..43441dfdd 100644
--- a/kornia/augmentation/_2d/intensity/erasing.py
+++ b/kornia/augmentation/_2d/intensity/erasing.py
@@ -28,6 +28,9 @@ from kornia.geometry.bbox import bbox_generator, bbox_to_mask
class RandomErasing(IntensityAugmentationBase2D):
r"""Erase a random rectangle of the image, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomErasing(scale, ratio, value, ...)(input)`` replaces one sampled rectangle in each selected
+ image ``(B, C, H, W)``.
+
.. image:: _static/img/RandomErasing.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -74,6 +77,10 @@ class RandomErasing(IntensityAugmentationBase2D):
This function accepts another transformation torch.Tensor (``(B, 3, 3)``), then the
applied transformation will be merged int to the input transformation torch.Tensor and returned.
+ See Also:
+ - :class:`RandomChannelDropout`: fills selected complete channels instead of one rectangle.
+ - :class:`RandomDissolving`: creates semantic image-to-image occlusion with a diffusion model.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.ones(1, 1, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/gamma.py b/kornia/augmentation/_2d/intensity/gamma.py
index 3f40e34d2..bda15e2c5 100644
--- a/kornia/augmentation/_2d/intensity/gamma.py
+++ b/kornia/augmentation/_2d/intensity/gamma.py
@@ -26,7 +26,10 @@ from kornia.enhance.adjust import adjust_gamma
class RandomGamma(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the gamma of a torch.Tensor image.
+ r"""Apply a random gamma power law to unit-range images.
+
+ ``output = RandomGamma(gamma, gain)(input)`` raises pixels in selected images to a sampled gamma and multiplies
+ them by sampled gain.
The formula is torchvision's ``adjust_gamma`` for a float image: ``clamp(gain * input ** gamma, 0, 1)``.
@@ -57,6 +60,10 @@ class RandomGamma(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.adjust_gamma`
+ See Also:
+ - :class:`RandomBrightness`: applies an additive linear adjustment.
+ - :class:`RandomContrast`: applies a multiplicative linear adjustment.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/gaussian_blur.py b/kornia/augmentation/_2d/intensity/gaussian_blur.py
index 725435fef..20efe868b 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_blur.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_blur.py
@@ -31,6 +31,9 @@ from kornia.filters.kernels import _check_kernel_size, _unpack_2d_ks
class RandomGaussianBlur(_PicklableCompileMixin, IntensityAugmentationBase2D):
r"""Blur images with a Gaussian kernel of random sigma, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomGaussianBlur(kernel_size, sigma, ...)(input)`` convolves each selected ``(B, C, H, W)`` image
+ with separable Gaussian weights.
+
The standard deviation is sampled for each instance.
.. image:: _static/img/RandomGaussianBlur.png
@@ -78,6 +81,11 @@ class RandomGaussianBlur(_PicklableCompileMixin, IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.filters.gaussian_blur2d`.
+ See Also:
+ - :class:`RandomBoxBlur`: uses uniform box-filter weights.
+ - :class:`RandomMedianBlur`: uses the median rather than a weighted average.
+ - :class:`RandomMotionBlur`: uses a directional motion kernel.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/gaussian_illumination.py b/kornia/augmentation/_2d/intensity/gaussian_illumination.py
index fbf751063..a92a800bc 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_illumination.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_illumination.py
@@ -47,6 +47,9 @@ def _apply_gaussian_illumination(
class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBase2D):
r"""Add a random Gaussian-shaped illumination pattern, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomGaussianIllumination(gain, center, sigma, ...)(input)`` adds a sampled Gaussian field to each
+ selected ``(B, C, H, W)`` image and clamps it to ``[0, 1]``.
+
.. image:: _static/img/RandomGaussianIllumination.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -79,7 +82,7 @@ class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBa
- ``sigma`` is a fraction of the axis length, not an absolute width: the generator draws it and
multiplies by the image's width and height before building the kernel, so the same ``sigma`` is a
narrower kernel on a smaller image. Every admitted ``sigma`` gives a finite kernel, ``0`` included.
- - ``center`` is a fraction of the axis length too, and the peak sits at the pixel-centre position
+ - ``center`` is a fraction of the axis length too, and the peak sits at the pixel-center position
``center * L - 0.5`` without rounding to a whole pixel: ``center=0.5`` is the middle of any axis, ``0``
and ``1`` are the outer edges of the first and last pixel. At ``sigma=0`` the field is an impulse on the
pixel nearest that position, split between two pixels when it falls halfway.
@@ -89,6 +92,10 @@ class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBa
the parameters will be generated on CPU. This can be changed by calling
``self.set_rng_device_and_dtype(device="cuda", dtype=torch.float64)``.
+ See Also:
+ - :class:`RandomLinearIllumination`: uses a linear rather than Gaussian-shaped field.
+ - :class:`RandomGaussianNoise`: adds unstructured noise rather than an illumination field.
+
Examples:
>>> rng = torch.manual_seed(1)
>>> input = torch.ones(1, 3, 3, 3) * 0.5
diff --git a/kornia/augmentation/_2d/intensity/gaussian_noise.py b/kornia/augmentation/_2d/intensity/gaussian_noise.py
index 1258842bc..27a46ddfe 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_noise.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_noise.py
@@ -25,7 +25,10 @@ from kornia.core.utils import _to_device_nonblocking
class RandomGaussianNoise(IntensityAugmentationBase2D):
- r"""Add Gaussian noise to images, applied per sample with probability ``p`` (default 0.5).
+ r"""Add sampled Gaussian noise without clipping the result, per sample with probability ``p`` (default 0.5).
+
+ ``output = RandomGaussianNoise(mean, std)(input)`` adds a sampled noise field to each selected image; with
+ ``same_on_batch=True``, the field is shared across the batch.
.. image:: _static/img/RandomGaussianNoise.png
@@ -50,6 +53,10 @@ class RandomGaussianNoise(IntensityAugmentationBase2D):
so ``mean`` offsets the image rather than naming the mean the output should have.
- nothing is clamped, so an input already inside ``[0, 1]`` can leave it in either direction.
+ See Also:
+ - :class:`RandomSaltAndPepperNoise`: replaces a sparse set of pixels with salt or pepper values.
+ - :class:`RandomGaussianIllumination`: adds a smooth spatial illumination field instead of noise.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.ones(1, 1, 2, 2)
diff --git a/kornia/augmentation/_2d/intensity/grayscale.py b/kornia/augmentation/_2d/intensity/grayscale.py
index efd0b0b09..b8545128d 100644
--- a/kornia/augmentation/_2d/intensity/grayscale.py
+++ b/kornia/augmentation/_2d/intensity/grayscale.py
@@ -29,6 +29,9 @@ from kornia.core.utils import _to_device_nonblocking
class RandomGrayscale(IntensityAugmentationBase2D):
r"""Convert images to grayscale (channel count kept), applied per sample with probability ``p`` (default 0.1).
+ ``output = RandomGrayscale(...)(input)`` turns selected images ``(B, C, H, W)`` into grayscale values while
+ retaining their channel count: RGB uses luminance weights and other channel counts default to equal weights.
+
.. image:: _static/img/RandomGrayscale.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -65,6 +68,9 @@ class RandomGrayscale(IntensityAugmentationBase2D):
For 3-channel RGB inputs this uses :func:`kornia.color.rgb_to_grayscale`; multispectral
inputs use a weighted channel average.
+ See Also:
+ - :class:`RandomChannelDropout`: removes selected channels instead of computing grayscale.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.randn((1, 3, 3, 3))
diff --git a/kornia/augmentation/_2d/intensity/hue.py b/kornia/augmentation/_2d/intensity/hue.py
index 0eff9a6e8..d7cb8b4ad 100644
--- a/kornia/augmentation/_2d/intensity/hue.py
+++ b/kornia/augmentation/_2d/intensity/hue.py
@@ -28,7 +28,9 @@ from kornia.enhance.adjust import adjust_hue
class RandomHue(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the hue of a torch.Tensor image.
+ r"""Rotate the hue of a three-channel image by a random number of turns.
+
+ ``output = RandomHue(hue)(input)`` samples an HSV hue rotation for each selected image.
The shift is in turns of the hue circle, the unit of torchvision's ``adjust_hue`` ``hue_factor``, so a
torchvision hue range carries over unchanged.
@@ -62,6 +64,11 @@ class RandomHue(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.adjust_hue`
+ See Also:
+ - :class:`RandomSaturation`: scales HSV saturation without rotating hue.
+ - :class:`ColorJiggle`: combines hue rotation with other Kornia color adjustments.
+ - :class:`ColorJitter`: combines hue rotation with torchvision-compatible color adjustments.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/invert.py b/kornia/augmentation/_2d/intensity/invert.py
index efc249c2e..230cc79eb 100644
--- a/kornia/augmentation/_2d/intensity/invert.py
+++ b/kornia/augmentation/_2d/intensity/invert.py
@@ -29,6 +29,8 @@ from kornia.enhance import invert
class RandomInvert(IntensityAugmentationBase2D):
r"""Invert image values as ``max_val - x``, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomInvert(max_val, ...)(input)`` subtracts selected image values from a chosen maximum.
+
.. image:: _static/img/RandomInvert.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -50,6 +52,9 @@ class RandomInvert(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.invert`.
+ See Also:
+ - :class:`RandomSolarize`: inverts only values above a sampled threshold.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/jpeg.py b/kornia/augmentation/_2d/intensity/jpeg.py
index d3e3fdb0f..45595aecf 100644
--- a/kornia/augmentation/_2d/intensity/jpeg.py
+++ b/kornia/augmentation/_2d/intensity/jpeg.py
@@ -26,7 +26,10 @@ from kornia.enhance import jpeg_codec_differentiable
class RandomJPEG(IntensityAugmentationBase2D):
- r"""Applies random (differentiable) JPEG coding to a torch.Tensor image.
+ r"""Simulate differentiable JPEG coding for RGB images.
+
+ ``output = RandomJPEG(jpeg_quality, ...)(input)`` simulates JPEG coding for selected RGB images of shape
+ ``(B, 3, H, W)``.
.. image:: _static/img/RandomJPEG.png
@@ -53,6 +56,9 @@ class RandomJPEG(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.jpeg_codec_differentiable`.
+ See Also:
+ - :class:`RandomGaussianBlur`: smooths with a filter rather than JPEG coding artifacts.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/intensity/linear_illumination.py b/kornia/augmentation/_2d/intensity/linear_illumination.py
index dd7401317..a5bca928a 100644
--- a/kornia/augmentation/_2d/intensity/linear_illumination.py
+++ b/kornia/augmentation/_2d/intensity/linear_illumination.py
@@ -28,6 +28,9 @@ from kornia.core.utils import _clamp_unit_range, _to_device_nonblocking
class RandomLinearIllumination(IntensityAugmentationBase2D):
r"""Brighten or darken by a linear ramp from an edge, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomLinearIllumination(...)(input)`` adds a sampled edge-to-edge ramp to selected images
+ ``(B, C, H, W)`` and clamps them to ``[0, 1]``.
+
.. image:: _static/img/RandomLinearIllumination.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -60,6 +63,10 @@ class RandomLinearIllumination(IntensityAugmentationBase2D):
the parameters will be generated on CPU. This can be changed by calling
``self.set_rng_device_and_dtype(device="cuda", dtype=torch.float64)``.
+ See Also:
+ - :class:`RandomGaussianIllumination`: adds a smooth Gaussian-shaped illumination field.
+ - :class:`RandomLinearCornerIllumination`: starts its ramp from a corner.
+
Examples:
>>> rng = torch.manual_seed(1)
>>> input = torch.ones(1, 3, 3, 3) * 0.5
@@ -148,6 +155,9 @@ class RandomLinearIllumination(IntensityAugmentationBase2D):
class RandomLinearCornerIllumination(IntensityAugmentationBase2D):
r"""Brighten or darken by a linear ramp from a corner, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomLinearCornerIllumination(...)(input)`` adds a sampled ramp from one corner to selected images
+ ``(B, C, H, W)`` and clamps them to ``[0, 1]``.
+
.. image:: _static/img/RandomLinearCornerIllumination.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -180,6 +190,9 @@ class RandomLinearCornerIllumination(IntensityAugmentationBase2D):
the parameters will be generated on CPU. This can be changed by calling
``self.set_rng_device_and_dtype(device="cuda", dtype=torch.float64)``.
+ See Also:
+ - :class:`RandomLinearIllumination`: starts the linear illumination ramp from an edge.
+
Examples:
>>> rng = torch.manual_seed(1)
>>> input = torch.ones(1, 3, 3, 3) * 0.5
diff --git a/kornia/augmentation/_2d/intensity/median_blur.py b/kornia/augmentation/_2d/intensity/median_blur.py
index b43f7ba69..ffba252c8 100644
--- a/kornia/augmentation/_2d/intensity/median_blur.py
+++ b/kornia/augmentation/_2d/intensity/median_blur.py
@@ -28,6 +28,9 @@ from kornia.filters.kernels import _check_kernel_size, _unpack_2d_ks
class RandomMedianBlur(IntensityAugmentationBase2D):
"""Blur images with a median filter, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomMedianBlur(kernel_size, ...)(input)`` replaces pixels in selected ``(B, C, H, W)`` images by
+ local medians.
+
.. image:: _static/img/RandomMedianBlur.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -54,6 +57,9 @@ class RandomMedianBlur(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.filters.median_blur`.
+ See Also:
+ - :class:`RandomGaussianBlur`: uses a weighted average rather than the median.
+
Examples:
>>> img = torch.ones(1, 1, 4, 4)
>>> out = RandomMedianBlur((3, 3), p = 1)(img)
diff --git a/kornia/augmentation/_2d/intensity/motion_blur.py b/kornia/augmentation/_2d/intensity/motion_blur.py
index 6412ac76a..83a77195e 100644
--- a/kornia/augmentation/_2d/intensity/motion_blur.py
+++ b/kornia/augmentation/_2d/intensity/motion_blur.py
@@ -29,6 +29,9 @@ from kornia.filters import motion_blur
class RandomMotionBlur(IntensityAugmentationBase2D):
r"""Blur images with a random motion-blur kernel, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomMotionBlur(kernel_size, angle, direction, ...)(input)`` convolves selected ``(B, C, H, W)``
+ images with a sampled directional kernel.
+
.. image:: _static/img/RandomMotionBlur.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -94,6 +97,11 @@ class RandomMotionBlur(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.filters.motion_blur`.
+ See Also:
+ - :class:`RandomMotionBlur3D`: applies a directional kernel to volumes.
+ - :class:`RandomGaussianBlur`: applies isotropic Gaussian smoothing.
+ - :class:`RandomBoxBlur`: applies uniform, non-directional smoothing.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.ones(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/normalize.py b/kornia/augmentation/_2d/intensity/normalize.py
index a8de1ee7b..64f6c4797 100644
--- a/kornia/augmentation/_2d/intensity/normalize.py
+++ b/kornia/augmentation/_2d/intensity/normalize.py
@@ -27,7 +27,9 @@ from kornia.enhance import normalize
class Normalize(IntensityAugmentationBase2D):
- r"""Normalize tensor images with mean and standard deviation.
+ r"""Normalize image channels with supplied mean and standard deviation.
+
+ ``output = Normalize(mean, std)(input)`` returns ``(input - mean) / std``.
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -54,13 +56,17 @@ class Normalize(IntensityAugmentationBase2D):
and takes no ``same_on_batch`` argument.
- the statistics live in ``flags`` rather than in a buffer: ``state_dict()`` is empty and
``Module.to(...)`` does not move them; they are cast to the input's device and dtype on each call.
- - :class:`Denormalize` built with the same ``mean`` and ``std`` inverts this class, up to float
- rounding, when both apply -- each draws its own ``p`` gate.
+ - :class:`Denormalize` built with the same ``mean`` and nonzero ``std`` inverts this class, up to
+ floating-point rounding, when both transforms apply and their intermediate values remain finite.
- the result is not clamped: moving an image out of ``[0, 1]`` is what this class is for.
.. note::
This function internally uses :func:`kornia.enhance.normalize`.
+ See Also:
+ - :class:`Denormalize`: reverses this operation when both use the same statistics and apply.
+ - :class:`RandomAutoContrast`: derives a rescaling from each image rather than supplied statistics.
+
Examples:
>>> norm = Normalize(mean=torch.zeros(4), std=torch.ones(4))
>>> x = torch.rand(1, 4, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/planckian_jitter.py b/kornia/augmentation/_2d/intensity/planckian_jitter.py
index 5d45ba056..83d24a0c7 100644
--- a/kornia/augmentation/_2d/intensity/planckian_jitter.py
+++ b/kornia/augmentation/_2d/intensity/planckian_jitter.py
@@ -94,6 +94,9 @@ def get_planckian_coeffs(mode: str) -> torch.Tensor:
class RandomPlanckianJitter(IntensityAugmentationBase2D):
r"""Shift the illuminant color (Planckian jitter), applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPlanckianJitter(...)(input)`` changes the illumination of selected RGB images ``(B, 3, H, W)``
+ along its color-temperature model.
+
.. image:: _static/img/RandomPlanckianJitter.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -131,6 +134,9 @@ class RandomPlanckianJitter(IntensityAugmentationBase2D):
does not load into an instance built with the other. Tracked in
`#4428 <https://github.com/kornia/kornia/issues/4428>`_.
+ See Also:
+ - :class:`ColorJiggle`: samples general color adjustments instead of illuminant coefficients.
+
Examples:
To apply planckian jitter based on mode
diff --git a/kornia/augmentation/_2d/intensity/plasma.py b/kornia/augmentation/_2d/intensity/plasma.py
index f7bc7c6dc..ccbbbb380 100644
--- a/kornia/augmentation/_2d/intensity/plasma.py
+++ b/kornia/augmentation/_2d/intensity/plasma.py
@@ -57,6 +57,9 @@ def _plasma_for_input(plasma: torch.Tensor, image: torch.Tensor) -> torch.Tensor
class RandomPlasmaBrightness(IntensityAugmentationBase2D):
r"""Shift brightness by a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPlasmaBrightness(roughness, intensity, ...)(input)`` adds a sampled fractal field to each
+ selected image ``(B, C, H, W)`` and clamps it to ``[0, 1]``.
+
.. image:: _static/img/RandomPlasmaBrightness.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -84,6 +87,10 @@ class RandomPlasmaBrightness(IntensityAugmentationBase2D):
does not.
- a one-pixel spatial axis is accepted, down to a ``1 x 1`` image.
+ See Also:
+ - :class:`RandomGaussianIllumination`: uses a smooth Gaussian field instead of a fractal field.
+ - :class:`RandomLinearIllumination`: uses a linear illumination ramp.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.ones(1, 1, 3, 4)
@@ -130,6 +137,9 @@ class RandomPlasmaBrightness(IntensityAugmentationBase2D):
class RandomPlasmaContrast(IntensityAugmentationBase2D):
r"""Scale contrast by a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPlasmaContrast(roughness, ...)(input)`` scales contrast locally with a sampled fractal field on
+ selected ``(B, C, H, W)`` images.
+
.. image:: _static/img/RandomPlasmaContrast.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -156,6 +166,10 @@ class RandomPlasmaContrast(IntensityAugmentationBase2D):
does not.
- a one-pixel spatial axis is accepted, down to a ``1 x 1`` image.
+ See Also:
+ - :class:`RandomPlasmaBrightness`: offsets brightness with a fractal map.
+ - :class:`RandomPlasmaShadow`: uses a fractal map to darken selected areas.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.ones(1, 1, 3, 4)
@@ -197,6 +211,9 @@ class RandomPlasmaContrast(IntensityAugmentationBase2D):
class RandomPlasmaShadow(IntensityAugmentationBase2D):
r"""Add shadows from a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPlasmaShadow(roughness, shade_intensity, ...)(input)`` darkens areas chosen by a sampled
+ fractal field in selected ``(B, C, H, W)`` images.
+
.. image:: _static/img/RandomPlasmaShadow.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -226,6 +243,10 @@ class RandomPlasmaShadow(IntensityAugmentationBase2D):
does not.
- a one-pixel spatial axis is accepted, down to a ``1 x 1`` image.
+ See Also:
+ - :class:`RandomPlasmaBrightness`: offsets brightness with a fractal map.
+ - :class:`RandomPlasmaContrast`: scales contrast with a fractal map.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> img = torch.ones(1, 1, 3, 4)
diff --git a/kornia/augmentation/_2d/intensity/posterize.py b/kornia/augmentation/_2d/intensity/posterize.py
index 1c276a234..470e67873 100644
--- a/kornia/augmentation/_2d/intensity/posterize.py
+++ b/kornia/augmentation/_2d/intensity/posterize.py
@@ -28,6 +28,8 @@ from kornia.enhance import posterize
class RandomPosterize(IntensityAugmentationBase2D):
r"""Posterize images to a random number of bits, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPosterize(bits, ...)(input)`` reduces the retained bit depth of selected images.
+
.. image:: _static/img/RandomPosterize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -62,6 +64,9 @@ class RandomPosterize(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.posterize`.
+ See Also:
+ - :class:`RandomSolarize`: thresholds values rather than reducing their bit depth.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/random_rain.py b/kornia/augmentation/_2d/intensity/random_rain.py
index 4ab57043b..d0249f9ab 100644
--- a/kornia/augmentation/_2d/intensity/random_rain.py
+++ b/kornia/augmentation/_2d/intensity/random_rain.py
@@ -30,6 +30,9 @@ from kornia.core.utils import _to_device_nonblocking
class RandomRain(IntensityAugmentationBase2D):
r"""Draw random rain-drop streaks on images, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomRain(...)(input)`` draws sampled streaks over selected one- or three-channel images
+ ``(B, C, H, W)``.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
@@ -61,6 +64,9 @@ class RandomRain(IntensityAugmentationBase2D):
5 pixels wide, therefore raises on some draws. A range that is reversed, fractional or non-finite
raises ``ValueError`` at construction.
+ See Also:
+ - :class:`RandomSnow`: creates a snow effect rather than rain streaks.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/random_rgb_shift.py b/kornia/augmentation/_2d/intensity/random_rgb_shift.py
index e25fd989c..fd7b7dc67 100644
--- a/kornia/augmentation/_2d/intensity/random_rgb_shift.py
+++ b/kornia/augmentation/_2d/intensity/random_rgb_shift.py
@@ -38,6 +38,10 @@ def _shift_bounds(limit: Union[torch.Tensor, float, Tuple[float, float], List[fl
class RandomRGBShift(IntensityAugmentationBase2D):
"""Shift each RGB channel by a random offset, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomRGBShift(r_shift_limit, g_shift_limit, b_shift_limit, ...)(input)`` offsets the channels of
+ selected RGB images ``(B, 3, H, W)`` separately and clamps their output to ``[0, 1]``. Use
+ :class:`RandomBrightness` for one shared additive offset.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
@@ -63,6 +67,10 @@ class RandomRGBShift(IntensityAugmentationBase2D):
- a ``(low, high)`` pair, as in ``albumentations.RGBShift``, is the sampling range itself. It must be
finite with ``low <= high``, otherwise it raises a ``ValueError`` at construction.
+ See Also:
+ - :class:`RandomBrightness`: offsets all channels equally instead of each RGB channel separately.
+ - :class:`ColorJiggle`: combines RGB color adjustments with HSV operations.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_2d/intensity/random_snow.py b/kornia/augmentation/_2d/intensity/random_snow.py
index 44cdb2911..8dd47a954 100644
--- a/kornia/augmentation/_2d/intensity/random_snow.py
+++ b/kornia/augmentation/_2d/intensity/random_snow.py
@@ -27,7 +27,10 @@ from kornia.core.utils import _clamp_unit_range, _to_device_nonblocking
class RandomSnow(IntensityAugmentationBase2D):
- r"""Generates snow effect on given torch.Tensor image or a batch torch.Tensor images.
+ r"""Create an HLS snow effect on selected RGB images.
+
+ ``output = RandomSnow(snow_coefficient, brightness, ...)(input)`` brightens pixels of selected ``(B, 3, H, W)``
+ images according to a sampled snow threshold.
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -54,6 +57,9 @@ class RandomSnow(IntensityAugmentationBase2D):
- a pixel whose lightness is below ``snow_coefficient`` has its lightness scaled by
``brightness``; it becomes white once that lightness reaches ``1``.
+ See Also:
+ - :class:`RandomRain`: creates rain streaks rather than an HLS snow effect.
+
Examples:
>>> inputs = torch.rand(2, 3, 4, 4)
>>> snow = kornia.augmentation.RandomSnow(p=1.0, snow_coefficient=(0.1, 0.6), brightness=(1.0, 5.0))
diff --git a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py b/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
index 2fe339faf..4524de30f 100644
--- a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
+++ b/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
@@ -28,6 +28,9 @@ from kornia.core.utils import _to_device_nonblocking
class RandomSaltAndPepperNoise(IntensityAugmentationBase2D):
r"""Add salt-and-pepper noise to images, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomSaltAndPepperNoise(amount, salt_vs_pepper, ...)(input)`` rewrites sampled pixels of selected
+ one- or three-channel images ``(B, C, H, W)`` to zero or one.
+
.. image:: _static/img/RandomSaltAndPepperNoise.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -64,6 +67,9 @@ class RandomSaltAndPepperNoise(IntensityAugmentationBase2D):
exact values, rather than randomly sampling from the specified range. However, the masks are still
generated randomly using these exact parameters.
+ See Also:
+ - :class:`RandomGaussianNoise`: adds a dense continuous noise field.
+
Examples:
>>> rng = torch.manual_seed(5)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/saturation.py b/kornia/augmentation/_2d/intensity/saturation.py
index 5555aeb8b..919f3f8e4 100644
--- a/kornia/augmentation/_2d/intensity/saturation.py
+++ b/kornia/augmentation/_2d/intensity/saturation.py
@@ -27,11 +27,11 @@ from kornia.enhance.adjust import adjust_saturation
class RandomSaturation(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the saturation of a torch.Tensor image.
+ r"""Scale the HSV saturation of a three-channel image by a random factor.
- The factor scales the HSV saturation. torchvision's and PIL's saturation blends the image with its
- grayscale instead (``factor * input + (1 - factor) * gray``); :class:`ColorJitter`'s saturation step is
- that formula.
+ ``output = RandomSaturation(saturation)(input)`` scales only the HSV saturation of each selected image by a
+ sampled factor. Use :class:`ColorJitter` for torchvision-compatible saturation, which blends the image with its
+ grayscale, ``factor * input + (1 - factor) * gray``.
.. image:: _static/img/RandomSaturation.png
@@ -59,6 +59,11 @@ class RandomSaturation(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.adjust_saturation`
+ See Also:
+ - :class:`RandomHue`: rotates hue instead of scaling saturation.
+ - :class:`ColorJiggle`: combines HSV saturation scaling with Kornia color adjustments.
+ - :class:`ColorJitter`: uses torchvision-compatible grayscale-blend saturation.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> inputs = torch.rand(1, 3, 3, 3)
diff --git a/kornia/augmentation/_2d/intensity/sharpness.py b/kornia/augmentation/_2d/intensity/sharpness.py
index e43ea780b..94945decf 100644
--- a/kornia/augmentation/_2d/intensity/sharpness.py
+++ b/kornia/augmentation/_2d/intensity/sharpness.py
@@ -29,6 +29,9 @@ from kornia.enhance import sharpness
class RandomSharpness(IntensityAugmentationBase2D):
r"""Blend each sample with a ``3 x 3`` smoothed copy by a random factor, with probability ``p`` (default 0.5).
+ ``output = RandomSharpness(sharpness, ...)(input)`` blends each selected ``(B, C, H, W)`` image with its local
+ smooth version.
+
A drawn factor above ``1`` sharpens and a factor below ``1`` blurs; the default
``sharpness=0.5`` draws from ``[0, 0.5]`` and therefore only ever blurs.
@@ -66,6 +69,9 @@ class RandomSharpness(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.sharpness`.
+ See Also:
+ - :class:`RandomBoxBlur`: smooths rather than blends an image with its smoothed copy.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/intensity/solarize.py b/kornia/augmentation/_2d/intensity/solarize.py
index 98628353b..003a8a0eb 100644
--- a/kornia/augmentation/_2d/intensity/solarize.py
+++ b/kornia/augmentation/_2d/intensity/solarize.py
@@ -28,6 +28,9 @@ from kornia.enhance import solarize
class RandomSolarize(IntensityAugmentationBase2D):
r"""Solarize images at a random threshold and addition, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomSolarize(thresholds, additions, ...)(input)`` offsets then inverts selected image values above a
+ sampled threshold, after clamping the selected input to ``[0, 1]``.
+
.. image:: _static/img/RandomSolarize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -54,8 +57,8 @@ class RandomSolarize(IntensityAugmentationBase2D):
- the addition comes first: the drawn ``additions`` value is added to the whole image and the sum
is clamped into ``[0, 1]``, and only then is everything at or above the drawn ``thresholds``
replaced by ``1 - value``.
- - the scalar forms are centred, not absolute: a scalar ``thresholds`` is a half-width around
- ``0.5`` and a scalar ``additions`` a half-width around ``0``, so the class defaults centre on
+ - the scalar forms are centered, not absolute: a scalar ``thresholds`` is a half-width around
+ ``0.5`` and a scalar ``additions`` a half-width around ``0``, so the class defaults center on
:func:`kornia.enhance.solarize`'s own default threshold rather than equalling it.
- an explicit ``additions`` range is checked against the closed ``[-0.5, 0.5]`` at construction, so a
range that reaches an endpoint is applied rather than rejected.
@@ -63,6 +66,10 @@ class RandomSolarize(IntensityAugmentationBase2D):
.. note::
This function internally uses :func:`kornia.enhance.solarize`.
+ See Also:
+ - :class:`RandomInvert`: inverts every pixel rather than values above a threshold.
+ - :class:`RandomPosterize`: reduces bit depth rather than applying a threshold.
+
Examples:
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 5, 5)
diff --git a/kornia/augmentation/_2d/mix/base.py b/kornia/augmentation/_2d/mix/base.py
index ad45dcb7a..0015da515 100644
--- a/kornia/augmentation/_2d/mix/base.py
+++ b/kornia/augmentation/_2d/mix/base.py
@@ -41,10 +41,12 @@ def _export_boxes(box: Boxes, mode: str, box_input: Any) -> torch.Tensor:
class MixAugmentationBaseV2(_BasicAugmentationBase):
- r"""MixAugmentationBase base class for customized mix augmentation implementations.
+ r"""Build a custom augmentation that mixes samples through data-key handlers.
- For any augmentation, the implementation of "generate_parameters" and "apply_transform" are required.
- "apply_transform" will need to handle the probabilities internally.
+ ``output = MyAugmentation(...)(input)`` combines batch samples or rearranges image content once a subclass
+ implements ``apply_transform`` and provides parameter generation, either through ``_param_generator`` or
+ by overriding ``generate_parameters``. Implement the additional data-key handlers that the operation supports;
+ the Convention block below describes how each handler uses the probability gate.
Args:
p: probability for applying an augmentation. This param controls the augmentation probabilities
@@ -76,6 +78,9 @@ class MixAugmentationBaseV2(_BasicAugmentationBase):
instead. The box and class-label handlers use the same gate: an unselected row's label describes an
unmixed image (its own class twice, with lambda 0).
+ See Also:
+ - :class:`AugmentationBase2D`: base class for single-image 2D augmentations.
+
"""
def _validate_data_key(self, key: DataKey) -> None:
diff --git a/kornia/augmentation/_2d/mix/cutmix.py b/kornia/augmentation/_2d/mix/cutmix.py
index da7bd1673..dedcfabf4 100644
--- a/kornia/augmentation/_2d/mix/cutmix.py
+++ b/kornia/augmentation/_2d/mix/cutmix.py
@@ -28,21 +28,10 @@ from kornia.geometry.bbox import bbox_to_mask, infer_bbox_shape
class RandomCutMixV2(MixAugmentationBaseV2):
- r"""Apply CutMix augmentation to a batch of torch.Tensor images.
+ r"""Mix rectangular image regions and labels, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/RandomCutMixV2.png
-
- Implementation for `CutMix: Regularization Strategy to Train Strong Classifiers with
- Localizable Features` :cite:`yun2019cutmix`.
-
- The function returns (inputs, labels), in which the inputs is the torch.Tensor that contains the mixup images
- while the labels is a :math:`(\text{num_mixes}, B, 3)` torch.Tensor that contains
- (label_batch, label_permuted_batch, lambda) for each cutmix.
-
- The implementation referred to the following repository: `https://github.com/clovaai/CutMix-PyTorch
- <https://github.com/clovaai/CutMix-PyTorch>`_.
-
- See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+ ``images, labels = RandomCutMixV2(data_keys=["input", "class"])(input, label)`` mixes image patches and
+ returns label pairs with their coefficients. Use :class:`RandomMixUpV2` to blend complete images instead.
Args:
p: probability for applying an augmentation to a batch. This param controls the augmentation
@@ -70,7 +59,7 @@ class RandomCutMixV2(MixAugmentationBaseV2):
Returns:
Tuple[torch.Tensor, torch.Tensor]:
- Adjusted image, shape of ``(B, C, H, W)``.
- - Raw labels, permuted labels and lambdas for each mix, shape of :math:`(num_mix, B, 3)`.
+ - Raw labels, permuted labels and lambdas for each mix, shape ``(num_mix, B, 3)``.
Convention:
- With ``data_keys=["input", "class"]``, the class output is ``(num_mix, B, 3)``. Its last axis holds
@@ -88,8 +77,18 @@ class RandomCutMixV2(MixAugmentationBaseV2):
pairing and geometry. At ``p=0`` the image is unchanged and each class row contains the original label twice
with lambda zero.
- Note:
- This implementation would randomly cutmix images in a batch. Ideally, the larger batch size would be preferred.
+ .. image:: _static/img/RandomCutMixV2.png
+
+ Implementation for `CutMix: Regularization Strategy to Train Strong Classifiers with
+ Localizable Features` :cite:`yun2019cutmix`.
+
+ The implementation referred to the following repository: `https://github.com/clovaai/CutMix-PyTorch
+ <https://github.com/clovaai/CutMix-PyTorch>`_.
+
+ See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+
+ See Also:
+ - :class:`RandomMixUpV2`: blends complete paired images instead of rectangular patches.
Examples:
>>> rng = torch.manual_seed(3)
diff --git a/kornia/augmentation/_2d/mix/jigsaw.py b/kornia/augmentation/_2d/mix/jigsaw.py
index 5333b80c4..17981b197 100644
--- a/kornia/augmentation/_2d/mix/jigsaw.py
+++ b/kornia/augmentation/_2d/mix/jigsaw.py
@@ -30,12 +30,7 @@ __all__ = ["RandomJigsaw"]
class RandomJigsaw(MixAugmentationBaseV2):
r"""Shuffle the tiles of each image like a jigsaw puzzle, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomJigsaw.png
-
- Make Jigsaw puzzles for each image individually. To mix with different images in a
- batch, referring to :class:`kornia.augmentation.RandomMosaic`.
-
- See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+ ``output = RandomJigsaw(grid, ...)(input)`` rearranges the grid cells of each selected image.
Args:
grid: the Jigsaw puzzle grid. e.g. (2, 2) means
@@ -61,6 +56,13 @@ class RandomJigsaw(MixAugmentationBaseV2):
- ``p`` is a per-sample gate; ``same_on_batch=True`` shares one gate draw and one permutation. Only image
input is implemented.
+ .. image:: _static/img/RandomJigsaw.png
+
+ See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+
+ See Also:
+ - :class:`RandomMosaic`: composes a crop from multiple images in the batch.
+
Examples:
>>> jigsaw = RandomJigsaw((4, 4))
>>> input = torch.randn(8, 3, 256, 256)
diff --git a/kornia/augmentation/_2d/mix/mixup.py b/kornia/augmentation/_2d/mix/mixup.py
index 0f4fdc103..14943d9d3 100644
--- a/kornia/augmentation/_2d/mix/mixup.py
+++ b/kornia/augmentation/_2d/mix/mixup.py
@@ -26,37 +26,10 @@ from kornia.core.utils import _to_device_nonblocking
class RandomMixUpV2(MixAugmentationBaseV2):
- r"""Apply MixUp augmentation to a batch of torch.Tensor images.
+ r"""Mix pairs of images and labels, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/RandomMixUpV2.png
-
- Implementation for `mixup: BEYOND EMPIRICAL RISK MINIMIZATION` :cite:`zhang2018mixup`.
-
- The function returns (inputs, labels), in which the inputs is the torch.Tensor that contains the mixup images
- while the labels is a ``(B, 3)`` torch.Tensor that contains (label_batch, label_permuted_batch, lambda) for
- each image.
-
- The implementation is on top of the following repository:
- `https://github.com/hongyi-zhang/mixup/blob/master/cifar/utils.py
- <https://github.com/hongyi-zhang/mixup/blob/master/cifar/utils.py>`_.
-
- See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
-
- The loss and accuracy are computed as:
-
- .. code-block:: python
-
- def loss_mixup(y, logits):
- criterion = F.cross_entropy
- loss_a = criterion(logits, y[:, 0].long(), reduction='none')
- loss_b = criterion(logits, y[:, 1].long(), reduction='none')
- return ((1 - y[:, 2]) * loss_a + y[:, 2] * loss_b).mean()
-
- .. code-block:: python
-
- def acc_mixup(y, logits):
- pred = torch.argmax(logits, dim=1).to(y.device)
- return (1 - y[:, 2]) * pred.eq(y[:, 0]).float() + y[:, 2] * pred.eq(y[:, 1]).float()
+ ``images, labels = RandomMixUpV2(data_keys=["input", "class"])(input, label)`` returns blended images and
+ paired labels with mixing coefficients. Use :class:`RandomCutMixV2` to replace a rectangular region instead.
Args:
p: probability for applying an augmentation to a batch. This param controls the augmentation
@@ -88,10 +61,34 @@ class RandomMixUpV2(MixAugmentationBaseV2):
and the class output holds the original label twice with a zero lambda. ``same_on_batch=True`` shares
the lambda draw but not the pairing, which may pair a sample with itself.
- Note:
- This implementation would randomly mixup images in a batch. Ideally, the larger batch size would be preferred.
+ .. image:: _static/img/RandomMixUpV2.png
+
+ Implementation for `mixup: BEYOND EMPIRICAL RISK MINIMIZATION` :cite:`zhang2018mixup`.
+
+ The implementation is on top of the following repository:
+ `https://github.com/hongyi-zhang/mixup/blob/master/cifar/utils.py
+ <https://github.com/hongyi-zhang/mixup/blob/master/cifar/utils.py>`_.
+
+ See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+
+ See Also:
+ - :class:`RandomCutMixV2`: mixes paired images through sampled rectangular regions.
Examples:
+ The loss and accuracy can use the returned original label, paired label and lambda:
+
+ .. code-block:: python
+
+ def loss_mixup(y, logits):
+ criterion = F.cross_entropy
+ loss_a = criterion(logits, y[:, 0].long(), reduction='none')
+ loss_b = criterion(logits, y[:, 1].long(), reduction='none')
+ return ((1 - y[:, 2]) * loss_a + y[:, 2] * loss_b).mean()
+
+ def acc_mixup(y, logits):
+ pred = torch.argmax(logits, dim=1).to(y.device)
+ return (1 - y[:, 2]) * pred.eq(y[:, 0]).float() + y[:, 2] * pred.eq(y[:, 1]).float()
+
>>> rng = torch.manual_seed(1)
>>> input = torch.rand(2, 1, 3, 3)
>>> label = torch.tensor([0, 1])
diff --git a/kornia/augmentation/_2d/mix/mosaic.py b/kornia/augmentation/_2d/mix/mosaic.py
index fcfce07fb..a53bd5c7e 100644
--- a/kornia/augmentation/_2d/mix/mosaic.py
+++ b/kornia/augmentation/_2d/mix/mosaic.py
@@ -35,18 +35,8 @@ __all__ = ["RandomMosaic"]
class RandomMosaic(MixAugmentationBaseV2):
r"""Replace each sample, with probability ``p`` (default 0.7), by a crop of a mosaic of batch images.
- .. image:: https://raw.githubusercontent.com/kornia/data/main/random_mosaic.png
-
- Given a certain number of images, mosaic transform combines them into one output image.
- The output image is composed of the parts from each sub-image. To mess up each image individually,
- referring to :class:`kornia.augmentation.RandomJigsaw`.
-
- The mosaic transform steps are as follows:
-
- 1. Concate selected images into a super-image.
- 2. Crop out the outcome image according to the top-left corner and crop size.
-
- See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+ ``output = RandomMosaic(output_size, ...)(input)`` arranges batch images in a mosaic before taking one output
+ crop.
Args:
output_size: the output ``(height, width)`` after mosaicing.
@@ -68,16 +58,9 @@ class RandomMosaic(MixAugmentationBaseV2):
to extract the window. Use `slice` for efficiency, or `resample` for proper
differentiability.
- Examples:
- >>> mosaic = RandomMosaic((300, 300), data_keys=["input", "bbox_xyxy"])
- >>> boxes = torch.tensor([[
- ... [70, 5, 150, 100],
- ... [60, 180, 175, 220],
- ... ]]).repeat(8, 1, 1)
- >>> input = torch.randn(8, 3, 224, 224)
- >>> out = mosaic(input, boxes)
- >>> out[0].shape, out[1].shape
- (torch.Size([8, 3, 300, 300]), torch.Size([8, 8, 4]))
+ .. image:: https://raw.githubusercontent.com/kornia/data/main/random_mosaic.png
+
+ See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
Convention:
- ``output_size`` and the default output shape are ordered ``(height, width)``. With ``output_size=None``
@@ -107,6 +90,20 @@ class RandomMosaic(MixAugmentationBaseV2):
:meth:`~kornia.geometry.boxes.Boxes.filter_boxes_by_area`. It exports as exact zeros in every box
format, from a direct call and from :class:`~kornia.augmentation.container.AugmentationSequential`.
+ See Also:
+ - :class:`RandomJigsaw`: shuffles tiles within each individual image.
+
+ Examples:
+ >>> mosaic = RandomMosaic((300, 300), data_keys=["input", "bbox_xyxy"])
+ >>> boxes = torch.tensor([[
+ ... [70, 5, 150, 100],
+ ... [60, 180, 175, 220],
+ ... ]]).repeat(8, 1, 1)
+ >>> input = torch.randn(8, 3, 224, 224)
+ >>> out = mosaic(input, boxes)
+ >>> out[0].shape, out[1].shape
+ (torch.Size([8, 3, 300, 300]), torch.Size([8, 8, 4]))
+
"""
def _validate_data_key(self, key: DataKey) -> None:
diff --git a/kornia/augmentation/_2d/mix/patchmix.py b/kornia/augmentation/_2d/mix/patchmix.py
index a02e3b1fd..3f19ac2b6 100644
--- a/kornia/augmentation/_2d/mix/patchmix.py
+++ b/kornia/augmentation/_2d/mix/patchmix.py
@@ -25,23 +25,16 @@ from kornia.constants import DataKey
class PatchMix(MixAugmentationBaseV2):
- r"""PatchMix augmentation.
+ r"""Replace a square patch with that of a paired sample, applied to a batch with probability ``p`` (default 1.0).
- .. image:: _static/img/PatchMix.png
-
- Replaces a random patch in each image of a batch with the corresponding
- region from a randomly chosen batch image, which can be the same image.
-
- See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
-
- Implementation for `CutMix: Regularization Strategy to Train Strong
- Classifiers with Localizable Features` :cite:`yun2019cutmix`.
+ ``output = PatchMix(alpha, patch_size, ...)(input)`` replaces a square patch in each image with the same region
+ of a randomly paired image of the batch, which can be the image itself.
Args:
alpha: Hyperparameter for the Beta distribution used to generate the
mixing parameter lambda.
patch_size: The size of the square patch to mix.
- p: Probability for applying the augmentation.
+ p: probability of applying the augmentation to the batch.
same_on_batch: Apply the same transformation across the batch.
keepdim: Whether to keep the output shape the same as input ``True``
or broadcast it to the batch form ``False``.
@@ -52,9 +45,18 @@ class PatchMix(MixAugmentationBaseV2):
whatever the gate. Each output sample copies that square from its paired input, ``_params["mix_pairs"]``,
at the same sampled ``(x, y)`` top-left corner, ``_params["patch_coords"]``. The sampled ``lam`` is
stored but blends nothing.
- - ``p`` is a batch-wide gate.
- ``same_on_batch=True`` shares the patch corner, not the pairing, which may pair a sample with itself.
- Only image input is implemented.
+ - ``p`` is a batch-wide gate. ``same_on_batch=True`` shares the patch corner, not the pairing. Only image
+ input is implemented.
+
+ .. image:: _static/img/PatchMix.png
+
+ See the Convention block on :class:`~kornia.augmentation.MixAugmentationBaseV2`.
+
+ Implementation for `CutMix: Regularization Strategy to Train Strong
+ Classifiers with Localizable Features` :cite:`yun2019cutmix`.
+
+ See Also:
+ - :class:`RandomCutMixV2`: CutMix with paired labels and a sampled rectangle.
Examples:
>>> aug = PatchMix(alpha=1.0, patch_size=4)
diff --git a/kornia/augmentation/_2d/mix/transplantation.py b/kornia/augmentation/_2d/mix/transplantation.py
index ecfe09136..13046d923 100644
--- a/kornia/augmentation/_2d/mix/transplantation.py
+++ b/kornia/augmentation/_2d/mix/transplantation.py
@@ -33,19 +33,10 @@ __all__ = ["RandomTransplantation"]
class RandomTransplantation(MixAugmentationBaseV2):
r"""Paste a labelled region from the previous batch image, applied per sample with probability ``p`` (default 0.5).
- .. image:: _static/img/RandomTransplantation.png
-
- Randomly transplant (copy and paste) image features and corresponding segmentation masks between images in a batch.
- The transplantation transform works as follows:
-
- 1. Based on the parameter `p`, a certain number of images in the batch are selected as acceptor of a
- transplantation.
- 2. For each acceptor, the image below in the batch is selected as donor (via circling: :math:`i - 1 \mod B`).
- 3. From the donor, a random label is selected and the corresponding image features and segmentation mask are
- transplanted to the acceptor.
-
- The augmentation is described in `Semantic segmentation of surgical hyperspectral images under geometric domain
- shifts` :cite:`sellner2023semantic`.
+ ``image_out, mask_out = RandomTransplantation(data_keys=["input", "mask"])(input, mask)`` copies the region of
+ one drawn label, image features and segmentation mask alike, from the previous batch image into each selected
+ image. Use :class:`RandomTransplantation3D` for volume dispatch in
+ :class:`~kornia.augmentation.container.AugmentationSequential`.
Args:
excluded_labels: sequence of labels which should not be transplanted from a donor. This can be useful if only
@@ -106,14 +97,12 @@ class RandomTransplantation(MixAugmentationBaseV2):
integer or floating). Only ``"input"`` / ``"image"`` and ``"mask"`` keys are implemented; any other key
raises ``NotImplementedError``. A mask is needed only to draw the parameters; a call that draws them
without one, or whose inputs do not match ``data_keys``, raises a kornia error that names the mask (and
- the key count, on a mismatch) before any input is read. With a complete
- ``params`` any subset of the inputs is accepted, which is how
- :class:`~kornia.augmentation.container.AugmentationSequential` applies the transplant, one input at a
- time. Outputs come back in input order, a single one as a bare
- tensor.
+ the key count, on a mismatch) before any input is read. With a complete ``params`` any subset of the
+ inputs is accepted, which is how :class:`~kornia.augmentation.container.AugmentationSequential` applies
+ the transplant, one input at a time. Outputs come back in input order, a single one as a bare tensor.
- like every mix augmentation it is not geometric: ``transform_matrix`` and ``inverse()`` both raise
- ``RuntimeError``, and the ``inverse()`` of a
- :class:`~kornia.augmentation.container.AugmentationSequential` holding one raises the same error.
+ ``RuntimeError``, and the ``inverse()`` of a :class:`~kornia.augmentation.container.AugmentationSequential`
+ holding one raises the same error.
- a mask with a singleton channel axis, ``(B, 1, *spatial)``, next to an image of the same rank is read as
the ``(B, *spatial)`` mask: the labels and ``selection`` come from its spatial layout and it comes back in
its own ``(B, 1, *spatial)`` layout. That is the layout a container hands on once any other augmentation
@@ -122,6 +111,14 @@ class RandomTransplantation(MixAugmentationBaseV2):
mask is read as ``(B, C, *spatial)``, and every channel moves through the same ``selection``. With no
image in the call, a mask keeps its own rank and a size-1 first spatial axis is not squeezed.
+ .. image:: _static/img/RandomTransplantation.png
+
+ The augmentation is described in `Semantic segmentation of surgical hyperspectral images under geometric domain
+ shifts` :cite:`sellner2023semantic`.
+
+ See Also:
+ - :class:`RandomTransplantation3D`: performs transplantation on 3D volumes and masks.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/base.py b/kornia/augmentation/_3d/base.py
index 39db17586..95ae899e2 100644
--- a/kornia/augmentation/_3d/base.py
+++ b/kornia/augmentation/_3d/base.py
@@ -30,7 +30,12 @@ from kornia.geometry.keypoints import Keypoints3D
class AugmentationBase3D(_AugmentationBase):
- r"""Base class for custom 3D augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a custom 3D augmentation, applied per sample with probability ``p`` (default 0.5).
+
+ ``output = MyAugmentation(...)(input)`` processes volumes of shape ``(B, C, D, H, W)`` once a subclass
+ implements ``apply_transform`` and supplies any parameter generation it needs. Use
+ :class:`GeometricAugmentationBase3D` when the operation moves coordinates, or :class:`IntensityAugmentationBase3D`
+ when it changes voxel values alone.
Args:
p: probability for applying an augmentation. This param controls the augmentation probabilities
@@ -61,6 +66,9 @@ class AugmentationBase3D(_AugmentationBase):
:class:`~kornia.augmentation.MixAugmentationBaseV2` and so carries that class's ``inverse``, which
raises ``RuntimeError``.
+ See Also:
+ - :class:`GeometricAugmentationBase3D`: base class for 3D geometric transforms.
+
"""
def validate_tensor(self, input: torch.Tensor) -> None:
@@ -85,10 +93,12 @@ class AugmentationBase3D(_AugmentationBase):
class RigidAffineAugmentationBase3D(AugmentationBase3D):
- r"""Base class for 3D rigid/affine augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Record a matrix for a custom 3D transform, applied per sample with probability ``p`` (default 0.5).
- RigidAffineAugmentationBase3D enables routined transformation with given transformation matrices
- for different data types like masks, boxes, and keypoints.
+ ``output = MyAugmentation(...)(input)`` records a ``(B, 4, 4)`` matrix once a subclass implements
+ ``compute_transformation`` and ``apply_transform``. This base manages matrix sampling and storage;
+ use :class:`GeometricAugmentationBase3D` for coordinate transforms or :class:`IntensityAugmentationBase3D`
+ for value-only operations.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase3D`.
@@ -101,6 +111,9 @@ class RigidAffineAugmentationBase3D(AugmentationBase3D):
keepdim: whether to keep the output shape the same as input ``True`` or broadcast it to the batch
form ``False``.
+ See Also:
+ - :class:`GeometricAugmentationBase3D`: applies and records 3D geometric transformations.
+
"""
_transform_matrix: Optional[torch.Tensor]
diff --git a/kornia/augmentation/_3d/geometric/affine.py b/kornia/augmentation/_3d/geometric/affine.py
index 53ee878e7..f6ad8f0e6 100644
--- a/kornia/augmentation/_3d/geometric/affine.py
+++ b/kornia/augmentation/_3d/geometric/affine.py
@@ -30,7 +30,7 @@ from kornia.geometry.transform.imgwarp import get_affine_matrix3d, warp_affine3d
class RandomAffine3D(GeometricAugmentationBase3D):
r"""Warp volumes by a random 3D affine transformation, applied per sample with probability ``p`` (default 0.5).
- The transformation is computed so that the center is kept invariant.
+ ``output = RandomAffine3D(degrees, ...)(input)`` warps volumes of shape ``(B, C, D, H, W)`` about their center.
Args:
degrees: Range of yaw (x-axis), pitch (y-axis), roll (z-axis) to select from. The three
@@ -88,6 +88,10 @@ class RandomAffine3D(GeometricAugmentationBase3D):
to all three axes, as the 2D :class:`~kornia.augmentation.RandomAffine` does. The three-pair form
``((a, b), (c, d), (e, f))`` draws each axis independently.
+ See Also:
+ - :class:`RandomRotation3D`: samples a 3D rotation without translation, scale or shear.
+ - :class:`RandomAffine`: applies the corresponding transform to 2D images.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/geometric/base.py b/kornia/augmentation/_3d/geometric/base.py
index 914d8da55..b894d6b56 100644
--- a/kornia/augmentation/_3d/geometric/base.py
+++ b/kornia/augmentation/_3d/geometric/base.py
@@ -19,7 +19,11 @@ from kornia.augmentation._3d.base import RigidAffineAugmentationBase3D
class GeometricAugmentationBase3D(RigidAffineAugmentationBase3D):
- r"""Base class for custom 3D geometric augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a 3D coordinate transform, applied per sample with probability ``p`` (default 0.5).
+
+ ``output = MyAugmentation(...)(input)`` warps volumes of shape ``(B, C, D, H, W)`` once a subclass implements
+ ``compute_transformation`` and ``apply_transform``. The 3D base does not support image inversion.
+ Use :class:`IntensityAugmentationBase3D` for an operation that changes voxel values without moving coordinates.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase3D`.
@@ -45,4 +49,7 @@ class GeometricAugmentationBase3D(RigidAffineAugmentationBase3D):
``float32`` on every device (`#5751 <https://github.com/kornia/kornia/issues/5751>`_,
`#5814 <https://github.com/kornia/kornia/issues/5814>`_).
+ See Also:
+ - :class:`AugmentationBase3D`: base class for general 3D augmentations.
+
"""
diff --git a/kornia/augmentation/_3d/geometric/center_crop.py b/kornia/augmentation/_3d/geometric/center_crop.py
index 2f0c47fb8..5de807193 100644
--- a/kornia/augmentation/_3d/geometric/center_crop.py
+++ b/kornia/augmentation/_3d/geometric/center_crop.py
@@ -28,7 +28,9 @@ from kornia.geometry import crop_by_transform_mat3d
class CenterCrop3D(GeometricAugmentationBase3D):
- r"""Apply center crop on 3D volumes (5D torch.Tensor).
+ r"""Extract a centered 3D subvolume, applied to a batch with probability ``p`` (default 1.0).
+
+ ``output = CenterCrop3D(size)(input)`` extracts a centered ``(D, H, W)`` patch.
Args:
p: probability of applying the transformation for the whole batch.
@@ -42,7 +44,7 @@ class CenterCrop3D(GeometricAugmentationBase3D):
Shape:
- Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``
- - Output: :math:`(B, C, out_d, out_h, out_w)`
+ - Output: ``(B, C, out_d, out_h, out_w)``
Note:
Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.
@@ -60,6 +62,10 @@ class CenterCrop3D(GeometricAugmentationBase3D):
(`#4417 <https://github.com/kornia/kornia/issues/4417>`_).
- defaults are bilinear resampling and ``align_corners=True``.
+ See Also:
+ - :class:`RandomCrop3D`: samples the subvolume position.
+ - :class:`CenterCrop`: extracts a centered patch from a 2D image.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/geometric/crop.py b/kornia/augmentation/_3d/geometric/crop.py
index a20fdeb4d..68fcc5f7e 100644
--- a/kornia/augmentation/_3d/geometric/crop.py
+++ b/kornia/augmentation/_3d/geometric/crop.py
@@ -41,9 +41,9 @@ def _crop_translation3d(src: torch.Tensor, dst: torch.Tensor) -> torch.Tensor:
class RandomCrop3D(GeometricAugmentationBase3D):
- r"""Apply random crop on 3D volumes (5D torch.Tensor).
+ r"""Crop random 3D subvolumes, applied to a batch with probability ``p`` (default 1.0).
- Crops random sub-volumes on a given size.
+ ``output = RandomCrop3D(size, ...)(input)`` selects patches of ``(D, H, W)`` voxels.
Args:
p: probability of applying the transformation for the whole batch.
@@ -72,7 +72,7 @@ class RandomCrop3D(GeometricAugmentationBase3D):
Shape:
- Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``
- - Output: :math:`(B, C, out_d, out_h, out_w)`
+ - Output: ``(B, C, out_d, out_h, out_w)``
Note:
Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.
@@ -97,6 +97,10 @@ class RandomCrop3D(GeometricAugmentationBase3D):
with an identity ``transform_matrix``.
Defaults are bilinear resampling and ``align_corners=True``.
+ See Also:
+ - :class:`CenterCrop3D`: extracts the deterministic centered subvolume.
+ - :class:`RandomCrop`: samples a fixed-size patch from a 2D image.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/geometric/depthical_flip.py b/kornia/augmentation/_3d/geometric/depthical_flip.py
index 906d44928..822b8e953 100644
--- a/kornia/augmentation/_3d/geometric/depthical_flip.py
+++ b/kornia/augmentation/_3d/geometric/depthical_flip.py
@@ -27,7 +27,8 @@ from kornia.core.ops import _device_literal
class RandomDepthicalFlip3D(GeometricAugmentationBase3D):
r"""Flip 3D volumes along the depth axis, applied per sample with probability ``p`` (default 0.5).
- Input should be a tensor of shape ``(C, D, H, W)`` or a batch of tensors ``(*, C, D, H, W)``.
+ ``output = RandomDepthicalFlip3D(...)(input)`` reverses the ``D`` axis of selected volumes shaped
+ ``(B, C, D, H, W)``.
Args:
p: probability of applying the transformation to each sample.
@@ -49,6 +50,10 @@ class RandomDepthicalFlip3D(GeometricAugmentationBase3D):
``D - 1 - z`` in inclusive voxel coordinates, rounded where the dtype cannot
represent it (see the base).
+ See Also:
+ - :class:`RandomHorizontalFlip3D`: reverses the width axis.
+ - :class:`RandomVerticalFlip3D`: reverses the height axis.
+
Examples:
>>> import torch
>>> x = torch.eye(3).repeat(3, 1, 1)
diff --git a/kornia/augmentation/_3d/geometric/horizontal_flip.py b/kornia/augmentation/_3d/geometric/horizontal_flip.py
index 9c32b983d..992b5f02c 100644
--- a/kornia/augmentation/_3d/geometric/horizontal_flip.py
+++ b/kornia/augmentation/_3d/geometric/horizontal_flip.py
@@ -27,6 +27,9 @@ from kornia.core.ops import _device_literal
class RandomHorizontalFlip3D(GeometricAugmentationBase3D):
r"""Flip 3D volumes horizontally, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomHorizontalFlip3D(...)(input)`` reverses the ``W`` axis of selected volumes shaped
+ ``(B, C, D, H, W)``.
+
Args:
p: probability of applying the transformation to each sample.
same_on_batch: apply the same transformation across the batch.
@@ -47,6 +50,11 @@ class RandomHorizontalFlip3D(GeometricAugmentationBase3D):
``W - 1 - x`` in inclusive voxel coordinates, rounded where the dtype cannot
represent it (see the base).
+ See Also:
+ - :class:`RandomHorizontalFlip`: reverses image columns in 2D.
+ - :class:`RandomVerticalFlip3D`: reverses the height axis.
+ - :class:`RandomDepthicalFlip3D`: reverses the depth axis.
+
Examples:
>>> import torch
>>> x = torch.eye(3).repeat(3, 1, 1)
diff --git a/kornia/augmentation/_3d/geometric/perspective.py b/kornia/augmentation/_3d/geometric/perspective.py
index 9de342255..8c0fc57c0 100644
--- a/kornia/augmentation/_3d/geometric/perspective.py
+++ b/kornia/augmentation/_3d/geometric/perspective.py
@@ -30,6 +30,9 @@ from kornia.geometry import get_perspective_transform3d, warp_perspective3d
class RandomPerspective3D(GeometricAugmentationBase3D):
r"""Warp 3D volumes with a random perspective transform, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomPerspective3D(distortion_scale, ...)(input)`` projectively warps volumes of shape
+ ``(B, C, D, H, W)``.
+
Args:
p: probability of applying the transformation to each sample.
distortion_scale: it controls the degree of distortion and ranges from 0 to 1.
@@ -59,6 +62,10 @@ class RandomPerspective3D(GeometricAugmentationBase3D):
slice, row or column maps onto itself. At ``distortion_scale=0`` the transform matrix is
the identity; output identity still requires ``align_corners=True`` as described above.
+ See Also:
+ - :class:`RandomAffine3D`: samples an affine rather than projective warp.
+ - :class:`RandomPerspective`: warps 2D images from sampled perspective endpoints.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/geometric/rotation.py b/kornia/augmentation/_3d/geometric/rotation.py
index 527fefc12..237695102 100644
--- a/kornia/augmentation/_3d/geometric/rotation.py
+++ b/kornia/augmentation/_3d/geometric/rotation.py
@@ -31,7 +31,7 @@ from kornia.geometry.transform.affwarp import _compute_rotation_matrix3d, _compu
class RandomRotation3D(GeometricAugmentationBase3D):
r"""Rotate 3D volumes by a random axis-angle rotation, applied per sample with probability ``p`` (default 0.5).
- Input should be a torch.Tensor of shape (C, D, H, W) or a batch of tensors ``(B, C, D, H, W)``.
+ ``output = RandomRotation3D(degrees, ...)(input)`` rotates volumes of shape ``(B, C, D, H, W)``.
Args:
degrees: Range of degrees to select from.
@@ -76,6 +76,10 @@ class RandomRotation3D(GeometricAugmentationBase3D):
(`#4408 <https://github.com/kornia/kornia/issues/4408>`_).
- the default interpolation is bilinear with ``align_corners=False``.
+ See Also:
+ - :class:`RandomAffine3D`: samples a combined 3D affine transformation.
+ - :class:`RandomRotation`: rotates 2D images by a sampled angle.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/geometric/vertical_flip.py b/kornia/augmentation/_3d/geometric/vertical_flip.py
index 736a1eb01..45b6f9057 100644
--- a/kornia/augmentation/_3d/geometric/vertical_flip.py
+++ b/kornia/augmentation/_3d/geometric/vertical_flip.py
@@ -27,7 +27,8 @@ from kornia.core.ops import _device_literal
class RandomVerticalFlip3D(GeometricAugmentationBase3D):
r"""Flip 3D volumes vertically, applied per sample with probability ``p`` (default 0.5).
- Input should be a tensor of shape ``(C, D, H, W)`` or a batch of tensors ``(*, C, D, H, W)``.
+ ``output = RandomVerticalFlip3D(...)(input)`` reverses the ``H`` axis of selected volumes shaped
+ ``(B, C, D, H, W)``.
Args:
p: probability of applying the transformation to each sample.
@@ -49,6 +50,11 @@ class RandomVerticalFlip3D(GeometricAugmentationBase3D):
``H - 1 - y`` in inclusive voxel coordinates, rounded where the dtype cannot
represent it (see the base).
+ See Also:
+ - :class:`RandomVerticalFlip`: reverses image rows in 2D.
+ - :class:`RandomHorizontalFlip3D`: reverses the width axis.
+ - :class:`RandomDepthicalFlip3D`: reverses the depth axis.
+
Examples:
>>> import torch
>>> x = torch.eye(3).repeat(3, 1, 1)
diff --git a/kornia/augmentation/_3d/intensity/base.py b/kornia/augmentation/_3d/intensity/base.py
index 4ad8618c4..5e4c49d56 100644
--- a/kornia/augmentation/_3d/intensity/base.py
+++ b/kornia/augmentation/_3d/intensity/base.py
@@ -19,7 +19,12 @@ from kornia.augmentation._3d.base import RigidAffineAugmentationBase3D
class IntensityAugmentationBase3D(RigidAffineAugmentationBase3D):
- r"""Base class for custom 3D intensity augmentations, applied per sample with probability ``p`` (default 0.5).
+ r"""Build a 3D value augmentation, applied per sample with probability ``p`` (default 0.5).
+
+ ``output = MyAugmentation(...)(input)`` changes voxel values while retaining their coordinates once a
+ subclass implements ``apply_transform`` and ``compute_transformation``. Unlike the 2D intensity base, this
+ base requires the subclass to return an identity ``(B, 4, 4)`` matrix from ``compute_transformation``.
+ Use :class:`GeometricAugmentationBase3D` for an operation that warps the volume.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase3D`.
@@ -36,4 +41,7 @@ class IntensityAugmentationBase3D(RigidAffineAugmentationBase3D):
- these augmentations leave voxel coordinates in place: they record an identity ``(B, 4, 4)`` matrix,
and a container skips them on its inverse path.
+ See Also:
+ - :class:`GeometricAugmentationBase3D`: base class for 3D coordinate transformations.
+
"""
diff --git a/kornia/augmentation/_3d/intensity/equalize.py b/kornia/augmentation/_3d/intensity/equalize.py
index dd5700a4f..70c398e98 100644
--- a/kornia/augmentation/_3d/intensity/equalize.py
+++ b/kornia/augmentation/_3d/intensity/equalize.py
@@ -26,6 +26,8 @@ from kornia.enhance import equalize3d
class RandomEqualize3D(IntensityAugmentationBase3D):
r"""Equalize the histogram of 3D volumes, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomEqualize3D(...)(input)`` redistributes intensity values without moving voxels.
+
Args:
p: probability of applying the transformation to each sample.
same_on_batch: apply the same transformation across the batch.
@@ -47,6 +49,10 @@ class RandomEqualize3D(IntensityAugmentationBase3D):
(:func:`kornia.enhance.equalize3d`), so a volume with at most 255 voxels per channel is returned
unchanged.
+ See Also:
+ - :class:`RandomEqualize`: equalizes 2D images.
+ - :class:`RandomMotionBlur3D`: blurs along a sampled 3D motion direction.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/intensity/motion_blur.py b/kornia/augmentation/_3d/intensity/motion_blur.py
index 2f79f8283..d4cafda3a 100644
--- a/kornia/augmentation/_3d/intensity/motion_blur.py
+++ b/kornia/augmentation/_3d/intensity/motion_blur.py
@@ -29,6 +29,9 @@ from kornia.filters import motion_blur3d
class RandomMotionBlur3D(IntensityAugmentationBase3D):
r"""Blur 3D volumes with a random motion-blur kernel, applied per sample with probability ``p`` (default 0.5).
+ ``output = RandomMotionBlur3D(kernel_size, angle, direction, ...)(input)`` blurs intensities while retaining
+ voxel coordinates.
+
Args:
p: probability of applying the transformation to each sample.
kernel_size: motion kernel size (odd and at least 3).
@@ -83,6 +86,10 @@ class RandomMotionBlur3D(IntensityAugmentationBase3D):
:class:`~kornia.augmentation.RandomMotionBlur` does for an image.
- this class fixes ``p_batch=1``; its ``p`` remains the per-sample gate.
+ See Also:
+ - :class:`RandomMotionBlur`: applies a directional kernel to 2D images.
+ - :class:`RandomEqualize3D`: equalizes intensity histograms without spatial filtering.
+
Examples:
>>> import torch
>>> rng = torch.manual_seed(0)
diff --git a/kornia/augmentation/_3d/mix/transplantation.py b/kornia/augmentation/_3d/mix/transplantation.py
index bf52c1cdc..36225c8c9 100644
--- a/kornia/augmentation/_3d/mix/transplantation.py
+++ b/kornia/augmentation/_3d/mix/transplantation.py
@@ -24,8 +24,8 @@ __all__ = ["RandomTransplantation3D"]
class RandomTransplantation3D(RandomTransplantation, AugmentationBase3D):
"""Paste a labelled region from the previous 3D volume, applied per sample with probability ``p`` (default 0.5).
- 3D version of the :class:`kornia.augmentation.RandomTransplantation` augmentation intended to be used with
- :class:`kornia.augmentation.container.AugmentationSequential`. The interface is identical to the 2D version.
+ ``image_out, mask_out = RandomTransplantation3D(...)(input, mask)`` copies selected labelled regions
+ between batched volumes and their segmentation masks. Use :class:`RandomTransplantation` for 2D images.
See the Convention block on :class:`~kornia.augmentation.RandomTransplantation`.
@@ -34,4 +34,8 @@ class RandomTransplantation3D(RandomTransplantation, AugmentationBase3D):
:class:`~kornia.augmentation.container.AugmentationSequential` dispatches it as a 3D augmentation. Inside a
container use it for ``(B, C, D, H, W)`` volumes and :class:`~kornia.augmentation.RandomTransplantation`
for ``(B, C, H, W)`` images; the container rejects 4D input for this class and 5D input for the 2D one.
+
+ See Also:
+ - :class:`RandomTransplantation`: performs the corresponding operation on 2D images.
+
"""
diff --git a/kornia/augmentation/__init__.py b/kornia/augmentation/__init__.py
index 473d179d0..2bc61f0e2 100644
--- a/kornia/augmentation/__init__.py
+++ b/kornia/augmentation/__init__.py
@@ -15,9 +15,98 @@
# limitations under the License.
#
-"""Kornia Augmentation β€” Differentiable image, video, and 3D data augmentation for PyTorch.
+"""Build image, video and volume augmentation pipelines with recorded random parameters.
-This subpackage provides a wide range of augmentation modules for computer vision tasks.
+Transforms take float tensors, ``(B, C, H, W)`` images or ``(B, C, D, H, W)`` volumes; color transforms expect
+values in ``[0, 1]``. ``AugmentationSequential`` applies one draw to images, masks, boxes and keypoints together,
+and ``ImageSequential`` chains image-only transforms. In eager mode, ``aug._params`` holds the last draw, and
+``aug(x, params=aug._params)`` replays it. Inverting a geometric warp cannot restore pixels lost to cropping or
+resampling.
+
+Which class to use:
+
+Pipelines and policies:
+ - ``AugmentationSequential``: coordinate image, mask, box and keypoint handlers.
+ - ``ImageSequential``: chain image transforms, including ordinary PyTorch modules.
+ - ``VideoSequential``: apply 2D transforms to video frames, optionally sharing a draw within each clip.
+ - ``PatchSequential``: split an image into a grid and augment its patches.
+ - ``ManyToManyAugmentationDispather``: send each input bundle to its corresponding pipeline.
+ - ``ManyToOneAugmentationDispather``: produce several augmented views of one input bundle.
+ - ``auto``: AutoAugment, RandAugment, TrivialAugment and their policy operations.
+ - ``container``: pipeline classes and their parameter records.
+
+Image size and geometry:
+ - ``Resize``: resize to a target size; ``LongestMaxSize`` and ``SmallestMaxSize`` select the controlling side.
+ - ``PadTo``: pad to a target size at the right and bottom, cropping oversized inputs by default.
+ - ``CenterCrop``: take a centered crop; ``RandomCrop`` samples its position.
+ - ``RandomResizedCrop``: sample a crop's area and aspect ratio, then resize it.
+ - ``RandomHorizontalFlip`` and ``RandomVerticalFlip``: reverse columns or rows.
+ - ``RandomAffine``: combine rotation, translation, scale and shear in one warp.
+ - ``RandomRotation``: rotate by a sampled angle; ``RandomRotation90`` samples multiples of 90 degrees.
+ - ``RandomShear`` and ``RandomTranslate``: sample only shear or translation.
+ - ``RandomPerspective``: perturb the four image corners for a projective warp.
+ - ``RandomElasticTransform``: warp with a smoothed random displacement field.
+ - ``RandomThinPlateSpline``: warp with displaced control points.
+ - ``RandomFisheye``: apply a radial distortion around a sampled center.
+
+Color and contrast:
+ - ``ColorJiggle``: combine additive brightness, multiplicative contrast and HSV saturation/hue adjustments.
+ - ``ColorJitter``: use torchvision-compatible brightness, contrast and saturation formulas.
+ - ``RandomBrightness`` and ``RandomContrast``: sample one brightness or contrast factor.
+ - ``RandomHue`` and ``RandomSaturation``: change one HSV color component.
+ - ``RandomGamma``: apply power-law intensity correction.
+ - ``RandomGrayscale``: average channels with RGB luminance weights or equal weights, keeping the channel count.
+ - ``RandomRGBShift``: shift the three RGB channels independently.
+ - ``RandomPlanckianJitter``: vary RGB illumination along a color-temperature curve.
+ - ``RandomChannelShuffle``: permute channels; ``RandomChannelDropout`` replaces selected channels.
+ - ``RandomAutoContrast``: stretch each channel's intensity range.
+ - ``RandomEqualize``: equalize a global histogram; ``RandomClahe`` uses local, contrast-limited histograms.
+ - ``RandomInvert``: subtract values from a maximum; ``RandomSolarize`` inverts values above a threshold.
+ - ``RandomPosterize``: reduce the number of retained intensity bits.
+ - ``Normalize`` and ``Denormalize``: apply or undo channel-wise mean and standard-deviation normalization.
+
+Blur, noise and occlusion:
+ - ``RandomBoxBlur``: average a rectangular window; ``RandomGaussianBlur`` uses Gaussian weights.
+ - ``RandomMedianBlur``: replace pixels with local medians.
+ - ``RandomMotionBlur``: convolve with a sampled directional motion kernel.
+ - ``RandomSharpness``: blend an image with its smoothed version.
+ - ``RandomGaussianNoise``: add Gaussian noise; ``RandomSaltAndPepperNoise`` inserts dark and bright pixels.
+ - ``RandomJPEG``: simulate JPEG compression at a sampled quality.
+ - ``RandomErasing``: fill a sampled rectangle with a constant.
+ - ``RandomDissolving``: apply a pretrained Stable Diffusion dissolving model.
+ - ``RandomRain`` and ``RandomSnow``: synthesize rain streaks or a snow effect.
+
+Spatially varying illumination:
+ - ``RandomGaussianIllumination``: add a Gaussian illumination pattern.
+ - ``RandomLinearIllumination``: add an edge-to-edge gradient.
+ - ``RandomLinearCornerIllumination``: add a gradient starting from a corner.
+ - ``RandomPlasmaBrightness``: shift brightness with a fractal map.
+ - ``RandomPlasmaContrast``: modulate contrast with a fractal map.
+ - ``RandomPlasmaShadow``: darken regions selected by a fractal map.
+
+Mixing and rearranging images:
+ - ``RandomMixUpV2``: blend paired images and return label weights when requested.
+ - ``RandomCutMixV2``: copy sampled rectangles from paired images.
+ - ``PatchMix``: copy a fixed-size square from a paired image.
+ - ``RandomMosaic``: assemble tiles from several batch images.
+ - ``RandomJigsaw``: permute an image's grid patches.
+ - ``RandomTransplantation``: copy regions selected by a donor segmentation mask.
+
+Volumes:
+ - ``CenterCrop3D`` and ``RandomCrop3D``: take centered or randomly positioned volume crops.
+ - ``RandomHorizontalFlip3D``, ``RandomVerticalFlip3D`` and ``RandomDepthicalFlip3D``: reverse width, height or
+ depth.
+ - ``RandomAffine3D``: sample a 3D affine warp; ``RandomRotation3D`` samples rotation alone.
+ - ``RandomPerspective3D``: perturb the volume corners for a projective warp.
+ - ``RandomEqualize3D``: equalize volume intensities; ``RandomMotionBlur3D`` applies a 3D motion kernel.
+ - ``RandomTransplantation3D``: copy regions selected by a donor volume's segmentation mask.
+
+Extending the module:
+ - ``AugmentationBase2D`` and ``AugmentationBase3D``: share shape handling, sampling and application gates.
+ - ``RigidAffineAugmentationBase2D`` and ``RigidAffineAugmentationBase3D``: add transformation-matrix tracking.
+ - ``GeometricAugmentationBase2D`` and ``GeometricAugmentationBase3D``: implement spatial transforms.
+ - ``IntensityAugmentationBase2D`` and ``IntensityAugmentationBase3D``: implement pixel-value transforms.
+ - ``MixAugmentationBaseV2``: implement transforms that combine batch samples and dispatch data keys.
"""
# Lazy loading auto module
diff --git a/kornia/augmentation/auto/__init__.py b/kornia/augmentation/auto/__init__.py
index c82cf2700..64b609b37 100644
--- a/kornia/augmentation/auto/__init__.py
+++ b/kornia/augmentation/auto/__init__.py
@@ -15,9 +15,18 @@
# limitations under the License.
#
-"""Kornia Augmentation Auto β€” Automated augmentation policies for computer vision.
+"""Choose a policy that samples image augmentation operations automatically.
-This subpackage provides AutoAugment and related policy-based augmentation utilities.
+Each policy records the operations it chose in ``_params``, so a call can be replayed. To chain transforms of your
+own choice, use ``kornia.augmentation.ImageSequential``.
+
+Which class to use:
+
+- :class:`AutoAugment`: choose one searched, dataset-specific sub-policy.
+- :class:`RandAugment`: choose a fixed number of operations at one magnitude.
+- :class:`TrivialAugment`: choose one operation, drawing magnitudes only for operations that have one.
+- :class:`PolicyAugmentBase`: build a custom policy selection class.
+- :class:`PolicySequential`: run the operations within one custom sub-policy.
"""
from .autoaugment import AutoAugment
diff --git a/kornia/augmentation/auto/autoaugment/autoaugment.py b/kornia/augmentation/auto/autoaugment/autoaugment.py
index a3c1ba539..64f07f965 100644
--- a/kornia/augmentation/auto/autoaugment/autoaugment.py
+++ b/kornia/augmentation/auto/autoaugment/autoaugment.py
@@ -115,7 +115,12 @@ svhn_policy: List[SUBPOLICY_CONFIG] = [
class AutoAugment(PolicyAugmentBase):
- """Apply AutoAugment :cite:`cubuk2018autoaugment` searched strategies.
+ """Sample a searched AutoAugment sub-policy for a named image dataset.
+
+ ``output = AutoAugment(policy)(input)`` selects one fixed two-operation sub-policy for ``imagenet``, ``cifar10``
+ or ``svhn`` from :cite:`cubuk2018autoaugment` and applies its probability gates to a floating image batch
+ ``(B, C, H, W)``. Use :class:`~kornia.augmentation.auto.RandAugment` to sample operation choices instead of
+ choosing from a searched list.
See the Convention block on :class:`~kornia.augmentation.auto.PolicyAugmentBase`.
@@ -140,6 +145,10 @@ class AutoAugment(PolicyAugmentBase):
contributes a matrix (an intensity operation the identity), so none is rejected.
If `skip`, transformation matrix will be totally ignored.
+ See Also:
+ - :class:`~kornia.augmentation.auto.RandAugment`: samples operations with one global magnitude.
+ - :class:`~kornia.augmentation.auto.TrivialAugment`: samples exactly one operation.
+
Examples:
>>> import torch
>>> import kornia.augmentation as K
diff --git a/kornia/augmentation/auto/base.py b/kornia/augmentation/auto/base.py
index 5bfd8e24b..29c18ed76 100644
--- a/kornia/augmentation/auto/base.py
+++ b/kornia/augmentation/auto/base.py
@@ -35,25 +35,35 @@ SUBPOLICY_CONFIG = List[OP_CONFIG]
class PolicyAugmentBase(ImageSequentialBase, TransformMatrixMinIn):
- """Base class for policy-based image augmentations.
+ """Build and replay image augmentation policies made of named operations.
+
+ ``output = MyPolicy(policy)(input)`` applies :class:`~kornia.augmentation.auto.PolicySequential` children to
+ floating images of shape ``(B, C, H, W)`` once a subclass implements two hooks: ``compose_subpolicy_sequential``,
+ which builds one sub-policy, and ``get_forward_sequence``, which picks the sub-policies for a call or, given
+ ``params``, returns the recorded ones. Without ``get_forward_sequence``, ``forward(input)`` raises
+ ``NotImplementedError``.
Convention:
- - a concrete policy selects one or more :class:`PolicySequential` children for each forward call and
- records that selected path, including every operation parameter dictionary, in ``_params``. Passing
- that list to ``forward(input, params=...)`` selects the recorded children rather than drawing a new
+ - a concrete policy selects one or more :class:`~kornia.augmentation.auto.PolicySequential` children for each
+ forward call and records that selected path, including every operation parameter dictionary, in ``_params``.
+ Passing that list to ``forward(input, params=...)`` selects the recorded children rather than drawing a new
path and reproduces their output.
- - the selected operations run in the order recorded in ``_params``: the listed order inside a sub-policy,
- and for :class:`RandAugment` the order in which its sub-policies were drawn. When matrix computation is
- enabled, their geometric transformation matrices
- compose in that same execution order; a nonempty policy containing only intensity
- operations has the identity matrix. An empty selected sub-policy has no matrix.
- ``inverse`` reverses a geometry-only selected path and raises ``RuntimeError`` when an applied
- intensity operation cannot be undone.
+ - the selected operations run in the order recorded in ``_params``: the listed order inside a sub-policy, and
+ for :class:`~kornia.augmentation.auto.RandAugment` the order in which its sub-policies were drawn. When
+ matrix computation is enabled, their geometric transformation matrices compose in that same execution order;
+ a nonempty policy containing only intensity operations has the identity matrix. An empty selected sub-policy
+ has no matrix. ``inverse`` reverses a geometry-only selected path and raises ``RuntimeError`` when an
+ applied intensity operation cannot be undone.
- input normalization, random-number generation, parameter placement, replay, and serialization follow
the canonical augmentation contract in :doc:`/get-started/conventions`. This base does not expose a
per-instance generator.
Concrete policies define how they select children and interpret policy magnitudes.
+
+ See Also:
+ - :class:`~kornia.augmentation.auto.PolicySequential`: runs the operations in one sub-policy.
+ - :class:`~kornia.augmentation.container.ImageSequential`: chains arbitrary image transforms without a policy.
+
"""
def __init__(self, policy: List[SUBPOLICY_CONFIG], transformation_matrix_mode: str = "silence") -> None:
diff --git a/kornia/augmentation/auto/operations/base.py b/kornia/augmentation/auto/operations/base.py
index 650298aca..21e0d2cd4 100644
--- a/kornia/augmentation/auto/operations/base.py
+++ b/kornia/augmentation/auto/operations/base.py
@@ -44,7 +44,12 @@ class _RandomSign:
class OperationBase(nn.Module):
- """Base class of differentiable augmentation operations.
+ """Wrap one augmentation module for use in an automatic augmentation policy.
+
+ ``output = OperationBase(op)(input)`` applies a wrapped shape-preserving augmentation to floating
+ images of shape ``(B, C, H, W)``. To control a magnitude, pass a list such as
+ ``initial_magnitude=[("brightness_factor", 0.5)]`` for a brightness operation. Use
+ :class:`~kornia.augmentation.auto.PolicySequential` to compose operations into a policy.
Args:
operation: Kornia augmentation module.
@@ -53,8 +58,8 @@ class OperationBase(nn.Module):
in each augmentation. If None, the augmentation will be randomly applied according to
the augmentation sampling range.
temperature: retained for API compatibility.
- is_batch_operation: determine if to obtain the probability from `p` or `p_batch`.
- Set to True for most non-shape-persistent operations (e.g. cropping).
+ is_batch_operation: initialize the legacy ``probability`` from ``p_batch`` instead of ``p``; sampling still
+ uses the wrapped gates.
Convention:
- ``probability`` is initialized from the wrapped augmentation's ``p`` (``p_batch`` for a batch operation),
@@ -68,6 +73,8 @@ class OperationBase(nn.Module):
augmentation transforms every row whose gate is above ``0``, so the same supplied fractional
``batch_prob`` produces the same soft blend whatever the wrapped ``p`` or ``p_batch``. Below ``p = 1`` the
wrapped augmentation skips a row with gate ``0``, so that row's matrix stays the identity.
+ Consequently, a wrapped operation that changes spatial dimensions cannot be used, even when
+ ``is_batch_operation=True``.
- ``magnitude_range`` is read-only and reads the wrapped generator on each access. A range that is an
``nn.Parameter`` belongs to the generator, so ``state_dict()`` and ``named_parameters()`` have no
``magnitude_range`` entry for it; a checkpoint or pickle that still has the former entry loads.
@@ -77,6 +84,10 @@ class OperationBase(nn.Module):
inherit their input, dtype, RNG and replay contracts. A wrapper pickles, with either sign setting, when
its magnitude mapping is picklable.
+ See Also:
+ - :class:`~kornia.augmentation.auto.PolicySequential`: runs the operations of a policy in order.
+ - :class:`~kornia.augmentation.auto.operations.ops.Rotate`: is a concrete geometric policy operation.
+
"""
def __init__(
diff --git a/kornia/augmentation/auto/operations/ops.py b/kornia/augmentation/auto/operations/ops.py
index 272193c7f..c6c8f7d1f 100644
--- a/kornia/augmentation/auto/operations/ops.py
+++ b/kornia/augmentation/auto/operations/ops.py
@@ -14,6 +14,17 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
+"""Implement color and geometric operations used by automatic augmentation policies.
+
+Which class to use:
+
+- :class:`AutoContrast`, :class:`Equalize`, :class:`Contrast`, :class:`Brightness`, :class:`Hue`,
+ :class:`Saturate` and :class:`Gray` change image tone or color.
+- :class:`Invert`, :class:`Posterize`, :class:`Solarize`, :class:`SolarizeAdd` and :class:`Sharpness` change values
+ or local appearance.
+- :class:`HorizontalFlip`, :class:`VerticalFlip`, :class:`Rotate`, :class:`ShearX`, :class:`ShearY`,
+ :class:`TranslateX` and :class:`TranslateY` change image geometry.
+"""
from typing import Any, Dict, Optional, Tuple
@@ -101,14 +112,20 @@ class _PILSaturation(RandomSaturation):
class AutoContrast(OperationBase):
- """Apply auto_contrast operation.
+ """Stretch each image channel's occupied range to the full value range.
+
+ ``output = AutoContrast(probability)(input)`` stretches each selected channel's occupied range in a floating
+ ``(B, C, H, W)`` batch toward ``[0, 1]``.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Contrast` : changes contrast by blending toward the grayscale
+ mean.
+
"""
def __init__(
@@ -125,17 +142,20 @@ class AutoContrast(OperationBase):
class Brightness(OperationBase):
"""Apply PIL-style multiplicative brightness for automatic augmentation.
- Unlike :class:`~kornia.augmentation.RandomBrightness`, the factor multiplies
- the input. The policy factors match the PIL ImageEnhance convention.
+ ``output = Brightness(magnitude, probability)(input)`` multiplies selected images in a floating ``(B, C, H, W)``
+ batch by the magnitude and keeps the shape. Inputs are clamped into ``[0, 1]`` before adjustment, as are outputs;
+ use :class:`~kornia.augmentation.RandomBrightness` for additive brightness.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
initial_magnitude: the initial magnitude.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Contrast`: changes contrast rather than brightness.
+
"""
def __init__(
@@ -157,17 +177,21 @@ class Brightness(OperationBase):
class Contrast(OperationBase):
"""Apply PIL-style contrast by blending each image towards its mean grayscale value.
- Unlike :class:`~kornia.augmentation.RandomContrast`, the factor scales the
- difference from the mean rather than multiplying the input directly.
+ ``output = Contrast(magnitude, probability)(input)`` scales selected floating images ``(B, C, H, W)`` around their
+ mean. RGB inputs use the grayscale mean; other channel counts use the mean over all channels and pixels. Selected
+ inputs and outputs are clamped into ``[0, 1]``; use :class:`~kornia.augmentation.RandomContrast` for direct
+ multiplication instead.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
initial_magnitude: the initial magnitude.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Brightness`: changes brightness rather than contrast.
+
"""
def __init__(
@@ -187,16 +211,21 @@ class Contrast(OperationBase):
class Hue(OperationBase):
- """Apply hue operation.
+ """Shift hue by a policy-controlled amount.
+
+ ``output = Hue(magnitude, probability)(input)`` shifts hue in a floating RGB batch ``(B, 3, H, W)`` and keeps its
+ shape. The magnitude is a fraction of a full hue turn. Selected inputs and outputs are clamped to ``[0, 1]``.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
initial_magnitude: the initial magnitude.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Saturate`: adjusts saturation rather than hue.
+
"""
def __init__(
@@ -218,17 +247,23 @@ class Hue(OperationBase):
class Saturate(OperationBase):
"""Apply PIL-style color enhancement by blending with grayscale.
+ ``output = Saturate(magnitude, probability)(input)`` blends selected floating images ``(B, C, H, W)`` with their
+ grayscale versions. One or three channels are accepted; grayscale inputs only undergo the ``[0, 1]`` input/output
+ clamps.
+
Unlike :class:`~kornia.augmentation.RandomSaturation`, this blends RGB
values with grayscale rather than scaling HSV saturation.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
initial_magnitude: the initial magnitude.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Hue`: shifts hue rather than saturation.
+
"""
def __init__(
@@ -249,16 +284,21 @@ class Saturate(OperationBase):
# TODO: Equalize cannot update probabilities yet.
class Equalize(OperationBase):
- """Apply equalize operation.
+ """Equalize image histograms when selected by a policy probability gate.
+
+ ``output = Equalize(probability)(input)`` equalizes the histograms of selected images in a floating ``(B, C, H, W)``
+ batch and keeps its shape. Selected inputs and outputs are clamped to ``[0, 1]``.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
Note:
Equalize cannot update probabilities yet.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.AutoContrast`: stretches ranges without equalization.
+
"""
def __init__(self, initial_probability: float = 0.5, temperature: float = 0.1) -> None:
@@ -271,13 +311,19 @@ class Equalize(OperationBase):
class Gray(OperationBase):
- """Apply grayscale operation.
+ """Convert selected images to grayscale while retaining their channel layout.
+
+ ``output = Gray(probability)(input)`` replaces each selected floating image ``(B, C, H, W)`` with a channel average
+ broadcast back to all channels. RGB inputs use luminance weights; other nonempty channel counts use equal weights.
+ Values are not clamped; use :class:`Saturate` for a continuous blend toward grayscale.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Saturate`: adjusts saturation continuously.
+
"""
def __init__(self, initial_probability: float = 0.5, temperature: float = 0.1) -> None:
@@ -290,13 +336,18 @@ class Gray(OperationBase):
class Invert(OperationBase):
- """Apply invert operation.
+ """Invert selected image values around the operation's supported range.
+
+ ``output = Invert(probability)(input)`` replaces selected values with ``1 - input`` in a floating ``(B, C, H, W)``
+ batch. It preserves the shape and does not clamp values.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Solarize`: inverts values above a threshold.
+
"""
def __init__(self, initial_probability: float = 0.5, temperature: float = 0.1) -> None:
@@ -309,16 +360,22 @@ class Invert(OperationBase):
class Posterize(OperationBase):
- """Apply posterize operation.
+ """Reduce selected images to a policy-controlled number of bits.
+
+ ``output = Posterize(magnitude, probability)(input)`` reduces the retained bits of selected floating
+ ``(B, C, H, W)`` images. Selected inputs are clamped to ``[0, 1]`` and the magnitude is truncated to an integer bit
+ count.
Args:
initial_magnitude: the initial magnitude.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Solarize`: applies thresholded inversion.
+
"""
@staticmethod
@@ -343,16 +400,21 @@ class Posterize(OperationBase):
class Solarize(OperationBase):
- """Apply solarize operation.
+ """Invert values at or above a policy-controlled solarization threshold.
+
+ ``output = Solarize(magnitude, probability)(input)`` inverts values at or above the magnitude's threshold in
+ selected floating ``(B, C, H, W)`` images after clamping inputs to ``[0, 1]``.
Args:
initial_magnitude: the initial magnitude.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
- magnitude_range: the sampling range for random sampling and clamping the optimized
- symmetric_megnitude: if to randomly assign the magnitude as negative or not.magnitude.
+ initial_probability: probability of applying the operation to each image.
+ magnitude_range: the range for sampling and clamping the magnitude.
+ symmetric_megnitude: whether to assign a random sign to the magnitude.
temperature: retained for API compatibility.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Invert`: inverts all values rather than a thresholded set.
+
"""
def __init__(
@@ -372,16 +434,24 @@ class Solarize(OperationBase):
class SolarizeAdd(OperationBase):
- """Apply solarize-addition operation with a fixed thresholds of 0.5.
+ """Add an intensity offset, then invert values above a random threshold.
+
+ ``output = SolarizeAdd(magnitude, probability)(input)`` clamps selected floating images ``(B, C, H, W)`` into
+ ``[0, 1]``, adds the magnitude to every pixel, clamps again, then inverts values at or above a sampled threshold.
+ The threshold is sampled from ``[0, 1]`` per selected image. This is a known defect tracked in
+ `#6561 <https://github.com/kornia/kornia/issues/6561>`_: reference solarize-add adds only below a fixed
+ ``128 / 255`` threshold and never inverts pixels.
Args:
initial_magnitude: the initial magnitude.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Solarize`: controls the threshold without an offset.
+
"""
def __init__(
@@ -401,16 +471,23 @@ class SolarizeAdd(OperationBase):
class Sharpness(OperationBase):
- """Apply sharpness operation.
+ """Blend selected images with a smoothed copy at a policy-controlled factor.
+
+ ``output = Sharpness(magnitude, probability)(input)`` blends selected floating ``(B, C, H, W)`` images with a
+ smoothed copy. A factor of zero selects the smoothed image, one keeps the input, and larger factors sharpen;
+ selected inputs and outputs are clamped into ``[0, 1]``. Height and width must be at least three pixels when the
+ operation runs.
Args:
initial_magnitude: the initial magnitude.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.Contrast`: changes contrast rather than sharpness.
+
"""
def __init__(
@@ -430,13 +507,18 @@ class Sharpness(OperationBase):
class HorizontalFlip(OperationBase):
- """Apply horizontal flip operation.
+ """Reverse image columns with a policy probability gate.
+
+ ``output = HorizontalFlip(probability)(input)`` reverses columns of selected floating ``(B, C, H, W)`` images,
+ preserving shape and pixel values.
Args:
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.VerticalFlip`: reverses image rows.
+
"""
def __init__(self, initial_probability: float = 0.5, temperature: float = 0.1) -> None:
@@ -449,12 +531,18 @@ class HorizontalFlip(OperationBase):
class VerticalFlip(OperationBase):
- """Apply vertical flip operation.
+ """Reverse image rows with a policy probability gate.
+
+ ``output = VerticalFlip(probability)(input)`` reverses rows of selected floating ``(B, C, H, W)`` images, preserving
+ shape and pixel values.
Args:
- initial_magnitude: the initial magnitude.
+ initial_probability: probability of applying the operation to each image.
temperature: retained for API compatibility.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.HorizontalFlip`: reverses image columns.
+
"""
def __init__(self, initial_probability: float = 0.5, temperature: float = 0.1) -> None:
@@ -467,16 +555,22 @@ class VerticalFlip(OperationBase):
class Rotate(OperationBase):
- """Apply rotate operation.
+ """Rotate selected images by a policy-controlled angle.
+
+ ``output = Rotate(magnitude, probability)(input)`` rotates selected floating ``(B, C, H, W)`` images about their
+ centers, keeping the output size. The magnitude is in degrees with a random sign by default.
Args:
initial_magnitude: the initial magnitude.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.ShearX`: shears along the x axis.
+ - :class:`~kornia.augmentation.auto.operations.ops.ShearY`: shears along the y axis.
+
"""
def __init__(
@@ -501,20 +595,25 @@ class Rotate(OperationBase):
class ShearX(OperationBase):
- """Apply shear operation along x-axis.
+ """Shear selected images along the x axis by a policy-controlled amount.
+
+ ``output = ShearX(magnitude, probability)(input)`` shears selected floating ``(B, C, H, W)`` images along x, keeping
+ the output size. The magnitude is a shear factor with a random sign by default.
The magnitude is the shear factor, as in PIL and torchvision, whether it is sampled from ``magnitude_range``,
- learned, or passed to :meth:`forward_parameters`. It is mapped to the wrapped augmentation's degrees with
+ learned, or passed to ``forward_parameters``. It is mapped to the wrapped augmentation's degrees with
``rad2deg(atan(magnitude))``, so a magnitude of ``0.3`` shears by about ``16.7`` degrees.
Args:
initial_magnitude: the initial magnitude, a shear factor.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.ShearY`: shears along the y axis.
+
"""
@staticmethod
@@ -546,20 +645,25 @@ class ShearX(OperationBase):
class ShearY(OperationBase):
- """Apply shear operation along y-axis.
+ """Shear selected images along the y axis by a policy-controlled amount.
+
+ ``output = ShearY(magnitude, probability)(input)`` shears selected floating ``(B, C, H, W)`` images along y, keeping
+ the output size. The magnitude is a shear factor with a random sign by default.
The magnitude is the shear factor, as in PIL and torchvision, whether it is sampled from ``magnitude_range``,
- learned, or passed to :meth:`forward_parameters`. It is mapped to the wrapped augmentation's degrees with
+ learned, or passed to ``forward_parameters``. It is mapped to the wrapped augmentation's degrees with
``rad2deg(atan(magnitude))``, so a magnitude of ``0.3`` shears by about ``16.7`` degrees.
Args:
initial_magnitude: the initial magnitude, a shear factor.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.ShearX`: shears along the x axis.
+
"""
@staticmethod
@@ -596,20 +700,24 @@ class ShearY(OperationBase):
class TranslateX(OperationBase):
- """Apply translate operation along x-axis.
+ """Translate selected images along the x axis by a policy-controlled amount.
- The magnitude is a fraction of the image width, whether it is sampled from ``magnitude_range``,
- learned, or passed to :meth:`forward_parameters`; the wrapped augmentation translates by that fraction
- of the width in pixels.
+ ``output = TranslateX(magnitude, probability)(input)`` shifts selected floating ``(B, C, H, W)`` images
+ horizontally, keeping the output size. The magnitude is a fraction of image width with a random sign by default.
+
+ The magnitude is a fraction of the image width, whether it is sampled from ``magnitude_range``, learned, or passed
+ to ``forward_parameters``; the wrapped augmentation translates by that fraction of the width in pixels.
Args:
initial_magnitude: the initial magnitude, a fraction of the image width.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.TranslateY`: translates along the y axis.
+
"""
def __init__(
@@ -649,20 +757,24 @@ class TranslateX(OperationBase):
class TranslateY(OperationBase):
- """Apply translate operation along y-axis.
+ """Translate selected images along the y axis by a policy-controlled amount.
- The magnitude is a fraction of the image height, whether it is sampled from ``magnitude_range``,
- learned, or passed to :meth:`forward_parameters`; the wrapped augmentation translates by that fraction
- of the height in pixels.
+ ``output = TranslateY(magnitude, probability)(input)`` shifts selected floating ``(B, C, H, W)`` images vertically,
+ keeping the output size. The magnitude is a fraction of image height with a random sign by default.
+
+ The magnitude is a fraction of the image height, whether it is sampled from ``magnitude_range``, learned, or
+ passed to ``forward_parameters``; the wrapped augmentation translates by that fraction of the height in pixels.
Args:
initial_magnitude: the initial magnitude, a fraction of the image height.
- initial_probability: the initial probability. If None, the augmentation will be randomly
- applied according to he augmentation sampling range.
+ initial_probability: probability of applying the operation to each image.
magnitude_range: the sampling range for random sampling and clamping the optimized magnitude.
temperature: retained for API compatibility.
symmetric_megnitude: if to randomly assign the magnitude as negative or not.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.ops.TranslateX`: translates along the x axis.
+
"""
def __init__(
diff --git a/kornia/augmentation/auto/operations/policy.py b/kornia/augmentation/auto/operations/policy.py
index ecc074f8e..736d255f9 100644
--- a/kornia/augmentation/auto/operations/policy.py
+++ b/kornia/augmentation/auto/operations/policy.py
@@ -31,7 +31,11 @@ from kornia.core.utils import is_exporting
class PolicySequential(TransformMatrixMinIn, ImageSequentialBase):
- """Policy tuple for applying multiple operations.
+ """Apply one ordered sub-policy of automatic augmentation operations.
+
+ ``output = PolicySequential(*operations)(input)`` applies the wrapped operations in order and records their
+ parameters for replay. Use :class:`~kornia.augmentation.auto.AutoAugment` to sample one of a searched policy's
+ sub-policies.
Convention:
- accepts only :class:`~kornia.augmentation.auto.operations.OperationBase` children. Generated parameters
@@ -41,14 +45,17 @@ class PolicySequential(TransformMatrixMinIn, ImageSequentialBase):
replay the same operations through ``forward(input, params=...)``.
- its transformation matrix is the ordered product of its geometric wrapped operations. Intensity
operations do not contribute to that matrix.
- - ``forward_parameters`` samples each child through
- :meth:`~kornia.augmentation.auto.operations.OperationBase.forward_parameters`, so the operation's
- magnitude, magnitude mapping and symmetric sign apply; the gate comes from the wrapped augmentation's
- ``p``.
+ - ``forward_parameters`` uses :meth:`~kornia.augmentation.auto.operations.OperationBase.forward_parameters`
+ for each child, so the operation's magnitude, magnitude mapping and symmetric sign apply; the gate comes
+ from the wrapped augmentation's ``p`` and ``p_batch``.
Args:
operations: the operations to perform, passed as positional arguments rather than as one list.
+ See Also:
+ - :class:`~kornia.augmentation.auto.operations.OperationBase`: wraps an individual policy operation.
+ - :class:`~kornia.augmentation.auto.AutoAugment`: selects from a fixed searched policy.
+
"""
def __init__(self, *operations: OperationBase) -> None:
diff --git a/kornia/augmentation/auto/rand_augment/rand_augment.py b/kornia/augmentation/auto/rand_augment/rand_augment.py
index d842b6887..9b0b26523 100644
--- a/kornia/augmentation/auto/rand_augment/rand_augment.py
+++ b/kornia/augmentation/auto/rand_augment/rand_augment.py
@@ -49,7 +49,14 @@ default_policy: List[SUBPOLICY_CONFIG] = [
class RandAugment(PolicyAugmentBase):
- """Apply RandAugment :cite:`cubuk2020randaugment` augmentation strategies.
+ """Sample a fixed number of RandAugment operations at one global magnitude.
+
+ ``output = RandAugment(n, m)(input)`` draws ``n`` operations from the supported pool and applies them in draw
+ order with magnitude ``m`` to a floating ``(B, C, H, W)`` image batch. Use
+ :class:`~kornia.augmentation.auto.AutoAugment` for a fixed searched sub-policy, or
+ :class:`~kornia.augmentation.auto.TrivialAugment` for one operation.
+
+ The policy follows :cite:`cubuk2020randaugment`.
See the Convention block on :class:`~kornia.augmentation.auto.PolicyAugmentBase`.
@@ -80,6 +87,10 @@ class RandAugment(PolicyAugmentBase):
contributes a matrix (an intensity operation the identity), so none is rejected.
If `skip`, transformation matrix will be totally ignored.
+ See Also:
+ - :class:`~kornia.augmentation.auto.AutoAugment`: chooses a searched, dataset-specific sub-policy.
+ - :class:`~kornia.augmentation.auto.TrivialAugment`: chooses a single operation.
+
Examples:
>>> import torch
>>> import kornia.augmentation as K
diff --git a/kornia/augmentation/auto/trivial_augment/trivial_augment.py b/kornia/augmentation/auto/trivial_augment/trivial_augment.py
index 79caa4ff3..c14d2151d 100644
--- a/kornia/augmentation/auto/trivial_augment/trivial_augment.py
+++ b/kornia/augmentation/auto/trivial_augment/trivial_augment.py
@@ -46,7 +46,10 @@ default_policy: List[SUBPOLICY_CONFIG] = [
class TrivialAugment(PolicyAugmentBase):
- """Apply TrivialAugment :cite:`muller2021trivialaugment` augmentation strategies.
+ """Sample one TrivialAugment operation for an image batch.
+
+ ``output = TrivialAugment()(input)`` selects one operation for a floating ``(B, C, H, W)`` image batch and draws
+ its magnitude per image, if it has one. The policy follows :cite:`muller2021trivialaugment`.
See the Convention block on :class:`~kornia.augmentation.auto.PolicyAugmentBase`.
@@ -54,8 +57,8 @@ class TrivialAugment(PolicyAugmentBase):
- selects one candidate sub-policy uniformly for each forward call. Each candidate holds one operation
whose probability is fixed at ``1``, so the selected operation is applied to every row and no
probability is sampled; a candidate's second and third entries are its magnitude range, not a
- probability, unlike :class:`~kornia.augmentation.auto.AutoAugment`. Only the magnitude is drawn
- independently for every batch row.
+ probability, unlike :class:`~kornia.augmentation.auto.AutoAugment`. For an operation with a magnitude, that
+ magnitude is drawn independently for every batch row.
- the operation wrapper's magnitude mapping applies, as under
:class:`~kornia.augmentation.auto.RandAugment`. A ``("rotate", -30, 30)`` candidate draws angles in
``[-30, 30]`` with a random sign, and ``("shear_x", -0.3, 0.3)`` shears by up to ``rad2deg(atan(0.3))``,
@@ -73,6 +76,10 @@ class TrivialAugment(PolicyAugmentBase):
contributes a matrix (an intensity operation the identity), so none is rejected.
If `skip`, transformation matrix will be totally ignored.
+ See Also:
+ - :class:`~kornia.augmentation.auto.RandAugment`: samples a configurable number of operations.
+ - :class:`~kornia.augmentation.auto.AutoAugment`: chooses from searched dataset policies.
+
Examples:
>>> import torch
>>> import kornia.augmentation as K
diff --git a/kornia/augmentation/container/augment.py b/kornia/augmentation/container/augment.py
index 9bf3aa296..ed012713e 100644
--- a/kornia/augmentation/container/augment.py
+++ b/kornia/augmentation/container/augment.py
@@ -81,7 +81,14 @@ _VOLUME_BATCH_SHAPES = "either (D, H, W) or (B, C, D, H, W)"
class AugmentationSequential(TransformMatrixMinIn, ImageSequential):
- r"""AugmentationSequential for handling multiple input types like inputs, masks, keypoints at once.
+ r"""Augment aligned images, masks, boxes, keypoints and labels with one parameter draw.
+
+ ``augmented = AugmentationSequential(*transforms, data_keys=keys)(*inputs)`` applies each selected child to the
+ aligned positional inputs and returns them in the same order. ``data_keys`` supports images, masks, boxes,
+ keypoints and class labels; inversion only reverses supported geometric children, so it is not generally a lossless
+ round trip. It records the selected children and their sampled parameters in ``_params`` for replay; use
+ :class:`~kornia.augmentation.container.ImageSequential` for an image tensor alone, or
+ :class:`~kornia.augmentation.container.VideoSequential` for a video tensor alone.
.. image:: _static/img/AugmentationSequential.png
@@ -164,7 +171,7 @@ class AugmentationSequential(TransformMatrixMinIn, ImageSequential):
fill value) and come back in their own dtype. Floating masks use the image's working dtype; integer
masks use at least float32 (float64 with a float64 image). Integer labels not exactly representable
in that working dtype raise ``RuntimeError`` instead of being rounded, unless checks are disabled
- (:func:`~kornia.core.check.disable_checks`, ``python -O`` or ``KORNIA_CHECKS=0``). On accelerators an
+ (``kornia.core.check.disable_checks``, ``python -O`` or ``KORNIA_CHECKS=0``). On accelerators an
asynchronous assertion may report by the next synchronization; MPS before torch 2.13 checks on the host.
- a ``mask`` list contains one tensor per image sample, in sample order. Each entry is
``(H, W)``, ``(C, H, W)`` or ``(1, C, H, W)``, with matching spatial dimensions; channel counts
@@ -172,7 +179,7 @@ class AugmentationSequential(TransformMatrixMinIn, ImageSequential):
nested sequences, auto-augment policies, replay and inverse. Full-batch mask tensors must use
separate ``mask`` data keys; a list with incompatible length or entry shape raises ``ValueError``,
also in an inverse without an image. Video, mix and 3D children, and a geometric
- :class:`~kornia.augmentation.PatchSequential`, do not support mask lists and raise
+ :class:`~kornia.augmentation.container.PatchSequential`, do not support mask lists and raise
``NotImplementedError``. Inverse warps can only approximately restore resampled pixels and
cannot recover pixels moved out of the frame.
- the ``mask``, box and ``keypoints`` handlers of a geometric child, or of a custom
@@ -213,6 +220,10 @@ class AugmentationSequential(TransformMatrixMinIn, ImageSequential):
.. note::
See a working example `here <https://www.kornia.org/tutorials/nbs/data_augmentation_sequential.html>`__.
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: chains transforms for an image tensor only.
+ - :class:`~kornia.augmentation.container.VideoSequential`: chains transforms for a video tensor only.
+
Examples:
>>> import kornia
>>> input = torch.randn(2, 3, 5, 6)
diff --git a/kornia/augmentation/container/base.py b/kornia/augmentation/container/base.py
index 050222127..2a2076907 100644
--- a/kornia/augmentation/container/base.py
+++ b/kornia/augmentation/container/base.py
@@ -15,6 +15,15 @@
# limitations under the License.
#
+"""Extend sequential augmentation containers with child settings and data handlers.
+
+Which class to use:
+
+- ``BasicSequentialBase`` names child modules and stores the recorded parameter list.
+- ``SequentialBase`` propagates batch and output-shape settings to compatible children.
+- ``ImageSequentialBase`` provides image, mask, box and keypoint dispatch methods for concrete containers.
+"""
+
from collections import OrderedDict
from itertools import zip_longest
from typing import Any, Dict, Iterator, List, Optional, Tuple
@@ -41,11 +50,20 @@ __all__ = ["BasicSequentialBase", "ImageSequentialBase", "SequentialBase"]
class BasicSequentialBase(nn.Sequential):
- r"""BasicSequential for creating kornia modulized processing pipeline.
+ r"""Provide child naming and recorded parameters for Kornia sequential containers.
+
+ Subclasses construct ``BasicSequentialBase(*modules)`` and use its named children with a list of
+ :class:`~kornia.augmentation.container.params.ParamItem` records. Use
+ :class:`~kornia.augmentation.container.ImageSequential` or
+ :class:`~kornia.augmentation.container.AugmentationSequential` as an application-facing container.
Args:
*args : a list of kornia augmentation and image operation modules.
+ See Also:
+ - :class:`~kornia.augmentation.container.base.SequentialBase`: adds sequence-wide child settings.
+ - :class:`~kornia.augmentation.container.ImageSequential`: is the public image-only container.
+
"""
def __init__(self, *args: nn.Module) -> None:
@@ -161,7 +179,11 @@ class BasicSequentialBase(nn.Sequential):
class SequentialBase(BasicSequentialBase):
- r"""SequentialBase for creating kornia modulized processing pipeline.
+ r"""Propagate batch and shape flags through a Kornia sequential container.
+
+ A subclass constructs ``SequentialBase(*modules, same_on_batch=..., keepdim=...)``; the supplied non-``None``
+ flags override compatible child augmentations, including nested sequential containers. Use
+ :class:`~kornia.augmentation.container.ImageSequential` to process an image tensor.
Args:
*args : a list of kornia augmentation and image operation modules.
@@ -170,6 +192,10 @@ class SequentialBase(BasicSequentialBase):
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False). If None, it will not overwrite the function-wise settings.
+ See Also:
+ - :class:`~kornia.augmentation.container.base.BasicSequentialBase`: provides child and parameter bookkeeping.
+ - :class:`~kornia.augmentation.container.base.ImageSequentialBase`: supplies data-type-specific operations.
+
"""
def __init__(self, *args: nn.Module, same_on_batch: Optional[bool] = None, keepdim: Optional[bool] = None) -> None:
@@ -237,10 +263,16 @@ class SequentialBase(BasicSequentialBase):
class ImageSequentialBase(SequentialBase):
- """Provide a base class for sequential image-only augmentations.
+ """Define image, mask, box and keypoint operations for a sequential container.
+
+ Subclasses provide child selection and parameter sampling; these methods apply the resulting parameter records to
+ their corresponding data type. Use :class:`~kornia.augmentation.container.AugmentationSequential` for public
+ multi-input augmentation, or :class:`~kornia.augmentation.container.ImageSequential` for images only.
+
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: processes image tensors through its children.
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: applies the operations to aligned data types.
- This class handles the logic for applying a series of transformations
- sequentially to input tensors while managing the transformation matrices.
"""
def identity_matrix(self, input: torch.Tensor) -> torch.Tensor:
diff --git a/kornia/augmentation/container/dispatcher.py b/kornia/augmentation/container/dispatcher.py
index 10a11fe58..36194ba70 100644
--- a/kornia/augmentation/container/dispatcher.py
+++ b/kornia/augmentation/container/dispatcher.py
@@ -45,7 +45,12 @@ def _fill_missing_augmentation_state(
class ManyToManyAugmentationDispather(nn.Module):
- r"""Dispatches different augmentations to different inputs element-wisely.
+ r"""Run one augmentation container for each matching input bundle.
+
+ ``outputs = ManyToManyAugmentationDispather(*augmentations)(*bundles)`` pairs each
+ :class:`~kornia.augmentation.container.AugmentationSequential` with the bundle at the same position and returns
+ its result. Use :class:`~kornia.augmentation.container.ManyToOneAugmentationDispather` to run several containers
+ over one shared bundle.
See the Convention block on :class:`~kornia.augmentation.container.AugmentationSequential`.
@@ -59,6 +64,10 @@ class ManyToManyAugmentationDispather(nn.Module):
of bundles raises ``ValueError`` before any augmentation runs. Each augmentation draws its own
parameters, so the members are independent of one another.
+ See Also:
+ - :class:`~kornia.augmentation.container.ManyToOneAugmentationDispather`: gives every container one bundle.
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: augments an aligned data bundle.
+
Examples:
>>> import torch
>>> input_1, input_2 = torch.randn(2, 3, 5, 6), torch.randn(2, 3, 5, 6)
@@ -113,7 +122,11 @@ class ManyToManyAugmentationDispather(nn.Module):
class ManyToOneAugmentationDispather(nn.Module):
- r"""Dispatches different augmentations to a single input and returns a list.
+ r"""Run several augmentation containers independently over one input bundle.
+
+ ``outputs = ManyToOneAugmentationDispather(*augmentations)(*inputs)`` gives the same inputs to every
+ :class:`~kornia.augmentation.container.AugmentationSequential` and returns one result per container. Use
+ :class:`~kornia.augmentation.container.ManyToManyAugmentationDispather` to pair containers and bundles.
See the Convention block on :class:`~kornia.augmentation.container.AugmentationSequential`.
@@ -130,6 +143,10 @@ class ManyToOneAugmentationDispather(nn.Module):
- with ``strict=True``, the default, the members must all declare the same ``data_keys``; a mismatch
raises ``RuntimeError`` at construction.
+ See Also:
+ - :class:`~kornia.augmentation.container.ManyToManyAugmentationDispather`: pairs containers with bundles.
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: augments an aligned data bundle.
+
Examples:
>>> import torch
>>> input = torch.randn(2, 3, 5, 6)
diff --git a/kornia/augmentation/container/image.py b/kornia/augmentation/container/image.py
index e7f88a48f..4af38fc2e 100644
--- a/kornia/augmentation/container/image.py
+++ b/kornia/augmentation/container/image.py
@@ -56,7 +56,12 @@ class ImageModuleForSequentialMixIn(ImageModuleMixIn):
class ImageSequential(ImageSequentialBase, ImageModuleForSequentialMixIn):
- r"""nn.Sequential for creating kornia image processing pipeline.
+ r"""Chain image augmentations and image-processing modules on one image tensor.
+
+ ``output = ImageSequential(*modules)(input)`` runs selected children on an image tensor and stores their order and
+ sampled Kornia augmentation parameters in ``_params`` for replay. Ordinary ``nn.Module`` children also run,
+ but their internal randomness is not recorded; use :class:`~kornia.augmentation.container.AugmentationSequential`
+ when masks, boxes or keypoints must receive the matching geometric transform.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
@@ -105,6 +110,11 @@ class ImageSequential(ImageSequentialBase, ImageModuleForSequentialMixIn):
The output cache retains a detached reference to the last tensor output and is omitted when pickled.
Setting ``disable_features = True`` clears it.
+ See Also:
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: also transforms aligned masks and annotations.
+ - :class:`~kornia.augmentation.container.PatchSequential`: runs transforms on a regular patch grid.
+ - :class:`~kornia.augmentation.container.VideoSequential`: runs transforms on videos.
+
Examples:
>>> _ = torch.manual_seed(77)
>>> import kornia
diff --git a/kornia/augmentation/container/params.py b/kornia/augmentation/container/params.py
index b138609ae..98335492b 100644
--- a/kornia/augmentation/container/params.py
+++ b/kornia/augmentation/container/params.py
@@ -14,6 +14,13 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
+"""Record selections and parameter draws made by sequential augmentation containers.
+
+Which class to use:
+
+- ``ParamItem`` stores the child name and its parameter data.
+- ``PatchParamItem`` adds the patch indices for a patch-level operation.
+"""
from typing import Dict, List, NamedTuple, Optional, Union
@@ -23,11 +30,19 @@ __all__ = ["ParamItem", "PatchParamItem"]
class ParamItem(NamedTuple):
- """Store the parameters for a single augmentation operation.
+ """Record the selected child and sampled parameters of one sequential operation.
+
+ Sequential containers create ``ParamItem(name, data)`` records in ``_params``; passing that list back through
+ ``params=`` replays the recorded selection and parameters. Use ``PatchParamItem`` when the record also needs patch
+ indices.
Attributes:
name: The name of the augmentation operation.
data: The dictionary of parameters or a list of nested parameters.
+
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: records these items when it runs children.
+
"""
name: str
@@ -35,11 +50,19 @@ class ParamItem(NamedTuple):
class PatchParamItem(NamedTuple):
- """Store parameters for patch-based augmentation operations.
+ """Record the patch indices and parameters for one patch-sequence operation.
+
+ :class:`~kornia.augmentation.container.PatchSequential` uses ``PatchParamItem(indices, param)`` to replay a
+ child on the same patch locations. Use ``ParamItem`` for a non-patch sequence.
Attributes:
indices: The list of patch indices where the augmentation is applied.
- param: The specific :class:`ParamItem` containing the operation parameters.
+ param: The specific :class:`~kornia.augmentation.container.params.ParamItem` containing the operation
+ parameters.
+
+ See Also:
+ - :class:`~kornia.augmentation.container.PatchSequential`: creates these patch-specific records.
+
"""
indices: List[int]
diff --git a/kornia/augmentation/container/patch.py b/kornia/augmentation/container/patch.py
index 116499b07..cfdf79ad4 100644
--- a/kornia/augmentation/container/patch.py
+++ b/kornia/augmentation/container/patch.py
@@ -59,24 +59,23 @@ def _patch_indices(indices: Union[List[int], torch.Tensor], device: torch.device
class PatchSequential(ImageSequential):
- r"""Container for performing patch-level image data augmentation.
+ r"""Apply image transforms independently to a regular grid of image patches.
+
+ ``output = PatchSequential(*modules, grid_size=...)(input)`` splits each image into a grid, runs the configured
+ children on the patch batch, then joins the patches.
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
.. image:: _static/img/PatchSequential.png
- PatchSequential breaks input images into patches by a given grid size, which will be resembled back
- afterwards.
-
- Different image processing and augmentation methods will be performed on each patch region as
- in :cite:`lin2021patch`.
+ Processing runs on each patch region as in :cite:`lin2021patch`.
Args:
*args: a list of processing modules.
grid_size: positive ``(rows, columns)`` of patches in each image.
padding: ``"same"`` temporarily zero-pads to a multiple of ``grid_size`` and removes the added
border after augmentation, preserving the input spatial size. ``"valid"`` crops the remainder
- before augmentation and keeps the cropped spatial size. Padding and cropping are centred;
+ before augmentation and keeps the cropped spatial size. Padding and cropping are centered;
an odd extra pixel is placed on the right or bottom. Both modes preserve the batch size.
Geometric transforms can move the temporary zero border into the retained image; removing
the added border does not undo that movement.
@@ -125,6 +124,10 @@ class PatchSequential(ImageSequential):
(`pytorch/pytorch#198270 <https://github.com/pytorch/pytorch/issues/198270>`__). Eager execution,
the ``aot_eager`` backend and torch 2.15 or later are not affected.
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: applies its child sequence to whole images.
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: transforms images with aligned annotations.
+
Examples:
>>> import kornia.augmentation as K
>>> input = torch.randn(2, 3, 224, 224)
diff --git a/kornia/augmentation/container/video.py b/kornia/augmentation/container/video.py
index 86a299c72..13dd31d41 100644
--- a/kornia/augmentation/container/video.py
+++ b/kornia/augmentation/container/video.py
@@ -40,19 +40,19 @@ __all__ = ["VideoSequential"]
class VideoSequential(ImageSequential):
- r"""VideoSequential for processing 5-dim video data like (B, T, C, H, W) and (B, C, T, H, W).
+ r"""Apply an image augmentation sequence to a video while optionally sharing draws across frames.
- See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
+ ``output = VideoSequential(*modules, data_format=...)(video)`` accepts ``(B, T, C, H, W)`` by default or
+ ``(B, C, T, H, W)`` with ``data_format="BCTHW"``, flattens it for the child modules, then restores that layout.
+ ``same_on_frame=True`` shares supported augmentation draws across each clip's frames; use
+ :class:`~kornia.augmentation.container.AugmentationSequential` to transform a video with aligned annotations.
- `VideoSequential` is used to replace `nn.Sequential` for processing video data augmentations.
- By default, `VideoSequential` enabled `same_on_frame` to make sure the same augmentations happen
- across temporal dimension. Meanwhile, it will not affect other augmentation behaviours like the
- settings on `same_on_batch`, etc.
+ See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
Args:
*args: a list of augmentation module.
data_format: only BCTHW and BTCHW are supported.
- same_on_frame: apply the same transformation across the channel per frame.
+ same_on_frame: share each clip's sampled transform parameters across its temporal frames.
random_apply: randomly select a sublist (order agnostic) of args to
apply transformation.
If int, a fixed number of transformations will be selected.
@@ -66,17 +66,19 @@ class VideoSequential(ImageSequential):
- the input is 5-dimensional and the layout is named by ``data_format``, which accepts ``"BTCHW"``
(the default) and ``"BCTHW"``, case-insensitively; any other spelling raises ``AssertionError``.
The output keeps the input layout.
- - ``same_on_frame`` is ``True`` by default, so one draw is shared by every frame of a clip and the
- clip stays temporally consistent. With ``same_on_frame=False`` each frame is drawn independently.
+ - ``same_on_frame`` is ``True`` by default, so supported Kornia augmentation parameters are shared by every
+ frame of a clip. With ``same_on_frame=False`` each frame draws parameters independently. It does not
+ synchronize randomness inside ordinary ``nn.Module`` children such as ``Dropout``. Nested
+ :class:`ImageSequential` and other ``SequentialBase`` children require ``same_on_frame=False``.
- like :class:`~kornia.augmentation.container.ImageSequential`, this container takes image tensors only: it has
no ``data_keys`` and no ``.transform_matrix`` attribute. Register a ``VideoSequential`` as a child of
:class:`~kornia.augmentation.container.AugmentationSequential` to augment video masks, boxes and keypoints
alongside the clip. For video boxes, use ``bbox`` vertices with shape ``(B, T, N, 4, 2)``;
coordinate keys ``bbox_xyxy`` and ``bbox_xywh`` do not accept ``(B, T, N, 4)`` tensors.
- Note:
- Transformation matrix returned only considers the transformation applied in ``kornia.augmentation`` module.
- Those transformations in ``kornia.geometry`` will not be taken into account.
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: applies the same kind of sequence to images.
+ - :class:`~kornia.augmentation.container.AugmentationSequential`: transforms a video with aligned annotations.
Example:
If set `same_on_frame` to True, we would expect the same augmentation has been applied to each
diff --git a/kornia/augmentation/utils/__init__.py b/kornia/augmentation/utils/__init__.py
index 813bdd076..efe57ed6d 100644
--- a/kornia/augmentation/utils/__init__.py
+++ b/kornia/augmentation/utils/__init__.py
@@ -15,9 +15,9 @@
# limitations under the License.
#
-"""Kornia Augmentation Utils β€” Helper functions and utilities for augmentations.
+"""Provide internal helpers for augmentation validation, sampling and tensor layouts.
-This subpackage provides internal helpers and utility functions for augmentation modules.
+These implementation utilities are not a stable public API.
"""
from kornia.augmentation.utils.helpers import (
diff --git a/kornia/augmentation/utils/helpers.py b/kornia/augmentation/utils/helpers.py
index 6f8dfdfbd..052b30b0b 100644
--- a/kornia/augmentation/utils/helpers.py
+++ b/kornia/augmentation/utils/helpers.py
@@ -501,9 +501,14 @@ def _shape_validation(param: torch.Tensor, shape: Union[Tuple[int, ...], List[in
def deepcopy_dict(params: Dict[str, Any]) -> Dict[str, Any]:
- """Perform deep copy on any dict.
+ """Copy an augmentation parameter dictionary while cloning tensor values.
+
+ ``copied = deepcopy_dict(params)`` returns a new dictionary whose tensor values are ``clone()`` copies; non-tensor
+ values are kept by reference. Use ``override_parameters`` to copy and replace selected entries.
+
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: stores parameter dictionaries for replay.
- Support torch.Tensor copying here.
"""
out = {}
for k, v in params.items():
@@ -521,15 +526,22 @@ def override_parameters(
if_none_exist: str = "ignore",
in_place: bool = False,
) -> Dict[str, Any]:
- """Override params dict w.r.t params_override.
+ """Replace selected entries of an augmentation parameter dictionary.
+
+ ``updated = override_parameters(params, params_override)`` returns a copied dictionary with every supplied key
+ replaced, unless ``in_place=True``. With no override it returns ``params`` itself; use ``deepcopy_dict`` when a
+ new dictionary with cloned tensor values is needed without replacement. Cloning preserves autograd history;
+ non-tensor values remain shared.
Args:
params: source parameters.
params_override: key-values to override the source parameters.
- if_none_exist: behaviour if the key in `params_override` does not exist in `params`.
- 'raise' | 'ignore'.
+ if_none_exist: currently unused; every override key is inserted, including keys absent from ``params``.
in_place: if to override in-place or not.
+ See Also:
+ - :class:`~kornia.augmentation.container.ImageSequential`: accepts recorded parameter lists for replay.
+
"""
# Nothing to override (None or an empty kwargs dict β€” the common forward path): return the
# params untouched. This skips a per-call `deepcopy_dict` (a full tensor clone of every
diff --git a/testing/docstring_rollout.py b/testing/docstring_rollout.py
index 51ab773aa..1e9548f9f 100644
--- a/testing/docstring_rollout.py
+++ b/testing/docstring_rollout.py
@@ -52,7 +52,19 @@ EXCLUDED_PACKAGES: dict[str, str] = {
}
"""Top-level packages left out of the rollout, with the reason."""
+CATALOG_EXCEPTIONS: dict[str, str] = {
+ "kornia.augmentation.utils": (
+ "internal augmentation helpers; __all__ supports implementation imports, not a public API catalog"
+ ),
+}
+"""Namespaces intentionally omitted from public catalogs, with a reason; exports remain unchanged."""
+
CATALOG_NAMESPACES: tuple[str, ...] = (
+ "kornia.augmentation",
+ "kornia.augmentation.auto",
+ "kornia.augmentation.auto.operations.ops",
+ "kornia.augmentation.container.base",
+ "kornia.augmentation.container.params",
"kornia.feature",
"kornia.feature.dedode.transformer",
"kornia.geometry.bbox",
@@ -90,6 +102,7 @@ CATALOG_NAMESPACES: tuple[str, ...] = (
"""Namespaces whose module docstring must name every export in ``__all__``."""
DOCSTRING_MODULES: tuple[str, ...] = (
+ "kornia.augmentation",
"kornia.feature.adalam",
"kornia.feature.affine_shape",
"kornia.feature.aliked",
diff --git a/tests/test_docstring_style.py b/tests/test_docstring_style.py
index 49f85f4b8..a22b576ee 100644
--- a/tests/test_docstring_style.py
+++ b/tests/test_docstring_style.py
@@ -51,6 +51,7 @@ import pytest
import kornia
from testing.docstring_rollout import (
+ CATALOG_EXCEPTIONS,
CATALOG_NAMESPACES,
DOCSTRING_MODULES,
EXCLUDED_PACKAGES,
@@ -151,6 +152,7 @@ def test_rollout_lists_are_real() -> None:
lists = {
"DOCSTRING_MODULES": DOCSTRING_MODULES,
"CATALOG_NAMESPACES": CATALOG_NAMESPACES,
+ "CATALOG_EXCEPTIONS": CATALOG_EXCEPTIONS,
}
for list_name, entries in lists.items():
for entry in entries:
@@ -162,6 +164,10 @@ def test_rollout_lists_are_real() -> None:
importlib.import_module(entry)
for entry in CATALOG_NAMESPACES:
assert hasattr(importlib.import_module(entry), "__all__"), f"CATALOG_NAMESPACES entry {entry!r} has no __all__"
+ for entry, reason in CATALOG_EXCEPTIONS.items():
+ assert entry not in CATALOG_NAMESPACES, f"{entry!r} is both catalogued and excepted"
+ assert reason.strip(), f"CATALOG_EXCEPTIONS entry {entry!r} needs a reason"
+ assert catalog_required(entry, CATALOG_NAMESPACES), f"{entry!r} no longer needs a catalog exception"
converted = {qualified for qualified, _ in CONVERTED}
for key, reason in SEE_ALSO_EXCEPTIONS.items():
assert key in converted, f"SEE_ALSO_EXCEPTIONS key {key!r} is not a converted object"
@@ -302,11 +308,19 @@ def test_rollout_progress() -> None:
"""Print, per in-scope package, the converted objects and catalogued namespaces (read it with ``-s``)."""
objects = [obj for obj, _ in rollout_objects(REGISTRY).values()]
namespaces = modules_declaring_all()
- print("\npackage converted objects catalogued namespaces")
+ print("\npackage converted objects catalogued namespaces excepted namespaces")
for package in IN_SCOPE_PACKAGES:
prefix = f"kornia.{package}"
in_package = [obj for obj in objects if covered(obj.__module__, [prefix])]
done = [obj for obj in in_package if covered(obj.__module__, DOCSTRING_MODULES)]
- required = [ns for ns in namespaces if covered(ns, [prefix]) and catalog_required(ns, CATALOG_NAMESPACES)]
+ excepted = [ns for ns in CATALOG_EXCEPTIONS if covered(ns, [prefix])]
+ required = [
+ ns
+ for ns in namespaces
+ if ns not in CATALOG_EXCEPTIONS and covered(ns, [prefix]) and catalog_required(ns, CATALOG_NAMESPACES)
+ ]
catalogued = [ns for ns in required if ns in CATALOG_NAMESPACES]
- print(f"{package:<14} {len(done):>4} / {len(in_package):<12} {len(catalogued):>4} / {len(required)}")
+ print(
+ f"{package:<14} {len(done):>4} / {len(in_package):<12} "
+ f"{len(catalogued):>4} / {len(required):<18} {len(excepted)}"
+ )
diff --git a/tests/test_docstring_style_helpers.py b/tests/test_docstring_style_helpers.py
index fa6006204..5d123b267 100644
--- a/tests/test_docstring_style_helpers.py
+++ b/tests/test_docstring_style_helpers.py
@@ -213,7 +213,8 @@ def test_only_func_and_meth_drop_parentheses():
def test_short_names_need_a_documented_object():
- reg = _registry()
+ # Keep this object deliberately unregistered even as the real documentation grows.
+ reg = {name: obj for name, obj in _registry().items() if obj is not AutoContrast}
assert is_documented(depth_to_3d, reg)
assert not is_documented(AutoContrast, reg)
# With no page, and so no scope, only a full name resolves from its docstring.