# 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 copy
import itertools
import math
import warnings
from typing import ClassVar, Dict, List, Literal, Optional, Tuple, Union

import torch
from torch import nn

from kornia.color import rgb_to_grayscale
from kornia.core.check import KORNIA_CHECK, KORNIA_CHECK_LAF
from kornia.core.ops import _copied_literal
from kornia.geometry.subpix import ConvQuadInterp3d
from kornia.geometry.transform import ScalePyramid

from .affine_shape import LAFAffNetShapeEstimator
from .hardnet import HardNet
from .keynet import KeyNetDetector
from .laf import (
    extract_patches_from_pyramid,
    get_laf_center,
    get_laf_orientation,
    get_laf_scale,
    laf_is_filled,
    scale_laf,
)
from .lightglue import LightGlue
from .matching import GeometryAwareDescriptorMatcher, _no_match
from .orientation import LAFOrienter, OriNet, PassLAF
from .responses import BlobDoG, BlobDoGSingle, BlobHessian, CornerGFTT
from .scale_space_detector import (
    Detector_config,
    MultiResolutionDetector,
    ScaleSpaceDetector,
    get_default_detector_config,
)
from .sift import SIFTDescriptorFromPyramid
from .sift.scale_space import _SIFTScalePyramid, _SIFTScaleSpaceDescriptor, _SIFTScaleSpaceDetector
from .siftdesc import SIFTDescriptor, _check_sift_descriptor_layout, convert_sift_descriptor_layout


def _in_sift_layout(descriptors: torch.Tensor, layout: str) -> torch.Tensor:
    """Return kornia-layout SIFT descriptors in ``layout``; the default ``"kornia"`` returns them unchanged."""
    return descriptors if layout == "kornia" else convert_sift_descriptor_layout(descriptors, "kornia", layout)


def _lightglue_keypoint_scale_ori(lafs: torch.Tensor, feature_name: str) -> Tuple[torch.Tensor, torch.Tensor]:
    r"""Return the keypoint scales and orientations, shape ``(1, N)``, that LightGlue takes for ``lafs``.

    LightGlue's ``"sift"`` weights were trained on COLMAP keypoints, whose scale is the detection sigma and whose
    orientation is, for the similarity frames ``A = s R`` of the SIFT features (nearly so for
    :class:`SIFTFeatureScaleSpace`'s), the image angle of the frame's x-axis in :math:`(-\pi, \pi]`, which is the
    negative of the LAF orientation; for another frame the two differ, and the negated LAF orientation is passed.
    The scale is taken as a sixth of the LAF scale, which is sigma for 6-sigma DoG frames such as
    :class:`SIFTFeatureScaleSpace`'s. Every other feature keeps the LAF scale and the LAF orientation in
    :math:`[0, 2\pi)`. The ``"sift"`` scale is converted here rather than through :class:`LightGlue`'s
    ``scale_coef``, which the ``"doghardnet"`` configurations use, so that ``LightGlue("sift")`` itself keeps taking
    keypoints in the training convention.
    """
    scales = get_laf_scale(lafs).reshape(1, -1)
    oris = torch.deg2rad(get_laf_orientation(lafs).reshape(1, -1))
    if feature_name == "sift":
        oris = -oris
        return scales / 6.0, torch.where(oris <= -math.pi, oris + 2.0 * math.pi, oris)
    # torch.where, not an in-place masked add: the boolean-mask write synchronizes with the device
    return scales, torch.where(oris < 0, oris + 2.0 * math.pi, oris)


def _image_size_from_hw(hw: Tuple[int, int], device: torch.device) -> torch.Tensor:
    """Return LightGlue's ``image_size`` ``[[W, H]]`` of an ``(H, W)`` pair, on ``device``.

    The copy does not block: a blocking copy from host memory would wait for all the work queued on the device.
    """
    return _copied_literal([[hw[1], hw[0]]], device=device, dtype=torch.int64)


def _run_descriptor(module: nn.Module, patches: torch.Tensor) -> torch.Tensor:
    """Run ``module`` in eval mode on ``patches``, leaving its device, dtype and parameters as they are.

    A module whose floating-point parameters and buffers already sit on the device and dtype of ``patches`` is called
    directly. Otherwise they are cast for the call only, through ``torch.func.functional_call`` or, for a TorchScript
    module, which that API refuses, in the slots of a copy of the module. The cast is differentiable, so gradients
    reach the module's own parameters. Eager calls, ``torch.compile`` and ``torch.export`` take the same path. Every
    submodule is switched to eval for the call and its ``training`` flag is restored afterwards.
    Descriptor statistics marked for float32 computation retain that precision for float16 patches.
    """
    modes = [m.training for m in module.modules()]
    module.eval()
    try:
        tensors = list(itertools.chain(module.named_parameters(), module.named_buffers()))
        float32_statistics: set[str] = set()
        if patches.dtype == torch.float16:
            for prefix, child in module.named_modules():
                if getattr(child, "_descriptor_float32_statistics", False):
                    float32_statistics.update(
                        f"{prefix}.{name}" if prefix else name for name in ("running_mean", "running_var")
                    )

        def target_dtype(name: str, tensor: torch.Tensor) -> torch.dtype:
            if name in float32_statistics:
                return torch.float32
            return patches.dtype if tensor.is_floating_point() else tensor.dtype

        needs_cast = any(t.device != patches.device or t.dtype != target_dtype(name, t) for name, t in tensors)
        if not needs_cast:
            return module(patches)
        state = {name: t.to(device=patches.device, dtype=target_dtype(name, t)) for name, t in tensors}
        if not isinstance(module, torch.jit.ScriptModule):
            return torch.func.functional_call(module, state, (patches,))
        # functional_call refuses a TorchScript module, so the cast tensors go into the slots of a copy instead; they
        # stay in the autograd graph, so gradients reach the module's own parameters on every device and dtype.
        with torch.no_grad():
            copied = copy.deepcopy(module)
        for name, t in state.items():
            *path, attr = name.split(".")
            owner = copied
            for part in path:  # ScriptModules have no get_submodule
                owner = getattr(owner, part)
            setattr(owner, attr, t)
        return copied(patches)
    finally:
        for m, mode in zip(module.modules(), modes):
            m.training = mode


def get_laf_descriptors(
    img: torch.Tensor,
    lafs: torch.Tensor,
    patch_descriptor: nn.Module,
    patch_size: int = 32,
    grayscale_descriptor: bool = True,
) -> torch.Tensor:
    r"""Describe LAFs on an image by running a patch descriptor on one patch sampled per LAF.

    ``descs = get_laf_descriptors(img, lafs, patch_descriptor, patch_size)`` takes images ``(B, C, H, W)``, their
    LAFs ``(B, N, 2, 3)`` in pixels and a patch descriptor module, and returns one descriptor per LAF, ``(B, N, D)``.
    The descriptor determines the output dtype. The function converts a 3-channel image to grayscale when
    ``grayscale_descriptor`` is set, samples a ``patch_size`` x ``patch_size`` patch per LAF with
    :func:`extract_patches_from_pyramid`, and runs the descriptor on the stack of the ``B * N`` patches.
    The patch follows the LAF's scale and orientation, so orient the LAFs first, e.g. with :class:`LAFOrienter`,
    unless upright descriptors are wanted. ``patch_size`` must be what the descriptor takes: 32 for :class:`HardNet`
    and the other learned descriptors, 41 for a default :class:`SIFTDescriptor`. For the module form, use
    :class:`LAFDescriptor`; for SIFT descriptors of LAFs without sampling patches, :class:`SIFTDescriptorFromPyramid`.

    Convention:
        - The descriptor sees the patches of :func:`~kornia.feature.extract_patches_from_pyramid` at ``patch_size``;
          see its Convention block for how they are sampled. ``patch_size`` is this argument, 32 by default, and is
          not read from the descriptor, so it has to be a size the descriptor accepts.
        - The descriptor runs in eval mode, with its floating-point parameters and buffers cast to the device and
          dtype of ``img`` for the call (a TorchScript module is called on a cast copy). SOSNet and HyNet retain their
          final BatchNorm statistics in float32 for float16 images. The module keeps its device, dtype and
          parameters, every submodule is switched to eval for the call and gets its train/eval mode back afterwards,
          and gradients reach the module's parameters.
        - An empty LAF set gives a ``(B, 0, D)`` result, ``D`` as wide as a non-empty result, and a warning.
          That result does not require grad, so no gradient reaches ``img`` or the descriptor's parameters through
          it.

    Args:
        img: image features with shape ``(B,C,H,W)``.
        lafs: local affine frames ``(B,N,2,3)`` in the pixels of ``img``, with its batch size.
        patch_descriptor: patch descriptor module, e.g. :class:`~kornia.feature.SIFTDescriptor`
            or :class:`~kornia.feature.HardNet`.
        patch_size: patch size in pixels, which descriptor expects.
        grayscale_descriptor: True if ``patch_descriptor`` expects single-channel image; a 3-channel ``img`` is
            then converted to grayscale. An image with another channel count is passed on unchanged.

    Returns:
        Local descriptors of shape ``(B,N,D)`` where :math:`D` is descriptor size.

    See Also:
        - :class:`LAFDescriptor`: the module form, which holds the descriptor, a pretrained :class:`HardNet` by
          default.
        - :func:`extract_patches_from_pyramid`: the patch sampler, for the patches themselves.
        - :func:`laf_from_center_scale_ori`: LAFs from keypoint centres, scales and orientations, to describe here.
        - :class:`SIFTDescriptorFromPyramid`: SIFT descriptors of LAFs, pooled from a gradient pyramid without
          sampling patches.
        - :class:`LAFOrienter`: orients LAFs from their patches, before they are described.

    """
    KORNIA_CHECK_LAF(lafs)
    timg: torch.Tensor = img
    if grayscale_descriptor and img.size(1) == 3:
        timg = rgb_to_grayscale(img)

    if lafs.shape[1] == 0:
        warnings.warn(f"LAF contains no keypoints {lafs.shape}, returning empty torch.Tensor", stacklevel=1)
        # Probe the descriptor for its output width instead of assuming 128, so the empty result
        # has the same trailing dimension and dtype as a non-empty one. The non-empty path ends in
        # `.reshape(B, N, -1)`, which flattens everything the descriptor produced per patch, so the
        # matching width is the whole probe -- `probe.shape[-1]` would only agree for descriptors
        # whose output is 2-D. The probe has a batch of one, so its numel is that width.
        with torch.no_grad():
            probe = _run_descriptor(
                patch_descriptor,
                torch.zeros(1, timg.size(1), patch_size, patch_size, dtype=timg.dtype, device=timg.device),
            )
        return torch.empty(lafs.shape[0], 0, probe.numel(), dtype=probe.dtype, device=probe.device)

    patches: torch.Tensor = extract_patches_from_pyramid(timg, lafs, patch_size)
    # Descriptor accepts standard torch.Tensor [B, CH, H, W], while patches are [B, N, CH, H, W] shape
    # So we need to reshape a bit :)
    B, N, CH, H, W = patches.size()
    # `reshape`, not `view`: a descriptor may return a non-contiguous output, e.g. a channels-last convolution.
    # The width is spelled out: a `-1` is ambiguous when the batch is empty.
    descriptors = _run_descriptor(patch_descriptor, patches.view(B * N, CH, H, W))
    return descriptors.reshape(B, N, descriptors.shape[1:].numel())


