π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
kornia.geometry.subpix
======================
.. meta::
:description: The kornia.geometry.subpix module provides functionalities for extracting coordinates with sub-pixel accuracy. It includes convolutional methods like soft argmax and quadratic interpolation for precise 2D and 3D coordinate extraction. Additionally, it offers spatial softmax and expectation techniques, as well as non-maximum suppression (NMS) for 2D and 3D data, making it ideal for tasks requiring high-resolution spatial localization in computer vision.
.. currentmodule:: kornia.geometry.subpix
Sub-pixel locations from heatmaps and scale-space volumes. :func:`spatial_soft_argmax2d` returns one ``(x, y)`` per
heatmap channel, the softmax-weighted mean over the whole map, and :func:`conv_soft_argmax2d` and
:func:`conv_soft_argmax3d` one per sliding window. :func:`nms2d` and :func:`nms3d` keep the strict local maxima, as
the suppressed map or a boolean mask, and :func:`nms3d_minmax` returns two boolean masks of a volume, its strict local
maxima and minima. :func:`conv_quad_interp3d` and :func:`iterative_quad_interp3d` refine the maxima of a scale-space
volume by a quadratic fit, with :class:`AdaptiveQuadInterp3d` picking the faster one for the device. Coordinates are
``(x, y)`` in 2D and ``(d, x, y)`` in 3D; see :ref:`Coordinates and sizes <coordinate-conventions>`. Each class under
Modules except :class:`AdaptiveQuadInterp3d` stores the arguments of its function form.
Convolutional
-------------
.. autofunction:: conv_soft_argmax2d
.. autofunction:: conv_soft_argmax3d
.. autofunction:: conv_quad_interp3d
.. autofunction:: iterative_quad_interp3d
.. tip::
:class:`AdaptiveQuadInterp3d` (the default subpix module in
:class:`~kornia.feature.ScaleSpaceDetector`) automatically picks the faster
backend based on the input device:
* **CUDA** β :func:`conv_quad_interp3d` β batched gather+solve, 1.5β2Γ faster on GPU.
* **CPU** β :func:`iterative_quad_interp3d` β processes only NMS maxima directly,
no dilation overhead.
With ``max_candidates`` unset, the backends agree on every maximum whose centre stays within
``dilation_radius`` voxels (default 1) of where it started. Beyond that :func:`conv_quad_interp3d` can reject a
maximum that :func:`iterative_quad_interp3d` still refines, so CPU and CUDA keypoints can differ;
``dilation_radius=n_iters`` makes the backends agree.
.. code-block:: python
import torch
from kornia.geometry.subpix import AdaptiveQuadInterp3d
from kornia.feature import ScaleSpaceDetector
from kornia.feature.responses import BlobDoG
from kornia.geometry.transform import ScalePyramid
detector = ScaleSpaceDetector(
num_features=2000,
resp_module=BlobDoG(),
# default β auto-selects conv on CUDA, patch on CPU:
subpix_module=AdaptiveQuadInterp3d(),
scale_pyr_module=ScalePyramid(3, 1.6, 32, double_image=True),
scale_space_response=True,
minima_are_also_good=True,
)
Spatial
-------
.. autofunction:: spatial_softmax2d
.. autofunction:: spatial_expectation2d
.. autofunction:: spatial_soft_argmax2d
.. autofunction:: render_gaussian2d
Non-Maxima Suppression
----------------------
.. autofunction:: nms2d
.. autofunction:: nms3d
.. autofunction:: nms3d_minmax
Modules
-------
.. autoclass:: SpatialSoftArgmax2d
.. autoclass:: ConvSoftArgmax2d
.. autoclass:: ConvSoftArgmax3d
.. autoclass:: AdaptiveQuadInterp3d
.. autoclass:: ConvQuadInterp3d
.. autoclass:: IterativeQuadInterp3d
.. autoclass:: NonMaximaSuppression2d
.. autoclass:: NonMaximaSuppression3d