Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

fix(geometry)!: reject ScalePyramid extra_levels below 1 (#6407)

Muhammad Talha19ffd3c06e45
diff --git a/changelog.d/6407.breaking.md b/changelog.d/6407.breaking.md
new file mode 100644
index 000000000..f35aa7a98
--- /dev/null
+++ b/changelog.d/6407.breaking.md
@@ -0,0 +1 @@
+`ScalePyramid` now raises `ValueCheckError` when `extra_levels` is not a positive integer. With `extra_levels=0` it used to start every octave after the first from the least blurred level of the previous octave instead of the level at twice the base blur, while `sigmas` still labelled the new octave as if it started at the base blur; a negative value built fewer than `n_levels` levels per octave or crashed, and a bool was read as 0 or 1. Use `extra_levels=1` or more: every positive integer builds the same pyramid as before.
diff --git a/kornia/geometry/transform/pyramid.py b/kornia/geometry/transform/pyramid.py
index f39f9863c..2c4bd72c3 100644
--- a/kornia/geometry/transform/pyramid.py
+++ b/kornia/geometry/transform/pyramid.py
@@ -40,12 +40,15 @@ Which function to use:
from __future__ import annotations
import math
+import operator
+from typing import Any
import torch
import torch.nn.functional as F
from torch import nn
from kornia.core.check import KORNIA_CHECK, KORNIA_CHECK_SHAPE
+from kornia.core.exceptions import ValueCheckError
from kornia.filters import filter2d, gaussian_blur2d
from kornia.filters.gaussian import _gaussian_blur2d_cpu, _gaussian_blur2d_cpu_eligible
@@ -198,6 +201,31 @@ 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`.
+
+ ``_extra_levels_as_int(extra_levels)`` 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()``.
+ """
+ dtype = getattr(extra_levels, "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
+ if not is_bool:
+ try:
+ value = operator.index(extra_levels)
+ 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
+
+
class ScalePyramid(nn.Module):
r"""Build octaves of progressively blurred images, with their sigmas, for scale-space detection.
@@ -205,8 +233,7 @@ class ScalePyramid(nn.Module):
``(B, C, H, W)`` images and returns three lists with one entry per octave. ``pyr[o]`` stacks
``L = n_levels + extra_levels`` levels as ``(B, C, L, H_o, W_o)``, each blurred ``2 ** (1 / n_levels)`` times more
than the previous, and ``sigmas[o]`` and ``pixel_dists[o]`` are ``(B, L)``. Each octave after the
- first starts from level ``n_levels`` of the previous one (for ``extra_levels >= 1``,
- `#6400 <https://github.com/kornia/kornia/issues/6400>`_), resized to half its size, and
+ first starts from level ``n_levels`` of the previous one, resized to half its size, and
octaves are added while that halved size stays above ``min_size`` on its shorter side. It is the pyramid
:class:`~kornia.feature.ScaleSpaceDetector` searches; for a plain list of halved images, use :func:`build_pyramid`.
@@ -230,16 +257,20 @@ class ScalePyramid(nn.Module):
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``.
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``; the default 3 is what DoG non-maximum
- suppression needs. Keep it at least 1: the next octave starts from level ``n_levels``, which
- ``extra_levels=0`` leaves out of the octave, and then starts from the least blurred level instead
- (`#6400 <https://github.com/kornia/kornia/issues/6400>`_).
+ 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
+ ``n_levels``, blurred to twice the first level's sigma, seeds the next octave, so ``1`` is the least
+ that works.
Returns:
1st output: images, the levels of each octave.
2nd output: sigmas, the nominal blur of each level in the octave's own pixels.
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.
+
Shape:
- Input: ``(B, C, H, W)``
- Output 1st: ``[(B, C, L, H, W), (B, C, L, H // 2, W // 2), ...]``, starting from ``(B, C, L, H * 2, W * 2)``
@@ -267,6 +298,7 @@ class ScalePyramid(nn.Module):
extra_levels: int = 3,
) -> None:
super().__init__()
+ extra_levels = _extra_levels_as_int(extra_levels)
# 3 extra levels are needed for DoG nms.
self.n_levels = n_levels
self.extra_levels = extra_levels
@@ -448,9 +480,11 @@ class ScalePyramid(nn.Module):
sigmas[-1][:, level_idx] = cur_sigma_oct
pixel_dists[-1][:, level_idx] = pixel_distance
- # Seed next octave: bilinear 2x downscale of the (-extra_levels) level.
+ # Seed next octave: bilinear 2x downscale of level ``n_levels``, the one blurred to twice the first
+ # level's sigma, so the new octave starts at the same octave-relative blur. It is addressed from the
+ # front: ``-self.extra_levels`` is the same level for ``extra_levels >= 1`` but selects level 0 for 0.
# Bilinear resampling is more accurate than integer-stride decimation.
- _pyr = pyr[-1][-self.extra_levels]
+ _pyr = pyr[-1][self.n_levels]
H, W = _pyr.shape[2], _pyr.shape[3]
if min(H // 2, W // 2) <= self.min_size:
break
diff --git a/tests/geometry/transform/test_pyramid.py b/tests/geometry/transform/test_pyramid.py
index de562d3ef..6a2d8d586 100644
--- a/tests/geometry/transform/test_pyramid.py
+++ b/tests/geometry/transform/test_pyramid.py
@@ -15,12 +15,14 @@
# limitations under the License.
#
+import numpy as np
import pytest
import torch
import kornia
from kornia.core._compat import torch_version_lt
-from kornia.core.exceptions import BaseError
+from kornia.core.check import are_checks_enabled, disable_checks, enable_checks
+from kornia.core.exceptions import BaseError, ValueCheckError
from testing.base import BaseTester, dynamo_is_available
@@ -351,6 +353,86 @@ class TestScalePyramid(BaseTester):
self.assert_close(sigmas[octave], ref_sigmas[octave])
self.assert_close(pyr[octave], ref_pyr[octave])
+ @pytest.mark.parametrize(
+ "extra_levels",
+ [
+ *[0, -1, -3, 1.5, 3.0, None, "3", True, False],
+ *[np.int64(0), np.int32(-1), np.float64(3.0), np.bool_(True), np.bool_(False)],
+ *[np.array(0), np.array(3.0), np.array(True)],
+ *[torch.tensor(0), torch.tensor(-1), torch.tensor(3.0), torch.tensor(True)],
+ ],
+ )
+ def test_invalid_extra_levels_6400(self, extra_levels):
+ # extra_levels=0 made `pyr[-1][-0]` pick level 0, so every octave after the first was seeded from the
+ # least blurred level while `sigmas` still labelled it with the base sigma.
+ with pytest.raises(BaseError, match="Invalid extra_levels, it must be a positive integer"):
+ kornia.geometry.ScalePyramid(extra_levels=extra_levels)
+
+ def test_non_scalar_extra_levels_6400(self):
+ # Not parametrized: conftest compares every parameter with `torch.float16`, which is ambiguous for an array.
+ for extra_levels in (np.array([1, 2]), torch.tensor([1, 2])):
+ with pytest.raises(BaseError, match="Invalid extra_levels, it must be a positive integer"):
+ kornia.geometry.ScalePyramid(extra_levels=extra_levels)
+
+ @pytest.mark.parametrize(
+ "extra_levels",
+ [
+ pytest.param(np.int8(2), id="np.int8"),
+ pytest.param(np.uint8(2), id="np.uint8"),
+ pytest.param(np.int32(2), id="np.int32"),
+ 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_extra_levels_6400(self, device, dtype, extra_levels):
+ # None of these is an `int` subclass, but all were accepted before extra_levels was validated.
+ inp = torch.rand(1, 1, 96, 96, device=device, dtype=dtype)
+ pyramid = kornia.geometry.ScalePyramid(extra_levels=extra_levels)
+ assert type(pyramid.extra_levels) is int
+ assert pyramid.extra_levels == 2
+ for got, expected in zip(pyramid(inp), kornia.geometry.ScalePyramid(extra_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("extra_levels", [0, -2, 1.5, None, True, np.bool_(True), torch.tensor(True)])
+ def test_invalid_extra_levels_rejected_with_checks_disabled_6400(self, extra_levels):
+ # Not a KORNIA_CHECK: with checks off, extra_levels=0 would construct and then fail inside forward.
+ checks_were_enabled = are_checks_enabled()
+ disable_checks()
+ try:
+ with pytest.raises(ValueCheckError, match="Invalid extra_levels"):
+ kornia.geometry.ScalePyramid(extra_levels=extra_levels)
+ 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):
+ # Level n_levels is blurred to twice the first level's sigma, so downscaling it by 2 gives the next octave
+ # the same octave-relative blur. It does not depend on how many spare levels follow it.
+ inp = torch.rand(1, 1, 96, 96, device=device, dtype=dtype)
+ pyr, sigmas, _ = kornia.geometry.ScalePyramid(n_levels, extra_levels=extra_levels)(inp)
+ assert len(pyr) >= 3
+ for octave in range(len(pyr) - 1):
+ assert pyr[octave].shape[2] == n_levels + extra_levels
+ size = (pyr[octave].shape[-2] // 2, pyr[octave].shape[-1] // 2)
+
+ def downscale(level, size=size, octave=octave):
+ return torch.nn.functional.interpolate(
+ pyr[octave][:, :, level], size=size, mode="bilinear", align_corners=True
+ )
+
+ self.assert_close(pyr[octave + 1][:, :, 0], downscale(n_levels))
+ assert not torch.allclose(pyr[octave + 1][:, :, 0], downscale(0))
+ # The labels agree with the seed: level n_levels is at twice the first level's sigma, and the next
+ # octave's first level, downscaled by 2, is back at the first level's sigma.
+ self.assert_close(sigmas[octave][:, n_levels], 2.0 * sigmas[octave][:, 0])
+ self.assert_close(sigmas[octave + 1][:, 0], sigmas[octave][:, 0])
+
class TestPyramidLevelValidation(BaseTester):
@pytest.mark.parametrize("op", ["build_pyramid", "build_laplacian_pyramid"])