π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
# 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.
#
from __future__ import annotations
import copy
import inspect
import io
import itertools
import pickle
import pytest
import torch
from torch.distributions import Distribution
import kornia.augmentation as K
from kornia.constants import BorderType, Resample
from kornia.core.exceptions import BaseError, ImageError, ShapeError
from kornia.filters import box_blur
from testing.base import (
DYNAMO_UNAVAILABLE_REASON,
BaseTester,
dynamo_is_available,
supports_reflect_padding,
supports_replicate_padding,
)
@pytest.fixture(autouse=True)
def _restore_global_rng(restore_torch_rng):
# The pins below seed the global RNG; the root fixture (#4446) restores every generator afterwards.
return
# The seed drawn immediately before each construct-and-forward.
_FORWARD_SEED = 0
_FIXTURE_SEED = 1234
def _sync(device) -> None:
# MPS dispatches asynchronously, so a kernel error raised by the forward under test would
# otherwise surface inside an unrelated later test.
if device.type == "mps":
torch.mps.synchronize()
def _lit_extent(plane: torch.Tensor, threshold: float = 1e-3) -> tuple[list[int], list[int]]:
"""Return the sorted distinct rows and columns of a single ``(H, W)`` plane above ``threshold``."""
indices = (plane.float().abs() > threshold).nonzero()
return sorted({int(row) for row, _ in indices}), sorted({int(col) for _, col in indices})
def _impulse(device, dtype, height: int = 7, width: int = 9, row: int = 2, col: int = 3) -> torch.Tensor:
"""A non-square zero image with a single 1.0 off both centre lines (7x9 centres are row 3, col 4)."""
image = torch.zeros(1, 1, height, width, device=device, dtype=dtype)
image[0, 0, row, col] = 1.0
return image
class TestBlurConventions(BaseTester):
# ``kernel_size`` is ``(kH, kW)``, also checked under relabelling (transposed image and kernel).
# Snippet used to generate expected:
# x = torch.zeros(1, 1, 7, 9); x[0, 0, 3, 4] = 1.0
# for ks in ((1, 5), (5, 1)):
# torch.manual_seed(0); y = K.RandomBoxBlur(ks, p=1.0)(x); print(ks, (y[0, 0] > 0).nonzero().T.tolist())
@pytest.mark.parametrize("name", ["RandomBoxBlur", "RandomGaussianBlur"])
def test_convention_blur_kernel_size_is_height_then_width(self, device, dtype, name):
if not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
factories = {
"RandomBoxBlur": lambda ks: K.RandomBoxBlur(ks, p=1.0),
"RandomGaussianBlur": lambda ks: K.RandomGaussianBlur(ks, (1.0, 1.0), p=1.0),
}
make = factories[name]
# Hot pixel on the 7x9 centre.
centred = _impulse(device, dtype, row=3, col=4)
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((1, 5))(centred)[0, 0]) == ([3], [2, 3, 4, 5, 6])
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((5, 1))(centred)[0, 0]) == ([1, 2, 3, 4, 5], [4])
# The same claim with the impulse off both centre lines, so no literal is its own transpose.
image = _impulse(device, dtype)
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((1, 5))(image)[0, 0]) == ([2], [1, 2, 3, 4, 5])
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((5, 1))(image)[0, 0]) == ([0, 1, 2, 3, 4], [3])
# Relabelling check: transpose the image and the kernel, and the support transposes too.
transposed = image.transpose(-1, -2).contiguous()
assert transposed.shape[-2:] == (9, 7)
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((5, 1))(transposed)[0, 0]) == ([1, 2, 3, 4, 5], [2])
torch.manual_seed(_FORWARD_SEED)
assert _lit_extent(make((1, 5))(transposed)[0, 0]) == ([3], [0, 1, 2, 3, 4])
def test_convention_median_blur_border_median_uses_reflect_padding(self, device, dtype):
# A constant-ones image: reflect padding reflects the boundary ones into the padding window,
# so corner, edge, and center windows all hold only ones and their medians evaluate to 1.
ones = torch.ones(1, 1, 4, 4, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomMedianBlur((3, 3), p=1.0)(ones)
assert float(out[0, 0, 0, 0]) == 1.0
assert float(out[0, 0, 0, 1]) == 1.0
assert float(out[0, 0, 1, 1]) == 1.0
# 5x5 on a 6x6 image: reflect padding preserves the constant value across the border,
# so the top row consists entirely of ones.
torch.manual_seed(_FORWARD_SEED)
wide = K.RandomMedianBlur((5, 5), p=1.0)(torch.ones(1, 1, 6, 6, device=device, dtype=dtype))
self.assert_close(wide[0, 0, 0], ones.new_tensor([1.0, 1.0, 1.0, 1.0, 1.0, 1.0]))
def test_convention_box_blur_even_kernel_is_accepted_and_off_centre(self, device, dtype):
# Snippet used to generate expected:
# imp = torch.zeros(1, 1, 7, 9); imp[0, 0, 3, 4] = 1.0
# for ks in ((2, 2), (4, 4), (3, 4)):
# torch.manual_seed(0); nz = K.RandomBoxBlur(ks, p=1.0)(imp)[0, 0].nonzero()
# print(ks, nz[:, 0].unique().tolist(), nz[:, 1].unique().tolist())
if not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
impulse = torch.zeros(1, 1, 7, 9, device=device, dtype=dtype)
impulse[0, 0, 3, 4] = 1.0
for kernel_size, rows, cols in (
((2, 2), [2, 3], [3, 4]),
((4, 4), [1, 2, 3, 4], [2, 3, 4, 5]),
((3, 4), [2, 3, 4], [2, 3, 4, 5]),
):
torch.manual_seed(_FORWARD_SEED)
out = K.RandomBoxBlur(kernel_size, p=1.0)(impulse)
lit = out[0, 0].nonzero()
assert lit[:, 0].unique().tolist() == rows
assert lit[:, 1].unique().tolist() == cols
self.assert_close(out.sum(), impulse.sum())
# A rank filter cannot be read off an impulse, so the detector is a one-row bar. A (1, kW) window slides
# along that row and keeps it; a (kH, 1) window spans five rows of which four are zero, so the median is
# zero and the bar is erased.
# Snippet used to generate expected:
# bar = torch.zeros(1, 1, 7, 9); bar[0, 0, 3, :] = 1.0
# for ks in ((1, 5), (5, 1)):
# torch.manual_seed(0); print(ks, K.RandomMedianBlur(ks, p=1.0)(bar)[0, 0].sum(-1).tolist())
def test_convention_median_blur_kernel_size_is_height_then_width(self, device, dtype):
bar = torch.zeros(1, 1, 7, 9, device=device, dtype=dtype)
bar[0, 0, 3, :] = 1.0
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.RandomMedianBlur((1, 5), p=1.0)(bar)[0, 0].sum(-1), bar.new_tensor([0, 0, 0, 9, 0, 0, 0]))
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.RandomMedianBlur((5, 1), p=1.0)(bar)[0, 0].sum(-1), bar.new_zeros(7))
# Off the centre row, and then transposed, so the surviving axis is not a symmetry of the fixture.
off_centre = torch.zeros(1, 1, 7, 9, device=device, dtype=dtype)
off_centre[0, 0, 2, :] = 1.0
torch.manual_seed(_FORWARD_SEED)
kept = K.RandomMedianBlur((1, 5), p=1.0)(off_centre)[0, 0].sum(-1)
self.assert_close(kept, off_centre.new_tensor([0, 0, 9, 0, 0, 0, 0]))
transposed = off_centre.transpose(-1, -2).contiguous()
torch.manual_seed(_FORWARD_SEED)
kept_t = K.RandomMedianBlur((5, 1), p=1.0)(transposed)[0, 0].sum(-2)
self.assert_close(kept_t, transposed.new_tensor([0, 0, 9, 0, 0, 0, 0]))
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.RandomMedianBlur((1, 5), p=1.0)(transposed)[0, 0].sum(-2), transposed.new_zeros(7))
# Fixed (#4781, https://github.com/kornia/kornia/issues/4781): an even entry used to be accepted at
# construction and then fail on every image size with a raw torch error. It is now rejected at
# construction with kornia's odd-size error.
@pytest.mark.parametrize("kernel_size", [(4, 4), (3, 4)])
def test_convention_random_median_blur_even_kernel_is_rejected_4781(self, kernel_size):
with pytest.raises(BaseError) as raised:
K.RandomMedianBlur(kernel_size, p=1.0)
assert "Kernel size must be an odd integer" in str(raised.value)
# ``normalized`` is forwarded as box_blur's ``separable``; both branches are means and agree to rounding.
# Snippet used to generate expected:
# torch.manual_seed(1234); x = torch.rand(2, 3, 7, 9)
# torch.manual_seed(0); yt = K.RandomBoxBlur((3, 3), normalized=True, p=1.0)(x)
# print(torch.equal(yt, box_blur(x, (3, 3), "reflect", separable=True)))
def test_convention_random_box_blur_normalized_selects_separable_box_blur(self, device, dtype):
if not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(2, 3, 7, 9).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
separable = K.RandomBoxBlur((3, 3), normalized=True, p=1.0)(image)
torch.manual_seed(_FORWARD_SEED)
joint = K.RandomBoxBlur((3, 3), normalized=False, p=1.0)(image)
assert torch.equal(separable, box_blur(image, (3, 3), "reflect", separable=True))
assert torch.equal(joint, box_blur(image, (3, 3), "reflect", separable=False))
assert not torch.equal(separable, box_blur(image, (3, 3), "reflect", separable=False))
# Both branches are the same mean, so they agree to float rounding.
self.assert_close(separable, joint)
# A mean leaves a constant image alone; a sum would multiply it by nine.
constant = torch.full((2, 3, 7, 9), 0.375, device=device, dtype=dtype)
for normalized in (True, False):
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.RandomBoxBlur((3, 3), normalized=normalized, p=1.0)(constant), constant)
# One scalar sigma per sample (a (B,) tensor), and the defaults are gaussian_blur2d's own.
# Snippet used to generate expected:
# aug = K.RandomGaussianBlur((3, 3), (0.5, 1.5), p=1.0)
# torch.manual_seed(0); aug(torch.rand(4, 3, 7, 9)); print(aug._params["sigma"].shape, aug.flags)
def test_convention_random_gaussian_blur_draws_one_sigma_per_sample(self, device, dtype):
if not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 7, 9).to(device=device, dtype=dtype)
aug = K.RandomGaussianBlur((3, 3), (0.5, 1.5), p=1.0)
torch.manual_seed(_FORWARD_SEED)
aug(image)
sigma = aug._params["sigma"]
assert sigma.shape == (4,)
assert len(set(sigma.flatten().tolist())) == 4
assert float(sigma.min()) >= 0.5
assert float(sigma.max()) <= 1.5
# Reach, not only containment: a draw shrunk to `[0.5, 0.6]` satisfies the bounds above.
torch.manual_seed(_FORWARD_SEED)
many = aug.forward_parameters((256, 3, 7, 9))["sigma"]
assert float(many.min()) < 0.6
assert float(many.max()) > 1.4
assert aug.flags["separable"] is True
assert aug.flags["border_type"] == BorderType.REFLECT
assert aug.flags["kernel_size"] == (3, 3)
# One parameter away: same_on_batch collapses the same key to a single repeated value.
shared = K.RandomGaussianBlur((3, 3), (0.5, 1.5), p=1.0, same_on_batch=True)
torch.manual_seed(_FORWARD_SEED)
shared(image)
assert len(set(shared._params["sigma"].flatten().tolist())) == 1
# An even kernel_size is rejected with gaussian_blur2d's own "odd integer" error, whatever the image
# size: a 2x2 image is below the reflect minimum, so a size check that ran first would blame the image.
# Snippet used to generate expected:
# torch.manual_seed(0); K.RandomGaussianBlur((4, 4), (0.1, 1.0), p=1.0)(torch.rand(1, 1, 2, 2))
@pytest.mark.parametrize(
("kernel_size", "shape"), [((2, 2), (4, 3, 7, 9)), ((4, 4), (1, 1, 2, 2)), ((3, 4), (1, 1, 2, 2))]
)
def test_convention_random_gaussian_blur_rejects_even_kernel_size(self, device, dtype, kernel_size, shape):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(*shape).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(BaseError, match="odd integer"):
_sync(K.RandomGaussianBlur(kernel_size, (0.1, 1.0), p=1.0)(image).device)
# ``angle`` is counter-clockwise as displayed; the impulse sits off both centre lines, so no literal
# is its own transpose.
# Snippet used to generate expected:
# x = torch.zeros(1, 1, 7, 9); x[0, 0, 2, 3] = 1.0
# for a in (0.0, 45.0, -45.0, 90.0):
# torch.manual_seed(0)
# print(a, (K.RandomMotionBlur(5, (a, a), (0.0, 0.0), p=1.0)(x)[0, 0].abs() > 1e-6).nonzero().tolist())
@pytest.mark.parametrize(
("angle", "support"),
[
(0.0, [(2, 1), (2, 2), (2, 3), (2, 4), (2, 5)]),
(45.0, [(1, 4), (2, 3), (3, 2)]),
(-45.0, [(1, 2), (2, 3), (3, 4)]),
(90.0, [(0, 3), (1, 3), (2, 3), (3, 3), (4, 3)]),
],
)
def test_convention_random_motion_blur_angle_is_counter_clockwise(self, device, dtype, angle, support):
image = _impulse(device, dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomMotionBlur(5, (angle, angle), (0.0, 0.0), p=1.0)(image)
lit = [(int(row), int(col)) for row, col in (out[0, 0].float().abs() > 1e-6).nonzero()]
assert sorted(lit) == support
# ``direction`` re-weights the kernel along its own axis (-1 start, +1 end, 0 uniform), on two angles.
# Snippet used to generate expected:
# x = torch.zeros(1, 1, 7, 9); x[0, 0, 2, 3] = 1.0
# for d in (-1.0, 0.0, 1.0):
# torch.manual_seed(0); print(K.RandomMotionBlur(5, (0.0, 0.0), (d, d), p=1.0)(x)[0, 0, 2].tolist())
# torch.manual_seed(0); print(K.RandomMotionBlur(5, (90.0, 90.0), (d, d), p=1.0)(x)[0, 0, :, 3].tolist())
@pytest.mark.parametrize(
("direction", "along_row", "along_col"),
[
(-1.0, [0.0, 0.4, 0.3, 0.2, 0.1, 0.0, 0.0, 0.0, 0.0], [0.0, 0.1, 0.2, 0.3, 0.4, 0.0, 0.0]),
(0.0, [0.0, 0.2, 0.2, 0.2, 0.2, 0.2, 0.0, 0.0, 0.0], [0.2, 0.2, 0.2, 0.2, 0.2, 0.0, 0.0]),
(1.0, [0.0, 0.0, 0.1, 0.2, 0.3, 0.4, 0.0, 0.0, 0.0], [0.4, 0.3, 0.2, 0.1, 0.0, 0.0, 0.0]),
],
)
def test_convention_random_motion_blur_direction_weights_the_kernel_axis(
self, device, dtype, direction, along_row, along_col
):
image = _impulse(device, dtype)
torch.manual_seed(_FORWARD_SEED)
horizontal = K.RandomMotionBlur(5, (0.0, 0.0), (direction, direction), p=1.0)(image)
self.assert_close(horizontal[0, 0, 2], image.new_tensor(along_row))
torch.manual_seed(_FORWARD_SEED)
vertical = K.RandomMotionBlur(5, (90.0, 90.0), (direction, direction), p=1.0)(image)
self.assert_close(vertical[0, 0, :, 3], image.new_tensor(along_col))
# The weighted line is rotated with ``resample``; a "nearest" rotation at 45 degrees keeps three of the
# five taps. The impulse response is the kernel, so these are its taps.
# Snippet used to generate expected:
# x = torch.zeros(1, 1, 9, 9); x[0, 0, 4, 4] = 1.0
# for angle in (0.0, 45.0):
# torch.manual_seed(0); y = K.RandomMotionBlur(5, (angle, angle), (1.0, 1.0), p=1.0)(x)
# print(angle, sorted(y[y > 0].tolist()))
def test_convention_random_motion_blur_nearest_rotation_resamples_the_taps(self, device, dtype):
image = _impulse(device, dtype, height=9, width=9, row=4, col=4)
taps = {}
for angle in (0.0, 45.0):
torch.manual_seed(_FORWARD_SEED)
out = K.RandomMotionBlur(5, (angle, angle), (1.0, 1.0), p=1.0)(image)
taps[angle] = out[out.abs() > 1e-3].sort().values
self.assert_close(taps[0.0], image.new_tensor([0.1, 0.2, 0.3, 0.4]))
self.assert_close(taps[45.0], image.new_tensor([1.0, 2.0, 3.0]) / 6.0)
# The class's resample="nearest" is motion_blur's mode="nearest", but it zero-pads by its own default, not reflect.
@pytest.mark.device_agnostic
def test_convention_random_motion_blur_defaults_are_constant_and_nearest(self):
aug = K.RandomMotionBlur(3, (45.0, 45.0), (0.0, 0.0), p=1.0)
assert aug.flags["border_type"] == BorderType.CONSTANT
assert aug.flags["resample"] == Resample.NEAREST
# Every odd size in a tuple range is drawn in near-equal shares, bounds included (#4599); an even upper
# bound caps at the odd size below it, and a range holding no odd size rounds up (``(4, 4)`` draws 5).
# The size is shared within a batch (#4671), so independent calls are sampled.
# Snippet used to generate expected:
# torch.manual_seed(0); aug = K.RandomMotionBlur(ks, (0., 0.), (0., 0.), p=1.)
# v = torch.cat([aug.forward_parameters((1, 1, 8, 8))["ksize_factor"] for _ in range(20000)])
@pytest.mark.device_agnostic
@pytest.mark.parametrize(
("kernel_size", "drawn"),
[
((3, 5), [3, 5]),
((3, 7), [3, 5, 7]),
((5, 11), [5, 7, 9, 11]),
((3, 20), [3, 5, 7, 9, 11, 13, 15, 17, 19]),
((4, 7), [5, 7]),
((4, 4), [5]),
],
)
def test_convention_random_motion_blur_draws_every_odd_size_in_the_range_4599(self, kernel_size, drawn):
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomMotionBlur(kernel_size, (0.0, 0.0), (0.0, 0.0), p=1.0)
factors = torch.cat([aug.forward_parameters((1, 1, 8, 8))["ksize_factor"] for _ in range(20000)])
counts = torch.stack([(factors == k).sum() for k in drawn])
assert sorted(set(factors.tolist())) == drawn
# Near-equal shares: each size within 10% of 20000 / len(drawn).
expected = 20000 / len(drawn)
assert bool(((counts - expected).abs() < 0.1 * expected).all()), counts.tolist()
# Issue #4671: the stored sizes describe the shared kernel actually applied to every image.
def test_convention_random_motion_blur_stored_kernel_sizes_match_impulse_widths_4671(self, device, dtype):
image = torch.zeros(8, 1, 17, 17, device=device, dtype=dtype)
image[:, :, 8, 8] = 1
aug = K.RandomMotionBlur((3, 9), (0.0, 0.0), (0.0, 0.0), p=1.0)
drawn = set()
for seed in range(8):
torch.manual_seed(seed)
output = aug(image)
# A horizontal, uniform blur spreads an impulse across exactly kernel_size pixels.
widths = (output[:, 0, 8] != 0).sum(-1)
assert widths.tolist() == aug._params["ksize_factor"].tolist()
assert widths.unique().numel() == 1
drawn.update(widths.tolist())
assert len(drawn) > 1
# At ``border_type="reflect"`` a "nearest" or "bilinear" kernel rotation stays inside the input's
# extremes; "bicubic" gives the kernel negative lobes that overshoot both at an edge.
# Snippet used to generate expected:
# x = torch.zeros(1, 1, 15, 15); x[..., 7:] = 1.0
# torch.manual_seed(0)
# print(K.RandomMotionBlur(5, (80., 80.), (1., 1.), border_type="reflect", resample="bicubic", p=1.)(x).aminmax())
def test_convention_random_motion_blur_reflect_bound_depends_on_resample(self, device, dtype):
if not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
edge = torch.zeros(1, 1, 15, 15, device=device, dtype=dtype)
edge[..., 7:] = 1.0
for resample in ("nearest", "bilinear"):
torch.manual_seed(_FORWARD_SEED)
out = K.RandomMotionBlur(5, (80.0, 80.0), (1.0, 1.0), border_type="reflect", resample=resample, p=1.0)(edge)
assert float(out.min()) >= -1e-3, resample
assert float(out.max()) <= 1.0 + 1e-3, resample
torch.manual_seed(_FORWARD_SEED)
out = K.RandomMotionBlur(5, (80.0, 80.0), (1.0, 1.0), border_type="reflect", resample="bicubic", p=1.0)(edge)
assert float(out.min()) < -0.02
assert float(out.max()) > 1.02
# The four filters do not clamp: a 1.1 impulse is attenuated below one, and the output is linear in the
# input (for the median blur, a negative plateau stays negative), so no wrapper clamp is hiding in there.
@pytest.mark.parametrize("name", ["RandomBoxBlur", "RandomGaussianBlur", "RandomMedianBlur", "RandomMotionBlur"])
def test_convention_filters_attenuate_an_out_of_range_impulse_without_clamping(self, device, dtype, name):
if name in ("RandomBoxBlur", "RandomGaussianBlur") and not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
factories = {
"RandomBoxBlur": lambda: K.RandomBoxBlur((3, 3), p=1.0),
"RandomGaussianBlur": lambda: K.RandomGaussianBlur((3, 3), (1.0, 1.0), p=1.0),
"RandomMedianBlur": lambda: K.RandomMedianBlur((3, 3), p=1.0),
"RandomMotionBlur": lambda: K.RandomMotionBlur(3, (0.0, 0.0), (0.0, 0.0), p=1.0),
}
make = factories[name]
impulse = torch.zeros(1, 1, 7, 7, device=device, dtype=dtype)
impulse[0, 0, 3, 3] = 1.1
out = make()(impulse)
assert float(out.min()) >= 0.0
assert float(out.max()) <= 1.0
if name == "RandomMedianBlur":
self.assert_close(out, torch.zeros_like(out))
# A negative plateau has a negative median and must come back negative.
negative = torch.full((1, 1, 7, 7), -0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
assert float(make()(negative).min()) < -0.4, "the wrapper clamped the median into [0, 1]"
return
half_impulse = impulse * 0.5
self.assert_close(out, make()(half_impulse) * 2.0)
self.assert_close(make()(-half_impulse), -make()(half_impulse))
# Issue #4559: RandomBoxBlur, RandomGaussianBlur and RandomSharpness raise a kornia `ValueError` naming
# the class, the kernel and the input shape. The two blurs reflect-pad, so an axis must be longer than the
# kernel radius (`k // 2`, one pixel for the 3x3 default); RandomSharpness convolves without padding, so
# it needs the full 3x3. RandomMedianBlur reflect-pads as well and raises the same error, while
# RandomMotionBlur, at its default constant border, accepts the degenerate image.
# Snippet used to generate expected:
# for shape in ((2, 3, 1, 8), (2, 3, 2, 2), (2, 3, 3, 3)):
# x = torch.rand(*shape)
# torch.manual_seed(0); K.RandomBoxBlur(p=1.0)(x) # and the four other classes
def test_convention_blur_and_sharpness_name_the_size_they_need_4559(self, device, dtype):
# Only the legs that reflect-pad are skipped where reflection_pad2d is unavailable.
reflect_ok = supports_reflect_padding(device, dtype)
torch.manual_seed(_FIXTURE_SEED)
thin = torch.rand(2, 3, 1, 8).to(device=device, dtype=dtype)
small = torch.rand(2, 3, 2, 2).to(device=device, dtype=dtype)
square = torch.rand(2, 3, 3, 3).to(device=device, dtype=dtype)
blurs = {
"RandomBoxBlur": lambda: K.RandomBoxBlur(p=1.0),
"RandomGaussianBlur": lambda: K.RandomGaussianBlur((3, 3), (1.0, 1.0), p=1.0),
}
for name, make in blurs.items():
if not reflect_ok:
continue
torch.manual_seed(_FORWARD_SEED)
# kornia's own error, raised before the filter runs, so it is device- and dtype-independent.
with pytest.raises(ValueError, match=rf"{name} cannot filter an image this small"):
_sync(make()(thin).device)
torch.manual_seed(_FORWARD_SEED)
assert make()(small).shape == small.shape, f"{name} should still accept a 2x2 image"
# The threshold is per axis, half the kernel's extent along that axis: a (7, 3) kernel runs on a
# 2-column image (2 > 3 // 2) and raises on a 3-row one (3 <= 7 // 2), in both classes.
rectangular = {
"RandomBoxBlur": lambda: K.RandomBoxBlur((7, 3), p=1.0),
"RandomGaussianBlur": lambda: K.RandomGaussianBlur((7, 3), (1.0, 1.0), p=1.0),
}
narrow = torch.rand(2, 3, 20, 2).to(device=device, dtype=dtype)
short = torch.rand(2, 3, 3, 20).to(device=device, dtype=dtype)
for name, make in rectangular.items():
if not reflect_ok:
continue
torch.manual_seed(_FORWARD_SEED)
assert make()(narrow).shape == narrow.shape
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match=rf"{name} cannot filter an image this small"):
_sync(make()(short).device)
# the message names the axis that is too short, not just the kernel
with pytest.raises(ValueError, match="along height"):
make()(short)
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match="RandomSharpness cannot filter an image this small"):
_sync(K.RandomSharpness(1.0, p=1.0)(small).device)
torch.manual_seed(_FORWARD_SEED)
assert K.RandomSharpness(1.0, p=1.0)(square).shape == square.shape
# RandomMedianBlur reflect-pads, so it refuses the one-row image with the same named error, before the
# filter runs; RandomMotionBlur, at its default constant border, still accepts it.
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match="RandomMedianBlur cannot filter an image this small"):
_sync(K.RandomMedianBlur(p=1.0)(thin).device)
if reflect_ok:
torch.manual_seed(_FORWARD_SEED)
assert K.RandomMedianBlur(p=1.0)(small).shape == small.shape
torch.manual_seed(_FORWARD_SEED)
assert K.RandomMotionBlur(3, (45.0, 45.0), (0.0, 0.0), p=1.0)(thin).shape == thin.shape
# ``border_type="circular"`` needs each axis at least the kernel radius (``k // 2``): the two padding
# blurs raise kornia's named error below it, while ``"constant"`` and ``"replicate"`` run there.
# Snippet used to generate expected:
# torch.manual_seed(1234); thin = torch.rand(2, 3, 3, 12)
# for bt in ("constant", "replicate", "circular"):
# torch.manual_seed(0); K.RandomBoxBlur((9, 9), border_type=bt, p=1.)(thin)
def test_convention_circular_padding_rejects_images_smaller_than_kernel_radius_4559(self, device, dtype):
if not supports_replicate_padding(device, dtype):
pytest.skip("replication_pad2d is unavailable for this device/dtype")
torch.manual_seed(_FIXTURE_SEED)
thin = torch.rand(2, 3, 3, 12).to(device=device, dtype=dtype)
blurs = {
"RandomBoxBlur": lambda border: K.RandomBoxBlur((9, 9), border_type=border, p=1.0),
"RandomGaussianBlur": lambda border: K.RandomGaussianBlur((9, 9), (1.0, 1.0), border_type=border, p=1.0),
}
for name, make in blurs.items():
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match=rf"{name} cannot filter an image this small"):
_sync(make("circular")(thin).device)
for border in ("constant", "replicate"):
torch.manual_seed(_FORWARD_SEED)
assert make(border)(thin).shape == thin.shape, f"{name} at {border} should accept a 3-row image"
# RandomMotionBlur has the same minimum size as the padding blurs under ``"reflect"`` and ``"circular"``
# and raises the same named ValueError below it (#4784); the controls below it do not move.
@pytest.mark.parametrize(
("border", "kernel_size", "shape"), [("reflect", 3, (2, 3, 1, 8)), ("circular", 5, (2, 3, 1, 1))]
)
def test_convention_random_motion_blur_names_the_size_it_needs_4784(
self, device, dtype, border, kernel_size, shape
):
if border == "reflect" and not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(*shape).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomMotionBlur(kernel_size, (45.0, 45.0), (0.0, 0.0), border_type=border, p=1.0)
with pytest.raises(ValueError, match="RandomMotionBlur cannot filter an image this small"):
_sync(aug(image).device)
# A ranged kernel_size is checked against the size drawn for the call.
torch.manual_seed(_FORWARD_SEED)
ranged = K.RandomMotionBlur((kernel_size, kernel_size), (45.0, 45.0), (0.0, 0.0), border_type=border, p=1.0)
with pytest.raises(ValueError, match="RandomMotionBlur cannot filter an image this small"):
_sync(ranged(image).device)
# The default constant border runs on the same image, and one radius less runs under circular.
torch.manual_seed(_FORWARD_SEED)
assert K.RandomMotionBlur(kernel_size, (45.0, 45.0), (0.0, 0.0), p=1.0)(image).shape == image.shape
if border == "circular":
torch.manual_seed(_FORWARD_SEED)
smaller = K.RandomMotionBlur(3, (45.0, 45.0), (0.0, 0.0), border_type=border, p=1.0)
assert smaller(image).shape == image.shape
# An even extent ``k`` is padded asymmetrically, so the minimum size follows the wider pad ``k // 2``:
# reflect needs ``k // 2 + 1`` pixels and circular ``k // 2``.
# Snippet used to generate expected:
# for k in range(1, 9):
# front, rear = (k - 1) // 2, k - 1 - (k - 1) // 2
# for mode in ("reflect", "circular"):
# min(s for s in range(1, 12) if F.pad(torch.rand(1, 1, s, s), [front, rear] * 2, mode=mode))
@pytest.mark.parametrize(
"kernel, border, too_small, big_enough",
[
((4, 4), "reflect", (1, 1, 2, 2), (1, 1, 3, 3)),
((4, 4), "circular", (1, 1, 1, 1), (1, 1, 2, 2)),
((2, 2), "reflect", (1, 1, 1, 1), (1, 1, 2, 2)),
((6, 6), "reflect", (1, 1, 3, 3), (1, 1, 4, 4)),
((6, 6), "circular", (1, 1, 2, 2), (1, 1, 3, 3)),
# the odd-extent circular boundary: `(k + 1) // 2` agrees with `k // 2` on every even row
# above, and only an odd kernel at its exact minimum tells them apart
((5, 5), "circular", (1, 1, 1, 1), (1, 1, 2, 2)),
],
)
def test_convention_even_kernels_use_the_wider_asymmetric_pad_4559(
self, kernel, border, too_small, big_enough, device, dtype
):
if border == "reflect" and not supports_reflect_padding(device, dtype):
pytest.skip("reflection_pad2d is unavailable for this device/dtype")
torch.manual_seed(_FIXTURE_SEED)
small = torch.rand(*too_small).to(device=device, dtype=dtype)
large = torch.rand(*big_enough).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match="RandomBoxBlur cannot filter an image this small"):
_sync(K.RandomBoxBlur(kernel, border_type=border, p=1.0)(small).device)
# one pixel more and it is kornia's job to run, not to refuse
torch.manual_seed(_FORWARD_SEED)
assert K.RandomBoxBlur(kernel, border_type=border, p=1.0)(large).shape == large.shape
# the modes that invent their padding are untouched by the widening
for invented in ("constant", "replicate"):
if invented == "replicate" and not supports_replicate_padding(device, dtype):
continue
torch.manual_seed(_FORWARD_SEED)
assert K.RandomBoxBlur(kernel, border_type=invented, p=1.0)(small).shape == small.shape
# Zero padding pulls a border pixel toward 0: below the minimum of a positive image, above the maximum
# of a negative one.
# Snippet used to generate expected:
# neg = torch.full((1, 1, 7, 7), -1.0)
# torch.manual_seed(0); print(K.RandomBoxBlur((3, 3), border_type="constant", p=1.0)(neg).aminmax())
@pytest.mark.parametrize("name", ["RandomBoxBlur", "RandomGaussianBlur", "RandomMotionBlur"])
def test_convention_constant_border_pulls_the_border_toward_zero(self, device, dtype, name):
factories = {
"RandomBoxBlur": lambda: K.RandomBoxBlur((3, 3), border_type="constant", p=1.0),
"RandomGaussianBlur": lambda: K.RandomGaussianBlur((3, 3), (1.0, 1.0), border_type="constant", p=1.0),
"RandomMotionBlur": lambda: K.RandomMotionBlur(3, (0.0, 0.0), (0.0, 0.0), border_type="constant", p=1.0),
}
positive = torch.full((1, 1, 7, 7), 1.0, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
positive_out = factories[name]()(positive)
low, high = positive_out.aminmax()
assert float(low) < 1.0, "a positive image is pulled below its minimum"
assert float(high) <= 1.0 + 1e-3, "a positive image is pulled below its minimum"
negative = torch.full((1, 1, 7, 7), -1.0, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
negative_out = factories[name]()(negative)
low, high = negative_out.aminmax()
assert float(high) > -1.0, "a negative image is pulled above its maximum, not below its minimum"
assert float(low) >= -1.0 - 1e-3
# Toward zero and not another constant ``v``: ``out(+1) + out(-1) = 2 * (1 - s) * v`` vanishes only at 0.
self.assert_close(positive_out + negative_out, torch.zeros_like(positive_out), atol=1e-6, rtol=0)
class TestNoiseAndWeatherConventions(BaseTester):
# ``scale`` is the target area fraction, ``ratio`` is height / width, the box is the half-open
# ``[ys, ys + h) x [xs, xs + w)`` in ``_params``, and ``value`` is the literal fill.
# Snippet used to generate expected:
# x = torch.ones(1, 1, 10, 20)
# torch.manual_seed(0); aug = K.RandomErasing(scale=(0.25, 0.25), ratio=(2.0, 2.0), p=1.0); y = aug(x)
# print((y != 1).sum(), {k: v.flatten().tolist() for k, v in aug._params.items()})
@pytest.mark.parametrize(("ratio", "value", "height", "width"), [(2.0, 0.0, 10, 5), (0.5, 0.3, 5, 10)])
def test_convention_random_erasing_scale_is_area_and_ratio_is_height_over_width(
self, device, dtype, ratio, value, height, width
):
image = torch.ones(1, 1, 10, 20, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomErasing(scale=(0.25, 0.25), ratio=(ratio, ratio), value=value, p=1.0)
out = aug(image)
params = aug._params
assert int(params["heights"][0]) == height
assert int(params["widths"][0]) == width
erased = out != 1.0
assert int(erased.sum()) == 50 == int(0.25 * image.numel())
# The box is exactly [ys, ys + h) x [xs, xs + w) -- half open, so the extents are h and w.
rows, cols = _lit_extent(erased[0, 0].to(dtype))
y_start, x_start = int(params["ys"][0]), int(params["xs"][0])
assert rows == list(range(y_start, y_start + height))
assert cols == list(range(x_start, x_start + width))
self.assert_close(out[erased], out.new_full((50,), value))
# The target box for scale 0.25 and ratio 3 on 10x20 is about 12.2 x 4.1: rounded to 12 x 4, then
# clipped to the 10-row image, so 40 of the 50 requested pixels are erased.
# Snippet used to generate expected:
# torch.manual_seed(0); aug = K.RandomErasing(scale=(0.25, 0.25), ratio=(3.0, 3.0), p=1.0)
# y = aug(torch.ones(1, 1, 10, 20)); print((y != 1).sum(), aug._params["heights"], aug._params["widths"])
def test_convention_random_erasing_box_is_rounded_and_clipped(self, device, dtype):
image = torch.ones(1, 1, 10, 20, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomErasing(scale=(0.25, 0.25), ratio=(3.0, 3.0), p=1.0)
out = aug(image)
assert (int(aug._params["heights"][0]), int(aug._params["widths"][0])) == (10, 4)
assert int((out != 1.0).sum()) == 40
# A ``mask`` data key is erased in the same box, but filled with 0 rather than the image's ``value``.
# Snippet used to generate expected:
# torch.manual_seed(0)
# seq = K.AugmentationSequential(K.RandomErasing(scale=(0.25, 0.25), ratio=(2.0, 2.0), value=0.3, p=1.0),
# data_keys=["input", "mask"])
# oi, om = seq(torch.ones(1, 1, 10, 20), torch.ones(1, 1, 10, 20))
def test_convention_random_erasing_erases_the_mask_in_the_same_box(self, device, dtype):
image = torch.ones(1, 1, 10, 20, device=device, dtype=dtype)
mask = torch.ones(1, 1, 10, 20, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
pipeline = K.AugmentationSequential(
K.RandomErasing(scale=(0.25, 0.25), ratio=(2.0, 2.0), value=0.3, p=1.0), data_keys=["input", "mask"]
)
out_image, out_mask = pipeline(image, mask)
image_box = (out_image != 1.0)[0, 0]
mask_box = (out_mask != 1.0)[0, 0]
assert int(image_box.sum()) == 50
assert torch.equal(image_box, mask_box)
# The image carries `value`, the mask carries 0.
self.assert_close(out_image[out_image != 1.0], out_image.new_full((50,), 0.3))
self.assert_close(out_mask[mask_box[None, None]], out_mask.new_zeros(50))
# The noise is added unclamped and recorded in full under ``_params["gaussian_noise"]``; ``mean`` is
# an offset, not a target.
def test_convention_random_gaussian_noise_is_additive_and_unclamped(self, device, dtype):
constant = torch.full((2, 3, 7, 9), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomGaussianNoise(mean=0.0, std=1.0, p=1.0)
noisy = aug(constant)
assert float(noisy.min()) < 0.0
assert float(noisy.max()) > 1.0
assert aug._params["gaussian_noise"].shape == constant.shape
self.assert_close(noisy, constant + aug._params["gaussian_noise"].to(device=device, dtype=dtype))
# std=0 makes the addition exact, which is what pins `mean` as an offset and not a target.
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.RandomGaussianNoise(mean=2.0, std=0.0, p=1.0)(constant), constant + 2.0)
# Parameter fields use the batched BCHW shape even when ``keepdim`` restores a CHW output.
@pytest.mark.parametrize(
"name",
[
"RandomGaussianNoise",
"RandomGaussianIllumination",
"RandomLinearIllumination",
"RandomLinearCornerIllumination",
"RandomPlasmaBrightness",
"RandomPlasmaContrast",
"RandomPlasmaShadow",
],
)
@pytest.mark.parametrize("keepdim", [False, True])
def test_convention_intensity_parameter_fields_normalize_chw_shape(self, device, dtype, name, keepdim):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(3, 7, 9).to(device=device, dtype=dtype)
aug, field_name, field_channels = _field_augmentation(name, keepdim=keepdim)
torch.manual_seed(_FORWARD_SEED)
out = aug(image)
assert out.shape == (image.shape if keepdim else (1, *image.shape))
assert aug._params[field_name].shape == (1, field_channels, *image.shape[-2:])
assert torch.equal(out, aug(image, params=aug._params))
# At a partial probability the stored field keeps the full batch length; unselected rows pass through
# and the parameter state replays exactly.
@pytest.mark.parametrize(
"name",
[
"RandomGaussianNoise",
"RandomGaussianIllumination",
"RandomLinearIllumination",
"RandomLinearCornerIllumination",
"RandomPlasmaBrightness",
"RandomPlasmaContrast",
"RandomPlasmaShadow",
],
)
def test_convention_intensity_parameter_fields_keep_original_batch_for_partial_probability(
self, device, dtype, name
):
# B=16 makes an all-or-nothing gate at p=0.5 unlikely (2 * 2 ** -16).
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(16, 3, 7, 9).to(device=device, dtype=dtype)
aug, field_name, field_channels = _field_augmentation(name, p=0.5)
torch.manual_seed(_FORWARD_SEED)
out = aug(image)
selected = aug._params["batch_prob"].bool()
assert 0 < int(selected.sum()) < image.shape[0]
assert aug._params[field_name].shape == (image.shape[0], field_channels, *image.shape[-2:])
assert torch.equal(out[~selected], image[~selected])
assert torch.equal(out, aug(image, params=aug._params))
def test_convention_gaussian_noise_same_on_batch_shares_one_normalized_field(self, device, dtype):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 7, 9).to(device=device, dtype=dtype)
aug = K.RandomGaussianNoise(mean=0.0, std=1.0, p=1.0, same_on_batch=True)
torch.manual_seed(_FORWARD_SEED)
out = aug(image)
noise = aug._params["gaussian_noise"]
assert noise.shape == (1, *image.shape[1:])
self.assert_close(out, image + noise.to(device=device, dtype=dtype).expand_as(image))
# ``amount`` is a per-pixel fraction (the rewrite mask is the same in every channel) and
# ``salt_vs_pepper`` the salt share of the rewritten pixels; both are asserted within five binomial
# standard deviations.
@pytest.mark.parametrize("amount", [0.1, 0.3, 0.6])
def test_convention_random_salt_and_pepper_amount_is_a_pixel_fraction(self, device, dtype, amount):
image = torch.full((2, 3, 96, 160), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomSaltAndPepperNoise(amount=(amount, amount), salt_vs_pepper=(0.25, 0.25), p=1.0)(image)
changed = out != 0.5
assert torch.equal(changed[:, 0], changed[:, 1])
assert torch.equal(changed[:, 0], changed[:, 2])
pixels = changed[:, 0].numel()
fraction = float(changed[:, 0].float().mean())
assert abs(fraction - amount) < 5.0 * (amount * (1.0 - amount) / pixels) ** 0.5
# salt_vs_pepper splits the touched pixels; 0.25 means a quarter of them go to salt.
salt = float((out[:, 0] == 1.0).float().sum())
pepper = float((out[:, 0] == 0.0).float().sum())
touched = salt + pepper
assert abs(salt / touched - 0.25) < 5.0 * (0.25 * 0.75 / touched) ** 0.5
# The poles are the literals 1.0 and 0.0 whatever the input's range.
# Snippet used to generate expected:
# torch.manual_seed(0)
# K.RandomSaltAndPepperNoise(amount=(0.3, 0.3), salt_vs_pepper=(1.0, 1.0), p=1.0)(torch.full((2, 3, 12, 20), 2.0))
@pytest.mark.parametrize(("salt_vs_pepper", "written"), [(1.0, 1.0), (0.0, 0.0)])
def test_convention_random_salt_and_pepper_writes_literal_zero_and_one(
self, device, dtype, salt_vs_pepper, written
):
image = torch.full((2, 3, 12, 20), 2.0, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomSaltAndPepperNoise(amount=(0.3, 0.3), salt_vs_pepper=(salt_vs_pepper, salt_vs_pepper), p=1.0)(
image
)
changed = out != 2.0
assert int(changed.sum()) > 0
self.assert_close(out[changed], out.new_full((int(changed.sum()),), written))
# The other pole is never written at this setting.
assert not bool((out == (1.0 - written)).any())
# ``drop_height`` runs down rows and ``drop_width`` along columns, also on the transposed image.
# Snippet used to generate expected:
# torch.manual_seed(0); aug = K.RandomRain(number_of_drops=(1, 1), drop_height=(6, 6), drop_width=(1, 1), p=1.0)
# print((aug(torch.zeros(1, 1, 12, 30))[0, 0] > 0).nonzero().tolist())
@pytest.mark.parametrize(("drop_height", "drop_width"), [(6, 1), (1, 6)])
def test_convention_random_rain_drop_height_runs_down_rows(self, device, dtype, drop_height, drop_width):
def extents(image: torch.Tensor) -> tuple[int, int]:
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomRain(
number_of_drops=(1, 1),
drop_height=(drop_height, drop_height),
drop_width=(drop_width, drop_width),
p=1.0,
)
rows, cols = _lit_extent(aug(image)[0, 0])
return len(rows), len(cols)
tall_rows, tall_cols = extents(torch.zeros(1, 1, 12, 30, device=device, dtype=dtype))
if drop_height > drop_width:
assert tall_rows >= 5
assert tall_cols <= 2
else:
assert tall_cols >= 5
assert tall_rows <= 2
# On a 30x12 image the arguments still mean rows and columns.
wide_rows, wide_cols = extents(torch.zeros(1, 1, 30, 12, device=device, dtype=dtype))
if drop_height > drop_width:
assert wide_rows >= 5
assert wide_cols <= 2
else:
assert wide_cols >= 5
assert wide_rows <= 2
# A drop is the literal 200/255, not a function of the image.
def test_convention_random_rain_drop_value_is_two_hundred_over_255(self, device, dtype):
image = torch.full((1, 1, 12, 30), 2.0, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomRain(number_of_drops=(5, 5), drop_height=(3, 3), drop_width=(1, 1), p=1.0)(image)
self.assert_close(out.min(), out.new_tensor(200 / 255))
self.assert_close(out.max(), out.new_tensor(2.0))
# A drop as tall or as wide as the image is rejected with kornia's error on the forward pass (the
# image size is only known there), and one pixel smaller runs.
@pytest.mark.parametrize(("drop_height", "drop_width", "message"), [(12, 1, "Height of drop"), (1, 30, "Width of")])
def test_convention_random_rain_rejects_a_drop_as_large_as_the_image(
self, device, dtype, drop_height, drop_width, message
):
image = torch.zeros(1, 1, 12, 30, device=device, dtype=dtype)
# Constructing an oversized drop is allowed; only the forward, which knows the image, raises.
aug = K.RandomRain(
number_of_drops=(1, 1),
drop_height=(drop_height, drop_height),
drop_width=(drop_width, drop_width),
p=1.0,
)
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(BaseError, match=message):
_sync(aug(image).device)
# One pixel smaller on the same axis runs.
inside_height, inside_width = min(drop_height, 11), min(drop_width, 29)
torch.manual_seed(_FORWARD_SEED)
smaller = K.RandomRain(
number_of_drops=(1, 1),
drop_height=(inside_height, inside_height),
drop_width=(inside_width, inside_width),
p=1.0,
)
assert smaller(image).shape == image.shape
# Issue #4810: each nonzero declared dimension is a pixel count, so lines have no skipped row or column.
# Snippet used to generate expected:
# torch.manual_seed(0)
# y = K.RandomRain(number_of_drops=(1, 1), drop_height=(h, h), drop_width=(w, w), p=1.0)(image)
# print((y[0, 0] != 0).nonzero().tolist())
@pytest.mark.parametrize(
("height", "width", "offsets"),
[
(2, 0, [[0, 0], [1, 0]]),
(5, 0, [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]]),
(1, 5, [[0, 0], [0, 1], [0, 2], [0, 3], [0, 4]]),
(3, 5, [[0, 0], [0, 1], [1, 2], [1, 3], [2, 4]]),
(5, 5, [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4]]),
(5, -3, [[0, 2], [1, 2], [2, 1], [3, 1], [4, 0]]),
(5, -5, [[0, 4], [1, 3], [2, 2], [3, 1], [4, 0]]),
],
)
def test_convention_random_rain_drop_is_contiguous_4810(self, device, dtype, height, width, offsets):
image = torch.zeros(1, 1, 8, 10, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomRain(number_of_drops=(1, 1), drop_height=(height, height), drop_width=(width, width), p=1.0)(
image
)
lit = (out[0, 0] != 0).nonzero()
relative = lit - lit.min(dim=0).values
assert relative.tolist() == offsets
@pytest.mark.device_agnostic
def test_convention_random_rain_negative_width_reaches_left_edge_4810(self, monkeypatch):
real_rand = torch.rand
monkeypatch.setattr(torch, "rand", lambda *a, **kw: torch.zeros_like(real_rand(*a, **kw)))
aug = K.RandomRain(number_of_drops=(1, 1), drop_height=(2, 2), drop_width=(-2, -2), p=1.0)
lit = (aug(torch.zeros(1, 1, 6, 10))[0, 0] != 0).nonzero().tolist()
assert sorted(lit) == [[0, 1], [1, 0]]
# The three integer ranges are closed and uniform (#4567), including signed widths that straddle or
# end at zero. The 15% band is wide for the 16-bin height at 22000 draws; what it has to separate is
# a factor of two (a truncating draw gives ``0`` twice its share).
# Snippet used to generate expected:
# torch.manual_seed(0)
# p = K.RandomRain(number_of_drops=(2, 4), drop_height=(5, 20), drop_width=(-5, 5), p=1.0)
# print(torch.bincount(p.forward_parameters((22000, 1, 64, 64))["drop_width_factor"] + 5))
@pytest.mark.device_agnostic
@pytest.mark.parametrize("drop_width", [(-5, 5), (-1, 1), (-5, -1), (-3, 0)])
def test_convention_random_rain_integer_ranges_are_closed_and_uniform(self, drop_width):
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomRain(number_of_drops=(2, 4), drop_height=(5, 20), drop_width=drop_width, p=1.0)
params = aug.forward_parameters((22000, 1, 64, 64))
for key, low, high in (
("number_of_drops_factor", 2, 4),
("drop_height_factor", 5, 20),
("drop_width_factor", *drop_width),
):
drawn = params[key].flatten()
assert drawn.dtype == torch.long
assert (int(drawn.min()), int(drawn.max())) == (low, high), key
counts = torch.bincount(drawn - low, minlength=high - low + 1)
expected = drawn.numel() / (high - low + 1)
assert bool(((counts > 0.85 * expected) & (counts < 1.15 * expected)).all()), (key, counts.tolist())
# The largest ``torch.rand`` value maps onto ``hi + 1`` in float32 (``5 + (1 - 2 ** -24) * 16 == 21.0``);
# kornia clamps it back to ``hi``.
@pytest.mark.device_agnostic
def test_convention_random_rain_largest_draw_stays_inside_the_closed_range(self, monkeypatch):
largest = 1 - 2**-24
real_rand = torch.rand
monkeypatch.setattr(torch, "rand", lambda *args, **kwargs: torch.full_like(real_rand(*args, **kwargs), largest))
aug = K.RandomRain(number_of_drops=(2, 4), drop_height=(5, 20), drop_width=(-5, 5), p=1.0)
params = aug.forward_parameters((4, 1, 64, 64))
# The patch has to reach the generator's own draws, or the pin below is vacuous.
assert float(params["coordinates_factor"].min()) == largest
assert params["number_of_drops_factor"].tolist() == [4, 4, 4, 4]
assert params["drop_height_factor"].tolist() == [20, 20, 20, 20]
assert params["drop_width_factor"].tolist() == [5, 5, 5, 5]
# Each integer range is validated at construction: reversed, fractional, non-finite or not a pair is
# a ValueError naming the argument.
@pytest.mark.device_agnostic
@pytest.mark.parametrize(
"bounds",
[(6, 5), (0.5, 2.5), (1, 2.5), (float("nan"), 5), (5, float("nan")), (1, float("inf")), (1, 2, 3), (1,), 5],
)
@pytest.mark.parametrize("name", ["number_of_drops", "drop_height", "drop_width"])
def test_convention_random_rain_rejects_an_invalid_range(self, name, bounds):
ranges = {"number_of_drops": (1, 1), "drop_height": (1, 1), "drop_width": (1, 1)}
ranges[name] = bounds
with pytest.raises(ValueError, match=name):
K.RandomRain(p=1.0, **ranges)
# Integral floats and a tensor pair are the same closed range written another way.
@pytest.mark.device_agnostic
def test_convention_random_rain_accepts_integral_float_and_tensor_ranges(self):
for name in ("number_of_drops", "drop_height", "drop_width"):
ranges = {"number_of_drops": (1, 1), "drop_height": (1, 1), "drop_width": (1, 1)}
ranges[name] = (1.0, 2.0)
K.RandomRain(p=1.0, **ranges)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomRain(p=1.0, number_of_drops=(1, 1), drop_height=torch.tensor([2, 4]), drop_width=(1, 1))
drawn = aug.forward_parameters((2000, 1, 64, 64))["drop_height_factor"]
assert sorted(set(drawn.flatten().tolist())) == [2, 3, 4]
# A drop starts anywhere that keeps it inside the image, so over many draws every row and column is
# painted, for a single pixel and for drops slanting either way (#4604).
@pytest.mark.parametrize("drop_height, drop_width", [(1, 0), (2, 2), (2, -2)])
def test_convention_random_rain_paints_every_row_and_column_4604(self, device, dtype, drop_height, drop_width):
image = torch.zeros(1, 3, 6, 10, device=device, dtype=dtype)
# `.to` so the coordinate sampler runs in the test's dtype, where a half `rand` can return 1.0 (#4553).
aug = K.RandomRain(
number_of_drops=(20, 20), drop_height=(drop_height, drop_height), drop_width=(drop_width, drop_width), p=1.0
).to(device=device, dtype=dtype)
rows, cols = set(), set()
for seed in range(300):
torch.manual_seed(seed)
lit = (aug(image)[0, 0] != 0).nonzero()
rows |= set(lit[:, 0].tolist())
cols |= set(lit[:, 1].tolist())
assert sorted(rows) == list(range(6))
assert sorted(cols) == list(range(10))
# A single drop paints a bounding box of exactly ``(h, max(|w|, 1))`` inside the image for every legal start
# (#4604); a drop wrapped across opposite edges by a negative index would still satisfy the union pin.
@pytest.mark.device_agnostic
def test_convention_random_rain_single_drop_box_is_its_size_4604(self):
for height, width in itertools.product(range(2, 8), repeat=2):
image = torch.zeros(1, 1, height, width)
for drop_height in range(1, height):
for drop_width in range(-(width - 1), width):
aug = K.RandomRain(
number_of_drops=(1, 1),
drop_height=(drop_height, drop_height),
drop_width=(drop_width, drop_width),
p=1.0,
)
expected = (drop_height, max(abs(drop_width), 1))
for seed in range(2):
torch.manual_seed(seed)
lit = (aug(image)[0, 0] != 0).nonzero()
rows, cols = lit[:, 0].tolist(), lit[:, 1].tolist()
case = (height, width, drop_height, drop_width, seed)
assert (max(rows) - min(rows) + 1, max(cols) - min(cols) + 1) == expected, case
assert min(rows) >= 0, case
assert max(rows) < height, case
assert min(cols) >= 0, case
assert max(cols) < width, case
# Every legal start row is equally likely, not merely reachable (#4604); single-pixel drops on a wide
# image, so each painted cell is one start.
# Snippet used to generate expected:
# torch.manual_seed(0)
# aug = K.RandomRain(number_of_drops=(100, 100), drop_height=(1, 1), drop_width=(0, 0), p=1.0)
# print(torch.bincount((aug(torch.zeros(200, 1, 6, 2000))[:, 0] != 0).nonzero()[:, 1], minlength=6))
@pytest.mark.device_agnostic
def test_convention_random_rain_start_row_is_uniform_4604(self):
aug = K.RandomRain(number_of_drops=(100, 100), drop_height=(1, 1), drop_width=(0, 0), p=1.0)
torch.manual_seed(_FORWARD_SEED)
lit = (aug(torch.zeros(200, 1, 6, 2000))[:, 0] != 0).nonzero()
counts = torch.bincount(lit[:, 1], minlength=6)
expected = int(counts.sum()) / 6
assert bool(((counts > 0.85 * expected) & (counts < 1.15 * expected)).all()), counts.tolist()
# A start draw of exactly 1.0 (possible for a half ``rand``, #4553) is clamped to the last legal start:
# the drop reaches the last row and the last column and stays inside (#4604).
@pytest.mark.device_agnostic
def test_convention_random_rain_start_draw_of_one_stays_inside_4604(self, monkeypatch):
real_rand = torch.rand
monkeypatch.setattr(torch, "rand", lambda *a, **kw: torch.ones_like(real_rand(*a, **kw)))
aug = K.RandomRain(number_of_drops=(1, 1), drop_height=(2, 2), drop_width=(-2, -2), p=1.0)
# The patch has to reach the generator's own draws, or the pin is vacuous.
assert float(aug.forward_parameters((1, 1, 6, 10))["coordinates_factor"].min()) == 1.0
lit = (aug(torch.zeros(1, 1, 6, 10))[0, 0] != 0).nonzero().tolist()
assert sorted(lit) == [[4, 9], [5, 8]]
# ``same_on_batch=True`` shares the drop count, the drop sizes and the coordinates; without it each
# sample draws its own.
def test_convention_random_rain_same_on_batch_draws_one_drop_count(self, device, dtype):
# B=16 makes an accidentally constant unshared draw over {1, 2, 3} unlikely.
batch_size = 16
image = torch.zeros(batch_size, 1, 12, 30, device=device, dtype=dtype)
drawn = {}
shared = {}
for same_on_batch in (True, False):
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomRain(
number_of_drops=(1, 50), drop_height=(1, 3), drop_width=(1, 3), p=1.0, same_on_batch=same_on_batch
)
aug(image)
drawn[same_on_batch] = aug._params["number_of_drops_factor"].flatten().tolist()
shared[same_on_batch] = aug._params
assert len(set(drawn[True])) == 1
assert len(drawn[True]) == batch_size
assert len(set(drawn[False])) > 1
for key in ("drop_height_factor", "drop_width_factor"):
assert len(set(shared[True][key].flatten().tolist())) == 1, key
assert len(set(shared[False][key].flatten().tolist())) > 1, key
coordinates = shared[True]["coordinates_factor"]
assert all(torch.equal(coordinates[0], coordinates[row]) for row in range(1, batch_size))
assert not torch.equal(shared[False]["coordinates_factor"][0], shared[False]["coordinates_factor"][1])
# ``snow_coefficient`` is validated against [0, 1] at construction (the channel-count rule is in the
# precondition table below).
@pytest.mark.device_agnostic
@pytest.mark.parametrize("coefficient", [1.5, -0.5])
def test_convention_random_snow_rejects_a_coefficient_outside_unit_range(self, coefficient):
with pytest.raises(BaseError, match="between 0 and 1"):
K.RandomSnow(snow_coefficient=(coefficient, coefficient), p=1.0)
# ``snow_coefficient`` and ``brightness`` are drawn per sample; ``same_on_batch=True`` shares both.
def test_convention_random_snow_draws_one_value_per_sample(self, device, dtype):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 7, 9).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomSnow(snow_coefficient=(0.2, 0.8), brightness=(1.5, 3.0), p=1.0)
aug(image)
torch.manual_seed(_FORWARD_SEED)
many = aug.forward_parameters((256, 3, 7, 9))
for key, low, high in (("snow_coefficient", 0.2, 0.8), ("brightness", 1.5, 3.0)):
drawn = aug._params[key].flatten()
assert drawn.shape == (4,)
assert len(set(drawn.tolist())) == 4
assert float(drawn.min()) >= low
assert float(drawn.max()) <= high
# Reach, not only containment.
width = high - low
assert float(many[key].min()) < low + 0.1 * width
assert float(many[key].max()) > high - 0.1 * width
torch.manual_seed(_FORWARD_SEED)
shared = K.RandomSnow(snow_coefficient=(0.2, 0.8), brightness=(1.5, 3.0), p=1.0, same_on_batch=True)
shared(image)
for key in ("snow_coefficient", "brightness"):
assert len(set(shared._params[key].flatten().tolist())) == 1
# Clamp before the HLS conversion (#4430): these pixels become white after lightness scaling,
# including the pixels that previously retained values above one or collapsed to black.
def test_convention_random_snow_clamps_before_hls_4430(self, device, dtype):
pixels = torch.tensor(
[
[1.5, 0.0, 0.0],
[2.0, 1.5, 1.5],
[1.2, -2.0, -2.0],
[1.5, 0.5, 0.5],
[2.0, -2.0, -2.0],
[1.8, 0.0, 0.0],
],
device=device,
dtype=dtype,
)
torch.manual_seed(_FORWARD_SEED)
aug = K.RandomSnow(snow_coefficient=(0.9, 0.9), brightness=(2.0, 2.0), p=1.0)
out = aug(pixels.T.reshape(1, 3, 1, 6).contiguous())[0, :, 0].T
self.assert_close(out, torch.ones_like(pixels))
def test_convention_random_snow_coverage_is_strictly_below_coefficient(self, device, dtype):
# Binary-exact lightness values on either side of and at 0.25 discriminate < from <= in every dtype.
pixels = torch.tensor([[0.25, 0.0, 0.0], [0.5, 0.0, 0.0], [0.75, 0.0, 0.0]], device=device, dtype=dtype)
aug = K.RandomSnow(snow_coefficient=(0.25, 0.25), brightness=(2.0, 2.0), p=1.0)
out = aug(pixels.T.reshape(1, 3, 1, 3).contiguous())[0, :, 0].T
self.assert_close(out, pixels.new_tensor([[0.5, 0.0, 0.0], [0.5, 0.0, 0.0], [0.75, 0.0, 0.0]]))
# Every achromatic pixel -- black, gray or white -- stays finite through the HLS round trip (#4571).
@pytest.mark.parametrize("value", [0.0, 0.5, 1.0])
def test_convention_random_snow_achromatic_pixel_is_finite_4571(self, device, dtype, value):
gray = torch.full((1, 3, 2, 2), value, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomSnow(p=1.0)(gray)
assert bool(torch.isfinite(out).all())
expected = gray.new_full(gray.shape, value)
self.assert_close(out, expected)
# The channel-count precondition, one table: "1 or 3" against "3 only". The type and kornia's own
# message are asserted, so an unrelated failure does not satisfy a row.
# Snippet used to generate expected:
# for c in (1, 2, 4): torch.manual_seed(0); factory()(torch.rand(2, c, 32, 32))
@pytest.mark.parametrize(
("name", "accepts_one", "error", "match"),
[
("ColorJiggle", False, ValueError, r"Input size must have a shape of \(\*, 3, H, W\)"),
("RandomHue", False, ValueError, r"Input size must have a shape of \(\*, 3, H, W\)"),
("RandomSaturation", False, ValueError, r"Input size must have a shape of \(\*, 3, H, W\)"),
("RandomJPEG", False, ShapeError, r"Shape mismatch at dimension 1: expected 3, got"),
("RandomPlanckianJitter", False, ShapeError, r"Shape mismatch at dimension 1: expected 3, got"),
("RandomRGBShift", False, ImageError, r"Not a color tensor"),
("RandomSnow", False, BaseError, r"Number of color channels should be 3\."),
("RandomRain", True, BaseError, r"Number of color channels should be 1 or 3\."),
("RandomSaltAndPepperNoise", True, BaseError, r"Number of color channels should be 1 or 3\."),
],
)
def test_convention_intensity_channel_count_preconditions(self, device, dtype, name, accepts_one, error, match):
if name == "RandomJPEG" and not supports_replicate_padding(device, dtype):
# The 3-channel baseline call needs the codec's replication padding.
pytest.skip("replication_pad2d is unavailable for this device/dtype")
factories = {
"ColorJiggle": lambda: K.ColorJiggle(0.0, 0.0, 0.2, 0.0, p=1.0),
"RandomHue": lambda: K.RandomHue((-0.2, 0.2), p=1.0),
"RandomSaturation": lambda: K.RandomSaturation((0.7, 1.3), p=1.0),
"RandomJPEG": lambda: K.RandomJPEG((50.0, 90.0), p=1.0),
"RandomPlanckianJitter": lambda: K.RandomPlanckianJitter(p=1.0),
"RandomRGBShift": lambda: K.RandomRGBShift(p=1.0),
"RandomSnow": lambda: K.RandomSnow(p=1.0),
"RandomRain": lambda: K.RandomRain(number_of_drops=(2, 3), drop_height=(2, 3), drop_width=(1, 2), p=1.0),
"RandomSaltAndPepperNoise": lambda: K.RandomSaltAndPepperNoise(p=1.0),
}
torch.manual_seed(_FIXTURE_SEED)
three = torch.rand(2, 3, 32, 32).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
assert factories[name]()(three).shape == three.shape, f"{name} must accept a 3-channel image"
for channels in (1, 2, 4):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(2, channels, 32, 32).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
if channels == 1 and accepts_one:
assert factories[name]()(image).shape == image.shape
continue
with pytest.raises(error, match=match):
_sync(factories[name]()(image).device)
class TestIlluminationAndNormalizeConventions(BaseTester):
# The three *Illumination classes add a gradient recorded as ``_params["gradient"]`` and clamp the sum
# into [0, 1]; ``sign`` is drawn per sample and fixes the direction. At gain 0.8 on a constant 0.5 the
# clamp engages on an in-range image.
# Snippet used to generate expected:
# c = torch.full((2, 3, 7, 9), 0.5)
# torch.manual_seed(0); a = K.RandomGaussianIllumination(gain=(0.8, 0.8), sign=(1.0, 1.0), p=1.0)
# y = a(c); raw = c + a._params["gradient"]; print(torch.equal(y, raw.clamp(0, 1)), torch.equal(y, raw))
@pytest.mark.parametrize(
"name", ["RandomGaussianIllumination", "RandomLinearIllumination", "RandomLinearCornerIllumination"]
)
def test_convention_illumination_adds_a_signed_gradient_and_clamps_to_unit_range(self, device, dtype, name):
aug = _illumination(name)
constant = torch.full((2, 3, 7, 9), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = aug(constant)
assert float(out.min()) >= 0.0
assert float(out.max()) <= 1.0
assert aug._params["gradient"].shape == constant.shape
assert float(aug._params["gradient"].float().abs().max()) > 0.0
# -1 can only darken, +1 can only brighten; the output is the clamped sum, not the raw one.
for sign, low, high in ((-1.0, 0.0, 0.5), (1.0, 0.5, 1.0)):
torch.manual_seed(_FORWARD_SEED)
clamped_aug = _illumination(name, gain=(0.8, 0.8), sign=(sign, sign))
clamped = clamped_aug(constant)
gradient = clamped_aug._params["gradient"]
if sign > 0:
assert float(gradient.float().min()) >= 0.0
else:
assert float(gradient.float().max()) <= 0.0
assert float(clamped.min()) >= low - 1e-3
assert float(clamped.max()) <= high + 1e-3
raw = constant + gradient.to(device=device, dtype=dtype)
self.assert_close(clamped, raw.clamp(0.0, 1.0))
assert not torch.equal(clamped, raw), "the clamp did not engage, so this leg proves nothing"
# With the default range one batch holds both directions; same_on_batch=True shares one gradient.
# B=16 makes an all-same-sign draw unlikely (2 * 2 ** -16).
batch_size = 16
batch = torch.full((batch_size, 3, 7, 9), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
per_sample = _illumination(name)
per_sample(batch)
directions = [float(per_sample._params["gradient"][b].float().max()) for b in range(batch_size)]
assert any(value > 0.0 for value in directions)
assert any(value <= 0.0 for value in directions)
torch.manual_seed(_FORWARD_SEED)
shared = _illumination(name, same_on_batch=True)
shared(batch)
gradients = shared._params["gradient"]
assert all(torch.equal(gradients[0], gradients[b]) for b in range(batch_size))
# The edge, corner or centre where the gradient is strongest is also drawn per sample.
flat = per_sample._params["gradient"].flatten(1).float().abs()
assert len(set(flat.argmax(1).tolist())) > 1, "the strongest-gradient location is not drawn per sample"
# Issue #4811: ``center`` maps to the pixel-centre position ``center * L - 0.5`` without rounding, so the
# column and row profiles are symmetric about it: the listed pair of indices sits the same distance on either
# side.
# Before the fix ``center=0.5`` peaked one column past the middle of a 3-, 7- or 11-wide image (rounding
# half to even), and ``center=0.25`` sat half a pixel off on a 6-wide axis. The 9- and 8-wide legs held before.
@pytest.mark.parametrize(
("width", "center", "pair"),
[(3, 0.5, (0, 2)), (7, 0.5, (2, 4)), (9, 0.5, (3, 5)), (8, 0.5, (3, 4)), (8, 0.25, (1, 2)), (6, 0.25, (0, 2))],
)
def test_convention_random_gaussian_illumination_center_is_pixel_centre_4811(
self, device, dtype, width, center, pair
):
aug = K.RandomGaussianIllumination(
gain=(0.5, 0.5), sigma=(0.2, 0.2), center=(center, center), sign=(1.0, 1.0), p=1.0
)
torch.manual_seed(_FORWARD_SEED)
aug(torch.zeros(1, 1, width, width, device=device, dtype=dtype))
field = aug._params["gradient"][0, 0].float()
for profile in (field.sum(0), field.sum(1)):
self.assert_close(profile[pair[0]], profile[pair[1]])
# The three classes round-trip through pickle, deepcopy and torch.save (#4435), and the copy
# reproduces the original's output under the same seed.
@pytest.mark.parametrize(
"name", ["RandomGaussianIllumination", "RandomLinearIllumination", "RandomLinearCornerIllumination"]
)
def test_convention_illumination_augmentations_are_picklable(self, device, dtype, name):
constant = torch.full((2, 3, 7, 9), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
expected = _illumination(name)(constant)
torch.manual_seed(_FORWARD_SEED)
unpickled = pickle.loads(pickle.dumps(_illumination(name))) # noqa: S301
assert torch.equal(unpickled(constant), expected)
torch.manual_seed(_FORWARD_SEED)
cloned = copy.deepcopy(_illumination(name))
assert torch.equal(cloned(constant), expected)
buffer = io.BytesIO()
torch.save(_illumination(name), buffer)
buffer.seek(0)
torch.manual_seed(_FORWARD_SEED)
reloaded = torch.load(buffer, weights_only=False)
assert torch.equal(reloaded(constant), expected)
# The illumination is finite at every admitted ``sigma``, including ``0`` and a small absolute width
# ``sigma * axis`` on an even axis (#4589). The kernel itself is pinned in tests/filters/test_gaussian.py.
@pytest.mark.parametrize("size", [3, 4])
def test_convention_random_gaussian_illumination_is_finite_at_every_sigma(self, device, dtype, size):
image = torch.full((1, 3, size, size), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
assert bool(K.RandomGaussianIllumination(p=1.0, sigma=0.0)(image).isfinite().all())
for sigma in (0.005, 0.01):
torch.manual_seed(_FORWARD_SEED)
small = K.RandomGaussianIllumination(p=1.0, sigma=(sigma, sigma), center=(0.5, 0.5))(image)
assert bool(small.isfinite().all()), (size, sigma)
# Absolute widths straddling the float32 underflow threshold (about 0.034).
for axis, small_sigma in ((4, 0.005), (8, 0.005), (8, 0.002), (64, 0.0005), (64, 0.00055)):
square = torch.full((1, 3, axis, axis), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = K.RandomGaussianIllumination(p=1.0, sigma=(small_sigma, small_sigma), center=(0.5, 0.5))(square)
assert bool(out.isfinite().all()), (axis, small_sigma)
# And with a drawn centre.
for odd in (1, 3, 5, 7):
for seed in range(16):
torch.manual_seed(seed)
odd_image = torch.full((1, 3, odd, odd), 0.5, device=device, dtype=dtype)
assert bool(K.RandomGaussianIllumination(p=1.0, sigma=(0.005, 0.005))(odd_image).isfinite().all()), (
odd,
seed,
)
torch.manual_seed(_FORWARD_SEED)
assert bool(K.RandomGaussianIllumination(p=1.0)(image).isfinite().all())
# Issue #4807: the classes with their own ``.compile()`` store compiled callables. Pickling stores the
# uncompiled ones and unpickling compiles them again, so like the linear illumination classes (torch's
# ``Module.compile``) they pickle, pass through torch.save and still run after the round trip.
# "compile" in the name is load-bearing: conftest deselects it unless KORNIA_TEST_OPTIMIZER is set, which
# keeps ``torch.compile``'s process-wide side effects (it disables Distribution argument validation) out
# of the ordinary CPU legs.
@pytest.mark.skipif(not dynamo_is_available(), reason=DYNAMO_UNAVAILABLE_REASON)
@pytest.mark.parametrize(
("name", "own_compile"),
[
("RandomGaussianIllumination", True),
("RandomGaussianBlur", True),
("ColorJitter", True),
("RandomLinearIllumination", False),
("RandomLinearCornerIllumination", False),
],
)
@pytest.mark.device_agnostic
def test_compiled_intensity_augmentation_pickles(self, name, own_compile):
if name == "RandomGaussianBlur":
compiled = K.RandomGaussianBlur((3, 3), (1.0, 1.0), p=1.0)
elif name == "ColorJitter":
compiled = K.ColorJitter(0.1, 0.1, 0.1, 0.1, p=1.0)
else:
compiled = _illumination(name)
validate_args = Distribution._validate_args
try:
compiled.compile()
finally:
Distribution.set_default_validate_args(validate_args)
constant = torch.full((2, 3, 7, 9), 0.5)
torch.manual_seed(_FORWARD_SEED)
cloned = copy.deepcopy(compiled)
assert isinstance(cloned, type(compiled))
assert cloned(constant).shape == constant.shape
torch.save(compiled, io.BytesIO())
try:
restored = pickle.loads(pickle.dumps(compiled)) # noqa: S301
finally:
Distribution.set_default_validate_args(validate_args)
assert isinstance(restored, type(compiled))
assert restored(constant).shape == constant.shape
if own_compile:
# Compiled again on load, with the arguments of the original compile() call.
assert restored._compile_kwargs == compiled._compile_kwargs
# Issue #4807: unpickling passes each uncompiled callable to ``torch.compile`` again, with the arguments of
# the last ``compile()`` call; a second ``compile()`` keeps the first, uncompiled callables for pickling, and a
# fixed ColorJitter order also compiles (and so must restore) the fixed-order dispatcher.
@pytest.mark.skipif(not dynamo_is_available(), reason=DYNAMO_UNAVAILABLE_REASON)
@pytest.mark.parametrize(
"name", ["RandomGaussianIllumination", "RandomGaussianBlur", "ColorJitter", "ColorJitterFixedOrder"]
)
@pytest.mark.device_agnostic
def test_unpickled_own_compile_recompiles_with_same_arguments(self, name, monkeypatch):
if name == "RandomGaussianBlur":
module = K.RandomGaussianBlur((3, 3), (0.5, 1.5), p=1.0)
elif name == "ColorJitter":
module = K.ColorJitter(0.1, 0.1, 0.1, 0.1, p=1.0)
elif name == "ColorJitterFixedOrder":
module = K.ColorJitter(0.1, 0.1, 0.1, 0.1, p=1.0, order=(3, 2, 1, 0))
else:
module = K.RandomGaussianIllumination(p=1.0)
eager_fns = {key: fn for key, fn in vars(module).items() if key.endswith("_fn") and fn is not None}
expected = {"fullgraph": True, "dynamic": True, "backend": "eager", "mode": None, "options": None}
expected["disable"] = False
calls = []
torch_compile = torch.compile
def spy(fn, **kwargs):
calls.append((fn, kwargs))
return torch_compile(fn, **kwargs)
validate_args = Distribution._validate_args
try:
module.compile(backend="eager")
module.compile(fullgraph=True, dynamic=True, backend="eager")
payload = pickle.dumps(module)
monkeypatch.setattr(torch, "compile", spy)
restored = pickle.loads(payload) # noqa: S301
finally:
Distribution.set_default_validate_args(validate_args)
assert len(calls) == len(eager_fns)
assert {fn for fn, _ in calls} == set(eager_fns.values())
assert all(kwargs == expected for _, kwargs in calls)
image = torch.linspace(0.0, 1.0, 2 * 3 * 7 * 9).reshape(2, 3, 7, 9)
torch.manual_seed(_FORWARD_SEED)
expected_out = module(image)
torch.manual_seed(_FORWARD_SEED)
self.assert_close(restored(image), expected_out, rtol=0.0, atol=0.0)
# The RandomPlasma* classes clamp into [0, 1] and record the fractal as ``_params["plasma"]``, so a
# replay with ``params=`` reproduces the output bitwise. The replay runs on a non-constant image,
# because a constant 0.5 is a fixed point of the plasma contrast transform.
@pytest.mark.parametrize("name", ["RandomPlasmaBrightness", "RandomPlasmaContrast", "RandomPlasmaShadow"])
def test_convention_plasma_clamps_and_replays_from_params(self, device, dtype, name):
constant = torch.full((2, 3, 7, 9), 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
constant_out = _plasma(name)(constant)
assert float(constant_out.min()) >= 0.0
assert float(constant_out.max()) <= 1.0
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 32, 32).to(device=device, dtype=dtype)
aug = _plasma(name)
torch.manual_seed(_FORWARD_SEED)
out = aug(image)
assert float(out.min()) >= 0.0
assert float(out.max()) <= 1.0
assert "plasma" in aug._params
# The transform actually moved this fixture, so an identity would not satisfy the replay.
assert float((out - image).abs().max()) > 0.03
assert torch.equal(aug(image, params=aug._params), out)
# With same_on_batch=True the RandomPlasma* classes share their scalar draws and one expanded fractal
# map (#4570).
@pytest.mark.parametrize("name", ["RandomPlasmaBrightness", "RandomPlasmaContrast", "RandomPlasmaShadow"])
def test_convention_plasma_same_on_batch_shares_map_4570(self, device, dtype, name):
image = torch.full((4, 3, 8, 8), 0.3, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
aug = getattr(K, name)(p=1.0, same_on_batch=True)
out = aug(image)
for key, value in aug._params.items():
if key not in ("plasma", "forward_input_shape"):
assert all(torch.equal(value[0], value[b]) for b in range(4)), f"{key} is not shared"
assert torch.equal(aug._params["plasma"][0], aug._params["plasma"][1])
# Expanded, not repeated: the stored map has batch stride 0.
assert aug._params["plasma"].stride()[0] == 0
assert torch.equal(out[0], out[1])
# A one-pixel spatial axis is accepted.
@pytest.mark.parametrize("name", ["RandomPlasmaBrightness", "RandomPlasmaContrast", "RandomPlasmaShadow"])
@pytest.mark.parametrize("shape", [(1, 3, 1, 1), (1, 3, 1, 8), (1, 3, 8, 1)])
def test_convention_plasma_accepts_a_single_pixel_axis(self, device, dtype, name, shape):
image = torch.full(shape, 0.5, device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
assert _plasma(name)(image).shape == shape
# ``mean`` and ``std`` accept a float, a sequence, a 1- or C-tensor and a per-sample (B, C) tensor, and
# each form rescales the image; a (B, C) statistic is applied to its own sample.
# Snippet used to generate expected:
# torch.manual_seed(1234); x = torch.rand(4, 3, 6, 8)
# torch.manual_seed(0); print((K.Normalize(mean=0.5, std=0.25, p=1.0)(x) - x).abs().max())
@pytest.mark.parametrize("form", ["float", "list3", "tuple3", "tensor1", "tensor3", "tensorB3"])
@pytest.mark.parametrize(("cls", "moved"), [(K.Normalize, 1.0), (K.Denormalize, 0.25)])
def test_convention_normalize_accepts_scalar_sequence_and_per_sample_statistics(
self, device, dtype, cls, moved, form
):
mean, std = _statistics(form, device, dtype)
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 6, 8).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
out = cls(mean=mean, std=std, p=1.0)(image)
assert out.shape == image.shape
assert float((out - image).abs().max()) > moved
if form == "tensorB3":
# The exact field: the threshold above cannot tell a per-sample application from a row-0 one.
stats = torch.arange(1, 13, device=device, dtype=dtype).reshape(4, 3) / 10.0
field = stats[..., None, None]
torch.manual_seed(_FORWARD_SEED)
per_sample = cls(mean=stats, std=stats, p=1.0)(image)
expected = image * field + field if cls is K.Denormalize else (image - field) / field
self.assert_close(per_sample, expected)
# Denormalize inverts Normalize built with the same statistics, checked on a forward that moved the
# tensor, so a no-op cannot satisfy it; integer statistics round-trip too (#4573).
@pytest.mark.parametrize("form", ["float", "list3", "tensor1", "tensorB3", "int"])
def test_convention_denormalize_inverts_normalize(self, device, dtype, form):
mean, std = (0, 4) if form == "int" else _statistics(form, device, dtype)
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 6, 8).to(device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
normalized = K.Normalize(mean=mean, std=std, p=1.0)(image)
assert float((normalized - image).abs().max()) > 0.5
torch.manual_seed(_FORWARD_SEED)
self.assert_close(K.Denormalize(mean=mean, std=std, p=1.0)(normalized), image)
# A mean or std whose length is neither 1 nor the channel count is rejected.
@pytest.mark.parametrize("cls", [K.Normalize, K.Denormalize])
def test_convention_normalize_rejects_a_statistic_of_the_wrong_length(self, device, dtype, cls):
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(4, 3, 6, 8).to(device=device, dtype=dtype)
mean = torch.tensor([0.4, 0.5], device=device, dtype=dtype)
std = torch.tensor([0.2, 0.25], device=device, dtype=dtype)
torch.manual_seed(_FORWARD_SEED)
with pytest.raises(ValueError, match="do not match"):
_sync(cls(mean=mean, std=std, p=1.0)(image).device)
# Normalize and Denormalize hard-code ``same_on_batch=True`` and take no such argument, so ``p`` gates
# the whole batch together.
# Snippet used to generate expected:
# torch.manual_seed(1234); x = torch.rand(8, 3, 6, 8)
# torch.manual_seed(seed); aug = K.Normalize(mean=0.5, std=0.25, p=0.5); aug(x); print(aug._params["batch_prob"])
@pytest.mark.parametrize("cls", [K.Normalize, K.Denormalize])
def test_convention_normalize_p_gates_the_whole_batch(self, device, dtype, cls):
assert "same_on_batch" not in inspect.signature(cls.__init__).parameters
torch.manual_seed(_FIXTURE_SEED)
image = torch.rand(8, 3, 6, 8).to(device=device, dtype=dtype)
applied = 0
for seed in range(6):
torch.manual_seed(seed)
aug = cls(mean=0.5, std=0.25, p=0.5)
out = aug(image)
gate = aug._params["batch_prob"].flatten()
assert gate.shape == (8,)
unchanged = sum(1 for b in range(8) if torch.equal(out[b], image[b]))
assert unchanged == int((gate == 0).sum())
assert len(set(gate.tolist())) == 1
applied += 8 - unchanged
# Both outcomes occur over these six seeds.
assert 0 < applied < 48
# p=0.0 is the identity.
torch.manual_seed(_FORWARD_SEED)
assert torch.equal(cls(mean=0.5, std=0.25, p=0.0)(image), image)
# The statistics live in ``flags``, not in buffers: ``state_dict()`` is empty and ``.to()`` leaves them
# alone (the forward casts them to the input).
@pytest.mark.device_agnostic
@pytest.mark.parametrize("cls", [K.Normalize, K.Denormalize])
def test_convention_normalize_keeps_no_state(self, cls):
aug = cls(mean=0.5, std=0.25, p=1.0)
assert list(aug.state_dict()) == []
assert [name for name, _ in aug.named_buffers()] == []
assert sorted(aug.flags) == ["mean", "std"]
before = aug.flags["mean"].clone()
moved = aug.to(torch.float64)
assert moved.flags["mean"].dtype == torch.float32
assert torch.equal(moved.flags["mean"], before)
def _illumination(name: str, **kwargs):
"""Point-range constructors for the three *Illumination classes."""
classes = {
"RandomGaussianIllumination": K.RandomGaussianIllumination,
"RandomLinearIllumination": K.RandomLinearIllumination,
"RandomLinearCornerIllumination": K.RandomLinearCornerIllumination,
}
kwargs.setdefault("gain", (0.5, 0.5))
return classes[name](p=1.0, **kwargs)
def _plasma(name: str):
"""Default constructors for the three RandomPlasma* classes."""
factories = {
"RandomPlasmaBrightness": lambda: K.RandomPlasmaBrightness(p=1.0),
"RandomPlasmaContrast": lambda: K.RandomPlasmaContrast(p=1.0),
"RandomPlasmaShadow": lambda: K.RandomPlasmaShadow(p=1.0),
}
return factories[name]()
def _field_augmentation(name: str, p: float = 1.0, keepdim: bool = False):
"""Return a field-producing augmentation, its parameter key, and its field channel count."""
factories = {
"RandomGaussianNoise": lambda: (
K.RandomGaussianNoise(mean=0.0, std=1.0, p=p, keepdim=keepdim),
"gaussian_noise",
3,
),
"RandomGaussianIllumination": lambda: (
K.RandomGaussianIllumination(gain=(0.1, 0.1), p=p, keepdim=keepdim),
"gradient",
3,
),
"RandomLinearIllumination": lambda: (
K.RandomLinearIllumination(gain=(0.1, 0.1), p=p, keepdim=keepdim),
"gradient",
3,
),
"RandomLinearCornerIllumination": lambda: (
K.RandomLinearCornerIllumination(gain=(0.1, 0.1), p=p, keepdim=keepdim),
"gradient",
3,
),
"RandomPlasmaBrightness": lambda: (K.RandomPlasmaBrightness(p=p, keepdim=keepdim), "plasma", 3),
"RandomPlasmaContrast": lambda: (K.RandomPlasmaContrast(p=p, keepdim=keepdim), "plasma", 3),
"RandomPlasmaShadow": lambda: (K.RandomPlasmaShadow(p=p, keepdim=keepdim), "plasma", 1),
}
return factories[name]()
def _statistics(form: str, device, dtype):
"""The six accepted ``mean`` / ``std`` forms."""
if form == "float":
return 0.5, 0.25
if form == "list3":
return [0.4, 0.5, 0.6], [0.2, 0.25, 0.3]
if form == "tuple3":
return (0.4, 0.5, 0.6), (0.2, 0.25, 0.3)
if form == "tensor1":
return (
torch.tensor([0.5], device=device, dtype=dtype),
torch.tensor([0.25], device=device, dtype=dtype),
)
if form == "tensor3":
return (
torch.tensor([0.4, 0.5, 0.6], device=device, dtype=dtype),
torch.tensor([0.2, 0.25, 0.3], device=device, dtype=dtype),
)
assert form == "tensorB3"
# Distinct rows, so a per-sample statistic is distinguishable from the scalar form.
return (
torch.tensor(
[[0.40, 0.50, 0.60], [0.45, 0.55, 0.65], [0.35, 0.45, 0.55], [0.50, 0.60, 0.70]],
device=device,
dtype=dtype,
),
torch.tensor(
[[0.20, 0.25, 0.30], [0.22, 0.27, 0.32], [0.18, 0.23, 0.28], [0.25, 0.30, 0.35]],
device=device,
dtype=dtype,
),
)