Skip to content

🐍 Geometric Computer Vision Library for Spatial 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.md
new file mode 100644
index 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.py
index 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.py
index 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.py
index 3b82958c0..661d32d03 100644
--- a/tests/augmentation/test_conventions_intensity_values.py
+++ b/tests/augmentation/test_conventions_intensity_values.py
@@ -25,7 +25,7 @@ import torch
import kornia.augmentation as K
from kornia.augmentation._2d.intensity.base import _clamp_unit_range
-from kornia.augmentation.random_generator import RectangleEraseGenerator
+from kornia.augmentation.random_generator import PosterizeGenerator, RectangleEraseGenerator
from kornia.core._compat import torch_version_ge
from kornia.core.exceptions import AsyncCheckError, BaseError, ShapeError
from kornia.enhance import (
@@ -792,6 +792,84 @@ class TestIntensityColourConventions(BaseTester):
assert int(drawn.min()) == bits
assert 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.py
index 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 = 8
res = 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)