# 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.
#

import math
from contextlib import nullcontext
from typing import ContextManager, List, Optional, Tuple, TypedDict, Union

import torch
import torch.nn.functional as F
from torch import nn

from kornia.core.check import KORNIA_CHECK, KORNIA_CHECK_SAME_SIZE, KORNIA_CHECK_SHAPE, KORNIA_CHECK_SIZES
from kornia.core.utils import _autocast_disabled
from kornia.geometry.subpix import (
    AdaptiveQuadInterp3d,
    ConvQuadInterp3d,
    IterativeQuadInterp3d,
    NonMaximaSuppression2d,
    nms3d_minmax,
)
from kornia.geometry.transform import ScalePyramid, pyrdown, resize

from .laf import laf_from_center_scale_ori, laf_is_filled
from .orientation import PassLAF
from .responses import BlobDoG, BlobHessian, CornerGFTT, CornerHarris


def _scale_index_to_scale(max_coords: torch.Tensor, sigmas: torch.Tensor, num_levels: int) -> torch.Tensor:
    r"""Auxiliary function for ScaleSpaceDetector.

    Converts scale level index from the subpix module to the actual
    scale, using the sigmas from the ScalePyramid output.

    Args:
        max_coords: torch.Tensor [BxNx3].
        sigmas: torch.Tensor [BxD], D >= 1
        num_levels: number of levels in the scale index.

    Returns:
        torch.Tensor [BxNx3].

    """
    B = max_coords.shape[0]
    base_sigma = sigmas[:, 0].view(B, 1, 1)  # (B, 1, 1) — per-batch base sigma
    max_coords[:, :, 0:1] = base_sigma * torch.pow(2.0, max_coords[:, :, 0:1] / float(num_levels))
    return max_coords


def _resize_mask(mask: torch.Tensor, ref: torch.Tensor) -> torch.Tensor:
    r"""Resample a full-resolution mask onto ``ref``'s spatial size and dtype, conservatively.

    A mask says where a detection may be. A boolean or integer mask is binary -- any non-zero
    value keeps a position, so a 0/1 and an OpenCV-style 0/255 mask mean the same thing -- and a
    floating-point mask is used as weights (see :func:`_weight_scores`). The resample is a
    min-pool: a level pixel takes the smallest mask value among the source pixels it covers, so a
    zero region suppresses every level pixel it touches and a thin one cannot fall between the
    samples of an interpolation. The result is cast to ``ref``'s dtype, so the weighting that
    follows cannot promote the response map to the mask's dtype; a weight the image dtype cannot
    hold (below ~6e-8 for a float16 image) rounds to zero and suppresses. Weights above one are
    clamped to one -- a weight never promotes -- so a float 0/255 mask, an OpenCV mask that went
    through ``.astype(np.float32)``, means the same as the integer one.
    """
    if mask.is_floating_point():
        m = mask.to(torch.float64 if mask.dtype == torch.float64 else torch.float32).clamp_max(1.0)
    else:
        m = mask.ne(0).to(torch.float32)
    h, w = ref.shape[-2], ref.shape[-1]
    m = _adaptive_min_pool_1d(m, h, dim=-2)
    m = _adaptive_min_pool_1d(m, w, dim=-1)
    return m.to(ref.dtype)


