Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

docs(augmentation): document p_batch as an attribute of every augmentation (#6330)

Omkar Kabde36cf72c80057
diff --git a/changelog.d/6330.added.md b/changelog.d/6330.added.md
new file mode 100644
index 000000000..b8f62e695
--- /dev/null
+++ b/changelog.d/6330.added.md
@@ -0,0 +1 @@
+The augmentation docs state that every augmentation honours `p_batch` and that it can be set as an attribute; only `RandomHorizontalFlip`, `RandomVerticalFlip`, `RandomTransplantation` and `RandomTransplantation3D` take it in the constructor.
diff --git a/docs/source/augmentation.base.rst b/docs/source/augmentation.base.rst
index 5dbddf29e..94d3f0d61 100644
--- a/docs/source/augmentation.base.rst
+++ b/docs/source/augmentation.base.rst
@@ -208,10 +208,12 @@ Some Further Notes
Probabilities
^^^^^^^^^^^^^
-:class:`AugmentationBase2D` states the ``p`` / ``p_batch`` model. A concrete constructor can map its public ``p``
-to either gate: `RandomMixUpV2` gates the batch and `RandomJigsaw` individual samples
-(`#4425 <https://github.com/kornia/kornia/issues/4425>`_). When ``0 < p_batch < 1``, the base draws the batch
-Bernoulli before the per-sample gate; endpoints skip that draw, and ``p=1.0, p_batch=0.0`` selects no sample.
+:class:`AugmentationBase2D` states the ``p`` / ``p_batch`` model. Every augmentation honours ``p_batch``, and it can
+be set as an attribute (``aug.p_batch = 0.5``). Only `RandomHorizontalFlip`, `RandomVerticalFlip`,
+`RandomTransplantation` and `RandomTransplantation3D` also take it in the constructor. A concrete constructor can map
+its public ``p`` to either gate: `RandomMixUpV2` gates the batch and `RandomJigsaw` individual samples. When
+``0 < p_batch < 1``, the base draws the batch Bernoulli before the per-sample gate; endpoints skip that draw, and
+``p=1.0, p_batch=0.0`` selects no sample.
With static ``p=1.0, p_batch=1.0`` every sample is transformed: a ``batch_prob`` put into ``params`` is not consulted
by the image, the transformation matrix, the labels or ``inverse``, in eager and compiled runs alike
diff --git a/docs/source/get-started/conventions.rst b/docs/source/get-started/conventions.rst
index c5f4d4d0f..679328ccc 100644
--- a/docs/source/get-started/conventions.rst
+++ b/docs/source/get-started/conventions.rst
@@ -589,9 +589,11 @@ Randomness in augmentations
order of ``ColorJiggle`` and ``ColorJitter`` is shared across the batch
regardless. On ``AugmentationSequential``, ``same_on_batch=None`` keeps each
child's setting, and ``True`` or ``False`` overwrites it.
-- Whether a constructor's ``p`` sets the per-sample or the whole-batch gate,
- and whether it exposes ``p_batch``, depends on the concrete class
- (`#4425 <https://github.com/kornia/kornia/issues/4425>`_). A sample the gate
+- Every augmentation honours ``p_batch`` as an attribute, and only
+ ``RandomHorizontalFlip``, ``RandomVerticalFlip``, ``RandomTransplantation``
+ and ``RandomTransplantation3D`` take it in the constructor; whether a
+ constructor's ``p`` sets the per-sample or the whole-batch gate depends on
+ the concrete class. A sample the gate
skips comes back with its input values, its values cannot make the call
raise, and where they are finite its gradient is the identity. Below ``p=1``
the transform still runs on the whole batch before the gate selects; classes
diff --git a/kornia/augmentation/_2d/base.py b/kornia/augmentation/_2d/base.py
index d1fe70804..f76d83a1b 100644
--- a/kornia/augmentation/_2d/base.py
+++ b/kornia/augmentation/_2d/base.py
@@ -85,7 +85,7 @@ class AugmentationBase2D(_AugmentationBase):
(`#4424 <https://github.com/kornia/kornia/issues/4424>`_).
- 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``;
- see `#4425 <https://github.com/kornia/kornia/issues/4425>`_. A sample the gate skips comes back
+ it can be set as an attribute on any augmentation. A sample the gate skips comes back
with its input values, its values cannot make the call raise, and where they are finite its gradient
is the identity; a class whose transform checks input values or has an unbounded derivative runs it
on 0.5 for skipped samples. An augmentation that changes the sample shape still raises ``ValueError``
diff --git a/kornia/augmentation/_2d/mix/cutmix.py b/kornia/augmentation/_2d/mix/cutmix.py
index d44bf6a66..8e53cdca0 100644
--- a/kornia/augmentation/_2d/mix/cutmix.py
+++ b/kornia/augmentation/_2d/mix/cutmix.py
@@ -80,8 +80,8 @@ class RandomCutMixV2(MixAugmentationBaseV2):
``2 ** 24`` stay exact.
``use_correct_lambda=True`` returns ``1 - cut_area / image_area``;
the compatibility default returns ``cut_area / image_area`` and emits a deprecation warning.
- - ``p`` is a batch-wide gate applied once, unlike the per-sample ``p`` of :class:`RandomJigsaw`
- (`#4425 <https://github.com/kornia/kornia/issues/4425>`_): ``_params["batch_prob"]`` is all ones or all zeros,
+ - ``p`` is a batch-wide gate applied once, unlike the per-sample ``p`` of :class:`RandomJigsaw`:
+ ``_params["batch_prob"]`` is all ones or all zeros,
and every row and mix of a selected batch receives a cut, though self-pairing or a zero-sized cut can
leave a row unchanged. With ``same_on_batch=False`` each row and mix draws its own cut size and placement;
``same_on_batch=True`` shares each mix's cut size and placement across rows; each mix still draws its own
diff --git a/kornia/augmentation/_2d/mix/mixup.py b/kornia/augmentation/_2d/mix/mixup.py
index f4b253291..2e0c6a9d9 100644
--- a/kornia/augmentation/_2d/mix/mixup.py
+++ b/kornia/augmentation/_2d/mix/mixup.py
@@ -82,8 +82,8 @@ class RandomMixUpV2(MixAugmentationBaseV2):
``input * (1 - lambda) + paired_input * lambda``. Labels must be one-dimensional and are returned as
floating values in the image dtype, except that a ``float16`` or ``bfloat16`` image yields ``float32``
labels so integer class ids up to ``2 ** 24`` stay exact.
- - ``p`` is a batch-wide gate applied once, unlike the per-sample ``p`` of :class:`RandomJigsaw`
- (`#4425 <https://github.com/kornia/kornia/issues/4425>`_): ``_params["batch_prob"]`` is all ones or all zeros,
+ - ``p`` is a batch-wide gate applied once, unlike the per-sample ``p`` of :class:`RandomJigsaw`:
+ ``_params["batch_prob"]`` is all ones or all zeros,
and every row of a selected batch draws its lambda from ``lambda_val``. At ``p=0`` the image is unchanged
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.
diff --git a/kornia/augmentation/_2d/mix/patchmix.py b/kornia/augmentation/_2d/mix/patchmix.py
index ed9cff2bd..a02e3b1fd 100644
--- a/kornia/augmentation/_2d/mix/patchmix.py
+++ b/kornia/augmentation/_2d/mix/patchmix.py
@@ -52,7 +52,7 @@ 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 (`#4425 <https://github.com/kornia/kornia/issues/4425>`_).
+ - ``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.
diff --git a/kornia/augmentation/_3d/base.py b/kornia/augmentation/_3d/base.py
index 037030bfd..60cbf8761 100644
--- a/kornia/augmentation/_3d/base.py
+++ b/kornia/augmentation/_3d/base.py
@@ -48,7 +48,8 @@ class AugmentationBase3D(_AugmentationBase):
only.
- ``p`` gates samples and ``p_batch`` gates a whole call; ``same_on_batch=True`` shares the generated
values. Of the concrete 3D constructors only :class:`~kornia.augmentation.RandomTransplantation3D`
- exposes ``p_batch`` (`#4425 <https://github.com/kornia/kornia/issues/4425>`_); :class:`CenterCrop3D` and
+ exposes ``p_batch`` in its constructor, though it can be set as an attribute on any 3D augmentation;
+ :class:`CenterCrop3D` and
:class:`RandomCrop3D` instead map their own ``p`` onto the call-wide gate. Parameters use the common
augmentation RNG and ``forward(x, params=...)`` replays a complete generated dictionary. See
:doc:`/get-started/conventions` for the canonical sampling, seeding, and serialization contract.
diff --git a/tests/augmentation/test_base.py b/tests/augmentation/test_base.py
index d5a94e00a..88791aec6 100644
--- a/tests/augmentation/test_base.py
+++ b/tests/augmentation/test_base.py
@@ -595,7 +595,7 @@ class TestConventionAugmentationBase2D(BaseTester):
assert any(len(set(row)) > 1 for row in rows)
@pytest.mark.parametrize("augmentation_cls", [K.RandomMixUpV2, K.RandomCutMixV2, K.PatchMix])
- def test_wart_mixup_cutmix_and_patchmix_map_p_to_a_batch_gate_4425(self, augmentation_cls):
+ def test_convention_mixup_cutmix_and_patchmix_map_p_to_a_batch_gate_4425(self, augmentation_cls):
# Their constructors map `p` to the mix base's batch-wide probability, unlike Jigsaw and Mosaic.
rows = []
for seed in range(8):
@@ -609,6 +609,21 @@ class TestConventionAugmentationBase2D(BaseTester):
assert all(len(set(row)) == 1 for row in rows)
assert {row[0] for row in rows} == {0.0, 1.0}
+ @pytest.mark.parametrize(
+ ("factory", "shape"),
+ [
+ (lambda: K.RandomAffine(30.0, p=1.0), (2, 3, 6, 8)),
+ (lambda: K.RandomRotation3D(30.0, p=1.0), (2, 1, 4, 6, 8)),
+ ],
+ )
+ def test_convention_p_batch_attribute_gates_any_augmentation_4425(self, factory, shape, device, dtype):
+ aug = factory()
+ aug.p_batch = 0.0
+ x = torch.rand(shape, device=device, dtype=dtype)
+ out = aug(x)
+ assert torch.equal(out, x)
+ assert not aug._params["batch_prob"].any()
+
@pytest.mark.parametrize(
"augmentation_cls", [K.RandomMixUpV2, K.RandomCutMixV2, K.PatchMix, K.RandomJigsaw, K.RandomMosaic]
)