class LAFDescriptor(nn.Module):
    r"""Describe LAFs with a held patch descriptor, as a module (HardNet by default).

    ``describer = LAFDescriptor()``, then ``descs = describer(img, lafs)`` takes images ``(B, C, H, W)`` and their
    LAFs ``(B, N, 2, 3)`` in pixels and returns one descriptor per LAF, ``(B, N, D)``: ``forward`` calls
    :func:`get_laf_descriptors` with the held descriptor, ``patch_size`` and ``grayscale_descriptor``, which samples a
    patch per LAF with :func:`extract_patches_from_pyramid`. By default it holds a pretrained :class:`HardNet` on
    32 x 32 grayscale patches, converts an RGB image to grayscale and returns ``(B, N, 128)``; with another
    descriptor, pass the patch size it takes, e.g. ``LAFDescriptor(SIFTDescriptor(41), patch_size=41)``. It is the
    descriptor of the HardNet local features, such as :class:`DoGHardNet`, and of the ``"patch"`` backend of
    :class:`SIFTFeature` and :class:`SIFTFeatureScaleSpace`. For SIFT descriptors of LAFs without sampling patches,
    use :class:`SIFTDescriptorFromPyramid` instead.

    Convention:
        See the Convention block on :func:`~kornia.feature.get_laf_descriptors`, which ``forward`` calls with this
        module's ``patch_size`` and ``grayscale_descriptor``. The default descriptor is a pretrained
        :class:`~kornia.feature.HardNet` on ``32 x 32`` grayscale patches; :class:`~kornia.feature.SIFTDescriptor`
        defaults to 41-pixel patches, so pass ``patch_size=41`` with it.

    Args:
        patch_descriptor_module: patch descriptor module, e.g. :class:`~kornia.feature.SIFTDescriptor`
            or :class:`~kornia.feature.HardNet`. Default: :class:`~kornia.feature.HardNet` with pretrained weights.
        patch_size: patch size in pixels, which descriptor expects.
        grayscale_descriptor: ``True`` if patch_descriptor expects single-channel image; a 3-channel image is then
            converted to grayscale.

    See Also:
        - :func:`get_laf_descriptors`: the function form, which takes the descriptor in each call.
        - :class:`HardNet`: the default descriptor; :class:`SIFTDescriptor`, :class:`HardNet8`, :class:`HyNet`,
          :class:`SOSNet`, :class:`TFeat` and :class:`MKDDescriptor` fit as well.
        - :func:`extract_patches_from_pyramid`: the patch sampler, for the patches themselves.
        - :func:`laf_from_center_scale_ori`: LAFs from keypoint centres, scales and orientations, to describe here.
        - :class:`SIFTDescriptorFromPyramid`: SIFT descriptors of LAFs, pooled from a gradient pyramid without
          sampling patches.
        - :class:`LocalFeature`: runs a detector and a descriptor such as this module in one call.

    """

    def __init__(
        self,
        patch_descriptor_module: Optional[nn.Module] = None,
        patch_size: int = 32,
        grayscale_descriptor: bool = True,
    ) -> None:
        super().__init__()
        if patch_descriptor_module is None:
            patch_descriptor_module = HardNet(True)
        self.descriptor = patch_descriptor_module
        self.patch_size = patch_size
        self.grayscale_descriptor = grayscale_descriptor

    def __repr__(self) -> str:
        return (
            f"{self.__class__.__name__}"
            f"(descriptor={self.descriptor.__repr__()}, "
            f"patch_size={self.patch_size}, "
            f"grayscale_descriptor='{self.grayscale_descriptor})"
        )

    def forward(self, img: torch.Tensor, lafs: torch.Tensor) -> torch.Tensor:
        r"""Describe the given LAFs with :func:`~kornia.feature.get_laf_descriptors`.

        Args:
            img: image features with shape ``(B,C,H,W)``.
            lafs: local affine frames ``(B,N,2,3)``.

        Returns:
            Local descriptors of shape ``(B,N,D)`` where :math:`D` is descriptor size.

        """
        return get_laf_descriptors(img, lafs, self.descriptor, self.patch_size, self.grayscale_descriptor)


