π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-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.mdnew file mode 100644index 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.pyindex 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 annotationsimport math+import operator+from typing import Anyimport torchimport torch.nn.functional as Ffrom torch import nnfrom kornia.core.check import KORNIA_CHECK, KORNIA_CHECK_SHAPE+from kornia.core.exceptions import ValueCheckErrorfrom kornia.filters import filter2d, gaussian_blur2dfrom 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 morethan 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, andoctaves 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 shorterside 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_levelsself.extra_levels = extra_levels@@ -448,9 +480,11 @@ class ScalePyramid(nn.Module):sigmas[-1][:, level_idx] = cur_sigma_octpixel_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:breakdiff --git a/tests/geometry/transform/test_pyramid.py b/tests/geometry/transform/test_pyramid.pyindex 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 npimport pytestimport torchimport korniafrom 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, ValueCheckErrorfrom 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"])