π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-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.mdnew file mode 100644index 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.rstindex 5dbddf29e..94d3f0d61 100644--- a/docs/source/augmentation.base.rst+++ b/docs/source/augmentation.base.rst@@ -208,10 +208,12 @@ Some Further NotesProbabilities^^^^^^^^^^^^^-: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 consultedby the image, the transformation matrix, the labels or ``inverse``, in eager and compiled runs alikediff --git a/docs/source/get-started/conventions.rst b/docs/source/get-started/conventions.rstindex c5f4d4d0f..679328ccc 100644--- a/docs/source/get-started/conventions.rst+++ b/docs/source/get-started/conventions.rst@@ -589,9 +589,11 @@ Randomness in augmentationsorder of ``ColorJiggle`` and ``ColorJitter`` is shared across the batchregardless. On ``AugmentationSequential``, ``same_on_batch=None`` keeps eachchild'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 gateskips comes back with its input values, its values cannot make the callraise, 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; classesdiff --git a/kornia/augmentation/_2d/base.py b/kornia/augmentation/_2d/base.pyindex 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 backwith its input values, its values cannot make the call raise, and where they are finite its gradientis the identity; a class whose transform checks input values or has an unbounded derivative runs iton 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.pyindex 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 canleave 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 owndiff --git a/kornia/augmentation/_2d/mix/mixup.py b/kornia/augmentation/_2d/mix/mixup.pyindex 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 asfloating 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 unchangedand the class output holds the original label twice with a zero lambda. ``same_on_batch=True`` sharesthe 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.pyindex 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`` isstored 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.pyindex 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 generatedvalues. 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 commonaugmentation 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.pyindex 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])