class LocalFeature(nn.Module):
    """Detect and describe LAFs in one call with a given detector and LAF descriptor module.

    ``feature = LocalFeature(detector, descriptor)``, then ``lafs, responses, descs = feature(img, mask)`` runs a
    detector and descriptor as one pipeline. It takes images ``(B, C, H, W)`` and an optional mask. The detector
    returns LAFs ``(B, N, 2, 3)`` in pixels and responses ``(B, N)``. The descriptor returns one descriptor per LAF,
    ``(B, N, D)``. ``scaling_coef`` changes the LAF shape before description. Use :class:`LAFDescriptor` to adapt a
    patch descriptor such as :class:`HardNet`; :class:`SIFTDescriptorFromPyramid` already takes images and LAFs.
    The detector and descriptor define accepted batch sizes, channels and intensity ranges. To match features from two
    images, use :class:`LocalFeatureMatcher`. For learned features, use :class:`DISK`, :class:`ALIKED`, :class:`XFeat`
    or :class:`DeDoDe`.

    Convention:
        - The returned LAFs use the pixel convention of :func:`~kornia.feature.laf_from_center_scale_ori`
          (see :ref:`Local features <local-features-conventions>`). ``scaling_coef`` multiplies their shape ``A``
          (:func:`~kornia.feature.scale_laf`) before the description and leaves the centres and the responses
          unchanged.
        - Cast the module to the image dtype before calling it, for example ``feature.to(img.dtype)``. See each preset
          for its supported dtypes.
        - A detector can return zero-LAF padding when fewer than ``N`` features are found. ``laf_is_filled(lafs)`` is
          ``True`` for detections; index LAFs, responses and descriptors with it to discard padding before matching.
          :class:`LocalFeatureMatcher` does this automatically.

    Args:
        detector: the detection module, called as ``detector(img, mask)`` and returning ``(lafs, responses)``, such
            as :class:`~kornia.feature.ScaleSpaceDetector`.
        descriptor: the descriptor module, called as ``descriptor(img, lafs)`` and returning ``(B, N, D)``, such as
            :class:`~kornia.feature.LAFDescriptor`.
        scaling_coef: the multiplier of the detector's LAFs before the description, see the Convention block. An
            ``int`` is converted to ``float``. Must be positive.

    Raises:
        ValueError: if ``scaling_coef`` is not positive.

    See Also:
        - :class:`ScaleSpaceDetector`: a scale-space detector for a batch of images.
        - :class:`MultiResolutionDetector`: a detector for one image per call.
        - :func:`laf_is_filled`: returns the detection slots to keep and discard padding.
        - :class:`LocalFeatureMatcher`: runs a local feature on two images and matches the descriptors.
        - :class:`SIFTFeatureScaleSpace`: the SIFT preset for a batch of images.

    Example:
        >>> feature = LocalFeature(ScaleSpaceDetector(10), LAFDescriptor(SIFTDescriptor(32), patch_size=32))
        >>> lafs, responses, descs = feature(torch.rand(2, 1, 64, 64))
        >>> lafs.shape, responses.shape, descs.shape
        (torch.Size([2, 10, 2, 3]), torch.Size([2, 10]), torch.Size([2, 10, 128]))

    """

    def __init__(self, detector: nn.Module, descriptor: nn.Module, scaling_coef: float = 1.0) -> None:
        super().__init__()
        self.detector = detector
        self.descriptor = descriptor
        if scaling_coef <= 0:
            raise ValueError(f"Scaling coef should be > 0, got {scaling_coef}")
        # scale_laf accepts a float or a tensor, not an int
        self.scaling_coef = float(scaling_coef)

    def forward(
        self, img: torch.Tensor, mask: Optional[torch.Tensor] = None
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Run forward.

        Args:
            img: image to extract features with shape ``(B,C,H,W)``.
            mask: a mask saying where a detection may be, shape ``(B,1,H,W)`` with the spatial size of the
                image. It is forwarded to the detector unchanged; see the detector for its semantics.

        Returns:
            - Detected local affine frames with shape ``(B,N,2,3)``.
            - Response function values for corresponding lafs with shape ``(B,N)``.
            - Local descriptors of shape ``(B,N,D)`` where :math:`D` is descriptor size.

        The Convention block of :class:`LocalFeature` gives the frame, ``N`` and the slots the detector did not fill,
        which have to be dropped before matching.

        """
        lafs, responses = self.detector(img, mask)
        lafs = scale_laf(lafs, self.scaling_coef)
        descs = self.descriptor(img, lafs)
        return (lafs, responses, descs)


class _DoGSingleMagnitude(nn.Module):
    """Magnitude of a single-scale DoG response, whose maxima are maxima of the DoG above zero or minima below zero."""

    def __init__(self, sigma1: float = 1.0, sigma2: float = 1.6) -> None:
        super().__init__()
        self.dog = BlobDoGSingle(sigma1, sigma2)

    def forward(self, input: torch.Tensor) -> torch.Tensor:
        return self.dog(input).abs()


class _SIFTFeature(LocalFeature):
    """Compose a sparse SIFT detector with a patch or pyramid extraction backend."""

    def __init__(
        self, detector: nn.Module, descriptor: nn.Module, upright: bool, descriptor_layout: str = "kornia"
    ) -> None:
        _check_sift_descriptor_layout(descriptor_layout)
        super().__init__(detector, descriptor)
        self.upright = upright
        self.descriptor_layout = descriptor_layout

    def forward(
        self, img: torch.Tensor, mask: Optional[torch.Tensor] = None
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Return sparse LAFs, detector responses, and one descriptor per LAF."""
        if not isinstance(self.descriptor, SIFTDescriptorFromPyramid):
            lafs, responses, descriptors = super().forward(img, mask)
        else:
            lafs, responses = self.detector(img, mask)
            lafs = scale_laf(lafs, self.scaling_coef)
            gray_image = rgb_to_grayscale(img) if img.shape[1] == 3 else img
            lafs, descriptors = self.descriptor.orient_and_describe(gray_image, lafs, upright=self.upright)
        return lafs, responses, _in_sift_layout(descriptors, self.descriptor_layout)


class SIFTFeature(_SIFTFeature):
    """Detect per-level DoG keypoints and describe them with SIFT, one image per call.

    ``sift = SIFTFeature(2048)`` loads a per-level DoG detector and SIFT descriptor. ``lafs, responses, descs =
    sift(img)`` takes one grayscale image ``(1, 1, H, W)``; a batch or color image raises. It returns LAFs
    ``(1, N, 2, 3)``, DoG-response magnitudes ``(1, N)``, strongest first, and RootSIFT descriptors
    ``(1, N, 128)`` in kornia's layout. Use :func:`laf_is_filled` to keep detections and discard padding.
    ``descriptor_backend`` chooses patches (``"patch"``, the default) or a gradient pyramid (``"pyramid"``). For
    scale-space extrema or batches, use :class:`SIFTFeatureScaleSpace` with ``descriptor_backend="pyramid"``.

    For CPU throughput use OpenCV's SIFT: on an Apple M1 CPU, a matching pipeline on it ran 11x faster than one on
    this module (640 px, 2,048 features). This module takes one image per call; for batches use
    :class:`SIFTFeatureScaleSpace`. See the `image matching guide
    <https://kornia.readthedocs.io/en/latest/applications/image_matching.html#feature-speed-by-device>`_.

    Convention:
        - A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract. The detector is
          a :class:`~kornia.feature.MultiResolutionDetector` on the magnitude of a single-scale
          :class:`~kornia.feature.BlobDoGSingle` response. With ``descriptor_backend="patch"``, the default,
          ``LAFOrienter(19)`` orients the LAFs unless ``upright`` and :class:`~kornia.feature.SIFTDescriptor`
          describes 41 x 41 patches. ``"pyramid"`` keeps the detector and orients and describes its LAFs with
          :class:`SIFTDescriptorFromPyramid`, which integrates smoothed image gradients without extracting patches.
        - The detector applies the response independently at each image resolution. It does not apply classical
          SIFT's contrast or Hessian edge rejection. One orientation is assigned per detection unless
          ``upright=True``.
        - Extrema of both polarities are kept: dark blobs are DoG maxima and bright blobs are DoG minima. On each
          image-pyramid level, a keypoint is a strict maximum of the response magnitude in its ``config["nms_size"]``
          window (15 pixels by default), so a stronger extremum of either polarity suppresses a weaker one.
          ``responses`` holds the magnitude.
        - The frames are those of :class:`~kornia.feature.MultiResolutionDetector`: a pixel of a pyramid level, with a
          scale of ``config["s_mult"]`` (22 by default) times that level's pixel size whatever the size of the blob.
          Unlike the 6-sigma frames of :class:`SIFTFeatureScaleSpace`, their scale is not a fixed multiple of the
          detection sigma: a sixth of it, which ``LightGlueMatcher("sift")`` takes as the detection sigma, is not that
          sigma here (see :ref:`sift-pipelines`).
        - Descriptors come in kornia's SIFT layout; ``descriptor_layout="opencv"`` returns them in OpenCV's, which
          :class:`~kornia.feature.LightGlueMatcher` expects with ``"sift"``.
          :func:`~kornia.feature.convert_sift_descriptor_layout` converts between the two.
        - Known defects: ``descriptor_backend="pyramid"`` is less accurate than the patch backend on Oxford
          homographies at 2048 features, and not faster on CPU at 1024 features
          (`#5748 <https://github.com/kornia/kornia/issues/5748>`_).

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        rootsift: if ``True``, the default, return RootSIFT descriptors, otherwise SIFT.
        device: the device of the detector and descriptor modules. Default: CPU.
        config: the pyramid and suppression settings of :class:`~kornia.feature.MultiResolutionDetector`, whose
            ``config`` argument lists them with their defaults.
        compile_model: wrap the DoG response and the non-maxima suppression with :func:`torch.compile`, see
            :class:`~kornia.feature.MultiResolutionDetector`.
        score_threshold: the response magnitude a detection has to exceed. Must be non-negative.
        descriptor_backend: ``"patch"`` or ``"pyramid"``, see the Convention block.
        descriptor_layout: ``"kornia"`` or ``"opencv"``, the order of the descriptor values.

    Raises:
        ValueError: for a ``descriptor_backend`` or ``descriptor_layout`` other than those listed, or a negative
            ``score_threshold``.

    See Also:
        - :class:`SIFTFeatureScaleSpace`: SIFT on a DoG scale space, with extrema across scale, sub-pixel refinement
          and 6-sigma frames, for a batch of images.
        - :class:`MultiResolutionDetector`: its detector, on the magnitude of the DoG.
        - :class:`BlobDoGSingle`: the single-scale DoG response whose magnitude it detects on.
        - :class:`SIFTDescriptor`: the descriptor of the ``"patch"`` backend, run on 41 x 41 patches through
          :class:`LAFDescriptor`.
        - :class:`SIFTDescriptorFromPyramid`: the orientation and descriptor of the ``"pyramid"`` backend.
        - :func:`convert_sift_descriptor_layout`: the reordering that ``descriptor_layout="opencv"`` applies.
        - :class:`LocalFeature`: its base class, which gives the output contract.

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

    """

    def __init__(
        self,
        num_features: int = 8000,
        upright: bool = False,
        rootsift: bool = True,
        device: Union[str, torch.device, None] = None,
        config: Optional[Detector_config] = None,
        compile_model: bool = False,
        score_threshold: float = 0.0,
        descriptor_backend: Literal["patch", "pyramid"] = "patch",
        descriptor_layout: Literal["kornia", "opencv"] = "kornia",
    ) -> None:
        if descriptor_backend not in ("patch", "pyramid"):
            raise ValueError(f"Unknown SIFT descriptor backend: {descriptor_backend!r}")
        _check_sift_descriptor_layout(descriptor_layout)
        patch_size: int = 41
        if device is None:
            device = torch.device("cpu")
        if config is None:
            config = get_default_detector_config()
        detector = MultiResolutionDetector(
            _DoGSingleMagnitude(1.0, 1.6),
            num_features,
            config,
            ori_module=PassLAF() if upright or descriptor_backend == "pyramid" else LAFOrienter(19),
            aff_module=PassLAF(),
            compile_model=compile_model,
            score_threshold=score_threshold,
        ).to(device)
        descriptor: nn.Module
        if descriptor_backend == "pyramid":
            descriptor = SIFTDescriptorFromPyramid(rootsift=rootsift).to(device)
        else:
            descriptor = LAFDescriptor(
                SIFTDescriptor(patch_size=patch_size, rootsift=rootsift),
                patch_size=patch_size,
                grayscale_descriptor=True,
            ).to(device)
        super().__init__(detector, descriptor, upright, descriptor_layout)


class SIFTFeatureScaleSpace(LocalFeature):
    """Detect refined DoG scale-space extrema and describe them with SIFT, for a batch.

    ``sift = SIFTFeatureScaleSpace(2048, descriptor_backend="pyramid")`` builds a DoG scale-space SIFT pipeline.
    ``lafs, responses, descs = sift(img)`` takes grayscale images ``(B, 1, H, W)``. It returns six-sigma LAFs
    ``(B, N, 2, 3)``, absolute DoG responses ``(B, N)``, strongest first, and RootSIFT descriptors ``(B, N, 128)``.
    Use :func:`laf_is_filled` to keep detections and discard padding. The ``"pyramid"`` backend reuses Gaussian
    images and accepts RGB input; ``"patch"`` samples patches and requires grayscale input. Use
    ``descriptor_layout="opencv"`` with ``LightGlueMatcher("sift")``; use :class:`DoGHardNet` for HardNet
    descriptors on the ``"patch"`` detections.

    For CPU throughput use OpenCV's SIFT: on an Apple M1 CPU, a matching pipeline on it ran 8x faster than one on this
    module with ``descriptor_backend="pyramid"``, and 14x faster with ``"patch"`` (640 px, 2,048 features). See the
    `image matching guide
    <https://kornia.readthedocs.io/en/latest/applications/image_matching.html#feature-speed-by-device>`_.

    Convention:
        - A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale
          images ``(B, 1, H, W)``; the pyramid backend converts an RGB image to grayscale first.
          ``descriptor_backend="patch"``, the default, runs :class:`~kornia.feature.ScaleSpaceDetector` with
          :class:`~kornia.feature.BlobDoG` on ``ScalePyramid(3, 1.6, 32, double_image=True)``, keeping minima as well
          as maxima, then ``LAFOrienter(19)`` unless ``upright``, and :class:`~kornia.feature.SIFTDescriptor` on 41 x
          41 patches. ``"pyramid"`` runs a dedicated DoG detector and reuses its Gaussian images and the octave and
          layer of each detection for orientation and description: it refines only sparse extrema, ranks all valid
          candidates by absolute response, and computes image gradients once per used layer.
        - Each backend assigns one orientation per detection unless ``upright=True``. The backend selects a different
          detector as well as different orientation and description stages, so the backends can return different
          detections as well as different descriptors; the feature budget is the same.
        - On both backends the LAF scale is 6 times the detection sigma, and ``responses`` is the absolute DoG, the
          same for a bright blob as for a dark one. The LAF centres are in the frame of
          :func:`~kornia.feature.laf_from_center_scale_ori` (see :ref:`Local features <local-features-conventions>`) on
          every octave. For a float16 or bfloat16 image the LAFs are float32 on both backends, and the responses and
          descriptors keep the image dtype.
        - Descriptors come in kornia's SIFT layout; ``descriptor_layout="opencv"`` returns them in OpenCV's, which
          :class:`~kornia.feature.LightGlueMatcher` expects with ``"sift"``.
          :func:`~kornia.feature.convert_sift_descriptor_layout` converts between the two.

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        rootsift: if ``True``, the default, return RootSIFT descriptors, otherwise SIFT.
        device: the device of the detector and descriptor modules. Default: CPU.
        compile_modules: the detector sub-modules to wrap with :func:`torch.compile`. With ``"patch"``, the
            ``compile_modules`` of :class:`~kornia.feature.ScaleSpaceDetector`; with ``"pyramid"``, ``"scale_pyr"``
            and ``"subpix"`` only, both for ``True``, while the orientation and description run eagerly.
        descriptor_backend: ``"patch"`` or ``"pyramid"``, see the Convention block.
        descriptor_layout: ``"kornia"`` or ``"opencv"``, the order of the descriptor values.

    Raises:
        ValueError: for a ``descriptor_backend`` or ``descriptor_layout`` other than those listed, or a
            ``compile_modules`` name the selected backend does not have.

    See Also:
        - :class:`SIFTFeature`: a per-level DoG approximation of SIFT, without selection across scale or sub-pixel
          refinement, one image per call.
        - :class:`ScaleSpaceDetector`: the detector of the ``"patch"`` backend, on a :class:`BlobDoG` response.
        - :class:`BlobDoG`: the scale-space DoG response of the ``"patch"`` backend.
        - :class:`SIFTDescriptor`: the descriptor of the ``"patch"`` backend, run on 41 x 41 patches through
          :class:`LAFDescriptor`.
        - :func:`convert_sift_descriptor_layout`: the reordering that ``descriptor_layout="opencv"`` applies.
        - :class:`LightGlueMatcher`: its ``"sift"`` weights match these features, in the ``"opencv"`` layout.
        - :class:`DoGHardNet`: the detections of the ``"patch"`` backend described by HardNet, at twice the frame
          scale.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    Example:
        >>> sift = SIFTFeatureScaleSpace(100, descriptor_backend="pyramid")
        >>> lafs, responses, descs = sift(torch.rand(2, 1, 64, 64))
        >>> lafs.shape, responses.shape, descs.shape
        (torch.Size([2, 100, 2, 3]), torch.Size([2, 100]), torch.Size([2, 100, 128]))

    """

    def __init__(
        self,
        num_features: int = 8000,
        upright: bool = False,
        rootsift: bool = True,
        device: Union[str, torch.device, None] = None,
        compile_modules: Union[bool, List[str]] = False,
        descriptor_backend: Literal["patch", "pyramid"] = "patch",
        descriptor_layout: Literal["kornia", "opencv"] = "kornia",
    ) -> None:
        if descriptor_backend not in ("patch", "pyramid"):
            raise ValueError(f"Unknown SIFT descriptor backend: {descriptor_backend!r}")
        _check_sift_descriptor_layout(descriptor_layout)
        if device is None:
            device = torch.device("cpu")
        patch_size: int = 41
        if descriptor_backend == "pyramid":
            detector = _SIFTScaleSpaceDetector(num_features, _SIFTScalePyramid()).to(device)
            if compile_modules:
                selected = {"scale_pyr", "subpix"} if compile_modules is True else set(compile_modules)
                unknown = selected - {"scale_pyr", "subpix"}
                if unknown:
                    raise ValueError("The SIFT pyramid backend supports compile_modules=['scale_pyr', 'subpix'] only")
                if "scale_pyr" in selected:
                    # In-place compilation preserves buffer paths and module
                    # serialization, unlike wrapping or replacing forward.
                    detector.scale_pyr.compile()
                if "subpix" in selected:
                    detector._refine = torch.compile(detector._refine)
        else:
            detector = ScaleSpaceDetector(
                num_features,
                resp_module=BlobDoG(),
                subpix_module=ConvQuadInterp3d(),
                scale_pyr_module=ScalePyramid(3, 1.6, 32, double_image=True),
                ori_module=PassLAF() if upright or descriptor_backend == "pyramid" else LAFOrienter(19),
                scale_space_response=True,
                minima_are_also_good=True,
                mr_size=6.0,
                compile_modules=compile_modules,
            ).to(device)
        descriptor: nn.Module
        if descriptor_backend == "pyramid":
            descriptor = _SIFTScaleSpaceDescriptor(rootsift=rootsift).to(device)
        else:
            descriptor = LAFDescriptor(
                SIFTDescriptor(patch_size=patch_size, rootsift=rootsift),
                patch_size=patch_size,
                grayscale_descriptor=True,
            ).to(device)
        super().__init__(detector, descriptor)
        self.upright = upright
        self.descriptor_backend = descriptor_backend
        self.descriptor_layout = descriptor_layout

    def forward(
        self, img: torch.Tensor, mask: Optional[torch.Tensor] = None
    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
        """Detect and describe SIFT features; the ``"pyramid"`` backend reuses the detector's Gaussian images."""
        if self.descriptor_backend == "patch":
            lafs, responses, descriptors = super().forward(img, mask)
            return lafs, responses, _in_sift_layout(descriptors, self.descriptor_layout)
        gray = rgb_to_grayscale(img) if img.shape[1] == 3 else img
        responses, lafs, _, pyramid, octaves, levels = self.detector._detect_with_pyramid(
            gray, self.detector.num_features, mask
        )
        lafs = scale_laf(lafs, self.scaling_coef)
        lafs, descriptors = self.descriptor(pyramid, lafs, octaves, levels, upright=self.upright)
        return lafs, responses, _in_sift_layout(descriptors.to(img.dtype), self.descriptor_layout)


class GFTTAffNetHardNet(LocalFeature):
    """Detect GFTT corners over scale with AffNet shapes and HardNet descriptors.

    ``feature = GFTTAffNetHardNet(2048)`` loads pretrained AffNet and HardNet in evaluation mode. ``lafs, responses,
    descs = feature(img)`` takes grayscale images ``(B, 1, H, W)``; convert color images with
    :func:`~kornia.color.rgb_to_grayscale` first. It returns affine LAFs ``(B, N, 2, 3)``, Shi-Tomasi responses
    ``(B, N)``, strongest first, and unit-norm HardNet descriptors ``(B, N, 128)``. Use :func:`laf_is_filled` to keep
    detections and discard padding. For blobs, use :class:`HesAffNetHardNet` or :class:`DoGAffNetHardNet`.

    Convention:
        A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale
        images ``(B, 1, H, W)``: a :class:`~kornia.feature.ScaleSpaceDetector` with the
        :class:`~kornia.feature.CornerGFTT` response, its maxima only and ``mr_size=6``, whose LAFs get their affine
        shape from :class:`~kornia.feature.LAFAffNetShapeEstimator`, then their orientation from ``LAFOrienter(19)``
        unless ``upright``, and are described by :class:`~kornia.feature.HardNet` on 32 x 32 patches.

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        compile_modules: the detector sub-modules to wrap with :func:`torch.compile`, see
            :class:`~kornia.feature.ScaleSpaceDetector`.

    See Also:
        - :class:`HesAffNetHardNet`: the same pipeline on Hessian blobs, 2048 slots by default.
        - :class:`DoGAffNetHardNet`: the same shapes and descriptors on DoG blobs, which
          ``LightGlueMatcher("dog_affnet_hardnet")`` matches.
        - :class:`CornerGFTT`: the corner response it detects on.
        - :class:`ScaleSpaceDetector`: its detector.
        - :class:`LAFAffNetShapeEstimator`: the AffNet shape estimation it runs before the orientation.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 8000,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        compile_modules: Union[bool, List[str]] = False,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        detector = ScaleSpaceDetector(
            num_features,
            resp_module=CornerGFTT(),
            # A per-level response reads n_levels + 2 levels per octave; a third extra level is never read.
            scale_pyr_module=ScalePyramid(3, 1.6, 32, double_image=True, extra_levels=2),
            ori_module=PassLAF() if upright else LAFOrienter(19),
            aff_module=LAFAffNetShapeEstimator(True, preserve_orientation=False).eval(),
            scale_space_response=False,
            minima_are_also_good=False,
            mr_size=6.0,
            compile_modules=compile_modules,
        ).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor)
        self.eval()


class HesAffNetHardNet(LocalFeature):
    """Detect Hessian blobs over scale with AffNet shapes and HardNet descriptors.

    ``feature = HesAffNetHardNet(2048)`` loads pretrained AffNet and HardNet in evaluation mode. ``lafs, responses,
    descs = feature(img)`` takes grayscale images ``(B, 1, H, W)``; convert color images with
    :func:`~kornia.color.rgb_to_grayscale` first. It returns affine LAFs ``(B, N, 2, 3)``, Hessian responses
    ``(B, N)``, strongest first, and unit-norm HardNet descriptors ``(B, N, 128)``. Use :func:`laf_is_filled` to keep
    detections and discard padding. For corners use :class:`GFTTAffNetHardNet`; for LightGlue-compatible DoG blobs,
    use :class:`DoGAffNetHardNet`.

    Convention:
        A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale
        images ``(B, 1, H, W)``: a :class:`~kornia.feature.ScaleSpaceDetector` with the
        :class:`~kornia.feature.BlobHessian` response, its maxima only and ``mr_size=6``, whose LAFs get their affine
        shape from :class:`~kornia.feature.LAFAffNetShapeEstimator`, then their orientation from ``LAFOrienter(19)``
        unless ``upright``, and are described by :class:`~kornia.feature.HardNet` on 32 x 32 patches.

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        compile_modules: the detector sub-modules to wrap with :func:`torch.compile`, see
            :class:`~kornia.feature.ScaleSpaceDetector`.

    See Also:
        - :class:`GFTTAffNetHardNet`: the same pipeline on Shi-Tomasi corners, 8000 slots by default.
        - :class:`DoGAffNetHardNet`: the same shapes and descriptors on DoG blobs, which
          ``LightGlueMatcher("dog_affnet_hardnet")`` matches.
        - :class:`BlobHessian`: the blob response it detects on.
        - :class:`ScaleSpaceDetector`: its detector, with this response by default.
        - :class:`LAFAffNetShapeEstimator`: the AffNet shape estimation it runs before the orientation.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 2048,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        compile_modules: Union[bool, List[str]] = False,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        detector = ScaleSpaceDetector(
            num_features,
            resp_module=BlobHessian(),
            # A per-level response reads n_levels + 2 levels per octave; a third extra level is never read.
            scale_pyr_module=ScalePyramid(3, 1.6, 32, double_image=True, extra_levels=2),
            ori_module=PassLAF() if upright else LAFOrienter(19),
            aff_module=LAFAffNetShapeEstimator(True, preserve_orientation=False).eval(),
            scale_space_response=False,
            minima_are_also_good=False,
            mr_size=6.0,
            compile_modules=compile_modules,
        ).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor)
        self.eval()


def _dog_detector(
    num_features: int,
    upright: bool,
    aff_module: Optional[nn.Module],
    compile_modules: Union[bool, List[str]],
) -> ScaleSpaceDetector:
    """Return the 6-sigma DoG detector of the ``"patch"`` backend of :class:`SIFTFeatureScaleSpace`."""
    return ScaleSpaceDetector(
        num_features,
        resp_module=BlobDoG(),
        subpix_module=ConvQuadInterp3d(),
        # DoG has one level fewer than its pyramid, so it needs the default three extra levels.
        scale_pyr_module=ScalePyramid(3, 1.6, 32, double_image=True),
        ori_module=PassLAF() if upright else LAFOrienter(19),
        aff_module=aff_module,
        scale_space_response=True,
        minima_are_also_good=True,
        mr_size=6.0,
        compile_modules=compile_modules,
    )


class DoGHardNet(LocalFeature):
    """Detect DoG blobs over scale and describe them with HardNet, without affine adaptation.

    ``feature = DoGHardNet(2048)`` loads pretrained HardNet in evaluation mode. ``lafs, responses, descs =
    feature(img)`` takes grayscale images ``(B, 1, H, W)``. It returns 12-sigma DoG LAFs ``(B, N, 2, 3)``, absolute
    DoG responses ``(B, N)``, strongest first, and unit-norm HardNet descriptors ``(B, N, 128)``. Use
    :func:`laf_is_filled` to keep detections and discard padding before calling ``LightGlueMatcher("doghardnet")``.
    Choose :class:`DoGAffNetHardNet` for affine shapes or :class:`SIFTFeatureScaleSpace` for SIFT descriptors.

    Convention:
        - A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract. The detector is
          the DoG :class:`~kornia.feature.ScaleSpaceDetector` of :class:`~kornia.feature.SIFTFeatureScaleSpace`'s
          ``"patch"`` backend, and the orientation is estimated on its 6-sigma frames. The returned LAFs are those
          frames scaled by two (``scaling_coef=2``), to 12 sigma or six times OpenCV's ``KeyPoint.size``, and
          :class:`~kornia.feature.HardNet` describes them on 32 x 32 patches.
        - The image must have one channel, ``(B, 1, H, W)``: convert a color image with
          :func:`~kornia.color.rgb_to_grayscale` first.

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        compile_modules: the detector sub-modules to wrap with :func:`torch.compile`, see
            :class:`~kornia.feature.ScaleSpaceDetector`.

    See Also:
        - :class:`DoGAffNetHardNet`: the same detections with AffNet shapes, estimated before the orientation.
        - :class:`SIFTFeatureScaleSpace`: the same detections with SIFT descriptors, at 6 sigma, with its
          ``"patch"`` backend.
        - :class:`ScaleSpaceDetector`: its detector, on a :class:`BlobDoG` response.
        - :class:`BlobDoG`: the scale-space DoG response it detects on.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`LightGlueMatcher`: its ``"doghardnet"`` weights match these features.
        - :class:`KeyNetHardNet`: HardNet descriptors of KeyNet detections, one image per call.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 2048,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        compile_modules: Union[bool, List[str]] = False,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        detector = _dog_detector(num_features, upright, None, compile_modules).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor, scaling_coef=2.0)
        self.eval()


class DoGAffNetHardNet(LocalFeature):
    """Detect DoG blobs over scale with AffNet shapes and HardNet descriptors.

    ``feature = DoGAffNetHardNet(2048)`` loads pretrained AffNet and HardNet in evaluation mode. ``lafs, responses,
    descs = feature(img)`` takes grayscale images ``(B, 1, H, W)``. It returns the outputs of :class:`DoGHardNet`,
    with affine LAF shapes adapted by AffNet before orientation. Use :func:`laf_is_filled` to keep detections and
    discard padding before calling ``LightGlueMatcher("dog_affnet_hardnet")``. Choose :class:`GFTTAffNetHardNet` or
    :class:`HesAffNetHardNet` for corners or Hessian blobs.

    Convention:
        As :class:`~kornia.feature.DoGHardNet`, with the affine shape of each 6-sigma DoG frame estimated by
        :class:`~kornia.feature.LAFAffNetShapeEstimator` before its orientation. The scale of the returned LAFs, the
        square root of their determinant, is again 12 sigma. The image must have one channel, ``(B, 1, H, W)``.

    Args:
        num_features: the number of slots per image; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        compile_modules: the detector sub-modules to wrap with :func:`torch.compile`, see
            :class:`~kornia.feature.ScaleSpaceDetector`.

    See Also:
        - :class:`DoGHardNet`: the same detections and descriptors without affine adaptation.
        - :class:`LAFAffNetShapeEstimator`: the AffNet shape estimation it runs before the orientation.
        - :class:`ScaleSpaceDetector`: its detector, on a :class:`BlobDoG` response.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`LightGlueMatcher`: its ``"dog_affnet_hardnet"`` mode matches these features.
        - :class:`GFTTAffNetHardNet`: the same shapes and descriptors on Shi-Tomasi corners.
        - :class:`HesAffNetHardNet`: the same shapes and descriptors on Hessian blobs.
        - :class:`KeyNetAffNetHardNet`: the same shapes and descriptors on KeyNet detections, one image per call.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 2048,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        compile_modules: Union[bool, List[str]] = False,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        aff_module = LAFAffNetShapeEstimator(True, preserve_orientation=False).eval()
        detector = _dog_detector(num_features, upright, aff_module, compile_modules).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor, scaling_coef=2.0)
        self.eval()


