Skip to content

šŸ Geometric Computer Vision Library for Spatial AI

docs: put the augmentation p default and homography_warp's convention on the first docstring line (#6352)

Dmytro Mishkin013411baa0f6
diff --git a/docs/source/_extra/llms-full.txt b/docs/source/_extra/llms-full.txt
index c42aaec91..c5b3a6686 100644
--- a/docs/source/_extra/llms-full.txt
+++ b/docs/source/_extra/llms-full.txt
@@ -58,9 +58,10 @@ These conventions hold library-wide; per-function docs note any exception.
- **Point coordinates:** `(x, y)` order, where x indexes columns and y indexes rows. A point tensor for N points is `(B, N, 2)`.
- **Sizes:** output sizes and `dsize` arguments are `(h, w)` order — the OPPOSITE axis order from points.
- **Angles:** degrees in the 2D image APIs (`rotate`, `get_rotation_matrix2d`, `RandomRotation`); radians in the 3D/conversion APIs (`axis_angle_to_rotation_matrix`, `So3`; convert with `deg2rad`/`rad2deg`). Positive 2D angle = counter-clockwise rotation as displayed, with the origin at the top-left corner (OpenCV convention).
-- **Transformation matrices:** batched. Homographies are `(B, 3, 3)`, affine matrices `(B, 2, 3)`. They act on pixel coordinates unless the function name or a flag says `normalized`. To apply a `(3, 3)` matrix, add the batch dim: `M[None]`.
+- **Transformation matrices:** batched. Homographies are `(B, 3, 3)`, affine matrices `(B, 2, 3)`. They act on pixel coordinates unless the function name or a flag says `normalized`. To apply a `(3, 3)` matrix, add the batch dim: `M[None]`. Exception: `homography_warp`, `homography_warp3d` and `HomographyWarper` take a destination→source homography, in normalized `[-1, 1]` coordinates by default (`normalized_coordinates=True`); `homography_warp(..., normalized_homography=False)` takes a pixel source→destination homography instead. For a pixel source→destination homography, as `RANSAC` and `find_homography_dlt` return it, use `warp_perspective`, or in 3D `warp_perspective3d(..., align_corners=True)`: its default `align_corners=False` resamples even an identity ([#4503](https://github.com/kornia/kornia/issues/4503)).
- **`align_corners`:** `warp_perspective` and `warp_affine` default to `align_corners=True`; `resize` defaults to `align_corners=None` (PyTorch's native default per interpolation mode). When mixing Kornia warps with `torch.nn.functional.interpolate` or `grid_sample`, pass `align_corners` explicitly everywhere.
- **Devices/dtypes:** ops run on whatever device/dtype the input tensors carry; there is no implicit `.cuda()` or `.float()`.
+- **Augmentation probability:** most augmentations apply per sample with probability `p` and default to `p=0.5`: `RandomRotation(degrees=30.0)` leaves about half the batch unrotated. `RandomGrayscale` defaults to 0.1 and `RandomMosaic` to 0.7; every class exported from `kornia.augmentation` with a default below 1 states it on its first docstring line. These default to `p=1.0`: `CenterCrop`, `CenterCrop3D`, `ColorJiggle`, `ColorJitter`, `Denormalize`, `LongestMaxSize`, `Normalize`, `PatchMix`, `RandomAutoContrast`, `RandomBrightness`, `RandomContrast`, `RandomCrop`, `RandomCrop3D`, `RandomCutMixV2`, `RandomGamma`, `RandomHue`, `RandomJPEG`, `RandomMixUpV2`, `RandomResizedCrop`, `RandomSaturation`, `RandomSnow`, `Resize` and `SmallestMaxSize`. The crop, resize and mix classes (`RandomCrop`, `CenterCrop`, `RandomResizedCrop`, `Resize`, `LongestMaxSize`, `SmallestMaxSize`, `RandomCrop3D`, `CenterCrop3D`, `RandomMixUpV2`, `RandomCutMixV2`, `PatchMix`) take their `p` as one draw for the whole batch, `Normalize`, `Denormalize` and `RandomDissolving` share one draw across the batch, and `same_on_batch=True` shares the draw for any class. torchvision's `RandomRotation`, `RandomAffine`, `ElasticTransform`, `GaussianBlur`, `GaussianNoise` and `RandomChannelPermutation` always apply: pass `p=1.0` for that behaviour. The reverse holds for `RandomAutoContrast`, which defaults to `p=1.0` while torchvision's `RandomAutocontrast` defaults to `p=0.5`.
- **Pretrained models:** in `kornia.models` and `kornia.feature` alike, a model built with complete pretrained weights comes back in eval mode, and a randomly initialised or only partly pretrained one in training mode; call `.eval()` before inference on random weights, and after loading your own weights. In `kornia.feature`, `HardNet`, `HardNet8`, `HyNet`, `SOSNet`, `TFeat`, `OriNet`, `LAFAffNetShapeEstimator`, `KeyNet`, `KeyNetDetector` (its `KeyNet` network; the detector itself keeps its mode), `DeFMO`, `SOLD2`, `SOLD2_detector`, `LoFTR` and `LightGlue` load their pretrained weights by default (`pretrained=False`, or `None` for `LoFTR` and `LightGlue`, gives random ones), and `DISK`, `DeDoDe`, `ALIKED` and `XFeat` load them with `from_pretrained`.
Full conventions reference with runnable proofs: <https://kornia.readthedocs.io/en/latest/get-started/conventions.html>
@@ -119,7 +120,7 @@ img_back, mask_back, kpts_back = aug.inverse(img_out, mask_out, kpts_out)
Notes:
- `data_keys` order defines the positional argument order.
-- Random parameters are sampled per batch element; `p=1.0` forces application.
+- Random parameters are sampled per batch element, and most augmentations apply to each sample with probability `p=0.5` by default; `p=1.0` forces application.
- The last applied transform matrices are available via `aug.transform_matrix` after a forward pass.
## kornia.color — color space conversions
@@ -196,7 +197,7 @@ img = img[None] # most ops want (B, C, H, W)
6. Radians where degrees are expected — rotation angles are degrees.
7. Uint8 `[0, 255]` tensors — ops expect float `[0, 1]`; divide by 255 first.
8. Augmenting image and mask through two separate augmentation calls — the random parameters will differ; use one `AugmentationSequential` with `data_keys`.
-9. Feeding `homography_warp` a source→destination pixel homography — it expects destination→source, normalized to [-1, 1]: normalize the forward homography FIRST, then invert (`torch.inverse(normalize_homography(M, size_src, size_dst))`). It also defaults to `align_corners=False` unlike `warp_perspective`.
+9. Feeding `homography_warp` a source→destination pixel homography — it expects destination→source, normalized to [-1, 1]. Use `warp_perspective` (or `normalized_homography=False`) instead. To keep the normalized form, normalize the forward homography FIRST with the `align_corners` the warp uses, then invert: `torch.inverse(normalize_homography(M, size_src, size_dst, align_corners=False))` for `homography_warp`'s default `align_corners=False`, which differs from `warp_perspective`'s `True`.
10. Mixing `axis_angle_to_rotation_matrix` (right-hand rule, math convention — screen-clockwise for +z on y-down images) with `rotate` (screen-counter-clockwise) without negating the angle.
11. Treating `kornia.geometry.bbox.infer_bbox_shape` width/height as exclusive — they are inclusive (`x_right - x_left + 1`): corners (1,1),(2,2) give width 2.
12. Quaternions in XYZW order — `kornia.geometry.quaternion.Quaternion` uses WXYZ (scalar first).
diff --git a/docs/source/_extra/llms.txt b/docs/source/_extra/llms.txt
index 1d8441350..8a2948e17 100644
--- a/docs/source/_extra/llms.txt
+++ b/docs/source/_extra/llms.txt
@@ -8,8 +8,9 @@ Conventions every code generator must know before writing Kornia code:
- Point coordinates are `(x, y)` ordered (x = column axis, y = row axis); output sizes and `dsize` arguments are `(h, w)` ordered.
- Angles are in degrees in the 2D image APIs (`rotate`, `get_rotation_matrix2d`) and radians in the 3D/conversion APIs (`axis_angle_*`, `So3`); a positive 2D angle rotates counter-clockwise as displayed (origin at the top-left corner, matching OpenCV). Exception: `kornia.augmentation.RandomAffine` turns a positive `degrees` clockwise, unlike `rotate` and `RandomRotation` ([#4408](https://github.com/kornia/kornia/issues/4408)).
- `warp_perspective` / `warp_affine` default to `align_corners=True`; `resize` defaults to `align_corners=None` (the PyTorch interpolation default). Do not assume they match. The geometric augmentations split too: `True` for `RandomRotation`, `RandomRotation90` and the crop/resize classes, `False` for `RandomAffine`, `RandomShear`, `RandomTranslate`, `RandomPerspective` and the elastic/thin-plate warps ([#4412](https://github.com/kornia/kornia/issues/4412)).
-- Transformation matrices are batched: homographies `(B, 3, 3)`, affine `(B, 2, 3)`, operating on pixel coordinates unless the function name or a flag says `normalized`.
+- Transformation matrices are batched: homographies `(B, 3, 3)`, affine `(B, 2, 3)`, operating on pixel coordinates unless the function name or a flag says `normalized`. Exception: `homography_warp`, `homography_warp3d` and `HomographyWarper` take a destination→source homography, in normalized `[-1, 1]` coordinates by default (`normalized_coordinates=True`); `homography_warp(..., normalized_homography=False)` takes a pixel source→destination homography instead. For a pixel source→destination homography, as `RANSAC` and `find_homography_dlt` return it, use `warp_perspective`, or in 3D `warp_perspective3d(..., align_corners=True)`: its default `align_corners=False` resamples even an identity ([#4503](https://github.com/kornia/kornia/issues/4503)).
- `kornia.augmentation.AugmentationSequential` applies one sampled transform consistently across image / mask / bbox / keypoints and can invert it with `.inverse()`.
+- Most augmentations apply per sample with probability `p` and default to `p=0.5`: `RandomRotation(degrees=30.0)` leaves about half the batch unrotated. `RandomGrayscale` defaults to 0.1 and `RandomMosaic` to 0.7; every class exported from `kornia.augmentation` with a default below 1 states it on its first docstring line, and one that takes `p` but names no probability there defaults to `p=1.0` (e.g. the crops and resizes, `Normalize`, `ColorJiggle`, `RandomBrightness`, `RandomAutoContrast`, `RandomJPEG`, `RandomSnow`, MixUp/CutMix/PatchMix). The crop, resize and mix classes (`RandomCrop`, `CenterCrop`, `RandomResizedCrop`, `Resize`, `LongestMaxSize`, `SmallestMaxSize`, `RandomCrop3D`, `CenterCrop3D`, `RandomMixUpV2`, `RandomCutMixV2`, `PatchMix`) take their `p` as one draw for the whole batch, `Normalize`, `Denormalize` and `RandomDissolving` share one draw across the batch, and `same_on_batch=True` shares the draw for any class. torchvision's `RandomRotation`, `RandomAffine`, `ElasticTransform`, `GaussianBlur`, `GaussianNoise` and `RandomChannelPermutation` always apply: pass `p=1.0` for that behaviour. The reverse holds for `RandomAutoContrast`, which defaults to `p=1.0` while torchvision's `RandomAutocontrast` defaults to `p=0.5`.
- `kornia.geometry.boxes.Boxes` stores boxes **inclusive** (`width = xmax - xmin + 1`); the `xyxy` / `xywh` modes are exclusive and converted on the way in and out ([#3934](https://github.com/kornia/kornia/issues/3934)). That conversion corrupts normalized `[0, 1]` boxes ([#4061](https://github.com/kornia/kornia/issues/4061)): keep boxes in pixels.
For the full self-contained reference with runnable examples, fetch [llms-full.txt](https://kornia.readthedocs.io/en/latest/llms-full.txt).
diff --git a/docs/source/get-started/conventions.rst b/docs/source/get-started/conventions.rst
index 679328ccc..eefd0ad50 100644
--- a/docs/source/get-started/conventions.rst
+++ b/docs/source/get-started/conventions.rst
@@ -286,10 +286,25 @@ Transformation matrices and homographies
**source→destination** homography in **pixel** coordinates.
- :func:`kornia.geometry.transform.homography_warp` is different on every
axis: it takes the **destination→source** homography, **normalized** to
- ``[-1, 1]`` by default (``normalized_homography=True``), and defaults to
+ ``[-1, 1]`` by default (``normalized_coordinates=True``), and defaults to
``align_corners=False``. ``normalized_coordinates=False`` takes the same
- destination→source homography in pixels. Convert a pixel
- source→destination homography by normalizing it FIRST with
+ destination→source homography in pixels, and
+ ``normalized_homography=False`` takes a pixel source→destination
+ homography instead and hands it to ``warp_perspective``.
+ :func:`~kornia.geometry.transform.homography_warp3d` and
+ :class:`~kornia.geometry.transform.HomographyWarper` read the homography the
+ same way but have no ``normalized_homography`` switch. For a pixel
+ source→destination homography, as :class:`~kornia.geometry.ransac.RANSAC`
+ and :func:`~kornia.geometry.homography.find_homography_dlt` return it, use
+ :func:`~kornia.geometry.transform.warp_perspective`, or in 3D
+ :func:`~kornia.geometry.transform.warp_perspective3d` with
+ ``align_corners=True``, because its default ``align_corners=False``
+ resamples even an identity
+ (`#4503 <https://github.com/kornia/kornia/issues/4503>`_). Passed to
+ ``homography_warp`` unchanged, such a homography usually samples outside
+ the source and the warp comes back mostly or entirely as zeros. To keep
+ ``homography_warp``, convert a pixel source→destination homography by
+ normalizing it FIRST with
:func:`kornia.geometry.conversions.normalize_homography` (which expects
the forward src→dst homography) and inverting AFTER — inverting first
with unswapped sizes is silently wrong whenever the source and
@@ -475,6 +490,31 @@ See the :doc:`enhancement API </enhance>` for clipping, histogram ranges, and kn
Augmentations
-------------
+- Most augmentations apply per sample with probability ``p`` and default to
+ ``p=0.5``: ``RandomRotation(degrees=30.0)`` leaves about half the batch
+ unrotated. :class:`kornia.augmentation.RandomGrayscale` defaults to ``0.1``
+ and :class:`kornia.augmentation.RandomMosaic` to ``0.7``; every class
+ exported from ``kornia.augmentation`` with a default below ``1`` states it
+ on its first docstring line. These default to ``p=1.0``: ``CenterCrop``,
+ ``CenterCrop3D``, ``ColorJiggle``, ``ColorJitter``, ``Denormalize``,
+ ``LongestMaxSize``, ``Normalize``, ``PatchMix``, ``RandomAutoContrast``,
+ ``RandomBrightness``, ``RandomContrast``, ``RandomCrop``, ``RandomCrop3D``,
+ ``RandomCutMixV2``, ``RandomGamma``, ``RandomHue``, ``RandomJPEG``,
+ ``RandomMixUpV2``, ``RandomResizedCrop``, ``RandomSaturation``,
+ ``RandomSnow``, ``Resize`` and ``SmallestMaxSize``.
+- The crop, resize and mix classes (``RandomCrop``, ``CenterCrop``,
+ ``RandomResizedCrop``, ``Resize``, ``LongestMaxSize``, ``SmallestMaxSize``,
+ ``RandomCrop3D``, ``CenterCrop3D``, ``RandomMixUpV2``, ``RandomCutMixV2``,
+ ``PatchMix``) take their ``p`` as one draw for the whole batch;
+ ``Normalize``, ``Denormalize`` and
+ :class:`kornia.augmentation.RandomDissolving` share one draw across the
+ batch, and ``same_on_batch=True`` shares the draw for any class (see
+ *Randomness in augmentations* below).
+- torchvision's ``RandomRotation``, ``RandomAffine``, ``ElasticTransform``,
+ ``GaussianBlur``, ``GaussianNoise`` and ``RandomChannelPermutation`` always
+ apply: pass ``p=1.0`` for that behaviour. The reverse holds for
+ ``RandomAutoContrast``, which defaults to ``p=1.0`` while torchvision's
+ ``RandomAutocontrast`` defaults to ``p=0.5``.
- Use one :class:`kornia.augmentation.container.AugmentationSequential` call
for an image and its annotations. Geometric children that implement a data
key's handler share their recorded parameters across the inputs; a transform
@@ -1317,7 +1357,8 @@ Quick self-review for generated code, most common first:
7. Uint8 ``[0, 255]`` values where float ``[0, 1]`` is expected.
8. Image and mask augmented through two separate augmentation calls.
9. ``homography_warp`` fed a source→destination pixel homography — it wants
- destination→source, normalized (or pass ``normalized_homography=False``).
+ destination→source, normalized; use ``warp_perspective`` (or pass
+ ``normalized_homography=False``).
10. Mixing ``axis_angle_to_rotation_matrix`` (math convention; screen-
clockwise for +z) with ``rotate`` (screen-counter-clockwise) without
negating the angle.
diff --git a/kornia/augmentation/_2d/base.py b/kornia/augmentation/_2d/base.py
index f76d83a1b..42e43d7e2 100644
--- a/kornia/augmentation/_2d/base.py
+++ b/kornia/augmentation/_2d/base.py
@@ -58,7 +58,7 @@ _LazyMatrixArgs = Tuple[Union[torch.Tensor, _InputMetadata], Dict[str, torch.Ten
class AugmentationBase2D(_AugmentationBase):
- r"""AugmentationBase2D base class for customized augmentation implementations.
+ r"""Base class for custom 2D augmentations, 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`
@@ -137,7 +137,7 @@ class AugmentationBase2D(_AugmentationBase):
class RigidAffineAugmentationBase2D(AugmentationBase2D):
- r"""AugmentationBase2D base class for rigid/affine augmentation implementations.
+ r"""Base class for 2D rigid/affine augmentations, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
diff --git a/kornia/augmentation/_2d/geometric/affine.py b/kornia/augmentation/_2d/geometric/affine.py
index b7ec0ef62..a7af5010b 100644
--- a/kornia/augmentation/_2d/geometric/affine.py
+++ b/kornia/augmentation/_2d/geometric/affine.py
@@ -28,12 +28,17 @@ from kornia.geometry.transform import get_affine_matrix2d, warp_affine
class RandomAffine(GeometricAugmentationBase2D):
- r"""Apply a random 2D affine transformation to a torch.Tensor image.
+ r"""Warp images by a random 2D affine transformation, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomAffine.png
The transformation is computed so that the image center is kept invariant.
+ .. note::
+ Unlike torchvision's ``RandomAffine``, which transforms every image, this class transforms 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 transform every sample.
+
Args:
degrees: Range of degrees to select from.
If degrees is a number instead of sequence like (min, max), the range of degrees
@@ -57,7 +62,7 @@ class RandomAffine(GeometricAugmentationBase2D):
Can be a float, int, or a torch.Tensor of shape (C) or (1).
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of applying the transformation.
+ 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).
Shape:
diff --git a/kornia/augmentation/_2d/geometric/base.py b/kornia/augmentation/_2d/geometric/base.py
index 744dd34af..45adcb854 100644
--- a/kornia/augmentation/_2d/geometric/base.py
+++ b/kornia/augmentation/_2d/geometric/base.py
@@ -29,7 +29,7 @@ from kornia.geometry.keypoints import Keypoints
class GeometricAugmentationBase2D(RigidAffineAugmentationBase2D):
- r"""GeometricAugmentationBase2D base class for customized geometric augmentation implementations.
+ r"""Base class for custom 2D geometric augmentations, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
diff --git a/kornia/augmentation/_2d/geometric/elastic_transform.py b/kornia/augmentation/_2d/geometric/elastic_transform.py
index b6061a7ef..3bb0d96a4 100644
--- a/kornia/augmentation/_2d/geometric/elastic_transform.py
+++ b/kornia/augmentation/_2d/geometric/elastic_transform.py
@@ -27,10 +27,15 @@ from kornia.geometry.transform import elastic_transform2d
class RandomElasticTransform(AugmentationBase2D):
- r"""Add random elastic transformation to a torch.Tensor image.
+ r"""Warp images with a random elastic displacement field, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomElasticTransform.png
+ .. note::
+ Unlike torchvision's ``ElasticTransform``, which warps every image, this class warps 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 warp every sample.
+
Convention:
This is a dense backward sampling field with no ``transform_matrix`` or ``inverse``; spatial labels in
containers have limitations (`#4420 <https://github.com/kornia/kornia/issues/4420>`_).
@@ -51,7 +56,7 @@ class RandomElasticTransform(AugmentationBase2D):
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.
+ 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).
diff --git a/kornia/augmentation/_2d/geometric/fisheye.py b/kornia/augmentation/_2d/geometric/fisheye.py
index 040d56720..dd88a7111 100644
--- a/kornia/augmentation/_2d/geometric/fisheye.py
+++ b/kornia/augmentation/_2d/geometric/fisheye.py
@@ -28,7 +28,7 @@ from kornia.geometry.transform import remap
class RandomFisheye(AugmentationBase2D):
- r"""Add random camera radial distortion.
+ r"""Add a random radial (fisheye) distortion, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomFisheye.png
@@ -47,7 +47,7 @@ class RandomFisheye(AugmentationBase2D):
center_y: Ranges to sample respect to y-coordinate center with shape (2,).
gamma: Ranges to sample for the gamma values respect to optical center with shape (2,).
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/geometric/horizontal_flip.py b/kornia/augmentation/_2d/geometric/horizontal_flip.py
index a63a36370..272c9e24b 100644
--- a/kornia/augmentation/_2d/geometric/horizontal_flip.py
+++ b/kornia/augmentation/_2d/geometric/horizontal_flip.py
@@ -28,9 +28,7 @@ from kornia.geometry.transform import hflip
class RandomHorizontalFlip(GeometricAugmentationBase2D):
- r"""Apply a random horizontal flip to a torch.Tensor image or a batch of torch.Tensor images.
-
- The flip is applied with a given probability.
+ r"""Flip images horizontally, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomHorizontalFlip.png
@@ -41,7 +39,7 @@ class RandomHorizontalFlip(GeometricAugmentationBase2D):
previous one. This is especially useful when using this functionality as part of an ``nn.Sequential`` module.
Args:
- p: probability of the image being flipped.
+ p: probability of applying the transformation to each sample.
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).
diff --git a/kornia/augmentation/_2d/geometric/perspective.py b/kornia/augmentation/_2d/geometric/perspective.py
index 38cd93f06..3a1a3d4e8 100644
--- a/kornia/augmentation/_2d/geometric/perspective.py
+++ b/kornia/augmentation/_2d/geometric/perspective.py
@@ -27,7 +27,7 @@ from kornia.geometry.transform import get_perspective_transform, warp_perspectiv
class RandomPerspective(GeometricAugmentationBase2D):
- r"""Apply a random perspective transformation to an image torch.Tensor with a given probability.
+ r"""Warp images with a random perspective transformation, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPerspective.png
@@ -36,7 +36,7 @@ class RandomPerspective(GeometricAugmentationBase2D):
resample: the interpolation method to use.
same_on_batch: apply the same transformation across the batch. Default: False.
align_corners: interpolation flag.
- p: probability of the image being perspectively transformed.
+ 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).
sampling_method: ``'basic'`` | ``'area_preserving'``. Default: ``'basic'``
diff --git a/kornia/augmentation/_2d/geometric/rotation.py b/kornia/augmentation/_2d/geometric/rotation.py
index 58120811d..78c0b6628 100644
--- a/kornia/augmentation/_2d/geometric/rotation.py
+++ b/kornia/augmentation/_2d/geometric/rotation.py
@@ -29,17 +29,22 @@ from kornia.geometry.transform.affwarp import _compute_rotation_matrix, _compute
class RandomRotation(GeometricAugmentationBase2D):
- r"""Apply a random rotation to a torch.Tensor image or a batch of torch.Tensor images given an amount of degrees.
+ r"""Rotate images by a random angle in degrees, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomRotation.png
+ .. note::
+ Unlike torchvision's ``RandomRotation``, which rotates every image, this class rotates 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 rotate every sample.
+
Args:
degrees: range of degrees to select from. If degrees is a number the
range of degrees to select from will be (-degrees, +degrees).
resample: Default: the interpolation mode.
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of applying the transformation.
+ 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).
@@ -145,7 +150,7 @@ class RandomRotation(GeometricAugmentationBase2D):
class RandomRotation90(GeometricAugmentationBase2D):
- r"""Apply a random 90 * n degree rotation to a torch.Tensor image or a batch of torch.Tensor images.
+ r"""Rotate images by a random multiple of 90 degrees, applied per sample with probability ``p`` (default 0.5).
Args:
times: the range of n times 90 degree rotation needs to be applied. A range of whole numbers is closed:
@@ -153,7 +158,7 @@ class RandomRotation90(GeometricAugmentationBase2D):
resample: Default: the interpolation mode.
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/geometric/shear.py b/kornia/augmentation/_2d/geometric/shear.py
index be0e194b5..75ba6f27f 100644
--- a/kornia/augmentation/_2d/geometric/shear.py
+++ b/kornia/augmentation/_2d/geometric/shear.py
@@ -30,10 +30,15 @@ from kornia.geometry.transform import get_shear_matrix2d, warp_affine
class RandomShear(GeometricAugmentationBase2D):
- r"""Apply a random 2D shear transformation to a torch.Tensor image.
+ 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.
+
Args:
shear: Range of degrees to select from.
If float, a shear parallel to the x axis in the range (-shear, +shear) will be applied.
@@ -44,7 +49,7 @@ class RandomShear(GeometricAugmentationBase2D):
padding_mode: padding mode from "torch.zeros" (0), "border" (1) or "reflection" (2).
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of applying the transformation.
+ 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).
Shape:
diff --git a/kornia/augmentation/_2d/geometric/thin_plate_spline.py b/kornia/augmentation/_2d/geometric/thin_plate_spline.py
index 01b59361d..d6859a878 100644
--- a/kornia/augmentation/_2d/geometric/thin_plate_spline.py
+++ b/kornia/augmentation/_2d/geometric/thin_plate_spline.py
@@ -28,7 +28,7 @@ from kornia.geometry.transform import get_tps_transform, warp_image_tps
# NOTE: This NEEDS to be updated. It is out of the random generator controller.
class RandomThinPlateSpline(AugmentationBase2D):
- r"""Add random noise to the Thin Plate Spline algorithm.
+ r"""Warp images with a random thin plate spline, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomThinPlateSpline.png
@@ -50,7 +50,7 @@ class RandomThinPlateSpline(AugmentationBase2D):
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.
+ 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::
diff --git a/kornia/augmentation/_2d/geometric/translate.py b/kornia/augmentation/_2d/geometric/translate.py
index 9e59ae1e2..ba1762b37 100644
--- a/kornia/augmentation/_2d/geometric/translate.py
+++ b/kornia/augmentation/_2d/geometric/translate.py
@@ -27,7 +27,12 @@ from kornia.geometry.transform import get_translation_matrix2d, warp_affine
class RandomTranslate(GeometricAugmentationBase2D):
- r"""Apply a random 2D affine transformation to a torch.Tensor image.
+ 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.
Args:
translate_x: tuple of maximum absolute fraction for horizontal translations.
@@ -40,7 +45,7 @@ class RandomTranslate(GeometricAugmentationBase2D):
padding_mode: padding mode from "torch.zeros" (0), "border" (1) or "reflection" (2).
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
- p: probability of applying the transformation.
+ 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).
Shape:
diff --git a/kornia/augmentation/_2d/geometric/vertical_flip.py b/kornia/augmentation/_2d/geometric/vertical_flip.py
index 3fdf9723f..4d4d4e8b2 100644
--- a/kornia/augmentation/_2d/geometric/vertical_flip.py
+++ b/kornia/augmentation/_2d/geometric/vertical_flip.py
@@ -27,12 +27,12 @@ from kornia.geometry.transform import vflip
class RandomVerticalFlip(GeometricAugmentationBase2D):
- r"""Apply a random vertical flip to a torch.Tensor image or a batch of torch.Tensor images with a given probability.
+ r"""Flip images vertically, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomVerticalFlip.png
Args:
- p: probability of the image being flipped.
+ p: probability of applying the transformation to each sample.
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).
diff --git a/kornia/augmentation/_2d/intensity/base.py b/kornia/augmentation/_2d/intensity/base.py
index 5bcb86b6b..c9d5eab02 100644
--- a/kornia/augmentation/_2d/intensity/base.py
+++ b/kornia/augmentation/_2d/intensity/base.py
@@ -77,7 +77,7 @@ class _PicklableCompileMixin:
class IntensityAugmentationBase2D(RigidAffineAugmentationBase2D):
- r"""IntensityAugmentationBase2D base class for customized intensity augmentation implementations.
+ r"""Base class for custom 2D intensity augmentations, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.AugmentationBase2D`.
diff --git a/kornia/augmentation/_2d/intensity/box_blur.py b/kornia/augmentation/_2d/intensity/box_blur.py
index df12381d8..80402aa55 100644
--- a/kornia/augmentation/_2d/intensity/box_blur.py
+++ b/kornia/augmentation/_2d/intensity/box_blur.py
@@ -26,7 +26,7 @@ from kornia.filters import box_blur
class RandomBoxBlur(IntensityAugmentationBase2D):
- """Add random blur with a box filter to an image tensor.
+ """Blur images with a box filter, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomBoxBlur.png
@@ -42,7 +42,7 @@ class RandomBoxBlur(IntensityAugmentationBase2D):
as two 1D passes (``separable=True``), ``False`` as one 2D pass. The kernel is L1-normalized either
way, so both return the mean of each window, never its sum, and differ only by float rounding.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/channel_dropout.py b/kornia/augmentation/_2d/intensity/channel_dropout.py
index 9981ac050..9ffb24d02 100644
--- a/kornia/augmentation/_2d/intensity/channel_dropout.py
+++ b/kornia/augmentation/_2d/intensity/channel_dropout.py
@@ -26,7 +26,7 @@ from kornia.core.utils import _to_device_nonblocking
class RandomChannelDropout(IntensityAugmentationBase2D):
- r"""Apply random channel dropout to a batch of images.
+ r"""Set random channels to ``fill_value`` (channel dropout) per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomChannelDropout.png
@@ -36,7 +36,7 @@ class RandomChannelDropout(IntensityAugmentationBase2D):
num_drop_channels: Number of channels to drop randomly. Default is 1.
fill_value: Value to fill the dropped channels with. Default is 0.0.
same_on_batch: Apply the same transformation across the batch. Defaults to False.
- p: Probability of applying the transformation. Defaults to 0.5.
+ p: Probability of applying the transformation to each sample. Defaults to 0.5.
keepdim: Whether to keep the output shape the same as input ``True`` or broadcast it
to the batch form ``False``. Defaults to False.
diff --git a/kornia/augmentation/_2d/intensity/channel_shuffle.py b/kornia/augmentation/_2d/intensity/channel_shuffle.py
index 0cbcfec4f..278923632 100644
--- a/kornia/augmentation/_2d/intensity/channel_shuffle.py
+++ b/kornia/augmentation/_2d/intensity/channel_shuffle.py
@@ -25,15 +25,20 @@ from kornia.core.utils import _to_device_nonblocking
class RandomChannelShuffle(IntensityAugmentationBase2D):
- r"""Shuffle the channels of a batch of multi-dimensional images.
+ r"""Randomly permute the channels of images, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomChannelShuffle.png
+ .. note::
+ Unlike torchvision's ``RandomChannelPermutation``, which permutes the channels of every image, this class
+ permutes the channels of 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 permute every sample.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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``.
diff --git a/kornia/augmentation/_2d/intensity/clahe.py b/kornia/augmentation/_2d/intensity/clahe.py
index 1ffe69405..2171f3dca 100644
--- a/kornia/augmentation/_2d/intensity/clahe.py
+++ b/kornia/augmentation/_2d/intensity/clahe.py
@@ -27,7 +27,7 @@ from kornia.enhance.equalization import _equalize_clahe
class RandomClahe(IntensityAugmentationBase2D):
- r"""Apply CLAHE equalization on the input torch.Tensor randomly.
+ r"""Equalize local contrast with CLAHE, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/equalize_clahe.png
@@ -44,7 +44,7 @@ class RandomClahe(IntensityAugmentationBase2D):
autograd graph -- the output has ``requires_grad=False`` and no ``grad_fn``, which no other 2D
intensity augmentation does -- so set it to ``True`` to keep the class differentiable.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/dissolving.py b/kornia/augmentation/_2d/intensity/dissolving.py
index 71cf1fa76..3ee5a3ad2 100644
--- a/kornia/augmentation/_2d/intensity/dissolving.py
+++ b/kornia/augmentation/_2d/intensity/dissolving.py
@@ -25,7 +25,7 @@ from kornia.filters import StableDiffusionDissolving
class RandomDissolving(IntensityAugmentationBase2D):
- r"""Perform dissolving transformation using StableDiffusion models.
+ r"""Dissolve images with a Stable Diffusion model, applied to the whole batch with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -47,7 +47,7 @@ class RandomDissolving(IntensityAugmentationBase2D):
- SD XL example image pending — see `#4601 <https://github.com/kornia/kornia/issues/4601>`_.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation, drawn once for the whole batch.
version: the version of the stable diffusion model. Options: ``"1.4"``, ``"1.5"``, ``"xl"``.
step_range: the step range of the diffusion model steps. Higher the step, stronger
the dissolving effects.
diff --git a/kornia/augmentation/_2d/intensity/equalize.py b/kornia/augmentation/_2d/intensity/equalize.py
index c3429af6b..b4e12a7bb 100644
--- a/kornia/augmentation/_2d/intensity/equalize.py
+++ b/kornia/augmentation/_2d/intensity/equalize.py
@@ -24,14 +24,14 @@ from kornia.enhance import equalize
class RandomEqualize(IntensityAugmentationBase2D):
- r"""Equalize given tensor image or a batch of tensor images randomly.
+ r"""Equalize the histogram of each image channel, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomEqualize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: Probability to equalize an image.
+ p: Probability of applying the transformation to each sample.
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).
diff --git a/kornia/augmentation/_2d/intensity/erasing.py b/kornia/augmentation/_2d/intensity/erasing.py
index cb213d244..69dbb402f 100644
--- a/kornia/augmentation/_2d/intensity/erasing.py
+++ b/kornia/augmentation/_2d/intensity/erasing.py
@@ -26,7 +26,7 @@ from kornia.geometry.bbox import bbox_generator, bbox_to_mask
class RandomErasing(IntensityAugmentationBase2D):
- r"""Erase a random rectangle of a torch.Tensor image according to a probability p value.
+ r"""Erase a random rectangle of the image, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomErasing.png
@@ -43,7 +43,7 @@ class RandomErasing(IntensityAugmentationBase2D):
ratio: range of aspect ratio of erased area.
value: the value to fill the erased area.
same_on_batch: apply the same transformation across the batch.
- p: probability that the random erasing operation will be performed.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/gaussian_blur.py b/kornia/augmentation/_2d/intensity/gaussian_blur.py
index 50ba402c8..c0ebc43cf 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_blur.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_blur.py
@@ -29,12 +29,17 @@ from kornia.filters.kernels import _check_kernel_size, _unpack_2d_ks
class RandomGaussianBlur(_PicklableCompileMixin, IntensityAugmentationBase2D):
- r"""Apply gaussian blur given tensor image or a batch of tensor images randomly.
+ r"""Blur images with a Gaussian kernel of random sigma, applied per sample with probability ``p`` (default 0.5).
The standard deviation is sampled for each instance.
.. image:: _static/img/RandomGaussianBlur.png
+ .. note::
+ Unlike torchvision's ``GaussianBlur``, which blurs every image, this class blurs 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 blur
+ every sample.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
@@ -44,7 +49,7 @@ class RandomGaussianBlur(_PicklableCompileMixin, IntensityAugmentationBase2D):
The expected modes are: ``constant``, ``reflect``, ``replicate`` or ``circular``.
separable: run as composition of two 1d-convolutions.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/gaussian_illumination.py b/kornia/augmentation/_2d/intensity/gaussian_illumination.py
index 483436d60..a397ef0f9 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_illumination.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_illumination.py
@@ -48,7 +48,7 @@ def _apply_gaussian_illumination(
class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBase2D):
- r"""Applies random 2D Gaussian illumination patterns to a batch of images.
+ r"""Add a random Gaussian-shaped illumination pattern, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomGaussianIllumination.png
@@ -62,7 +62,7 @@ class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBa
percentage of the spatial dimensions :math:(H, W).
sign: Range for the sign of the Gaussian distribution. If only one sign is needed,
insert only as a tuple or float.
- p: Probability of applying the transformation.
+ p: Probability of applying the transformation to each sample.
same_on_batch: If True, apply the same transformation across the entire batch. Default is False.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
diff --git a/kornia/augmentation/_2d/intensity/gaussian_noise.py b/kornia/augmentation/_2d/intensity/gaussian_noise.py
index 668f92b0a..1258842bc 100644
--- a/kornia/augmentation/_2d/intensity/gaussian_noise.py
+++ b/kornia/augmentation/_2d/intensity/gaussian_noise.py
@@ -25,17 +25,22 @@ from kornia.core.utils import _to_device_nonblocking
class RandomGaussianNoise(IntensityAugmentationBase2D):
- r"""Add gaussian noise to a batch of multi-dimensional images.
+ r"""Add Gaussian noise to images, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomGaussianNoise.png
+ .. note::
+ Unlike torchvision's ``GaussianNoise``, which adds noise to every image, this class adds noise to 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 add noise to every sample.
+
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
mean: The mean of the gaussian distribution.
std: The standard deviation of the gaussian distribution.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/grayscale.py b/kornia/augmentation/_2d/intensity/grayscale.py
index 20518cdfa..1693ac4d0 100644
--- a/kornia/augmentation/_2d/intensity/grayscale.py
+++ b/kornia/augmentation/_2d/intensity/grayscale.py
@@ -27,7 +27,7 @@ from kornia.core.utils import _to_device_nonblocking
class RandomGrayscale(IntensityAugmentationBase2D):
- r"""Apply random transformation to Grayscale according to a probability p value.
+ r"""Convert images to grayscale (channel count kept), applied per sample with probability ``p`` (default 0.1).
.. image:: _static/img/RandomGrayscale.png
@@ -42,7 +42,7 @@ class RandomGrayscale(IntensityAugmentationBase2D):
channel (three, for the usual RGB case). If ``None``, RGB inputs use the standard
luminance weights and multispectral inputs weight every band equally. Weights are applied
as given and are not normalized, so weights that do not sum to one rescale the output.
- p: probability of the image to be transformed to grayscale.
+ p: probability of applying the transformation to each sample.
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).
diff --git a/kornia/augmentation/_2d/intensity/invert.py b/kornia/augmentation/_2d/intensity/invert.py
index 45a3299af..efc249c2e 100644
--- a/kornia/augmentation/_2d/intensity/invert.py
+++ b/kornia/augmentation/_2d/intensity/invert.py
@@ -27,7 +27,7 @@ from kornia.enhance import invert
class RandomInvert(IntensityAugmentationBase2D):
- r"""Invert the tensor images values randomly.
+ r"""Invert image values as ``max_val - x``, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomInvert.png
@@ -37,7 +37,7 @@ class RandomInvert(IntensityAugmentationBase2D):
max_val: The expected maximum value in the input tensor. The shape has to
according to the input tensor shape, or at least has to work with broadcasting.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/linear_illumination.py b/kornia/augmentation/_2d/intensity/linear_illumination.py
index c2073b960..228f8400d 100644
--- a/kornia/augmentation/_2d/intensity/linear_illumination.py
+++ b/kornia/augmentation/_2d/intensity/linear_illumination.py
@@ -26,7 +26,7 @@ from kornia.core.utils import _to_device_nonblocking
class RandomLinearIllumination(IntensityAugmentationBase2D):
- r"""Applies random 2D Linear illumination patterns to a batch of images.
+ r"""Brighten or darken by a linear ramp from an edge, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomLinearIllumination.png
@@ -36,7 +36,7 @@ class RandomLinearIllumination(IntensityAugmentationBase2D):
gain: Range for the gain factor (intensity) applied to the generated illumination.
sign: Range for the sign of the distribution. If only one sign is needed,
insert only as a tuple or float.
- p: Probability of applying the transformation.
+ p: Probability of applying the transformation to each sample.
same_on_batch: If True, apply the same transformation across the entire batch. Default is False.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
@@ -146,7 +146,7 @@ class RandomLinearIllumination(IntensityAugmentationBase2D):
class RandomLinearCornerIllumination(IntensityAugmentationBase2D):
- r"""Applies random 2D Linear from corner illumination patterns to a batch of images.
+ r"""Brighten or darken by a linear ramp from a corner, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomLinearCornerIllumination.png
@@ -156,7 +156,7 @@ class RandomLinearCornerIllumination(IntensityAugmentationBase2D):
gain: Range for the gain factor (intensity) applied to the generated illumination.
sign: Range for the sign of the distribution. If only one sign is needed,
insert only as a tuple or float.
- p: Probability of applying the transformation.
+ p: Probability of applying the transformation to each sample.
same_on_batch: If True, apply the same transformation across the entire batch. Default is False.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
diff --git a/kornia/augmentation/_2d/intensity/median_blur.py b/kornia/augmentation/_2d/intensity/median_blur.py
index a4130fa7d..b43f7ba69 100644
--- a/kornia/augmentation/_2d/intensity/median_blur.py
+++ b/kornia/augmentation/_2d/intensity/median_blur.py
@@ -26,7 +26,7 @@ from kornia.filters.kernels import _check_kernel_size, _unpack_2d_ks
class RandomMedianBlur(IntensityAugmentationBase2D):
- """Add random blur with a median filter to an image tensor.
+ """Blur images with a median filter, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomMedianBlur.png
@@ -35,7 +35,7 @@ class RandomMedianBlur(IntensityAugmentationBase2D):
Args:
kernel_size: the blurring kernel size.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/motion_blur.py b/kornia/augmentation/_2d/intensity/motion_blur.py
index cdefacdbc..ac7d54c4d 100644
--- a/kornia/augmentation/_2d/intensity/motion_blur.py
+++ b/kornia/augmentation/_2d/intensity/motion_blur.py
@@ -27,14 +27,14 @@ from kornia.filters import motion_blur
class RandomMotionBlur(IntensityAugmentationBase2D):
- r"""Perform motion blur on 2D images (4D torch.Tensor).
+ r"""Blur images with a random motion-blur kernel, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomMotionBlur.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
kernel_size: motion kernel size (odd and positive).
If int, the kernel will have a fixed size.
If Tuple[int, int] or a two-element list, it will randomly generate one odd value from the closed
diff --git a/kornia/augmentation/_2d/intensity/planckian_jitter.py b/kornia/augmentation/_2d/intensity/planckian_jitter.py
index fa31430e2..b37733447 100644
--- a/kornia/augmentation/_2d/intensity/planckian_jitter.py
+++ b/kornia/augmentation/_2d/intensity/planckian_jitter.py
@@ -92,7 +92,7 @@ def get_planckian_coeffs(mode: str) -> torch.Tensor:
class RandomPlanckianJitter(IntensityAugmentationBase2D):
- r"""Apply planckian jitter transformation to input torch.Tensor.
+ r"""Shift the illuminant color (Planckian jitter), applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPlanckianJitter.png
@@ -110,7 +110,7 @@ class RandomPlanckianJitter(IntensityAugmentationBase2D):
The entries index the table like a Python sequence: one past the end raises at construction, and a
negative one counts from the end.
same_on_batch: apply the same transformation across the batch.
- p: probability that the random erasing operation will be performed.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/plasma.py b/kornia/augmentation/_2d/intensity/plasma.py
index d89cd5b8a..4930f1ba1 100644
--- a/kornia/augmentation/_2d/intensity/plasma.py
+++ b/kornia/augmentation/_2d/intensity/plasma.py
@@ -54,7 +54,7 @@ def _plasma_for_input(plasma: torch.Tensor, image: torch.Tensor) -> torch.Tensor
class RandomPlasmaBrightness(IntensityAugmentationBase2D):
- r"""Adds brightness to the image based on a fractal map generated by the diamond square algorithm.
+ r"""Shift brightness by a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPlasmaBrightness.png
@@ -70,7 +70,7 @@ class RandomPlasmaBrightness(IntensityAugmentationBase2D):
roughness: value to scale during the recursion in the generation of the fractal map.
intensity: value that scales the intensity values of the generated maps.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
@@ -127,7 +127,7 @@ class RandomPlasmaBrightness(IntensityAugmentationBase2D):
class RandomPlasmaContrast(IntensityAugmentationBase2D):
- r"""Adds contrast to the image based on a fractal map generated by the diamond square algorithm.
+ r"""Scale contrast by a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPlasmaContrast.png
@@ -142,7 +142,7 @@ class RandomPlasmaContrast(IntensityAugmentationBase2D):
Args:
roughness: value to scale during the recursion in the generation of the fractal map.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
@@ -194,7 +194,7 @@ class RandomPlasmaContrast(IntensityAugmentationBase2D):
class RandomPlasmaShadow(IntensityAugmentationBase2D):
- r"""Add gaussian noise to a batch of multi-dimensional images.
+ r"""Add shadows from a diamond-square fractal map, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPlasmaShadow.png
@@ -211,7 +211,7 @@ class RandomPlasmaShadow(IntensityAugmentationBase2D):
shade_intensity: value that scales the intensity values of the generated maps.
shade_quantity: value to select the pixels to mask.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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).
diff --git a/kornia/augmentation/_2d/intensity/posterize.py b/kornia/augmentation/_2d/intensity/posterize.py
index 0a8556079..d54c0d9b5 100644
--- a/kornia/augmentation/_2d/intensity/posterize.py
+++ b/kornia/augmentation/_2d/intensity/posterize.py
@@ -26,14 +26,14 @@ from kornia.enhance import posterize
class RandomPosterize(IntensityAugmentationBase2D):
- r"""Posterize given torch.Tensor image or a batch of torch.Tensor images randomly.
+ r"""Posterize images to a random number of bits, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomPosterize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
bits: number of high bits to keep, in ``[0, 8]``, in which 0 gives a black image and 8 gives the
original. A range of whole numbers is closed and uniform: every integer from the lower to the upper
bound is drawn with the same probability. A non-integral argument is accepted; the drawn factor is
diff --git a/kornia/augmentation/_2d/intensity/random_rain.py b/kornia/augmentation/_2d/intensity/random_rain.py
index 2784a4e93..92ab7a8a5 100644
--- a/kornia/augmentation/_2d/intensity/random_rain.py
+++ b/kornia/augmentation/_2d/intensity/random_rain.py
@@ -28,12 +28,12 @@ from kornia.core.utils import _to_device_nonblocking
class RandomRain(IntensityAugmentationBase2D):
- r"""Add Random Rain to the image.
+ r"""Draw random rain-drop streaks on images, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
number_of_drops: number of drops per image
drop_height: Height of the drop in the image (same for each drop in one image). Sampled values must be
greater than zero and strictly smaller than the input image height.
diff --git a/kornia/augmentation/_2d/intensity/random_rgb_shift.py b/kornia/augmentation/_2d/intensity/random_rgb_shift.py
index d374d865d..b40246c4e 100644
--- a/kornia/augmentation/_2d/intensity/random_rgb_shift.py
+++ b/kornia/augmentation/_2d/intensity/random_rgb_shift.py
@@ -33,7 +33,7 @@ def _shift_bounds(limit: Union[torch.Tensor, float, Tuple[float, float], List[fl
class RandomRGBShift(IntensityAugmentationBase2D):
- """Randomly shift each channel of an image.
+ """Shift each RGB channel by a random offset, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
@@ -43,7 +43,7 @@ class RandomRGBShift(IntensityAugmentationBase2D):
g_shift_limit: shift range for the green channel, in the same form as ``r_shift_limit``.
b_shift_limit: shift range for the blue channel, in the same form as ``r_shift_limit``.
same_on_batch: apply the same transformation across the batch.
- p: probability of applying the transformation.
+ 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``.
diff --git a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py b/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
index 5d652ea05..076b4fb68 100644
--- a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
+++ b/kornia/augmentation/_2d/intensity/salt_pepper_noise.py
@@ -26,7 +26,7 @@ from kornia.core.utils import _to_device_nonblocking
class RandomSaltAndPepperNoise(IntensityAugmentationBase2D):
- r"""Apply random Salt and Pepper noise to input images.
+ r"""Add salt-and-pepper noise to images, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomSaltAndPepperNoise.png
@@ -35,7 +35,7 @@ class RandomSaltAndPepperNoise(IntensityAugmentationBase2D):
Args:
amount: A float or a tuple representing the range for the amount of noise to apply.
salt_vs_pepper: A float or a tuple representing the range for the ratio of Salt to Pepper noise.
- p: The probability of applying the transformation. Default is 0.5.
+ p: The probability of applying the transformation to each sample. Default is 0.5.
same_on_batch: If True, apply the same transformation across the entire batch. Default is False.
keepdim: whether to keep the output shape the same as input (True) or broadcast it
to the batch form (False).
diff --git a/kornia/augmentation/_2d/intensity/sharpness.py b/kornia/augmentation/_2d/intensity/sharpness.py
index d70066ab7..2ec445686 100644
--- a/kornia/augmentation/_2d/intensity/sharpness.py
+++ b/kornia/augmentation/_2d/intensity/sharpness.py
@@ -26,7 +26,7 @@ from kornia.enhance import sharpness
class RandomSharpness(IntensityAugmentationBase2D):
- r"""Blend a random amount of a ``3 x 3`` smoothed copy with the image.
+ r"""Blend each sample with a ``3 x 3`` smoothed copy by a random factor, with probability ``p`` (default 0.5).
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.
@@ -36,7 +36,7 @@ class RandomSharpness(IntensityAugmentationBase2D):
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
sharpness: the blend factor between the blurred image and the input. If ``sharpness`` is a single
non-negative number ``x``, the factor is sampled from ``[0, x]``; a tuple gives the range
directly.
diff --git a/kornia/augmentation/_2d/intensity/solarize.py b/kornia/augmentation/_2d/intensity/solarize.py
index 0df654d88..688f0a79b 100644
--- a/kornia/augmentation/_2d/intensity/solarize.py
+++ b/kornia/augmentation/_2d/intensity/solarize.py
@@ -25,14 +25,14 @@ from kornia.enhance import solarize
class RandomSolarize(IntensityAugmentationBase2D):
- r"""Solarize given torch.Tensor image or a batch of torch.Tensor images randomly.
+ r"""Solarize images at a random threshold and addition, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomSolarize.png
See the Convention block on :class:`~kornia.augmentation.IntensityAugmentationBase2D`.
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
thresholds:
If float x, threshold will be generated from (0.5 - x, 0.5 + x).
If tuple (x, y), threshold will be generated from (x, y).
diff --git a/kornia/augmentation/_2d/mix/jigsaw.py b/kornia/augmentation/_2d/mix/jigsaw.py
index de4a18a00..5333b80c4 100644
--- a/kornia/augmentation/_2d/mix/jigsaw.py
+++ b/kornia/augmentation/_2d/mix/jigsaw.py
@@ -28,7 +28,7 @@ __all__ = ["RandomJigsaw"]
class RandomJigsaw(MixAugmentationBaseV2):
- r"""RandomJigsaw augmentation.
+ 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
diff --git a/kornia/augmentation/_2d/mix/mosaic.py b/kornia/augmentation/_2d/mix/mosaic.py
index f3f9764f3..b8d1dd96e 100644
--- a/kornia/augmentation/_2d/mix/mosaic.py
+++ b/kornia/augmentation/_2d/mix/mosaic.py
@@ -33,7 +33,7 @@ __all__ = ["RandomMosaic"]
class RandomMosaic(MixAugmentationBaseV2):
- r"""Mosaic augmentation.
+ 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
diff --git a/kornia/augmentation/_2d/mix/transplantation.py b/kornia/augmentation/_2d/mix/transplantation.py
index f6d7e5b35..a77098ec7 100644
--- a/kornia/augmentation/_2d/mix/transplantation.py
+++ b/kornia/augmentation/_2d/mix/transplantation.py
@@ -31,7 +31,7 @@ __all__ = ["RandomTransplantation"]
class RandomTransplantation(MixAugmentationBaseV2):
- r"""RandomTransplantation augmentation.
+ r"""Paste a labelled region from the previous batch image, applied per sample with probability ``p`` (default 0.5).
.. image:: _static/img/RandomTransplantation.png
@@ -52,8 +52,8 @@ class RandomTransplantation(MixAugmentationBaseV2):
parts of the image are annotated and the non-annotated regions (with a specific label index) should be
excluded from the augmentation. If no label is left in a donor image, that acceptor receives nothing
while the rest of the batch is transplanted as usual.
- p: probability for applying an augmentation to an image. This parameter controls how many images in a batch
- receive a transplant.
+ p: probability of applying the transformation to each sample. This parameter controls how many images in a
+ batch receive a transplant.
p_batch: probability for applying an augmentation to a batch. This param controls the augmentation
probabilities batch-wise.
data_keys: the input type sequential for applying augmentations. There must be at least one "mask" torch.Tensor.
diff --git a/kornia/augmentation/_3d/base.py b/kornia/augmentation/_3d/base.py
index 60cbf8761..d7ae33690 100644
--- a/kornia/augmentation/_3d/base.py
+++ b/kornia/augmentation/_3d/base.py
@@ -29,7 +29,7 @@ from kornia.geometry.keypoints import Keypoints3D
class AugmentationBase3D(_AugmentationBase):
- r"""AugmentationBase3D base class for customized augmentation implementations.
+ r"""Base class for custom 3D augmentations, applied per sample with probability ``p`` (default 0.5).
Args:
p: probability for applying an augmentation. This param controls the augmentation probabilities
@@ -84,7 +84,7 @@ class AugmentationBase3D(_AugmentationBase):
class RigidAffineAugmentationBase3D(AugmentationBase3D):
- r"""AugmentationBase3D base class for rigid/affine augmentation implementations.
+ r"""Base class for 3D rigid/affine augmentations, 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.
diff --git a/kornia/augmentation/_3d/geometric/affine.py b/kornia/augmentation/_3d/geometric/affine.py
index 5bfcfea18..25e05901c 100644
--- a/kornia/augmentation/_3d/geometric/affine.py
+++ b/kornia/augmentation/_3d/geometric/affine.py
@@ -28,7 +28,7 @@ from kornia.geometry.transform.imgwarp import get_affine_matrix3d, warp_affine3d
class RandomAffine3D(GeometricAugmentationBase3D):
- r"""Apply affine transformation 3D volumes (5D torch.Tensor).
+ 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.
@@ -63,6 +63,7 @@ class RandomAffine3D(GeometricAugmentationBase3D):
resample: resample mode from "nearest" (0) or "bilinear" (1).
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
+ 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). Default: False.
diff --git a/kornia/augmentation/_3d/geometric/base.py b/kornia/augmentation/_3d/geometric/base.py
index 583979c10..4364dd4c7 100644
--- a/kornia/augmentation/_3d/geometric/base.py
+++ b/kornia/augmentation/_3d/geometric/base.py
@@ -19,7 +19,7 @@ from kornia.augmentation._3d.base import RigidAffineAugmentationBase3D
class GeometricAugmentationBase3D(RigidAffineAugmentationBase3D):
- r"""Base class for 3D geometric augmentations.
+ r"""Base class for custom 3D geometric augmentations, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.AugmentationBase3D`.
diff --git a/kornia/augmentation/_3d/geometric/depthical_flip.py b/kornia/augmentation/_3d/geometric/depthical_flip.py
index 4efb7acb8..2a9aa0c80 100644
--- a/kornia/augmentation/_3d/geometric/depthical_flip.py
+++ b/kornia/augmentation/_3d/geometric/depthical_flip.py
@@ -25,12 +25,12 @@ from kornia.core.ops import _device_literal
class RandomDepthicalFlip3D(GeometricAugmentationBase3D):
- r"""Apply random flip along the depth axis of 3D volumes (5D tensor).
+ r"""Flip 3D volumes along the depth axis, applied per sample with probability ``p`` (default 0.5).
Input should be a tensor of shape :math:`(C, D, H, W)` or a batch of tensors :math:`(*, C, D, H, W)`.
Args:
- p: probability of the image being flipped.
+ p: probability of applying the transformation to each sample.
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``.
diff --git a/kornia/augmentation/_3d/geometric/horizontal_flip.py b/kornia/augmentation/_3d/geometric/horizontal_flip.py
index 84a8c5079..05b6a87be 100644
--- a/kornia/augmentation/_3d/geometric/horizontal_flip.py
+++ b/kornia/augmentation/_3d/geometric/horizontal_flip.py
@@ -25,10 +25,10 @@ from kornia.core.ops import _device_literal
class RandomHorizontalFlip3D(GeometricAugmentationBase3D):
- r"""Apply random horizontal flip to 3D volumes (5D tensor).
+ r"""Flip 3D volumes horizontally, applied per sample with probability ``p`` (default 0.5).
Args:
- p: probability of the image being flipped.
+ p: probability of applying the transformation to each sample.
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``.
diff --git a/kornia/augmentation/_3d/geometric/perspective.py b/kornia/augmentation/_3d/geometric/perspective.py
index 740647a4f..452c545ed 100644
--- a/kornia/augmentation/_3d/geometric/perspective.py
+++ b/kornia/augmentation/_3d/geometric/perspective.py
@@ -28,10 +28,10 @@ from kornia.geometry import get_perspective_transform3d, warp_perspective3d
class RandomPerspective3D(GeometricAugmentationBase3D):
- r"""Apply random perspective transformation to 3D volumes (5D torch.Tensor).
+ r"""Warp 3D volumes with a random perspective transform, applied per sample with probability ``p`` (default 0.5).
Args:
- p: probability of the image being perspectively transformed.
+ p: probability of applying the transformation to each sample.
distortion_scale: it controls the degree of distortion and ranges from 0 to 1.
resample: resample mode from "nearest" (0) or "bilinear" (1).
same_on_batch: apply the same transformation across the batch.
diff --git a/kornia/augmentation/_3d/geometric/rotation.py b/kornia/augmentation/_3d/geometric/rotation.py
index f7d3617df..b69e26506 100644
--- a/kornia/augmentation/_3d/geometric/rotation.py
+++ b/kornia/augmentation/_3d/geometric/rotation.py
@@ -29,7 +29,7 @@ from kornia.geometry.transform.affwarp import _compute_rotation_matrix3d, _compu
class RandomRotation3D(GeometricAugmentationBase3D):
- r"""Apply random rotations to 3D volumes (5D torch.Tensor).
+ 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 :math:`(B, C, D, H, W)`.
@@ -45,6 +45,7 @@ class RandomRotation3D(GeometricAugmentationBase3D):
resample: resample mode from "nearest" (0) or "bilinear" (1).
same_on_batch: apply the same transformation across the batch.
align_corners: interpolation flag.
+ 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).
diff --git a/kornia/augmentation/_3d/geometric/vertical_flip.py b/kornia/augmentation/_3d/geometric/vertical_flip.py
index 26f8225f0..9ecfe9d6f 100644
--- a/kornia/augmentation/_3d/geometric/vertical_flip.py
+++ b/kornia/augmentation/_3d/geometric/vertical_flip.py
@@ -25,12 +25,12 @@ from kornia.core.ops import _device_literal
class RandomVerticalFlip3D(GeometricAugmentationBase3D):
- r"""Apply random vertical flip to 3D volumes (5D tensor).
+ r"""Flip 3D volumes vertically, applied per sample with probability ``p`` (default 0.5).
Input should be a tensor of shape :math:`(C, D, H, W)` or a batch of tensors :math:`(*, C, D, H, W)`.
Args:
- p: probability of the image being flipped.
+ p: probability of applying the transformation to each sample.
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``.
diff --git a/kornia/augmentation/_3d/intensity/base.py b/kornia/augmentation/_3d/intensity/base.py
index 91ef6de46..4ad8618c4 100644
--- a/kornia/augmentation/_3d/intensity/base.py
+++ b/kornia/augmentation/_3d/intensity/base.py
@@ -19,7 +19,7 @@ from kornia.augmentation._3d.base import RigidAffineAugmentationBase3D
class IntensityAugmentationBase3D(RigidAffineAugmentationBase3D):
- r"""Base class for 3D intensity augmentations.
+ r"""Base class for custom 3D intensity augmentations, applied per sample with probability ``p`` (default 0.5).
See the Convention block on :class:`~kornia.augmentation.AugmentationBase3D`.
diff --git a/kornia/augmentation/_3d/intensity/equalize.py b/kornia/augmentation/_3d/intensity/equalize.py
index c654dc74c..cdc1cb46e 100644
--- a/kornia/augmentation/_3d/intensity/equalize.py
+++ b/kornia/augmentation/_3d/intensity/equalize.py
@@ -24,10 +24,10 @@ from kornia.enhance import equalize3d
class RandomEqualize3D(IntensityAugmentationBase3D):
- r"""Apply random equalization to 3D volumes (5D tensor).
+ r"""Equalize the histogram of 3D volumes, applied per sample with probability ``p`` (default 0.5).
Args:
- p: probability of the image being equalized.
+ p: probability of applying the transformation to each sample.
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).
diff --git a/kornia/augmentation/_3d/intensity/motion_blur.py b/kornia/augmentation/_3d/intensity/motion_blur.py
index df9677351..abed0a29e 100644
--- a/kornia/augmentation/_3d/intensity/motion_blur.py
+++ b/kornia/augmentation/_3d/intensity/motion_blur.py
@@ -27,10 +27,10 @@ from kornia.filters import motion_blur3d
class RandomMotionBlur3D(IntensityAugmentationBase3D):
- r"""Apply random motion blur on 3D volumes (5D torch.Tensor).
+ r"""Blur 3D volumes with a random motion-blur kernel, applied per sample with probability ``p`` (default 0.5).
Args:
- p: probability of applying the transformation.
+ p: probability of applying the transformation to each sample.
kernel_size: motion kernel size (odd and at least 3).
If int, the kernel will have a fixed size.
If Tuple[int, int], it will randomly generate the value from the range batch-wisely.
diff --git a/kornia/augmentation/_3d/mix/transplantation.py b/kornia/augmentation/_3d/mix/transplantation.py
index 4fce28306..bf52c1cdc 100644
--- a/kornia/augmentation/_3d/mix/transplantation.py
+++ b/kornia/augmentation/_3d/mix/transplantation.py
@@ -22,7 +22,7 @@ __all__ = ["RandomTransplantation3D"]
class RandomTransplantation3D(RandomTransplantation, AugmentationBase3D):
- """RandomTransplantation3D augmentation.
+ """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.
diff --git a/kornia/geometry/transform/homography_warper.py b/kornia/geometry/transform/homography_warper.py
index 561034a83..67b6f97f8 100644
--- a/kornia/geometry/transform/homography_warper.py
+++ b/kornia/geometry/transform/homography_warper.py
@@ -75,7 +75,12 @@ class BaseWarper(nn.Module):
class HomographyWarper(BaseWarper):
- r"""Warp tensors by homographies.
+ r"""Warp tensors by a normalized destination→source homography (default ``normalized_coordinates=True``).
+
+ For a source→destination homography in pixel coordinates, as :class:`~kornia.geometry.ransac.RANSAC` and
+ :func:`~kornia.geometry.homography.find_homography_dlt` return it, use
+ :func:`~kornia.geometry.transform.warp_perspective`. This class has no ``normalized_homography`` switch:
+ ``normalized_coordinates=False`` still reads a destination→source homography, in pixels.
.. math::
diff --git a/kornia/geometry/transform/imgwarp.py b/kornia/geometry/transform/imgwarp.py
index 1ad55355a..b2215cfcc 100644
--- a/kornia/geometry/transform/imgwarp.py
+++ b/kornia/geometry/transform/imgwarp.py
@@ -1937,7 +1937,15 @@ def homography_warp(
normalized_coordinates: bool = True,
normalized_homography: bool = True,
) -> torch.Tensor:
- r"""Warp image patches or tensors by normalized 2D homographies.
+ r"""Warp an image by a destination→source homography in normalized ``[-1, 1]`` coordinates (the defaults).
+
+ For a source→destination homography in pixel coordinates, as :class:`~kornia.geometry.ransac.RANSAC` and
+ :func:`~kornia.geometry.homography.find_homography_dlt` return it, use :func:`warp_perspective`. Passed here
+ unchanged, such a homography is read as a normalized destination→source one, which typically samples outside
+ the source, so the output is mostly or entirely zeros (with the default ``padding_mode="zeros"``).
+ ``normalized_homography=False`` instead hands it to :func:`warp_perspective` with this function's
+ ``align_corners=False`` default, which for a pixel homography samples the same positions as
+ ``align_corners=True`` (see ``align_corners`` below).
See :class:`~kornia.geometry.transform.HomographyWarper` for details.
@@ -2052,7 +2060,12 @@ def homography_warp3d(
align_corners: bool = False,
normalized_coordinates: bool = True,
) -> torch.Tensor:
- r"""Warp image patches or tensors by 3D homographies.
+ r"""Warp a volume by a normalized destination→source 3D homography (default ``normalized_coordinates=True``).
+
+ For a source→destination homography in voxel coordinates, use :func:`warp_perspective3d` with
+ ``align_corners=True``: at its default ``align_corners=False`` it resamples even an identity
+ (`#4503 <https://github.com/kornia/kornia/issues/4503>`_). Alternatively pass the inverse of that homography
+ here with ``normalized_coordinates=False``. This function has no ``normalized_homography`` switch.
Convention:
- input: :math:`(N, C, D, H, W)`; ``dsize`` is the output size ``(d, h, w)``
diff --git a/tests/augmentation/test_docstring_probability.py b/tests/augmentation/test_docstring_probability.py
new file mode 100644
index 000000000..2d0499832
--- /dev/null
+++ b/tests/augmentation/test_docstring_probability.py
@@ -0,0 +1,68 @@
+# LICENSE HEADER MANAGED BY add-license-header
+#
+# Copyright 2018 Kornia Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""The first docstring line of an augmentation that is not always applied states its default ``p``.
+
+``help()``, ``inspect.getdoc`` and API listings show the first docstring line first, and a reader who stops
+there must not miss that ``RandomRotation(degrees=30.0)`` leaves about half of the batch unrotated. Every
+public class in ``kornia.augmentation.__all__`` whose constructor defaults ``p`` below ``1`` therefore says
+"probability ``p`` (default <value>)" on that line. A new class with such a default is picked up here.
+"""
+
+import inspect
+
+import pytest
+
+import kornia.augmentation as K
+
+
+def _classes_with_partial_default_p() -> list[tuple[str, float]]:
+ found = []
+ for name in K.__all__:
+ obj = getattr(K, name)
+ if not inspect.isclass(obj):
+ continue
+ param = inspect.signature(obj.__init__).parameters.get("p")
+ if param is None or not isinstance(param.default, (int, float)):
+ continue
+ if param.default < 1:
+ found.append((name, param.default))
+ return found
+
+
+_CLASSES = _classes_with_partial_default_p()
+
+
+def test_the_discovery_finds_the_known_classes():
+ found = dict(_CLASSES)
+ # A guard against a vacuous pass: the discovery must keep seeing the classes it was written for.
+ assert found["RandomRotation"] == 0.5
+ assert found["RandomGrayscale"] == 0.1
+ assert found["RandomMosaic"] == 0.7
+ assert found["RandomAffine3D"] == 0.5
+ assert found["AugmentationBase2D"] == 0.5
+ assert len(found) >= 57
+
+
[email protected](("name", "default"), _CLASSES, ids=[name for name, _ in _CLASSES])
+def test_first_docstring_line_states_the_default_probability(name, default):
+ first_line = next(iter((inspect.getdoc(getattr(K, name)) or "").splitlines()), "")
+
+ assert f"probability ``p`` (default {default})" in first_line, (
+ f"{name} defaults to p={default}; its first docstring line must say "
+ f"'probability ``p`` (default {default})'. Got: {first_line!r}"
+ )