Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

fix(geometry)!: reject ScalePyramid n_levels below 1 and a negative min_size (#6511)

Debanjan Sarkar31e6a92fdc94
diff --git a/changelog.d/6511.breaking.md b/changelog.d/6511.breaking.md
new file mode 100644
index 000000000..0a5a490be
--- /dev/null
+++ b/changelog.d/6511.breaking.md
@@ -0,0 +1 @@
+`ScalePyramid` now raises `ValueCheckError` when `n_levels` is not a positive integer or `min_size` is negative or NaN, as it does for `extra_levels`. `n_levels=0` used to fail with a `ZeroDivisionError`, `n_levels=-1` with `extra_levels=1` returned octaves of a single level without an error, other negative values failed inside `forward`, and `n_levels=True` was read as 1; a negative or NaN `min_size` failed inside `forward` once the octaves reached an empty image. Every positive integer `n_levels` and non-negative `min_size` builds the same pyramid as before.
diff --git a/kornia/geometry/transform/pyramid.py b/kornia/geometry/transform/pyramid.py
index 2c4bd72c3..7b48afecf 100644
--- a/kornia/geometry/transform/pyramid.py
+++ b/kornia/geometry/transform/pyramid.py
@@ -201,29 +201,28 @@ class PyrUp(nn.Module):
return pyrup(input, self.border_type, self.align_corners)
-def _extra_levels_as_int(extra_levels: Any) -> int:
- """Return ``extra_levels`` as a positive ``int``, or raise :class:`~kornia.core.exceptions.ValueCheckError`.
+def _positive_int(name: str, value: Any) -> int:
+ """Return ``value`` as a positive ``int``, or raise :class:`~kornia.core.exceptions.ValueCheckError`.
- ``_extra_levels_as_int(extra_levels)`` converts a positive integer-like value to ``int`` through ``operator.index``.
+ ``_positive_int(name, value)`` converts a positive integer-like value to ``int`` through ``operator.index``.
Python and NumPy integers, 0-d integer arrays and integer tensors are accepted, as is anything else that
- ``operator.index`` converts to a positive integer; bools of every kind are rejected. The error is raised directly
- instead of through ``KORNIA_CHECK``: with ``extra_levels < 1`` the level that seeds the next octave does not exist,
- so the guard must also hold under ``python -O``, ``KORNIA_CHECKS=0`` and ``disable_checks()``.
+ ``operator.index`` converts to a positive integer; bools of every kind are rejected. ``name`` is the argument named
+ in the error. The error is raised directly instead of through ``KORNIA_CHECK``: :class:`ScalePyramid` cannot build
+ an octave from ``n_levels < 1`` or seed the next one from ``extra_levels < 1``, so the guard must also hold under
+ ``python -O``, ``KORNIA_CHECKS=0`` and ``disable_checks()``.
"""
- dtype = getattr(extra_levels, "dtype", None)
+ dtype = getattr(value, "dtype", None)
# ``operator.index`` turns ``True``, ``torch.tensor(True)`` and, on older NumPy, ``np.bool_`` into 1.
- is_bool = isinstance(extra_levels, bool) or dtype is torch.bool or getattr(dtype, "kind", None) == "b"
- value: int | None = None
+ is_bool = isinstance(value, bool) or dtype is torch.bool or getattr(dtype, "kind", None) == "b"
+ index: int | None = None
if not is_bool:
try:
- value = operator.index(extra_levels)
+ index = operator.index(value)
except TypeError:
- value = None
- if value is None or value < 1:
- raise ValueCheckError(
- f"Invalid extra_levels, it must be a positive integer. Got: {extra_levels!r}", actual_value=extra_levels
- )
- return value
+ index = None
+ if index is None or index < 1:
+ raise ValueCheckError(f"Invalid {name}, it must be a positive integer. Got: {value!r}", actual_value=value)
+ return index
class ScalePyramid(nn.Module):
@@ -252,10 +251,12 @@ class ScalePyramid(nn.Module):
:math:`2^o` (:math:`2^{o - 1}` with ``double_image=True``), not this map
Args:
- n_levels: number of the levels in octave.
+ n_levels: number of levels per octave over which the blur doubles, a positive integer (a NumPy integer or
+ integer tensor is converted to ``int``). Each level is blurred ``2 ** (1 / n_levels)`` times more than
+ the one before.
init_sigma: initial blur level.
- min_size: the minimum size of the octave in pixels: an octave after the first is built only when its shorter
- side is larger than ``min_size``.
+ min_size: the minimum size of the octave in pixels, a non-negative number: an octave after the first is built
+ only when its shorter side is larger than ``min_size``, so ``0`` halves the image down to one pixel.
double_image: add 2x upscaled image as 1st level of pyramid. OpenCV SIFT does this.
extra_levels: number of levels per octave beyond ``n_levels``, a positive integer (a NumPy integer or
integer tensor is converted to ``int``); the default 3 is what DoG non-maximum suppression needs. Level
@@ -268,8 +269,9 @@ class ScalePyramid(nn.Module):
3rd output: pixel_dists, the nominal pixel spacing of each level relative to the input.
Raises:
- ValueCheckError: if ``extra_levels`` is not a positive integer. Raised even when the ``KORNIA_CHECK``
- helpers are disabled, because ``forward`` could not build the pyramid.
+ ValueCheckError: if ``n_levels`` or ``extra_levels`` is not a positive integer, or ``min_size`` is negative
+ or NaN. Raised even when the ``KORNIA_CHECK`` helpers are disabled, because ``forward`` could not build
+ the pyramid.
Shape:
- Input: ``(B, C, H, W)``
@@ -298,7 +300,14 @@ class ScalePyramid(nn.Module):
extra_levels: int = 3,
) -> None:
super().__init__()
- extra_levels = _extra_levels_as_int(extra_levels)
+ n_levels = _positive_int("n_levels", n_levels)
+ extra_levels = _positive_int("extra_levels", extra_levels)
+ # `not (min_size >= 0)` also rejects NaN; a negative or NaN min_size never stops the octave loop, which then
+ # halves the image down to an empty one.
+ if not (min_size >= 0):
+ raise ValueCheckError(
+ f"Invalid min_size, it must be a non-negative number. Got: {min_size!r}", actual_value=min_size
+ )
# 3 extra levels are needed for DoG nms.
self.n_levels = n_levels
self.extra_levels = extra_levels
diff --git a/tests/geometry/transform/test_pyramid.py b/tests/geometry/transform/test_pyramid.py
index 6a2d8d586..a68355571 100644
--- a/tests/geometry/transform/test_pyramid.py
+++ b/tests/geometry/transform/test_pyramid.py
@@ -409,6 +409,81 @@ class TestScalePyramid(BaseTester):
if checks_were_enabled:
enable_checks()
+ @pytest.mark.parametrize(
+ "n_levels",
+ [
+ *[0, -1, -2, 1.5, 3.0, None, "3", True, False],
+ *[np.int64(0), np.int32(-1), np.float64(3.0), np.bool_(True)],
+ *[torch.tensor(0), torch.tensor(-1), torch.tensor(3.0), torch.tensor(True)],
+ ],
+ )
+ def test_invalid_n_levels(self, n_levels):
+ # n_levels=0 divided by zero in the level-to-level blur step 2 ** (1 / n_levels), n_levels=-1 with
+ # extra_levels=1 built a one-level pyramid without an error, and other negatives failed inside forward.
+ with pytest.raises(ValueCheckError, match="Invalid n_levels, it must be a positive integer"):
+ kornia.geometry.ScalePyramid(n_levels=n_levels)
+
+ def test_negative_n_levels_no_longer_builds_a_pyramid(self):
+ # The one negative value that used to construct and run: it returned three octaves of a single level.
+ with pytest.raises(ValueCheckError, match="Invalid n_levels"):
+ kornia.geometry.ScalePyramid(n_levels=-1, extra_levels=1)
+
+ @pytest.mark.parametrize(
+ "n_levels",
+ [
+ pytest.param(np.int64(2), id="np.int64"),
+ pytest.param(np.array(2), id="np.array-0d"),
+ pytest.param(torch.tensor(2), id="tensor-0d-int64"),
+ pytest.param(torch.tensor(2, dtype=torch.int32), id="tensor-0d-int32"),
+ ],
+ )
+ def test_integer_like_n_levels(self, device, dtype, n_levels):
+ # These were accepted before n_levels was validated; they now build the same pyramid as the Python int.
+ torch.manual_seed(0)
+ inp = torch.rand(1, 1, 96, 96).to(device=device, dtype=dtype)
+ pyramid = kornia.geometry.ScalePyramid(n_levels=n_levels)
+ assert type(pyramid.n_levels) is int
+ assert pyramid.n_levels == 2
+ for got, expected in zip(pyramid(inp), kornia.geometry.ScalePyramid(n_levels=2)(inp)):
+ assert len(got) == len(expected)
+ for got_octave, expected_octave in zip(got, expected):
+ self.assert_close(got_octave, expected_octave, rtol=0, atol=0)
+
+ @pytest.mark.parametrize("min_size", [-1, -0.5, float("nan"), torch.tensor(-1)])
+ def test_invalid_min_size(self, min_size):
+ # A negative or NaN min_size never stopped the octave loop, which halved the image to an empty one and failed
+ # inside F.interpolate.
+ with pytest.raises(ValueCheckError, match="Invalid min_size, it must be a non-negative number"):
+ kornia.geometry.ScalePyramid(min_size=min_size)
+
+ @pytest.mark.parametrize(("min_size", "num_octaves"), [(0, 7), (0.0, 7), (15.0, 3), (float("inf"), 1)])
+ def test_min_size_bounds(self, device, dtype, min_size, num_octaves):
+ # min_size=0 keeps halving down to one pixel: 64, 32, ..., 1.
+ torch.manual_seed(0)
+ inp = torch.rand(1, 1, 64, 64).to(device=device, dtype=dtype)
+ pyr, _, _ = kornia.geometry.ScalePyramid(min_size=min_size)(inp)
+ assert len(pyr) == num_octaves
+ assert pyr[-1].shape[-2:] == (64 // 2 ** (num_octaves - 1),) * 2
+
+ @pytest.mark.parametrize(
+ ("kwargs", "message"),
+ [
+ ({"n_levels": 0}, "Invalid n_levels"),
+ ({"n_levels": True}, "Invalid n_levels"),
+ ({"min_size": -1}, "Invalid min_size"),
+ ],
+ )
+ def test_invalid_n_levels_and_min_size_rejected_with_checks_disabled(self, kwargs, message):
+ # Not a KORNIA_CHECK, like extra_levels: with checks off, these would construct and then fail inside forward.
+ checks_were_enabled = are_checks_enabled()
+ disable_checks()
+ try:
+ with pytest.raises(ValueCheckError, match=message):
+ kornia.geometry.ScalePyramid(**kwargs)
+ finally:
+ if checks_were_enabled:
+ enable_checks()
+
@pytest.mark.parametrize("n_levels", [1, 3])
@pytest.mark.parametrize("extra_levels", [1, 2, 3])
def test_octave_is_seeded_from_level_n_levels_6400(self, device, dtype, n_levels, extra_levels):