def _adaptive_min_pool_1d(m: torch.Tensor, out_size: int, dim: int) -> torch.Tensor:
    r"""Min-pool ``m`` along ``dim`` onto ``out_size`` samples with :func:`adaptive_max_pool2d`'s windows.

    Output sample ``i`` covers the source samples ``floor(i * n / out_size) .. ceil((i + 1) * n / out_size) - 1``,
    exactly the window of ``torch.nn.functional.adaptive_max_pool2d``, so the result equals
    ``-adaptive_max_pool2d(-m)`` on CPU. It is spelled as a gather so that every device pools the same windows:
    on MPS, ``adaptive_max_pool2d`` returns the wrong shape when the output is larger than the input and pools
    other windows than CPU when the ratio is not an integer, so the resampled mask, and with it the detections,
    would depend on the device.
    """
    dim = dim % m.dim()
    n = m.shape[dim]
    if n == out_size:
        return m
    # Window bounds are shape arithmetic, so they are Python constants under `torch.compile`.
    starts = [(i * n) // out_size for i in range(out_size)]
    ends = [-((-(i + 1) * n) // out_size) for i in range(out_size)]
    width = max(e - s for s, e in zip(starts, ends))
    # (out_size, width) source indices per output sample; the positions past a window's end are
    # clamped onto its last sample, which is inside the window, so they never change the min.
    idx = [[min(s + j, e - 1) for j in range(width)] for s, e in zip(starts, ends)]
    index = torch.tensor(idx, device=m.device, dtype=torch.long).reshape(-1)
    gathered = m.index_select(dim, index)
    shape = list(m.shape)
    shape[dim] = out_size
    shape.insert(dim + 1, width)
    return gathered.reshape(shape).amin(dim=dim + 1)


def _weight_scores(
    scores: torch.Tensor, weights: torch.Tensor, bound_dtype: Optional[torch.dtype] = None
) -> torch.Tensor:
    r"""Scale detection ``scores`` by ``weights`` toward the worst score, so a weight never promotes.

    A weight in ``(0, 1]`` multiplies a non-negative score and *divides* a negative one: the score
    moves away from the best in both cases, and a down-weighted candidate can never outrank a
    full-weight candidate whose unweighted score was at least as good. A plain multiply pulls a
    negative score toward zero, i.e. up the ranking, which inverted the order of a signed
    response. Positions with a zero or negative weight are excluded from the candidates before
    this runs; their divisor is replaced by one so no ``inf`` is produced there.

    The quotient of a negative score and a small weight can leave the dtype's range, and ``-inf``
    is the sentinel an unfilled slot carries into the ranking, so the arithmetic runs in float32
    for half-precision input and the result is bounded at ``finfo.min`` of the score dtype before
    the cast back: a weighted detection is finite and so always stays ahead of the padding. Wider
    dtypes are unchanged wherever the quotient is representable. ``bound_dtype`` names the dtype the
    score is reported in when that is narrower than ``scores``, as for the float32 copy of a
    half-precision response that :class:`ScaleSpaceDetector` ranks, so the bound still fits it.
    """
    dtype = scores.dtype
    wide = torch.float32 if dtype in (torch.float16, torch.bfloat16) else dtype
    s, w = scores.to(wide), weights.to(wide)
    divisor = torch.where(w > 0, w, torch.ones_like(w))
    out = torch.where(s >= 0, s * w, s / divisor)
    return out.clamp_min(torch.finfo(dtype if bound_dtype is None else bound_dtype).min).to(dtype)


def _create_octave_mask(mask: torch.Tensor, octave_resp: torch.Tensor) -> torch.Tensor:
    r"""Resample a mask onto the given octave response map, as ``(B, 1, 1, H, W)``."""
    return _resize_mask(mask, octave_resp).unsqueeze(1)


def _check_mask(mask: torch.Tensor, img: torch.Tensor) -> None:
    r"""Check that ``mask`` is ``(1 or B, 1, H, W)`` for an image ``(B, C, H, W)``.

    The mask is resampled onto every level, so a mask of another spatial size would be stretched
    silently onto the wrong geometry -- a stale mask from before a resize, or a transposed one.
    It must be single-channel: it multiplies a single-channel response per level in
    :class:`MultiResolutionDetector`, and in :class:`ScaleSpaceDetector` it is broadcast over the
    scale levels, where a channel axis would land on the level axis instead.
    """
    KORNIA_CHECK(mask.dim() == 4 and mask.shape[1] == 1, f"mask must be (1 or B, 1, H, W). Got {tuple(mask.shape)}")
    KORNIA_CHECK(mask.device == img.device, f"mask device {mask.device} must match the image device {img.device}")
    KORNIA_CHECK_SAME_SIZE(mask, img, allow_one=True, msg="The mask batch must be 1 or match the image batch.")
    KORNIA_CHECK(
        mask.shape[-2:] == img.shape[-2:],
        f"mask spatial size {tuple(mask.shape[-2:])} must match the image {tuple(img.shape[-2:])}",
    )


def _zero_unfilled(lafs: torch.Tensor, filled: torch.Tensor) -> torch.Tensor:
    r"""Replace unused detection slots with zero LAFs.

    ``filled`` is a ``(B, N)`` boolean mask of the slots a detection actually filled. The
    affine-shape and orientation modules may normalise or propagate invalid padding frames
    differently by dtype, so the mask is re-applied after them. ``where`` rather than a multiply,
    so a module that returns NaN for a zero frame cannot leak it into the padding.

    Both detectors' ``forward`` read the mask off the LAFs that ``detect`` returns: a zero LAF is
    the padding contract, and it is the one signal a subclass overriding ``detect`` also honours.
    The response cannot serve: :class:`ScaleSpaceDetector`'s response function is pluggable and
    may be signed, so an exact zero there is a legitimate maximum.
    """
    return torch.where(filled[..., None, None], lafs, torch.zeros_like(lafs))


_BUILTIN_SUBPIX = (ConvQuadInterp3d, AdaptiveQuadInterp3d, IterativeQuadInterp3d)


def _subpix_dispatch(module: nn.Module) -> Tuple[bool, bool]:
    """Classify the sub-pixel refiner the detector currently holds.

    Returns ``(is_iterative, batchable)``. ``is_iterative`` means the module is one of the built-in
    refiners or a subclass, so it accepts ``precomputed_nms_mask``. ``batchable`` means both response
    signs can be refined in one stacked call: only the exact built-in classes qualify (a subclass may
    change the per-image semantics), and only without a candidate cap, which
    :func:`~kornia.geometry.subpix.iterative_quad_interp3d` applies across the whole batch rather
    than per image. Both flags read through a :func:`torch.compile` wrapper, whether the detector
    compiled the module itself or the caller passed a compiled one, so the same module is dispatched
    the same way on every path.
    """
    subpix = getattr(module, "_orig_mod", module)
    is_iterative = isinstance(subpix, _BUILTIN_SUBPIX)
    batchable = type(subpix) in _BUILTIN_SUBPIX and getattr(subpix, "max_candidates", None) is None
    return is_iterative, batchable


_FLOAT16_IN_FLOAT32_RESPONSES = (BlobHessian, BlobDoG, CornerHarris, CornerGFTT)


def _holds_only_scalars(module: nn.Module) -> bool:
    """Return whether every parameter and buffer of ``module`` is zero-dimensional, so none rejects an input dtype."""
    return all(t.dim() == 0 for t in (*module.parameters(), *module.buffers()))


def _detects_float16_in_float32(pyramid: nn.Module, response: nn.Module, subpix: nn.Module) -> bool:
    """Return whether a float16 image can run through these modules in float32, with autocast off.

    The pyramid and the response function get the image, so only their exact built-in classes qualify, read through a
    :func:`torch.compile` wrapper. These follow their input's dtype, whatever dtype the module was converted to, so a
    float32 input comes back as float32, which `_detect` can round to float16. A custom module or a subclass may hold
    float16 weights that reject float32 input, or return a wider response on purpose, and from the outside neither can
    be told from a module that follows its input, so it gets the float16 image. So does a :class:`CornerHarris` with a
    non-scalar ``k``, which promotes a float16 response. The refiner gets the response in at least float32 on every
    path, so its class does not matter; only autocast changes for it, and turning that off would make float16 weights
    reject the input they now get cast for.

    Measured on a float16 image, CPU and CUDA: with ``isinstance``, a subclass with a float16 weight raises and a
    subclass returning a wider response has its float32 score of 1.0001 rounded to 1.0; the exact check costs an
    unmodified subclass the fix (5120 of 5120 non-finite, as on main).
    """
    return (
        type(getattr(pyramid, "_orig_mod", pyramid)) is ScalePyramid
        and type(getattr(response, "_orig_mod", response)) in _FLOAT16_IN_FLOAT32_RESPONSES
        and _holds_only_scalars(response)
        and _holds_only_scalars(subpix)
    )


def _nms_candidates(response: torch.Tensor, float16_scores: bool) -> Tuple[torch.Tensor, torch.Tensor]:
    """Return the masks of the strict maxima and minima of ``response``, an octave's response in at least float32.

    With ``float16_scores`` it comes from a float16 image, whose quantisation noise makes weak maxima with scores below
    float16's resolution, so only those are dropped. Rounding the response before NMS would also merge real maxima:
    Harris fills 252 slots against float32's 825 on HPatches, this 545.
    """
    max_mask, min_mask = nms3d_minmax(response)
    if float16_scores:
        scored = response.to(torch.float16) != 0
        return max_mask & scored, min_mask & scored
    return max_mask, min_mask


class ScaleSpaceDetector(nn.Module):
    r"""Detect LAFs at the sub-pixel scale-space maxima of a pluggable response, for a batch of images.

    ``detector = ScaleSpaceDetector(num_features)`` builds a detector with a Hessian response by default.
    ``lafs, responses = detector(img)`` takes grayscale images ``(B, 1, H, W)`` and returns LAFs
    ``(B, num_features, 2, 3)`` in input pixels and responses ``(B, num_features)``, strongest first.
    Use :func:`laf_is_filled` to keep detected features and discard padded slots in both outputs.
    For per-level 2D maxima, use :class:`MultiResolutionDetector`; for SIFT detection and description,
    use :class:`SIFTFeatureScaleSpace`.

    Convention:
        - The modules run in this order: ``scale_pyr_module``, ``resp_module``, ``subpix_module``, ``aff_module``,
          then ``ori_module``. The last two default to :class:`PassLAF`, which leaves frames unchanged.
          ``detector.detect(img, num_feats)`` returns ``(responses, lafs)`` before shape and orientation estimation;
          note the reversed output order compared with ``detector(img)``.
        - The candidates are the strict :math:`3 \times 3 \times 3` maxima of the response over level, row and column
          (:func:`~kornia.geometry.subpix.nms3d_minmax`) on the levels given under ``scale_pyr_module``, whatever their
          sign. With ``minima_are_also_good`` a strict minimum is a candidate too when its negated response after
          sub-pixel refinement exceeds the response the maxima pass reports at that voxel, which the built-in refiners
          leave at its sampled value: in effect every minimum below zero, and a minimum above zero only when the
          refinement extrapolates it below minus its sampled value. There is no response threshold. The
          ``num_features`` strongest candidates of all octaves are kept; a minimum is ranked and returned with its
          refined response negated.
        - The default Hessian response is a maximum at bright and dark blobs alike. It keeps the channels, so a
          multi-channel image needs a ``resp_module`` that returns one map. A DoG response
          (:class:`~kornia.feature.BlobDoG`) is a maximum at a dark blob and a minimum at a bright one, which only
          ``minima_are_also_good=True`` detects.
        - A LAF centre is the refined sub-pixel position, mapped to input pixels as given under
          ``scale_pyr_module``, using the pixel convention of :func:`~kornia.feature.laf_from_center_scale_ori`
          (see :ref:`Local features <local-features-conventions>`). Before ``aff_module`` and ``ori_module`` run, the
          frame is diagonal: ``mr_size`` times the detection scale, mapped to input pixels along each axis like the
          centre.
        - A candidate is kept when half its frame lies at least 5 octave pixels inside the octave's outer pixel
          centres; the whole frame can reach outside the image.
        - The output has ``num_features`` slots: the detections by decreasing response, then the unfilled slots, which
          hold a zero response and a zero LAF.
        - The LAFs are float32 for a float16 or bfloat16 image and float64 for a float64 one; the responses keep the
          response function's dtype. Non-maximum suppression and sub-pixel refinement run on the response promoted to
          at least float32. With :class:`~kornia.geometry.transform.ScalePyramid`, a :class:`BlobHessian`,
          :class:`BlobDoG`, :class:`CornerHarris` or :class:`CornerGFTT` response, and a response and refiner holding
          only scalar parameters and buffers, a float16 image is detected in float32 with autocast off and its scores
          are returned in float16, because the gradient overflows float16 on the way through the scale space. A
          candidate whose score is zero in float16 is dropped. With any other pyramid or response function, a subclass
          or a :class:`CornerHarris` with a non-scalar ``k`` included, or a refiner with non-scalar state, the detector
          passes the float16 image on, in the caller's autocast region.
        - With the default modules the responses, centres and scales carry gradients to the image.
        - A batch of zero images returns empty outputs of the documented shapes, after the checks a non-empty batch
          runs.
        - Border and refined-centre mask checks run before the per-octave feature budget, so a rejected
          candidate cannot displace a weaker valid candidate.

    Args:
        num_features: Number of features to detect. In order to keep everything batchable,
          output would always have num_features output, even for completely homogeneous images.
        mr_size: multiplier from the detection scale to the LAF scale. The default 6.0 gives a frame of about six
          times the :math:`\sigma` of a detected Gaussian blob.
        scale_pyr_module: generates scale pyramid. See :class:`~kornia.geometry.transform.ScalePyramid` for details.
          Default: ``ScalePyramid(3, 1.6, 16, extra_levels=3)`` with a scale-space response,
          ``extra_levels=2`` without. A detection at octave pixel :math:`(u, v)` is reported at
          :math:`(u (W - 1) / (W_o - 1), v (H - 1) / (H_o - 1))` in the input, the map of
          :class:`~kornia.geometry.transform.ScalePyramid`'s ``align_corners=True`` resizes; a custom pyramid has to
          resize the same way. Each octave searches ``n_levels`` response levels, levels
          ``1..n_levels``; the levels below and above them are NMS neighbours only, and any further
          level is ignored. A per-level response therefore needs ``extra_levels >= 2``, and DoG,
          which has one level fewer than its pyramid, ``extra_levels >= 3``.
        resp_module: calculates ``'cornerness'`` of the pixel. Default: :class:`~kornia.feature.BlobHessian`.
        subpix_module: refines the position and scale of each candidate to sub-pixel / sub-scale accuracy. The
          candidates are those of the Convention block, whatever the module. Default:
          :class:`~kornia.geometry.subpix.AdaptiveQuadInterp3d` with ``allow_scale_steps=True``.
        ori_module: for local feature orientation estimation. Default: :class:`~kornia.feature.PassLAF`,
           which does nothing. See :class:`~kornia.feature.LAFOrienter` for details.
        aff_module: for local feature affine shape estimation. Default: :class:`~kornia.feature.PassLAF`,
            which does nothing. See :class:`~kornia.feature.LAFAffineShapeEstimator` for details.
        minima_are_also_good: if True, then both response function minima and maxima are detected.
            A DoG response needs it to detect bright blobs. Default is False.
            Refining both signs can use roughly twice the peak memory of refining maxima alone.
        scale_space_response: if True, ``resp_module`` gets each whole octave ``(B, C, L, H, W)`` with its
            sigmas ``(B * L,)`` and returns a ``(B, 1, L', H, W)`` scale-space response, as
            :class:`~kornia.feature.BlobDoG` does. If False (the default), it gets the octave's levels
            ``0 .. n_levels + 1`` as ``(B * L, C, H, W)`` images, ``L = n_levels + 2``, with their sigmas
            and returns ``(B * L, 1, H, W)``.
        compile_modules: selects which sub-modules to wrap with :func:`torch.compile`.
            Pass ``True`` to compile every sub-module, ``False`` (default) for none, or a list
            containing any subset of ``["scale_pyr", "resp", "subpix", "ori", "aff"]``.
            The first call compiles, and a new input shape, such as another batch size, can compile again.

    See Also:
        - :class:`MultiResolutionDetector`: one image per call, the 2D maxima of a response on each level of an image
          pyramid, at integer level pixels and without scale selection.
        - :class:`KeyNetDetector`: that detector on the learned KeyNet response.
        - :class:`SIFTFeatureScaleSpace`: SIFT, whose ``"patch"`` backend is this detector on a DoG response.
        - :class:`DoGHardNet`: this detector on a DoG response, with HardNet descriptors.
        - :class:`~kornia.geometry.subpix.ConvSoftArgmax3d`: a ``subpix_module`` that takes the soft-argmax of a
          window instead of a quadratic fit.

    Example:
        >>> lafs, responses = ScaleSpaceDetector(num_features=100)(torch.rand(2, 1, 64, 64))
        >>> lafs.shape, responses.shape
        (torch.Size([2, 100, 2, 3]), torch.Size([2, 100]))

    """

    def __init__(
        self,
        num_features: int = 500,
        mr_size: float = 6.0,
        scale_pyr_module: Optional[nn.Module] = None,
        resp_module: Optional[nn.Module] = None,
        subpix_module: Optional[nn.Module] = None,
        ori_module: Optional[nn.Module] = None,
        aff_module: Optional[nn.Module] = None,
        minima_are_also_good: bool = False,
        scale_space_response: bool = False,
        compile_modules: Union[bool, List[str]] = False,
    ) -> None:
        super().__init__()
        self.mr_size = mr_size
        self.num_features = num_features

        _all_names = {"scale_pyr", "resp", "subpix", "ori", "aff"}
        if compile_modules is True:
            _compile_set = _all_names
        elif compile_modules is False:
            _compile_set = set()
        else:
            _compile_set = set(compile_modules)
            unknown = _compile_set - _all_names
            if unknown:
                raise ValueError(f"Unknown module names in compile_modules: {unknown}. Valid: {_all_names}")

        self._compile_set: frozenset[str] = frozenset(_compile_set)

        def _maybe_compile(mod: nn.Module, name: str) -> nn.Module:
            return torch.compile(mod, dynamic=True) if name in self._compile_set else mod

        if scale_pyr_module is None:
            extra_levels = 3 if scale_space_response else 2
            scale_pyr_module = ScalePyramid(3, 1.6, 16, extra_levels=extra_levels)
        self.scale_pyr = _maybe_compile(scale_pyr_module, "scale_pyr")
        if resp_module is None:
            resp_module = BlobHessian()
        self.resp = _maybe_compile(resp_module, "resp")
        if subpix_module is None:
            subpix_module = AdaptiveQuadInterp3d(allow_scale_steps=True)
        self.subpix = _maybe_compile(subpix_module, "subpix")
        if ori_module is None:
            ori_module = PassLAF()
        self.ori = _maybe_compile(ori_module, "ori")
        if aff_module is None:
            aff_module = PassLAF()
        self.aff = _maybe_compile(aff_module, "aff")
        self.minima_are_also_good = minima_are_also_good
        # scale_space_response should be True if the response function works on scale space
        # like Difference-of-Gaussians
        self.scale_space_response = scale_space_response

    def _dynamo_config_patch(self, modules: Tuple[str, ...]) -> ContextManager[None]:
        if self._compile_set.intersection(modules):
            # Allow torch.compile to keep data-dependent shape ops (torch.where / nonzero)
            # inside the compiled graph as unbacked symbols, avoiding graph breaks and the
            # 0/1-specialization recompilations that would otherwise fire whenever an octave
            # first encounters zero NMS maxima (blurry/extreme-viewpoint images).
            return torch._dynamo.config.patch(capture_dynamic_output_shape_ops=True)
        return nullcontext()

    def __repr__(self) -> str:
        return (
            f"{self.__class__.__name__}("
            f"num_features={self.num_features}, "
            f"mr_size={self.mr_size}, "
            f"scale_pyr={self.scale_pyr.__repr__()}, "
            f"resp={self.resp.__repr__()}, "
            f"subpix={self.subpix.__repr__()}, "
            f"ori={self.ori.__repr__()}, "
            f"aff={self.aff.__repr__()})"
        )

    def _refine_minmax(
        self,
        response: torch.Tensor,
        max_mask: torch.Tensor,
        min_mask: torch.Tensor,
        is_iterative_subpix: bool,
        batchable_subpix: bool,
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
        """Refine both response signs, batching only independent built-in refiners."""
        if batchable_subpix:
            # Keep NMS neighbourhoods separate: merging masks would let extrema
            # move into the other sign's dilation neighbourhood. The candidate cap
            # excluded above needs separate calls, since it applies across the whole batch.
            batch = response.shape[0]
            coords, values = self.subpix(
                torch.cat((response, -response), dim=0),
                precomputed_nms_mask=torch.cat((max_mask, min_mask), dim=0),
            )
            return coords[:batch], values[:batch], coords[batch:], values[batch:]
        if is_iterative_subpix:
            coord_max, response_max = self.subpix(response, precomputed_nms_mask=max_mask)
            coord_min, response_min = self.subpix(-response, precomputed_nms_mask=min_mask)
        else:
            coord_max, response_max = self.subpix(response)
            coord_min, response_min = self.subpix(-response)
        return coord_max, response_max, coord_min, response_min

    def _process_octave(
        self,
        octave: torch.Tensor,
        sigmas_oct: torch.Tensor,
        num_feats: int,
        mask: Optional[torch.Tensor],
        rotmat: torch.Tensor,
        num_levels: int,
        is_iterative_subpix: bool,
        batchable_subpix: bool,
        octave_to_image: Tuple[float, float],
        float16_scores: bool = False,
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.dtype]:
        """Process one scale-space octave: response → NMS/subpix → validity → top-K → LAF.

        Returns the top-K responses, their LAFs, a boolean mask of the slots a detection
        actually filled, and the dtype of the response function's output. The batched top-K below
        ranks over the whole volume and returns its ``fill`` sentinel once the octave runs out of
        valid candidates; the mask tells those slots apart from a detection, since the response alone
        cannot. The responses and LAFs are in at least float32; ``_detect`` casts the responses back to
        the returned dtype.
        """
        dev = octave.device
        # An octave searches `num_levels` response levels, 1..num_levels; levels 0 and num_levels + 1 are only
        # their NMS neighbours. A further level would make level num_levels + 1 searchable too, and that level has
        # the scale of level 1 of the next octave, which the per-octave NMS never compares it with: that scale
        # would be detected twice. A per-level response is computed on the levels it needs only; a scale-space
        # response is cut once it has run.
        n_resp_levels = num_levels + 2
        if not self.scale_space_response:
            octave = octave[:, :, :n_resp_levels]
            sigmas_oct = sigmas_oct[:, :n_resp_levels]
        B, CH, L, H, W = octave.size()

        # Run response function
        if self.scale_space_response:
            with self._dynamo_config_patch(("resp",)):
                oct_resp = self.resp(octave, sigmas_oct.view(-1))  # (B, 1, Ldog, H, W)
        else:
            with self._dynamo_config_patch(("resp",)):
                level_resp = self.resp(octave.permute(0, 2, 1, 3, 4).reshape(B * L, CH, H, W), sigmas_oct.reshape(-1))
            KORNIA_CHECK_SIZES(
                level_resp, [B * L, 1, H, W], "resp_module must return one response map per image, (B * L, 1, H, W)."
            )
            oct_resp = level_resp.view(B, L, 1, H, W)
            # Reorder to (B, CH, L, H, W) for scale-space NMS
            oct_resp = oct_resp.permute(0, 2, 1, 3, 4)
        KORNIA_CHECK_SIZES(
            oct_resp,
            [B, 1, None, H, W],
            "resp_module must return one scale-space response channel, (B, 1, L, H, W). For a multi-channel image, "
            "convert it to grayscale first or use a response function that reduces the channels to one.",
        )
        # Iterative sub-pixel modules flatten the full response volume internally. The
        # level/channel permutation above is contiguous when CH == 1 (the common path), but
        # not for a response that preserves multiple channels, nor for a scale-space response cut to its levels.
        oct_resp = oct_resp[:, :, :n_resp_levels].contiguous()
        # The mask weights are cast to the response's own dtype (see `_resize_mask`), before the promotion below.
        resampled = None if mask is None else _create_octave_mask(mask, oct_resp)
        # The refiners write absolute pixel coordinates into a tensor of the response's dtype, and bfloat16 holds no
        # odd integer above 256 (float16: above 2048). Run NMS, refinement and top-K on the response in at least
        # float32; promoting is exact, so NMS selects the same candidates. `_detect` casts the responses back.
        resp_dtype = torch.float16 if float16_scores else oct_resp.dtype
        oct_resp = oct_resp.to(torch.promote_types(oct_resp.dtype, torch.float32))
        scale_sigmas = sigmas_oct[:, : oct_resp.shape[2]].to(oct_resp.dtype)

        # Always precompute NMS masks in one fused pass.
        # - For minima_are_also_good: both masks are needed anyway.
        # - Otherwise: max_nms_mask is passed to subpix (skips its internal NMS on GPU)
        #   and drives the sparse top-K below.
        max_nms_mask: torch.Tensor
        min_nms_mask: torch.Tensor
        max_nms_mask, min_nms_mask = _nms_candidates(oct_resp, float16_scores)

        # The mask is applied to the candidates, not to the response the NMS reads: multiplying the
        # response first would carve a hard edge into it, and every response pixel next to a zeroed
        # neighbour becomes a "maximum" along that edge. The resampled mask is conservative (see
        # `_resize_mask`), so a zero region drops every candidate it touches; a weight scales the
        # score of the candidates it keeps.
        oct_mask: Optional[torch.Tensor] = None
        oct_keep: Optional[torch.Tensor] = None
        if mask is not None and resampled is not None:
            oct_keep = resampled > 0
            max_nms_mask = max_nms_mask & oct_keep
            min_nms_mask = min_nms_mask & oct_keep
            # A boolean or integer mask resamples to exactly 0/1, and the zeros are already dropped
            # above, so weighting by it is a no-op over the whole volume; only real weights run.
            if mask.is_floating_point():
                oct_mask = resampled

        with self._dynamo_config_patch(("subpix",)):
            if self.minima_are_also_good:
                coord_max, response_max, coord_min, response_min = self._refine_minmax(
                    oct_resp, max_nms_mask, min_nms_mask, is_iterative_subpix, batchable_subpix
                )
            elif is_iterative_subpix:
                coord_max, response_max = self.subpix(oct_resp, precomputed_nms_mask=max_nms_mask)
            else:
                coord_max, response_max = self.subpix(oct_resp)

        # Zero responses at scale border levels so they never reach top-K.
        # (nms3d_minmax already sets the masks False at these positions.)
        response_max[:, :, 0] = 0.0
        response_max[:, :, -1] = 0.0
        if oct_mask is not None:
            response_max = _weight_scores(response_max, oct_mask, resp_dtype)

        if self.minima_are_also_good:
            response_min[:, :, 0] = 0.0
            response_min[:, :, -1] = 0.0
            if oct_mask is not None:
                response_min = _weight_scores(response_min, oct_mask, resp_dtype)
            take_min_mask = (response_min > response_max) & min_nms_mask
            response_max = torch.where(take_min_mask, response_min, response_max)
            # Candidate positions: original max-NMS plus swapped min-NMS positions.
            cand_mask = max_nms_mask | take_min_mask
        else:
            cand_mask = max_nms_mask

        # Sparse top-K: gather the small set of NMS candidates first, then run top-K
        # on that (~few-thousand) set instead of the full CHxLxHxW volume (~millions).
        # nms3d_minmax guarantees cand_mask is False at scale border levels already.
        # Response/candidate tensors are (B, C, L, H, W), while coordinates are
        # (B, C, 3, L, H, W). Move the xyz axis last before flattening so entry i in
        # every tensor describes the same (channel, scale, y, x) candidate. Responses
        # are single-channel by the contract checked above, but custom sub-pixel modules
        # still have to preserve this axis order.
        mask_flat = cand_mask.flatten(1)  # (B, C*L*H*W)
        resp_flat = response_max.flatten(1)  # (B, C*L*H*W)
        coord_flat = coord_max.movedim(2, -1).flatten(1, -2)  # (B, C*L*H*W, 3)

        # Validate every sparse NMS candidate before budgeting: a stronger rejected frame must
        # not hide a weaker valid one. Only candidate coordinates are materialized, not dense LAFs.
        # CPU float32, 240x320 graf, 512 features: B=1/2 medians 25.7/45.1 ms
        # versus 25.9/45.0 ms before validation moved here (one thread, no gradients).
        batch_idx, candidate_idx = mask_flat.nonzero(as_tuple=True)
        candidate_coords = coord_flat[batch_idx, candidate_idx]
        if self.minima_are_also_good:
            coord_min_flat = coord_min.movedim(2, -1).flatten(1, -2)
            candidate_coords = torch.where(
                take_min_mask.flatten(1)[batch_idx, candidate_idx, None],
                coord_min_flat[batch_idx, candidate_idx],
                candidate_coords,
            )
        candidate_scale = scale_sigmas[batch_idx, 0] * torch.pow(2.0, candidate_coords[:, 0] / float(num_levels))
        # Match the promotion of scale * rotmat in the final LAF, including custom responses that are either
        # narrower or wider than the image. Narrowing either operand can round an overhanging frame onto the border.
        frame_dtype = torch.promote_types(candidate_scale.dtype, rotmat.dtype)
        half_s = (self.mr_size * candidate_scale).to(frame_dtype) * 0.5
        cx, cy = candidate_coords[:, 1], candidate_coords[:, 2]
        # Equivalent to laf_is_inside_image(scale_laf(laf, 0.5), octave[:, 0], 5)
        # for the isotropic frames assembled below, in octave pixel coordinates.
        good_mask = (cx - half_s >= 5) & (cx + half_s <= W - 1 - 5)
        good_mask = good_mask & (cy - half_s >= 5) & (cy + half_s <= H - 1 - 5)
        if oct_keep is not None:
            # Every pixel touched by the refined centre must be allowed, including after
            # refinement moves a candidate away from its initially allowed integer NMS site.
            keep_flat = oct_keep.flatten(1).expand(B, -1)
            x0 = cx.floor().long().clamp_(0, W - 1)
            x1 = cx.ceil().long().clamp_(0, W - 1)
            y0 = cy.floor().long().clamp_(0, H - 1)
            y1 = cy.ceil().long().clamp_(0, H - 1)
            for yy in (y0, y1):
                for xx in (x0, x1):
                    good_mask = good_mask & keep_flat[batch_idx, yy * W + xx]
        if B == 1:
            nms_idx = candidate_idx[good_mask]  # (M,)
            resp_cands = resp_flat[0][nms_idx]  # (M,)
            k_eff = min(num_feats, nms_idx.shape[0])
            # Only NMS candidates are gathered here, so every returned slot is one.
            is_cand = torch.ones(1, k_eff, dtype=torch.bool, device=dev)
            if k_eff > 0:
                resp_flat_best, local_idx = torch.topk(resp_cands, k=k_eff)
                idxs = nms_idx[local_idx].unsqueeze(0)
                resp_flat_best = resp_flat_best.unsqueeze(0)  # (1, k_eff)
            else:
                # A zero-width slice, not a fresh tensor: the empty result stays linked to the response.
                resp_flat_best = resp_flat[:, :0]
                idxs = nms_idx.new_empty(1, 0)
        else:
            # Batched fallback: mask non-candidates to -inf so they lose top-K to every finite
            # response. (A finite sentinel such as `finfo.min / 2` is not below every finite
            # response, and outranked a genuine extreme maximum.)
            mask_flat = mask_flat.clone()
            mask_flat[batch_idx, candidate_idx] = good_mask
            resp_masked = resp_flat.masked_fill(~mask_flat, float("-inf"))
            k_eff = min(num_feats, resp_masked.size(1))
            resp_flat_best, idxs = torch.topk(resp_masked, k=k_eff, dim=1)
            # `topk` cannot rank among the masked-out positions -- they all carry the same
            # `fill` -- so an image with fewer than `num_feats` maxima gets an arbitrary subset
            # of non-candidates back. Carry the candidacy of each selected slot forward.
            is_cand = torch.gather(mask_flat, 1, idxs)

        coord_idxs = idxs.unsqueeze(-1).expand(-1, -1, 3)
        max_coords_best = torch.gather(coord_flat, 1, coord_idxs)
        if self.minima_are_also_good:
            # Merge coordinates only for the selected features, not for every voxel
            # in the octave (three full image volumes per scale level).
            coord_min_flat = coord_min.movedim(2, -1).flatten(1, -2)
            min_coords_best = torch.gather(coord_min_flat, 1, coord_idxs)
            take_min_best = torch.gather(take_min_mask.flatten(1), 1, idxs)
            max_coords_best = torch.where(take_min_best.unsqueeze(-1), min_coords_best, max_coords_best)

        B, N = resp_flat_best.size()

        max_coords_best = _scale_index_to_scale(max_coords_best, scale_sigmas, num_levels)

        current_lafs = torch.cat(
            [
                self.mr_size * max_coords_best[:, :, 0].view(B, N, 1, 1) * rotmat,
                max_coords_best[:, :, 1:3].view(B, N, 2, 1),
            ],
            3,
        )

        # Invalid batched top-K sentinels lose to every real detection, including negative
        # responses, in the cross-octave ranking. `_detect` zeroes their response and LAF.
        filled = is_cand
        resp_flat_best = resp_flat_best.masked_fill(~filled, float("-inf"))
        # Octave pixels to input pixels, per axis: x scales the first LAF row, y the second.
        current_lafs[:, :, 0, :].mul_(octave_to_image[0])
        current_lafs[:, :, 1, :].mul_(octave_to_image[1])
        return resp_flat_best, current_lafs, filled, resp_dtype

    def _detect(
        self, img: torch.Tensor, num_feats: int, mask: Optional[torch.Tensor] = None
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Run the detection and also return the boolean mask of the slots a detection filled.

        ``forward`` needs the mask after ``aff`` and ``ori`` have run, and it cannot be recovered
        from the responses, so :meth:`detect` is a two-value view of this.
        """
        if mask is not None:
            _check_mask(mask, img)
        # The backward pass of a float16 scale space overflows: a response's gradient, about 4e4 even when the image's
        # is about 10, is multiplied by sigma ** 4, and a convolution then turns that inf into NaN at every pixel. So a
        # float16 image is detected in float32 when the modules allow it (see `_detects_float16_in_float32`), with
        # autocast off, since its convolutions would otherwise go back to the autocast dtype. The mask weights keep
        # their float16 values and only the scores are cast back. Every other image takes the path below untouched.
        if img.dtype == torch.float16 and _detects_float16_in_float32(self.scale_pyr, self.resp, self.subpix):
            if mask is not None and mask.is_floating_point():
                mask = mask.to(torch.float16)
            with _autocast_disabled(img.device.type):
                return self._detect_in_image_dtype(img.float(), num_feats, mask, True)
        return self._detect_in_image_dtype(img, num_feats, mask, False)

    def _detect_in_image_dtype(
        self, img: torch.Tensor, num_feats: int, mask: Optional[torch.Tensor], float16_scores: bool
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Run the scale space, the octaves and the cross-octave ranking on ``img`` in the dtype it has.

        ``float16_scores`` says that ``img`` is the float32 copy of a float16 image: see :meth:`_detect`.
        """
        dev = img.device
        dtype: torch.dtype = img.dtype
        with self._dynamo_config_patch(("scale_pyr",)):
            sp, sigmas, _ = self.scale_pyr(img)

        # ── Hoist loop invariants ────────────────────────────────────────────
        if isinstance(self.scale_pyr.n_levels, torch.Tensor):
            num_levels = int(self.scale_pyr.n_levels.item())
        elif isinstance(self.scale_pyr.n_levels, int):
            num_levels = self.scale_pyr.n_levels
        else:
            raise TypeError(
                "Expected the scale pyramid module to have `n_levels` as a torch.Tensor or int."
                f"Got {type(self.scale_pyr.n_levels)}"
            )
        # The LAFs are assembled in at least float32, the dtype `_process_octave` refines the centres in.
        rotmat = torch.eye(2, dtype=torch.promote_types(dtype, torch.float32), device=dev).view(1, 1, 2, 2)
        # Read the live module once per forward, so a refiner swapped in after construction, or a
        # compiled one passed by the caller, is dispatched consistently on both the single-sign and
        # the minima-and-maxima path.
        is_iterative_subpix, batchable_subpix = _subpix_dispatch(self.subpix)
        # ScalePyramid resizes with align_corners=True, which keeps the first and last pixel centres: octave pixel u
        # is input pixel u * (W - 1) / (W_o - 1) along x, and likewise along y. The nominal spacing 2 ** o is off by
        # up to half a pixel on a doubled octave and by more on every coarser one.
        H, W = img.shape[-2:]
        octave_to_image = [
            ((W - 1) / max(octave.shape[-1] - 1, 1), (H - 1) / max(octave.shape[-2] - 1, 1)) for octave in sp
        ]

        # ── Process octaves sequentially ────────────────────────────────────
        # All octaves are independent once the scale pyramid is built, but CUDA
        # stream parallelism does not help here: subpix allocates large scatter
        # tables per call, and concurrent CUDA allocations contend for the same
        # device memory allocator lock.  Tested: sequential ≈ parallel on GPU.
        n_oct = len(sp)
        results: List[Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.dtype]] = [
            self._process_octave(
                sp[i],
                sigmas[i],
                num_feats,
                mask,
                rotmat,
                num_levels,
                is_iterative_subpix,
                batchable_subpix,
                octave_to_image[i],
                float16_scores,
            )
            for i in range(n_oct)
        ]

        # Sort and keep best n across all octaves. Sparse per-octave top-K may yield fewer total
        # candidates than num_feats (e.g. small images with very few NMS maxima); the result is
        # padded to preserve the shape contract [B, num_feats, ...]. Every unfilled slot -- the
        # padding or a batched top-K sentinel -- carries `-inf` through the ranking so that a
        # genuine detection, however negative, still sorts ahead of it, and is zeroed only
        # afterwards. (`_weight_scores` keeps a weighted score finite.)
        responses = torch.cat([r[0] for r in results], 1)
        lafs = torch.cat([r[1] for r in results], 1)
        filled = torch.cat([r[2] for r in results], 1)
        n_candidates = responses.size(1)
        if n_candidates < num_feats:
            pad = num_feats - n_candidates
            responses = F.pad(responses, (0, pad), value=float("-inf"))
            lafs = F.pad(lafs, (0, 0, 0, 0, 0, pad))
            filled = F.pad(filled, (0, pad))
        responses, idxs = torch.topk(responses, k=num_feats, dim=1)
        lafs = torch.gather(lafs, 1, idxs.unsqueeze(-1).unsqueeze(-1).expand(-1, -1, 2, 3))
        filled = torch.gather(filled, 1, idxs)
        # The ranking ran on the float32 copy of a half-precision response; the scores keep the response's dtype.
        responses = torch.where(filled, responses, torch.zeros_like(responses)).to(results[0][3])
        return responses, _zero_unfilled(lafs, filled), filled

    def detect(
        self, img: torch.Tensor, num_feats: int, mask: Optional[torch.Tensor] = None
    ) -> Tuple[torch.Tensor, torch.Tensor]:
        """Detect local features in an image batch.

        Args:
            img: Input image tensor with shape ``(B, C, H, W)``.
            num_feats: Number of features requested from the detector.
            mask: Optional mask with shape ``(1 or B, 1, H, W)`` saying where a detection may be. A boolean or integer
                mask is binary (any non-zero value keeps a position), a floating-point mask is used as weights on the
                detection scores: a weight in ``(0, 1]`` scales a score toward the worst (a non-negative score is
                multiplied by it, a negative one divided), so a down-weighted candidate never outranks a full-weight
                one, and a zero or negative weight suppresses. Weights above one are clamped to one, so a float
                0/255 mask means what the integer one means. The weights are cast to the response's dtype. The mask is
                resampled onto every octave conservatively, so a zero region suppresses every candidate within one
                octave pixel of it.

        Returns:
            Tuple containing detection scores and local affine frames, shaped ``(B, num_feats)`` and
            ``(B, num_feats, 2, 3)``, in that order, the reverse of ``forward``'s. A slot that no detection filled --
            there were fewer candidates inside the border and the mask than requested -- carries a
            zero response and a zero LAF, and sorts after every real detection. The converse does not hold: a signed
            response function can peak at exactly zero, and that slot keeps its frame. A batch of zero images returns
            empty outputs of these shapes.
        """
        responses, lafs, _ = self._detect(img, num_feats, mask)
        return responses, lafs

    def forward(self, img: torch.Tensor, mask: Optional[torch.Tensor] = None) -> Tuple[torch.Tensor, torch.Tensor]:
        """Three stage local feature detection.

        First the location and scale of interest points are determined by detect function.
        Then affine shape and orientation.

        Args:
            img: image to extract features with shape ``(B, C, H, W)``.
            mask: a mask saying where a detection may be, shape ``(1, 1, H, W)`` or ``(B, 1, H, W)``. A boolean or
                integer mask is binary, a floating-point mask weights the detection scores; see :meth:`detect`.

        Returns:
            Tuple of ``lafs`` with shape ``(B, N, 2, 3)``, the detected local affine frames, and ``responses`` with
            shape ``(B, N)``, the response function values for the corresponding lafs, with ``N = num_features``.
            When fewer detections than ``num_features`` survive for an image, the remaining slots hold a zero
            response and a zero LAF, whichever affine-shape and orientation modules are configured.

        """
        # `detect` is the public extension point used by subclasses. Infer occupancy from its
        # zero-LAF padding contract rather than bypassing an override through `_detect`.
        responses, lafs = self.detect(img, self.num_features, mask)
        filled = laf_is_filled(lafs)
        with self._dynamo_config_patch(("aff",)):
            lafs = self.aff(lafs, img)
        with self._dynamo_config_patch(("ori",)):
            lafs = self.ori(lafs, img)
        return _zero_unfilled(lafs, filled), responses


class Detector_config(TypedDict):
    """Configuration for the multi-resolution detector, the ``config`` of :class:`MultiResolutionDetector`.

    Attributes:
        nms_size: The size of the Non-Maximum Suppression window, in level pixels.
        pyramid_levels: The number of image-pyramid levels below the input.
        up_levels: The number of image-pyramid levels above the input, upscaled.
        scale_factor_levels: The scale factor between adjacent levels.
        s_mult: The LAF scale, in level pixels.
    """

    nms_size: int
    pyramid_levels: int
    up_levels: int
    scale_factor_levels: float
    s_mult: float


def get_default_detector_config() -> Detector_config:
    """Return default config."""
    # Return a shallow copy to ensure modifications outside don't affect the module-level config.
    return _DEFAULT_DETECTOR_CONFIG.copy()


class MultiResolutionDetector(nn.Module):
    """Detect LAFs at the 2D maxima of a response on each level of an image pyramid, one image per call.

    ``detector = MultiResolutionDetector(model, num_features)`` builds an image pyramid detector from a response
    model. ``lafs, responses = detector(img)`` takes one image ``(1, C, H, W)`` and returns LAFs
    ``(1, num_features, 2, 3)`` in input pixels and responses ``(1, num_features)``, strongest first.
    Use :func:`laf_is_filled` to keep detected features and discard padded slots in both outputs.
    Detections lie at integer pixels of each pyramid level, without scale selection or subpixel refinement.
    For a batch or refined centres and scales, use :class:`ScaleSpaceDetector`; for KeyNet responses,
    use :class:`KeyNetDetector`.

    This is based on the original code from the paper "Key.Net: Keypoint Detection by Handcrafted and Learned CNN
    Filters". See :cite:`KeyNet2019` for more details.

    The Key.Net reference code zeroes a 15 px strip along each side of a level before the non-maxima
    suppression, which reports a "maximum" beside the strip wherever the response rises into it. This
    detector suppresses on the whole response and removes the strip from the suppression output instead;
    see :meth:`detect_features_on_single_level`.

    Convention:
        - ``model`` maps each pyramid level ``(1, C, H_l, W_l)`` to a response ``(1, 1, H_l, W_l)``.
          Only responses carry gradients; the selected centres and scales do not.
          ``aff_module`` and then ``ori_module`` modify the upright frames; both default to :class:`PassLAF`.
          ``detector.detect(img)`` returns ``(responses, lafs)`` before those two modules run, reversing the output
          order of ``detector(img)``.
        - Detections are maxima of the response above ``score_threshold``. For a signed response whose minima are
          features as well, such as a difference of Gaussians, pass its magnitude, as
          :class:`~kornia.feature.SIFTFeature` does.
        - A detection is an integer pixel :math:`(u, v)` of a pyramid level of size ``(H_l, W_l)``, without a
          sub-pixel step. It is reported at the centre of that level pixel,
          :math:`((u + 0.5) W / W_l - 0.5, (v + 0.5) H / H_l - 0.5)` of the ``(H, W)`` input, in the frame of
          :func:`~kornia.feature.laf_from_center_scale_ori` (see :ref:`Local features <local-features-conventions>`).
          The Key.Net reference reports :math:`(u W / W_l, v H / H_l)` instead. For :math:`f = W / W_l > 1` (likewise
          along y) that is :math:`0.5 (f - 1)` px up and to the left of the centre, about 1.5 px on the default coarsest
          level; on the default up level, where :math:`f < 1`, it is about 0.15 px down and to the right.
        - Before ``aff_module`` and ``ori_module`` run, the frame is upright and isotropic, with the scale
          ``s_mult * (W / W_l + H / H_l) / 2`` whatever the response; ``s_mult`` of ``config`` is 22 by default.

    Args:
        model: response function, such as KeyNet or BlobHessian
        num_features: Number of features to detect. Every pyramid level is searched for this many
            candidates and the whole set is ranked together, so the result is the ``num_features``
            highest responses in the image, and the sorted response vector for one value is a prefix
            of the vector for any larger one. Which detection carries a given response is not pinned
            when responses tie: ``topk`` breaks a tie by position, and the positions it ranks over
            depend on ``num_features``.
        config: Dict with initialization parameters. Do not pass it, unless you know what you are doing. The
            pyramid has ``up_levels`` levels (1 by default) upscaled by successive powers of ``scale_factor_levels``
            (``sqrt(2)``), the input, and ``pyramid_levels`` levels (4) below it, each the previous one downscaled by
            ``scale_factor_levels`` with :func:`~kornia.geometry.transform.pyrdown`; ``nms_size`` (15) is the side of
            the suppression window in level pixels, and ``s_mult`` (22) the frame scale, in level pixels.
        ori_module: for local feature orientation estimation. Default: :class:`~kornia.feature.PassLAF`,
           which does nothing. See :class:`~kornia.feature.LAFOrienter` for details.
        aff_module: for local feature affine shape estimation. Default: :class:`~kornia.feature.PassLAF`,
            which does nothing. See :class:`~kornia.feature.LAFAffineShapeEstimator` for details.
        compile_model: wrap the response function and the non-maxima suppression with :func:`torch.compile`.
        score_threshold: minimum response for a position to count as a detection. Must be non-negative:
            non-maxima suppression writes an exact zero at every suppressed position, so a negative
            threshold would admit all of them; it raises ``ValueError``.

    See Also:
        - :class:`ScaleSpaceDetector`: a batch of images, the sub-pixel maxima of a response over a Gaussian scale
          space, with scale selection across levels.
        - :class:`KeyNetDetector`: this detector on the learned KeyNet response.
        - :class:`SIFTFeature`: this detector on the magnitude of a DoG response, with SIFT descriptors.

    Example:
        >>> detector = MultiResolutionDetector(BlobHessian(), num_features=50)
        >>> lafs, responses = detector(torch.rand(1, 1, 64, 64))
        >>> lafs.shape, responses.shape
        (torch.Size([1, 50, 2, 3]), torch.Size([1, 50]))

    """

    def __init__(
        self,
        model: nn.Module,
        num_features: int = 2048,
        config: Optional[Detector_config] = None,
        ori_module: Optional[nn.Module] = None,
        aff_module: Optional[nn.Module] = None,
        compile_model: bool = False,
        score_threshold: float = 0.0,
    ) -> None:
        super().__init__()
        if config is None:
            config = get_default_detector_config()
        # Load extraction configuration
        self.num_pyramid_levels = config["pyramid_levels"]
        self.num_upscale_levels = config["up_levels"]
        self.scale_factor_levels = config["scale_factor_levels"]
        self.mr_size = config["s_mult"]
        self.nms_size = config["nms_size"]
        if score_threshold < 0:
            # Non-maxima suppression encodes a suppressed position as an exact zero, so a
            # negative threshold admits every suppressed pixel in the image as a "detection"
            # and collides with the zero response that marks an unfilled slot.
            raise ValueError(f"score_threshold must be non-negative. Got {score_threshold}")
        self.score_threshold = score_threshold
        nms = NonMaximaSuppression2d((self.nms_size, self.nms_size))
        self.num_features = num_features

        if compile_model:
            self.model = torch.compile(model, dynamic=True)
            self.nms = torch.compile(nms, dynamic=True)
        else:
            self.model = model
            self.nms = nms

        if ori_module is None:
            self.ori: nn.Module = PassLAF()
        else:
            self.ori = ori_module

        if aff_module is None:
            self.aff: nn.Module = PassLAF()
        else:
            self.aff = aff_module

    def remove_borders(self, score_map: torch.Tensor, borders: int = 15) -> torch.Tensor:
        """Zero the strip of ``borders`` pixels along each side of a level, so that no detection is made there.

        :meth:`detect_features_on_single_level` applies it to the non-maxima suppression output, not to the
        response, so an override receives the suppressed map. The strip is set to an exact zero whatever the
        score there, an infinite one included.
        """
        h, w = score_map.shape[-2:]
        rows = torch.arange(h, device=score_map.device)
        cols = torch.arange(w, device=score_map.device)
        inside = ((rows >= borders) & (rows < h - borders)).view(h, 1) & ((cols >= borders) & (cols < w - borders))
        return score_map.masked_fill(~inside, 0.0)

    def detect_features_on_single_level(
        self,
        level_img: torch.Tensor,
        num_kp: int,
        factor: Tuple[float, float],
        *,
        mask: Optional[torch.Tensor] = None,
    ) -> Tuple[torch.Tensor, torch.Tensor]:
        """Detect keypoints on one image-pyramid level.

        The response function may consume a multi-channel image -- for example, a learned color detector -- but must
        return one response map. A LAF has no response-channel identity, so independent per-channel detections are
        ambiguous and rejected. :class:`ScaleSpaceDetector` follows the same contract.

        A detection is a strict maximum of the response over its ``nms_size`` window, above ``score_threshold``,
        that lies outside the 15 px strip along the level's sides. The suppression reads the whole response, the
        strip included, and :meth:`remove_borders` then zeroes the strip in its output: a position beside the strip
        is reported only when no response at least as strong, inside the strip or not, lies within its window.

        Args:
            level_img: Image tensor for a single pyramid level.
            num_kp: Number of keypoints requested from this pyramid level.
            factor: Per-axis factor ``(W / W_l, H / H_l)`` from the current pyramid level to the original image:
                level pixel :math:`(u, v)` is reported at its centre,
                ``((u + 0.5) * factor[0] - 0.5, (v + 0.5) * factor[1] - 0.5)``.
            mask: Optional mask with shape ``(1, 1, H, W)`` at the *original* image resolution, saying where a
                detection may be. It is resampled onto this level conservatively and applied to the non-maxima
                suppression output, so a zero region drops every maximum within one level pixel of it and a
                floating-point weight scales the score. Keyword-only.

        Returns:
            Tuple containing scores and local affine frames detected at the requested pyramid level, with
            ``min(num_kp, H_l * W_l)`` slots for a level of size ``(H_l, W_l)``. When the level holds fewer
            above-threshold maxima than that, the remaining slots are padded with a zero response and a zero LAF.
        """
        resp_map = self.model(level_img)
        KORNIA_CHECK(
            resp_map.dim() == 4 and resp_map.shape[0] == 1 and resp_map.shape[1] == 1,
            f"model must return one response map with shape (1, 1, H, W). Got {tuple(resp_map.shape)}. "
            "For a multi-channel image, convert it to grayscale first or use a response function that "
            "reduces the channels to one map.",
        )
        # A response index is decoded as a level pixel with no offset or stride, so a map of another
        # size -- a valid-convolution net -- would put every keypoint off its peak and have the mask
        # resampled onto the wrong geometry. Nothing can infer the offset from the shape.
        KORNIA_CHECK(
            resp_map.shape[-2:] == level_img.shape[-2:],
            f"model must return a response map with the level's spatial size {tuple(level_img.shape[-2:])}. "
            f"Got {tuple(resp_map.shape[-2:])}; pad the response function so that its output matches its input.",
        )
        # The border and the mask are applied to the maxima, not to the response the NMS reads: a hard
        # edge in the response would turn every pixel beside a zeroed neighbour into a "maximum". A
        # stronger response inside the strip therefore suppresses a weaker one beside it, as a stronger
        # neighbour does anywhere else in the image.
        det_map = self.remove_borders(self.nms(resp_map))
        if mask is not None:
            weights = _resize_mask(mask, det_map)
            # A boolean or integer mask resamples to exactly 0/1: dropping is all it can do. A float
            # mask is gated the same way `ScaleSpaceDetector` gates its candidates, `weight > 0`, which
            # also drops a NaN weight: `s * NaN` sorts first in `topk` and would consume a slot.
            if mask.is_floating_point():
                det_map = _weight_scores(det_map, weights).masked_fill(~(weights > 0), 0.0)
            else:
                det_map = det_map * weights
        w = det_map.shape[-1]
        det_flat = det_map.view(-1)  # (H*W,)

        # Mask out non-maxima (zeroed by NMS) and below-threshold scores, then topk.
        # Using masked_fill + topk instead of nonzero: avoids data-dependent output shapes,
        # supports score_threshold, and is compatible with torch.compile.
        det_masked = det_flat.masked_fill(det_flat <= self.score_threshold, float("-inf"))
        k = min(num_kp, det_flat.numel())
        top_scores, top_flat_idx = torch.topk(det_masked, k=k)

        # `topk` cannot rank among the masked-out positions — they all carry the same `fill` —
        # so once this level runs out of real candidates it returns an arbitrary tie-break subset
        # of them, in practice the lowest flat indices, i.e. the border strip `remove_borders` has
        # just zeroed. Neutralise those slots rather than handing the sentinel back: zero response
        # and zero LAF, which is how `ScaleSpaceDetector.detect` pads a short result.
        valid = top_scores > self.score_threshold
        top_scores = torch.where(valid, top_scores, torch.zeros_like(top_scores))

        # Convert flat indices to (y, x) pixel coordinates and project the centres of those level pixels
        # to the original resolution: every level is resampled with align_corners=False, so a level
        # pixel's centre is (u + 0.5) * f - 0.5 in the input, and u itself when f is 1. The LAFs are built
        # in at least float32: a half-precision dtype cannot hold a pixel index times a scale factor, nor
        # an odd pixel above 256 (bfloat16) or 2048 (float16).
        yx = torch.stack([top_flat_idx // w, top_flat_idx % w], dim=1)  # (k, 2)
        wide = torch.promote_types(level_img.dtype, torch.float32)
        fx = torch.tensor([factor[0], factor[1]], device=level_img.device, dtype=wide)
        xy_projected = (yx.view(1, k, 2).flip(2).to(wide) + 0.5) * fx - 0.5
        scale_val = 0.5 * (factor[0] + factor[1]) * self.mr_size
        scale = torch.full((1, k, 1, 1), scale_val, device=level_img.device, dtype=wide)
        lafs = laf_from_center_scale_ori(xy_projected, scale, scale.new_zeros(1, k, 1))
        lafs = lafs * valid.view(1, k, 1, 1).to(lafs.dtype)
        return top_scores, lafs

    def _detect_level(
        self, level_img: torch.Tensor, num_kp: int, factor: Tuple[float, float], mask: Optional[torch.Tensor]
    ) -> Tuple[torch.Tensor, torch.Tensor]:
        # `mask` is passed only when there is one, so a subclass that overrides the public method
        # with the historical three-argument signature keeps working for the unmasked call.
        if mask is None:
            return self.detect_features_on_single_level(level_img, num_kp, factor)
        return self.detect_features_on_single_level(level_img, num_kp, factor, mask=mask)

    def detect(self, img: torch.Tensor, mask: Optional[torch.Tensor] = None) -> Tuple[torch.Tensor, torch.Tensor]:
        """Detect local features in one image, a batch of one.

        Args:
            img: Input image tensor with shape ``(1, C, H, W)``.
            mask: Optional mask with shape ``(1, 1, H, W)`` saying where a detection may be. A boolean or integer
                mask is binary (any non-zero value keeps a position), a floating-point mask is used as weights on
                the detection scores: a weight in ``(0, 1]`` scales a score toward the worst, so a down-weighted
                maximum never outranks a full-weight one, and a zero or negative weight suppresses. Weights above
                one are clamped to one, so a float 0/255 mask means what the integer one means. The weights are
                cast to the response's dtype. The mask is resampled onto every pyramid level conservatively, so a
                zero region suppresses every maximum within one level pixel of it.

        Returns:
            Tuple containing detection scores and local affine frames, shaped ``(1, num_features)`` and
            ``(1, num_features, 2, 3)``, in that order, the reverse of ``forward``'s, holding the ``num_features``
            highest responses in the image and sorted by response, descending. The shape holds even when the image
            yields fewer above-threshold maxima than requested: those slots carry a zero response and a zero LAF,
            and sort after every real detection. The LAFs are float32 for a float16 or bfloat16 image and float64
            for a float64 one; the responses keep the response function's dtype.
        """
        KORNIA_CHECK_SHAPE(img, ["1", "C", "H", "W"])
        if mask is not None:
            _check_mask(mask, img)
        # Every level is asked for the whole budget, not for a per-level share of it. A share is a
        # cap on what the level may contribute, and the final global `topk` cannot rank in a
        # detection that was never requested, so a per-level quota silently returns something other
        # than the top `num_features` whenever an image's strongest maxima concentrate on one level.
        # Asking each level for `num_features` is exactly sufficient rather than merely generous:
        # the m detections a level contributes to the global top-k are necessarily that level's own
        # top-m, so a request of `num_features` always reaches them. It costs ~1.2x the candidates
        # the old apportionment carried -- the coarse levels were already asked for a cumulative
        # prefix of the quotas, close to `num_features` -- which is not measurable next to the
        # response function and the non-maxima suppression.
        _, _, h, w = img.shape
        img_up = img
        cur_img = img
        all_responses: List[torch.Tensor] = []
        all_lafs: List[torch.Tensor] = []
        # Extract features from the upper levels
        for idx_level in range(self.num_upscale_levels):
            # Resize input image
            up_factor = self.scale_factor_levels ** (1 + idx_level)
            nh, nw = int(h * up_factor), int(w * up_factor)
            up_factor_kpts = (float(w) / float(nw), float(h) / float(nh))
            img_up = resize(img_up, (nh, nw), interpolation="bilinear", align_corners=False)

            cur_scores, cur_lafs = self._detect_level(img_up, self.num_features, up_factor_kpts, mask)

            all_responses.append(cur_scores.view(1, -1))
            all_lafs.append(cur_lafs)

        # Extract features from the downsampling pyramid
        for idx_level in range(self.num_pyramid_levels + 1):
            if idx_level > 0:
                cur_img = pyrdown(cur_img, factor=self.scale_factor_levels)
                _, _, nh, nw = cur_img.shape
                factor = (float(w) / float(nw), float(h) / float(nh))
            else:
                factor = (1.0, 1.0)

            cur_scores, cur_lafs = self._detect_level(cur_img, self.num_features, factor, mask)
            all_responses.append(cur_scores.view(1, -1))
            all_lafs.append(cur_lafs)
        responses = torch.cat(all_responses, 1)
        lafs = torch.cat(all_lafs, 1)
        # The levels can produce fewer slots than requested — a level is capped at its own pixel
        # count, so a deep enough pyramid level runs out of positions before it fills its quota.
        # Pad up so the returned shape is always `num_features`, the same way
        # `ScaleSpaceDetector.detect` does; the padding is the zero response and zero LAF used
        # everywhere else here.
        if lafs.shape[1] < self.num_features:
            pad = self.num_features - lafs.shape[1]
            responses = F.pad(responses, (0, pad))
            lafs = F.pad(lafs, (0, 0, 0, 0, 0, pad))
        # Rank unconditionally. The levels are concatenated in level order, and a level that under-
        # fills its own quota pads in place, so without this a short result interleaves the real
        # detections with the padding instead of listing them first, unlike every other path here
        # and unlike `ScaleSpaceDetector.detect`. Detections score strictly above the non-negative
        # threshold, so they sort ahead of the zero-response padding.
        responses, idxs = torch.topk(responses, k=self.num_features, dim=1)
        lafs = torch.gather(lafs, 1, idxs[..., None, None].expand(-1, -1, 2, 3))
        return responses, lafs

    def forward(self, img: torch.Tensor, mask: Optional[torch.Tensor] = None) -> Tuple[torch.Tensor, torch.Tensor]:
        """Three stage local feature detection.

        First the location and scale of interest points are determined by detect function.
        Then affine shape and orientation.

        Args:
            img: image to extract features with shape ``(1, C, H, W)``. Only a batch of one image is accepted.
            mask: a mask saying where a detection may be, shape ``(1, 1, H, W)``. A boolean or integer mask is
                binary, a floating-point mask weights the detection scores; see
                :meth:`~kornia.feature.MultiResolutionDetector.detect`.

        Returns:
            Tuple of ``lafs`` with shape ``(1, N, 2, 3)``, the detected local affine frames, and ``responses`` with
            shape ``(1, N)``, the response function values for the corresponding lafs, with ``N = num_features``.
            When the image yields fewer above-threshold maxima than ``num_features``, the remaining slots hold a zero
            response and a zero LAF, whichever affine-shape and orientation modules are configured.

        """
        KORNIA_CHECK_SHAPE(img, ["1", "C", "H", "W"])
        responses, lafs = self.detect(img, mask)
        # Occupancy comes from `detect`'s zero-LAF padding contract, the same way as in
        # `ScaleSpaceDetector.forward`, so an override of `detect` is honoured as well.
        filled = laf_is_filled(lafs)
        lafs = self.aff(lafs, img)
        lafs = self.ori(lafs, img)
        return _zero_unfilled(lafs, filled), responses


_DEFAULT_DETECTOR_CONFIG: Detector_config = {
    # Extraction Parameters
    "nms_size": 15,
    "pyramid_levels": 4,
    "up_levels": 1,
    "scale_factor_levels": math.sqrt(2),
    "s_mult": 22.0,
}
