π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
fix(augmentation): draw RandomPosterize's bits uniformly over closed integer range (#6339)
Pushkar Shahif3da7ba6aaf8
diff --git a/changelog.d/6339.fixed.md b/changelog.d/6339.fixed.mdnew file mode 100644index 000000000..ba927fd97--- /dev/null+++ b/changelog.d/6339.fixed.md@@ -0,0 +1 @@+`RandomPosterize` now draws `bits` uniformly over the whole numbers of its closed range. The draw used to be a continuous number that was then rounded, which gave the two end points half the probability of interior values: `bits=(0, 8)` drew 0 and 8 about half as often as values 1 through 7 (#6334). The auto-augment `Posterize` op draws through the same generator, so `TrivialAugment`'s posterize draws over `(4, 8)` are now uniform too; `RandAugment` sets the magnitude directly and `AutoAugment`'s posterize bins have fractional bounds, so neither changes. Seeded draws therefore differ from earlier releases. A range with a fractional bound is drawn as before.diff --git a/kornia/augmentation/_2d/intensity/posterize.py b/kornia/augmentation/_2d/intensity/posterize.pyindex 68e5aa456..0a8556079 100644--- a/kornia/augmentation/_2d/intensity/posterize.py+++ b/kornia/augmentation/_2d/intensity/posterize.py@@ -35,8 +35,9 @@ class RandomPosterize(IntensityAugmentationBase2D):Args:p: probability of applying the transformation.bits: number of high bits to keep, in ``[0, 8]``, in which 0 gives a black image and 8 gives the- original. A non-integral argument is accepted; the drawn factor is rounded to an integer, half to- even, so ``2.5`` gives ``2`` and ``3.5`` gives ``4``.+ 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+ rounded to an integer, half to even, so ``2.5`` gives ``2`` and ``3.5`` gives ``4``.If int x, bits will be generated from (x, 8) then convert to int.If tuple (x, y), bits will be generated from (x, y) then convert to int.same_on_batch: apply the same transformation across the batch.diff --git a/kornia/augmentation/random_generator/_2d/posterize.py b/kornia/augmentation/random_generator/_2d/posterize.pyindex 98cf839d7..ff81a5f6f 100644--- a/kornia/augmentation/random_generator/_2d/posterize.py+++ b/kornia/augmentation/random_generator/_2d/posterize.py@@ -29,8 +29,11 @@ __all__ = ["PosterizeGenerator"]class PosterizeGenerator(RandomGeneratorBase):r"""Generate random posterize parameters for a batch of images.+ A range of whole numbers is closed and uniform: every whole number from the lower to the upper bound is+ drawn with the same probability. A range with a fractional bound keeps the continuous draw and rounds it.+Args:- bits: floats that ranged from (0, 8], in which 0 gives black image and 8 gives the original.+ bits: floats that ranged from [0, 8], in which 0 gives black image and 8 gives the original.If float x, bits will be generated from (x, 8).If tuple (x, y), bits will be generated from (x, y).@@ -53,6 +56,7 @@ class PosterizeGenerator(RandomGeneratorBase):return f"bits={self.bits_factor}"def make_samplers(self, device: torch.device, dtype: torch.dtype) -> None:+ r"""Create uniform distribution samplers for the bits parameter on the target device."""bits = torch.as_tensor(self.bits_factor, device=device, dtype=dtype)if len(bits.size()) == 0:bits = bits.repeat(2)@@ -60,11 +64,26 @@ class PosterizeGenerator(RandomGeneratorBase):elif not (len(bits.size()) == 1 and bits.size(0) == 2):raise ValueError(f"'bits' shall be either a scalar or a length 2 torch.Tensor. Got {bits}.")_joint_range_check(bits, "bits", (0, 8))- self.bit_sampler = UniformDistribution(bits[0], bits[1], validate_args=False)+ self._whole_range = bool(bits.round().eq(bits).all())+ if self._whole_range:+ # The sampler covers ``[lo, hi + 1)`` and ``forward`` floors the draw, so every whole number from ``lo``+ # to ``hi`` owns a bucket of width one. Rounding a draw on ``[lo, hi]`` gave the two end points half of+ # that width, so ``bits=(0, 8)`` drew ``0`` and ``8`` about half as often as the interior values (#6334).+ self.bit_sampler = UniformDistribution(bits[0], bits[1] + 1, validate_args=False)+ else:+ self.bit_sampler = UniformDistribution(bits[0], bits[1], validate_args=False)def forward(self, batch_shape: Tuple[int, ...], same_on_batch: bool = False) -> Dict[str, torch.Tensor]:+ r"""Sample random bits factors for the given batch shape."""batch_size = batch_shape[0]_common_param_check(batch_size, same_on_batch)_device, _ = _extract_device_dtype([self.bits_factor if isinstance(self.bits_factor, torch.Tensor) else None])bits_factor = _adapted_rsampling((batch_size,), self.bit_sampler, same_on_batch)- return {"bits_factor": bits_factor.round().to(device=_device, dtype=torch.int32)}+ if getattr(self, "_whole_range", False):+ # The clamp removes the excluded end point: for the largest draw ``u = 1 - 2 ** -24``,+ # ``lo + u * (hi + 1 - lo)`` rounds up onto ``hi + 1`` for a range such as ``(1, 1)``,+ # which ``floor`` would keep.+ bits_factor = bits_factor.floor().clamp(max=self.bit_sampler.high - 1)+ else:+ bits_factor = bits_factor.round()+ return {"bits_factor": bits_factor.to(device=_device, dtype=torch.int32)}diff --git a/tests/augmentation/test_conventions_intensity_values.py b/tests/augmentation/test_conventions_intensity_values.pyindex 3b82958c0..661d32d03 100644--- a/tests/augmentation/test_conventions_intensity_values.py+++ b/tests/augmentation/test_conventions_intensity_values.py@@ -25,7 +25,7 @@ import torchimport kornia.augmentation as Kfrom kornia.augmentation._2d.intensity.base import _clamp_unit_range-from kornia.augmentation.random_generator import RectangleEraseGenerator+from kornia.augmentation.random_generator import PosterizeGenerator, RectangleEraseGeneratorfrom kornia.core._compat import torch_version_gefrom kornia.core.exceptions import AsyncCheckError, BaseError, ShapeErrorfrom kornia.enhance import (@@ -792,6 +792,84 @@ class TestIntensityColourConventions(BaseTester):assert int(drawn.min()) == bitsassert int(drawn.max()) == 8+ # RandomPosterize used to draw a continuous number on [lo, hi] and round it, which gave the endpoints half+ # the probability of interior values (#6334). Whole-number ranges are now uniform over [lo, hi].+ # The pin allows 15% around the uniform count, 8 sigma for 3000 draws per value.+ @pytest.mark.device_agnostic+ @pytest.mark.parametrize("bits", [(0, 8), (1, 4), 3, (5, 7)])+ def test_convention_random_posterize_bits_are_closed_and_uniform_6334(self, bits):+ """Check that RandomPosterize draws whole numbers uniformly across closed range."""+ if isinstance(bits, int):+ low, high = bits, 8+ else:+ low, high = bits+ count = high - low + 1+ torch.manual_seed(0)+ drawn = K.RandomPosterize(bits=bits, p=1.0).forward_parameters((count * 3000, 1, 4, 4))["bits_factor"]++ assert drawn.dtype == torch.int32+ assert (int(drawn.min()), int(drawn.max())) == (low, high)+ counts = torch.bincount((drawn - low).long(), minlength=count)+ expected = drawn.numel() / count+ assert bool(((counts > 0.85 * expected) & (counts < 1.15 * expected)).all()), counts.tolist()++ @pytest.mark.device_agnostic+ def test_convention_random_posterize_same_on_batch_shares_one_whole_number_6334(self):+ """Check that same_on_batch draws a single uniform whole number across the batch."""+ torch.manual_seed(0)+ drawn = K.RandomPosterize((0, 8), p=1.0, same_on_batch=True).forward_parameters((16, 1, 4, 4))["bits_factor"]++ assert drawn.shape == (16,)+ assert bool((drawn == drawn[0]).all())+ assert drawn.dtype == torch.int32++ # The excluded end point of the half-open sampler range is clamped back: for the largest draw+ # ``u = 1 - 2 ** -24``, ``lo + u * (hi + 1 - lo)`` rounds up onto ``hi + 1`` in float32.+ @pytest.mark.device_agnostic+ @pytest.mark.parametrize("bits", [(1, 1), (0, 0), (8, 8), (0, 8), (3, 5)])+ def test_convention_random_posterize_largest_draw_stays_in_the_closed_range_6334(self, monkeypatch, bits):+ """Check that upper bound draw is clamped within closed range."""+ largest = 1 - 2**-24+ real_rand = torch.rand+ monkeypatch.setattr(torch, "rand", lambda *args, **kwargs: torch.full_like(real_rand(*args, **kwargs), largest))+ drawn = K.RandomPosterize(bits=bits, p=1.0).forward_parameters((4, 1, 4, 4))["bits_factor"]++ high = bits[1] if isinstance(bits, tuple) else (8 if isinstance(bits, int) else int(bits))+ assert drawn.tolist() == [high] * 4++ # A range with a fractional bound is not a closed range of whole numbers, so it keeps the continuous draw+ # and rounds half-to-even.+ @pytest.mark.device_agnostic+ def test_convention_random_posterize_fractional_range_6334(self, monkeypatch):+ """Check that fractional ranges preserve continuous draw with round half-to-even."""+ # Force continuous draws that are half-to-even ties on range (1.5, 4.5) with span 3.0:+ # 1.5 + (1/3) * 3.0 = 2.5 -> rounds to 2 (even)+ # 1.5 + (2/3) * 3.0 = 3.5 -> rounds to 4 (even)+ u = torch.tensor([1.0 / 3.0, 2.0 / 3.0])+ monkeypatch.setattr(+ torch, "rand", lambda *args, **kwargs: u.to(device=kwargs.get("device"), dtype=kwargs.get("dtype"))+ )+ drawn_controlled = K.RandomPosterize(bits=(1.5, 4.5), p=1.0).forward_parameters((2, 1, 4, 4))["bits_factor"]+ assert drawn_controlled.tolist() == [2, 4]++ monkeypatch.undo()+ torch.manual_seed(0)+ drawn = K.RandomPosterize(bits=(1.5, 4.5), p=1.0).forward_parameters((6000, 1, 4, 4))["bits_factor"]+ assert int(drawn.min()) >= 1+ assert int(drawn.max()) <= 5++ def test_convention_random_posterize_generator_supports_mps_device_6334(self):+ """Check that PosterizeGenerator avoids float64 conversion on MPS device."""+ if not torch.backends.mps.is_available():+ pytest.skip("MPS device not available")+ generator = PosterizeGenerator(torch.tensor([0, 8], device="mps"))+ params = generator(torch.Size([4]))+ assert params["bits_factor"].device.type == "mps"++ generator_tuple = PosterizeGenerator((0, 8))+ generator_tuple.set_rng_device_and_dtype(device=torch.device("mps"), dtype=torch.float32)+ assert generator_tuple.bit_sampler.low.device.type == "mps"+# The factor blends linearly between the blurred image (0) and the input (1); above 1 it sharpens.# Snippet used to generate expected:# torch.manual_seed(0); print((K.RandomSharpness((f, f), p=1.0)(x) - x).abs().max())diff --git a/tests/augmentation/test_random_generator.py b/tests/augmentation/test_random_generator.pyindex 4cf3d7170..dd495e7ed 100644--- a/tests/augmentation/test_random_generator.py+++ b/tests/augmentation/test_random_generator.py@@ -1569,7 +1569,7 @@ class TestRandomPosterizeGen(RandomGeneratorBaseTests):torch.manual_seed(9)batch_size = 8res = PosterizeGenerator(bits=torch.tensor([0, 8], device=device, dtype=dtype))(torch.Size([batch_size]))- expected = {"bits_factor": torch.tensor([5, 2, 4, 6, 7, 7, 2, 8], device=device, dtype=torch.int32)}+ expected = {"bits_factor": torch.tensor([5, 2, 4, 6, 8, 8, 2, 8], device=device, dtype=torch.int32)}assert res.keys() == expected.keys()assert_close(res["bits_factor"], expected["bits_factor"], rtol=1e-4, atol=1e-4)