class KeyNetHardNet(LocalFeature):
    """Detect KeyNet keypoints and describe them with HardNet, without affine adaptation.

    ``feature = KeyNetHardNet(2048)`` loads pretrained KeyNet, OriNet and HardNet in evaluation mode. ``lafs,
    responses, descs = feature(img)`` takes one grayscale image ``(1, 1, H, W)`` in ``[0, 1]``; a batch or color image
    raises. It returns LAFs ``(1, N, 2, 3)``, KeyNet responses ``(1, N)``, strongest first, and unit-norm HardNet
    descriptors ``(1, N, 128)``. Use :func:`laf_is_filled` to keep detections and discard padding. Choose
    :class:`KeyNetAffNetHardNet` for AffNet shapes and its LightGlue weights. For batches, use :class:`DoGHardNet`.

    Convention:
        A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of one grayscale
        image per call, ``(1, 1, H, W)``: a :class:`~kornia.feature.KeyNetDetector`, whose LAFs get their
        orientation from :class:`~kornia.feature.OriNet` on 32 x 32 patches unless ``upright``, and are described by
        :class:`~kornia.feature.HardNet` on 32 x 32 patches. ``scale_laf`` is the ``scaling_coef`` of
        :class:`~kornia.feature.LocalFeature`: it multiplies the detector's LAFs before the description.

    Args:
        num_features: the number of slots; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        scale_laf: the multiplier of the detector's LAFs before the description. Must be positive.
        compile_model: wrap the KeyNet response and the non-maxima suppression with :func:`torch.compile`, see
            :class:`~kornia.feature.KeyNetDetector`.
        score_threshold: the KeyNet response a detection has to exceed. Must be non-negative.

    Raises:
        ValueError: if ``scale_laf`` is not positive or ``score_threshold`` is negative.

    See Also:
        - :class:`KeyNetAffNetHardNet`: the same detections with AffNet shapes, estimated before the orientation.
        - :class:`KeyNetDetector`: its detector.
        - :class:`KeyNet`: the learned response it detects on.
        - :class:`OriNet`: the learned orientation, run on each LAF's patch through :class:`LAFOrienter`.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`DoGHardNet`: HardNet descriptors of DoG detections, for a batch of images.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 8000,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        scale_laf: float = 1.0,
        compile_model: bool = False,
        score_threshold: float = 0.0,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        ori_module = PassLAF() if upright else LAFOrienter(angle_detector=OriNet(True))
        detector = KeyNetDetector(
            True,
            num_features=num_features,
            ori_module=ori_module,
            compile_model=compile_model,
            score_threshold=score_threshold,
        ).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor, scale_laf)
        self.eval()


class KeyNetAffNetHardNet(LocalFeature):
    """Detect KeyNet keypoints with AffNet shapes and HardNet descriptors.

    ``feature = KeyNetAffNetHardNet(2048)`` loads pretrained KeyNet, AffNet, OriNet and HardNet in evaluation mode.
    ``lafs, responses, descs = feature(img)`` takes one grayscale image ``(1, 1, H, W)`` in ``[0, 1]``. It returns
    the outputs of :class:`KeyNetHardNet`, with affine LAF shapes adapted by AffNet before orientation. Use
    :func:`laf_is_filled` to keep detections and discard padding before calling
    ``LightGlueMatcher("keynet_affnet_hardnet")``. For batches, use :class:`DoGAffNetHardNet`.

    .. image:: _static/img/keynet_affnet.jpg

    Convention:
        As :class:`~kornia.feature.KeyNetHardNet`, with the affine shape of each frame estimated by
        :class:`~kornia.feature.LAFAffNetShapeEstimator` before its orientation.

    Args:
        num_features: the number of slots; the strongest detections fill them, the rest are padding.
        upright: if ``True``, skip the orientation estimation and return upright frames.
        device: the device of the detector and descriptor modules. Default: CPU.
        scale_laf: the multiplier of the detector's LAFs before the description. Must be positive.
        compile_model: wrap the KeyNet response and the non-maxima suppression with :func:`torch.compile`, see
            :class:`~kornia.feature.KeyNetDetector`.
        score_threshold: the KeyNet response a detection has to exceed. Must be non-negative.

    Raises:
        ValueError: if ``scale_laf`` is not positive or ``score_threshold`` is negative.

    See Also:
        - :class:`KeyNetHardNet`: the same detections and descriptors without affine adaptation.
        - :class:`KeyNetDetector`: its detector.
        - :class:`LAFAffNetShapeEstimator`: the AffNet shape estimation it runs before the orientation.
        - :class:`OriNet`: the learned orientation, run on each LAF's patch through :class:`LAFOrienter`.
        - :class:`HardNet`: its descriptor, run on 32 x 32 patches through :class:`LAFDescriptor`.
        - :class:`LightGlueMatcher`: its ``"keynet_affnet_hardnet"`` weights match these features.
        - :class:`DoGAffNetHardNet`: the same shapes and descriptors on DoG detections, for a batch of images.
        - :class:`LocalFeature`: its base class, which gives the output contract.

    """

    def __init__(
        self,
        num_features: int = 8000,
        upright: bool = False,
        device: Union[str, torch.device, None] = None,
        scale_laf: float = 1.0,
        compile_model: bool = False,
        score_threshold: float = 0.0,
    ) -> None:
        if device is None:
            device = torch.device("cpu")
        ori_module = PassLAF() if upright else LAFOrienter(angle_detector=OriNet(True))
        detector = KeyNetDetector(
            True,
            num_features=num_features,
            ori_module=ori_module,
            aff_module=LAFAffNetShapeEstimator(True, preserve_orientation=False).eval(),
            compile_model=compile_model,
            score_threshold=score_threshold,
        ).to(device)
        descriptor = LAFDescriptor(None, patch_size=32, grayscale_descriptor=True).to(device)
        super().__init__(detector, descriptor, scale_laf)
        self.eval()


class LocalFeatureMatcher(nn.Module):
    r"""Detect, describe and match the local features of two images with a descriptor matcher.

    ``matcher = LocalFeatureMatcher(local_feature, DescriptorMatcher("snn", 0.8))`` builds the module and
    ``out = matcher({"image0": img0, "image1": img1})`` runs ``local_feature`` on both batches of images, which the
    :class:`LocalFeature` presets take as grayscale ``(B, 1, H, W)``, except :class:`SIFTFeature`,
    :class:`KeyNetHardNet` and :class:`KeyNetAffNetHardNet`, which take one image per call, ``(1, 1, H, W)``. It
    matches the descriptors of each pair of images and returns a dict of the matches of all pairs: ``keypoints0``
    and ``keypoints1`` ``(NC, 2)``, ``lafs0`` and ``lafs1`` ``(1, NC, 2, 3)``, ``confidence`` ``(NC,)`` and the pair
    of each match, ``batch_indexes`` ``(NC,)``. Features already computed for an image can be passed instead of
    running ``local_feature`` on it. For a matcher that reads the LAFs, such as :class:`LightGlueMatcher`, call it on
    the outputs of the local feature yourself; for matching without a detector, use :class:`LoFTR`.

    Convention:
        - ``keypoints0`` and ``keypoints1`` are the centres ``(x, y)`` of the returned LAF tensors ``lafs0`` and
          ``lafs1``, respectively; see :func:`~kornia.feature.laf_from_center_scale_ori` and
          :ref:`Local features <local-features-conventions>` for the LAF frame.
          ``confidence`` is ``1 - dists`` of the matcher (see :func:`~kornia.feature.match_nn`).
        - All-zero LAFs, the padding slots of kornia's detectors (see :func:`~kornia.feature.laf_is_filled`), are
          dropped before matching.
        - ``matcher`` is called as ``matcher(descriptors0, descriptors1)`` for each image pair, so it has to be a
          descriptor-only matcher such as :class:`~kornia.feature.DescriptorMatcher`;
          :class:`~kornia.feature.GeometryAwareDescriptorMatcher` and :class:`~kornia.feature.LightGlueMatcher`
          need LAFs and do not fit.

    Args:
        local_feature: Local feature detector and descriptor, called as ``local_feature(image, mask)`` and returning
            ``(lafs, responses, descriptors)`` like :class:`~kornia.feature.LocalFeature`. See
            :class:`~kornia.feature.GFTTAffNetHardNet`.
        matcher: Descriptor matcher, see :class:`~kornia.feature.DescriptorMatcher`.

    Returns:
        Dict[str, torch.Tensor]: Dictionary with image correspondences and confidence scores.

    See Also:
        - :class:`LocalFeature`: the detector and descriptor pipeline that ``local_feature`` usually is.
        - :class:`DescriptorMatcher`: the descriptor-only matcher it takes.
        - :class:`LightGlueMatcher`: a learned matcher, which takes the LAFs and the image sizes as well.
        - :class:`LoFTR`: matches two images directly, without a detector.
        - :class:`~kornia.geometry.ransac.RANSAC`: the next step, which keeps the matches one geometric model
          explains.

    Example:
        >>> img1 = torch.rand(1, 1, 320, 200)
        >>> img2 = torch.rand(1, 1, 128, 128)
        >>> input = {"image0": img1, "image1": img2}
        >>> gftt_hardnet_matcher = LocalFeatureMatcher(
        ...     GFTTAffNetHardNet(10), kornia.feature.DescriptorMatcher('snn', 0.8)
        ... )
        >>> out = gftt_hardnet_matcher(input)

    """

    def __init__(self, local_feature: nn.Module, matcher: nn.Module) -> None:
        super().__init__()
        self.local_feature = local_feature
        self.matcher = matcher
        self.eval()

    def extract_features(self, image: torch.Tensor, mask: Optional[torch.Tensor] = None) -> Dict[str, torch.Tensor]:
        """Extract features from simple image."""
        lafs0, resps0, descs0 = self.local_feature(image, mask)
        return {"lafs": lafs0, "responses": resps0, "descriptors": descs0}

    def no_match_output(self, device: Union[str, torch.device, None], dtype: torch.dtype) -> Dict[str, torch.Tensor]:
        """Create an empty output structure when no correspondences are found.

        Args:
            device: Device on which empty tensors should be allocated.
            dtype: Floating-point dtype used for keypoints/LAF/confidence.

        Returns:
            Dictionary with correctly typed empty tensors for all expected
            output fields.
        """
        return {
            "keypoints0": torch.empty(0, 2, device=device, dtype=dtype),
            "keypoints1": torch.empty(0, 2, device=device, dtype=dtype),
            # batch dim 1, matching the success path's `.view(1, -1, 2, 3)`, so that callers
            # can index `lafs0[0]` regardless of whether anything matched.
            "lafs0": torch.empty(1, 0, 2, 3, device=device, dtype=dtype),
            "lafs1": torch.empty(1, 0, 2, 3, device=device, dtype=dtype),
            "confidence": torch.empty(0, device=device, dtype=dtype),
            "batch_indexes": torch.empty(0, device=device, dtype=torch.long),
        }

    def forward(self, data: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
        """Run forward.

        Args:
            data: dictionary containing the input data in the following format:

        Keyword Args:
            image0: left image with shape ``(N, 1, H1, W1)``. Required also with ``lafs0`` and ``descriptors0``:
                its first dimension gives the number of image pairs.
            image1: right image with shape ``(N, 1, H2, W2)``; not read when ``lafs1`` and ``descriptors1`` are
                given.
            mask0 (optional): left image mask. '0' suppresses detection, with shape
                ``(N, H1, W1)`` or ``(N, 1, H1, W1)``.
            mask1 (optional): right image mask. '0' suppresses detection, with shape
                ``(N, H2, W2)`` or ``(N, 1, H2, W2)``.
            lafs0 (optional): pre-extracted LAFs of image0, ``(N, M0, 2, 3)``. When ``lafs0`` and
                ``descriptors0`` are both given, they are matched and ``local_feature`` does not run on image0.
            descriptors0 (optional): pre-extracted descriptors of image0, ``(N, M0, D)``.
            lafs1 (optional): pre-extracted LAFs of image1, ``(N, M1, 2, 3)``; with ``descriptors1``, as for image0.
            descriptors1 (optional): pre-extracted descriptors of image1, ``(N, M1, D)``.

        Returns:
            - ``keypoints0``, matching keypoints from image0 ``(NC, 2)``.
            - ``keypoints1``, matching keypoints from image1 ``(NC, 2)``.
            - ``confidence``, ``1 - descriptor distance`` ``(NC,)``. This lies in :math:`[0, 1]`
              only for the ratio-based ``DescriptorMatcher`` modes (``snn``, ``smnn``); ``nn`` and
              ``mnn`` return raw distances, which are unbounded for an arbitrary descriptor, so the
              confidence has no lower bound in general -- it goes at least down to -1, the value
              reached by unit-norm descriptors, whose distance tops out at 2.0.
            - ``lafs0``, matching LAFs from image0 ``(1, NC, 2, 3)``.
            - ``lafs1``, matching LAFs from image1 ``(1, NC, 2, 3)``.
            - ``batch_indexes``, batch indexes for the keypoints and lafs ``(NC,)``.

        """
        num_image_pairs: int = data["image0"].shape[0]

        if ("lafs0" not in data) or ("descriptors0" not in data):
            # One can supply pre-extracted local features
            mask0 = data.get("mask0")
            if mask0 is not None and mask0.dim() == 3:
                mask0 = mask0.unsqueeze(1)
            feats_dict0: Dict[str, torch.Tensor] = self.extract_features(data["image0"], mask0)
            lafs0, descs0 = feats_dict0["lafs"], feats_dict0["descriptors"]
        else:
            lafs0, descs0 = data["lafs0"], data["descriptors0"]

        if ("lafs1" not in data) or ("descriptors1" not in data):
            mask1 = data.get("mask1")
            if mask1 is not None and mask1.dim() == 3:
                mask1 = mask1.unsqueeze(1)
            feats_dict1: Dict[str, torch.Tensor] = self.extract_features(data["image1"], mask1)
            lafs1, descs1 = feats_dict1["lafs"], feats_dict1["descriptors"]
        else:
            lafs1, descs1 = data["lafs1"], data["descriptors1"]

        # The padding mask below is read off the LAFs and applied to the descriptors, so the two
        # must describe the same features; a mismatch would otherwise surface as an opaque
        # boolean-index error, or silently mis-associate the matches when every index fits.
        KORNIA_CHECK(
            lafs0.shape[:2] == descs0.shape[:2],
            f"lafs0 and descriptors0 must describe the same features, "
            f"got {tuple(lafs0.shape)} and {tuple(descs0.shape)}",
        )
        KORNIA_CHECK(
            lafs1.shape[:2] == descs1.shape[:2],
            f"lafs1 and descriptors1 must describe the same features, "
            f"got {tuple(lafs1.shape)} and {tuple(descs1.shape)}",
        )

        keypoints0: torch.Tensor = get_laf_center(lafs0)
        keypoints1: torch.Tensor = get_laf_center(lafs1)

        out_keypoints0: List[torch.Tensor] = []
        out_keypoints1: List[torch.Tensor] = []
        out_confidence: List[torch.Tensor] = []
        out_batch_indexes: List[torch.Tensor] = []
        out_lafs0: List[torch.Tensor] = []
        out_lafs1: List[torch.Tensor] = []

        # Fixed-shape detectors represent an unfilled slot with a zero LAF. Do not let the
        # descriptor sampled at that dummy frame become a correspondence (NN/MNN would match
        # identical padding at the origin). Occupancy cannot be inferred from the response:
        # a pluggable signed scale-space response may have a genuine maximum at exactly zero.
        # Computed for the whole batch once, rather than per pair inside the loop.
        filled0 = laf_is_filled(lafs0)
        filled1 = laf_is_filled(lafs1)

        for batch_idx in range(num_image_pairs):
            valid0 = filled0[batch_idx]
            valid1 = filled1[batch_idx]
            current_descs0 = descs0[batch_idx][valid0]
            current_descs1 = descs1[batch_idx][valid1]
            current_keypoints0 = keypoints0[batch_idx][valid0]
            current_keypoints1 = keypoints1[batch_idx][valid1]
            current_lafs0 = lafs0[batch_idx][valid0]
            current_lafs1 = lafs1[batch_idx][valid1]

            # `matcher` is an arbitrary module with no obligation to accept a `(0, D)` input, and a
            # textureless or fully masked image leaves nothing to match anyway.
            if current_descs0.shape[0] == 0 or current_descs1.shape[0] == 0:
                continue

            dists, idxs = self.matcher(current_descs0, current_descs1)
            if len(idxs) == 0:
                continue

            current_keypoints_0 = current_keypoints0[idxs[:, 0]]
            current_keypoints_1 = current_keypoints1[idxs[:, 1]]
            current_lafs_0 = current_lafs0[idxs[:, 0]]
            current_lafs_1 = current_lafs1[idxs[:, 1]]

            out_confidence.append(1.0 - dists)
            batch_idxs = batch_idx * torch.ones(len(dists), device=keypoints0.device, dtype=torch.long)
            out_keypoints0.append(current_keypoints_0)
            out_keypoints1.append(current_keypoints_1)
            out_lafs0.append(current_lafs_0)
            out_lafs1.append(current_lafs_1)
            out_batch_indexes.append(batch_idxs)

        if len(out_batch_indexes) == 0:
            out = self.no_match_output(data["image0"].device, data["image0"].dtype)
            # As on the match path, keypoints and LAFs keep the LAFs' dtype: float32 for a half-precision detector.
            out["keypoints0"], out["lafs0"] = out["keypoints0"].to(lafs0.dtype), out["lafs0"].to(lafs0.dtype)
            out["keypoints1"], out["lafs1"] = out["keypoints1"].to(lafs1.dtype), out["lafs1"].to(lafs1.dtype)
            return out

        return {
            "keypoints0": torch.cat(out_keypoints0, dim=0).view(-1, 2),
            "keypoints1": torch.cat(out_keypoints1, dim=0).view(-1, 2),
            "lafs0": torch.cat(out_lafs0, dim=0).view(1, -1, 2, 3),
            "lafs1": torch.cat(out_lafs1, dim=0).view(1, -1, 2, 3),
            "confidence": torch.cat(out_confidence, dim=0).view(-1),
            "batch_indexes": torch.cat(out_batch_indexes, dim=0).view(-1),
        }


class LightGlueMatcher(GeometryAwareDescriptorMatcher):
    r"""Match descriptors and LAFs with LightGlue, called like GeometryAwareDescriptorMatcher.

    ``matcher = LightGlueMatcher("disk")`` loads the LightGlue weights trained for that local feature, and
    ``scores, idxs = matcher(desc1, desc2, lafs1, lafs2, hw1, hw2)`` takes the descriptors ``(B1, D)`` and
    ``(B2, D)`` of two images (or ``(1, B1, D)`` and ``(1, B2, D)``), their LAFs ``(1, B1, 2, 3)`` and
    ``(1, B2, 2, 3)`` in pixels and, optionally, the image sizes ``(H, W)``, and returns LightGlue's matching scores
    ``(B3, 1)``, higher for better matches, and the index pairs ``(B3, 2)``, in the format of
    :class:`GeometryAwareDescriptorMatcher`. The descriptors must come from the feature the weights were trained for,
    see ``feature_name`` in the Convention block. To pass batches of
    keypoints in dicts and read every output of the network, use :class:`LightGlue`; for an exported ONNX model, use
    :class:`OnnxLightGlue`. It is based on the original code of "LightGlue: Local Feature Matching at Light Speed",
    see :cite:`LightGlue2023` for more details.

    Convention:
        - ``lafs1`` and ``lafs2`` use the pixel convention of :func:`~kornia.feature.laf_from_center_scale_ori`
          (see :ref:`Local features <local-features-conventions>`), and their centres go to LightGlue unchanged as
          the keypoints. ``hw1`` and ``hw2`` are the ``(H, W)`` of each image, which become LightGlue's
          ``image_size`` ``(W, H)``; without them, the image size is taken as the largest keypoint coordinates of
          that image, ``(max x, max y)``.
        - Choose ``feature_name`` for the source of the descriptors (case-insensitive). The network receives the
          following data besides keypoints:

          - ``"aliked"``: use the 128-D descriptors of :class:`ALIKED`. The 64-D ``"aliked-t16"`` descriptors are
            incompatible with these weights.
          - ``"dedodeb"``, ``"dedodeg"``: use the ``B``, respectively ``G``, descriptors of :class:`DeDoDe`. Build
            the LAFs at keypoints minus 0.5, because DeDoDe puts pixel ``i`` at ``i + 0.5``.
          - ``"disk"``, ``"raco-aliked"``, ``"superpoint"``, ``"xfeat"``: use descriptors from the named feature and
            no additional LAF attributes. For ``"xfeat"``, pass the 64-D
            descriptors of :meth:`~kornia.feature.XFeat.detectAndCompute` and LAFs centred on its keypoints, such as
            ``laf_from_center_scale_ori(keypoints[None])``, and call the matcher under ``torch.no_grad()`` or
            ``torch.inference_mode()``: it raises on XFeat's inference tensors with gradients enabled
            (`#6533 <https://github.com/kornia/kornia/issues/6533>`_).
          - ``"sift"``: use :class:`SIFTFeatureScaleSpace` with ``descriptor_layout="opencv"``. The weights expect
            the scale and orientation of the COLMAP keypoints they were trained on: the negated
            LAF orientation in :math:`(-\pi, \pi]`, and a sixth of the LAF scale, which is the detection sigma for
            6-sigma DoG frames such as :class:`~kornia.feature.SIFTFeatureScaleSpace`'s. The descriptors must be in
            OpenCV's SIFT layout, which these weights expect, while kornia's SIFT descriptors use another order of the
            same values: create the feature with ``descriptor_layout="opencv"``, or convert the descriptors with
            ``convert_sift_descriptor_layout(descs, "kornia", "opencv")``
            (:func:`~kornia.feature.convert_sift_descriptor_layout`).
          - ``"doghardnet"``, ``"dog_affnet_hardnet"``: use :class:`DoGHardNet` or :class:`DoGAffNetHardNet`.
            Pass the LAFs the HardNet descriptors were computed on, at
            the scale the weights were trained with: 12 sigma, six times OpenCV's ``KeyPoint.size`` and twice the
            6-sigma DoG frames of :class:`~kornia.feature.SIFTFeatureScaleSpace`. :class:`~kornia.feature.DoGHardNet`
            and :class:`~kornia.feature.DoGAffNetHardNet` return such LAFs and their descriptors; with another
            6-sigma DoG detector, apply :func:`~kornia.feature.scale_laf` with ``2.0`` to its LAFs before describing
            them. The network takes a sixth of the LAF scale, which is ``KeyPoint.size`` for these frames, and the
            LAF orientation in :math:`[0, 2\pi)`.
          - ``"keynet_affnet_hardnet"``: use :class:`KeyNetAffNetHardNet`. The network receives the ends of the two
            LAF axes, ``c + A[:, 0]`` and ``c + A[:, 1]``,
            normalised like the keypoints.
        - The first returned value is LightGlue's matching score, not a distance: higher is better, and only matches
          scoring above ``filter_threshold`` (0.1 by default) are returned. The index rows are ``(index in desc1,
          index in desc2)``. Fewer than two descriptors on either side give no match.
        - All-zero padding LAFs are not filtered out: such a slot reaches the network as a keypoint at ``(0, 0)``.
          Drop them with :func:`~kornia.feature.laf_is_filled` first.

    Args:
        feature_name: type of feature for matching, one of ``known_modes``.
        params: keyword arguments of :class:`~kornia.feature.LightGlue`, such as ``filter_threshold``.

    See Also:
        - :class:`LightGlue`: takes batches of keypoints in dictionaries and returns all network outputs.
        - :class:`OnnxLightGlue`: runs an exported LightGlue model for one image pair.
        - :class:`LocalFeatureMatcher`: matches local features with a descriptor-only matcher.
        - :class:`LoFTR`: matches images directly, without a detector.
        - :class:`GeometryAwareDescriptorMatcher`: offers FGINN and AdaLAM with the same call.

    """

    known_modes: ClassVar[List[str]] = [
        "aliked",
        "dedodeb",
        "dedodeg",
        "disk",
        "dog_affnet_hardnet",
        "doghardnet",
        "keynet_affnet_hardnet",
        "raco-aliked",
        "sift",
        "superpoint",
        "xfeat",
    ]

    def __init__(self, feature_name: str = "disk", params: Optional[Dict] = None) -> None:
        feature_name_: str = feature_name.lower()
        super().__init__(feature_name_)
        self.feature_name = feature_name_
        if params is None:
            params = {}
        self.params = params
        self.matcher = LightGlue(self.feature_name, **params)
        if not self.matcher.training:
            self.eval()

    def forward(
        self,
        desc1: torch.Tensor,
        desc2: torch.Tensor,
        lafs1: torch.Tensor,
        lafs2: torch.Tensor,
        hw1: Optional[Tuple[int, int]] = None,
        hw2: Optional[Tuple[int, int]] = None,
    ) -> Tuple[torch.Tensor, torch.Tensor]:
        """Run forward.

        Args:
            desc1: Batch of descriptors of a shape ``(B1, D)``, or ``(1, B1, D)`` for a batch of one.
            desc2: Batch of descriptors of a shape ``(B2, D)``, or ``(1, B2, D)`` for a batch of one.
            lafs1: LAFs of a shape ``(1, B1, 2, 3)``.
            lafs2: LAFs of a shape ``(1, B2, 2, 3)``.
            hw1: ``(H, W)`` of the first image; see the Convention block.
            hw2: ``(H, W)`` of the second image; see the Convention block.

        Return:
            - LightGlue's matching score of each match, higher is better, shape of ``(B3, 1)``.
            - Long torch.Tensor indexes of matching descriptors in desc1 and desc2,
                shape of ``(B3, 2)`` where :math:`0 <= B3 <= B1`.

        """
        if (desc1.shape[-2] < 2) or (desc2.shape[-2] < 2):
            return _no_match(desc1)
        keypoints1 = get_laf_center(lafs1)
        keypoints2 = get_laf_center(lafs2)
        if len(desc1.shape) == 2:
            desc1 = desc1.unsqueeze(0)
        if len(desc2.shape) == 2:
            desc2 = desc2.unsqueeze(0)
        dev = lafs1.device
        size1 = keypoints1.max(dim=1)[0].reshape(-1, 2) if hw1 is None else _image_size_from_hw(hw1, dev)
        size2 = keypoints2.max(dim=1)[0].reshape(-1, 2) if hw2 is None else _image_size_from_hw(hw2, dev)
        input_dict = {
            "image0": {"keypoints": keypoints1, "lafs": lafs1, "descriptors": desc1, "image_size": size1},
            "image1": {"keypoints": keypoints2, "lafs": lafs2, "descriptors": desc2, "image_size": size2},
        }
        # Only the weights trained with keypoint scales and orientations read them; the others skip their kernels.
        if self.matcher.conf.add_scale_ori:
            for image, lafs in (("image0", lafs1), ("image1", lafs2)):
                scales, oris = _lightglue_keypoint_scale_ori(lafs, self.feature_name)
                input_dict[image].update(scales=scales, oris=oris)
        pred = self.matcher(input_dict)
        # LightGlue already lists the matched index pairs and their scores; deriving them again from ``matches0``
        # would read the device three more times.
        return pred["scores"][0].reshape(-1, 1), pred["matches"][0]
