π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
docs: write tensor shapes as literals and check it in every source file and docs page (#6393)
Dmytro Mishkin234ce62666be
diff --git a/AGENTS.md b/AGENTS.mdindex deed0c94e..7edf2d906 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -119,7 +119,7 @@ when more than one virtualenv is in play: name the interpreter explicitly rather- A `KORNIA_CHECK` message that formats a tensor size or an `int` argument specializes it under a dynamic-shape `torch.compile`, which then compiles a graph per value. Compare sizes with `KORNIA_CHECK_SAME_SIZE`, `KORNIA_CHECK_SIZES` or `KORNIA_CHECK_SHAPE`, or pass the message as `lambda: f"..."`. TorchScript rejects a `lambda`, so a function it compiles formats whole shapes instead, such as `{x.shape}`, which do not specialize. `tests/core/test_check_message_call_sites.py` enforces both and lists the functions TorchScript compiles.- Use `BaseTester` from `testing.base`, injected `device`/`dtype` fixtures, and `self.assert_close()` for tensor comparisons. Its dtype-specific tolerances are intentional.- Follow [TESTING.md](TESTING.md) for test mechanisms. Use `self.gradcheck()` for gradient checks and the injected `torch_optimizer` fixture for `torch.compile` coverage. Include smoke, exception, shape/cardinality, numerical, gradient, and compile tests when they apply; not every change needs every kind.-- Write docstrings in the style of [CONTRIBUTING.md](CONTRIBUTING.md#docstring-style): a unique task-word title line, a contract paragraph that starts from the call, `See Also:` with explanations, and shape literals instead of `:math:`. `tests/test_docstring_style.py` checks See Also, references, shape literals and catalogs for the modules listed in `testing/docstring_rollout.py`; `kornia/geometry/depth.py` is the worked example.+- Write docstrings in the style of [CONTRIBUTING.md](CONTRIBUTING.md#docstring-style): a unique task-word title line, a contract paragraph that starts from the call, `See Also:` with explanations, and shape literals instead of `:math:`. `tests/test_docstring_style.py` checks shape literals in every kornia source file and docs page, and See Also, references and catalogs for the modules listed in `testing/docstring_rollout.py`; `kornia/geometry/depth.py` is the worked example.- Keep numerical correctness tests self-contained. For expected values produced by an optional reference library, prefer a hardcoded literal plus the small generation snippet and source. Optional-dependency integration tests, including ONNX tests, may still use `pytest.importorskip`.- For a new algorithm, name the source that defines it, such as a paper or a reference implementation in PyTorch, OpenCV, or scikit-image.- Do not keep or copy a bug just because the original implementation has it. When a port differs from its reference, decide which behaviour is correct before changing anything: "the reference does it" is not a justification on its own. For example, a non-maxima suppression that keeps positions equal to their window maximum (`>=`), or that re-admits positions once their stronger neighbours are suppressed, is unstable and wrong in principle; kornia keeps strict maxima. When kornia departs from a reference on purpose, say so in the docstring and give the reason.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 24d236afb..51ae883fd 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -211,17 +211,17 @@ A docstring is how a reader, human or agent, decides which function to call, so- Spell targets as Sphinx registers them: a short name for an object documented under the same module, the documented path (`~kornia.geometry.camera.perspective.unproject_points`) for the rest. A shorter import alias renders as plain text, with no warning.- List kornia objects only, with no self-links or private names; mention torch and Python functions in the contract paragraph instead. Link true siblings both ways (v1 and v2, 2D and 3D); reviewers check that, no test does.- **Module docstrings** open with a title line, then the conventions the module's functions share, then "Which function to use", grouped by task, one line each, naming every entry of the `__all__` of the namespace users import from as a role (`` :func:`name` ``) or a literal (``` ``name`` ```). A namespace without `__all__` (`kornia.geometry`, `kornia.geometry.transform`) catalogs its subpackages and main entry points instead; a defining file without `__all__` gets no catalog.-- **Shapes** are literals such as ``` ``(B, 1, H, W)`` ```. Keep `:math:` for formulas.+- **Shapes** are literals such as ``` ``(B, 1, H, W)`` ```. Keep `:math:` for formulas, and for a tuple that is a value, such as a point's `` :math:`(X, Y, Z)` ``; write a value range as an interval, `` :math:`[0, 1]` ``.What `tests/test_docstring_style.py` checks:- every package of `kornia` is assigned to in scope or excluded (global);- each public function and class of a converted module has a `See Also:` whose entries carry an explanation and name a kornia object, with no self-link or private target; an exception needs a non-empty reason;- every Python-domain object role (`:func:`, `:class:`, `:meth:`, `:attr:`, `:data:`, `:const:`, `:exc:`, `:obj:`) in a converted object's docstring resolves as Sphinx resolves it. It must name either an object registered by the `.rst` pages under `docs/source`, or a torch, Python or NumPy object in the cached intersphinx inventories (`docs/source/_intersphinx`). Registered objects include the data attributes autodoc documents: enum members and dataclass fields under `:undoc-members:`, and variables with a `#:` comment or a docstring. An intersphinx object must be of a type the role links to: a function for `:func:`, a method for `:meth:`, an attribute or property for `:attr:`, and nothing for `:const:`. Only `:func:` and `:meth:` drop a trailing `()`. Roles in a catalog module docstring must import;-- no source file of a shape-checked module writes a shape tuple as `:math:`, comments included;+- no `kornia/**/*.py` file or `docs/source` page writes a shape tuple as `:math:`, comments included (global); a tuple that reads as a shape but is a value is listed with what it is in `MATH_NON_SHAPES` (`testing/docstring_rollout.py`), and an entry that no longer occurs fails;- a catalog namespace's module docstring names every export of its `__all__` inside a role or a double-backtick literal, where a qualified name must be a path to that export (`torch.nn.functional.normalize` does not catalog `kornia.enhance.normalize`); the same word in plain prose or in single backticks does not count.-Read the Docs builds with `fail_on_warning: true` (`readthedocs.yml`) and the docs dependencies pinned in `uv.lock`, the same versions as `pixi run build-docs`, so a Sphinx warning fails the docs check. A module joins these checks when it is added to the lists in `testing/docstring_rollout.py`: `DOCSTRING_MODULES` (defining-module prefixes: `See Also:` and references), `CATALOG_NAMESPACES` (namespaces whose `__all__` the module docstring must name) and `SHAPE_CHECK_MODULES` (source-file prefixes, or `None` for all of `kornia/`). An object that needs no `See Also:` goes into `SEE_ALSO_EXCEPTIONS` with a reason. The package inventory is `IN_SCOPE_PACKAGES` and `EXCLUDED_PACKAGES`. The helpers are in `testing/docstring_style.py`; its `sphinx_registry` raises on an autodoc option it does not model, so a docs page that adds one (`:no-index:`, `:exclude-members:`, `:inherited-members:`) needs the registry taught first.+Read the Docs builds with `fail_on_warning: true` (`readthedocs.yml`) and the docs dependencies pinned in `uv.lock`, the same versions as `pixi run build-docs`, so a Sphinx warning fails the docs check. A module joins these checks when it is added to the lists in `testing/docstring_rollout.py`: `DOCSTRING_MODULES` (defining-module prefixes: `See Also:` and references) and `CATALOG_NAMESPACES` (namespaces whose `__all__` the module docstring must name). An object that needs no `See Also:` goes into `SEE_ALSO_EXCEPTIONS` with a reason. The package inventory is `IN_SCOPE_PACKAGES` and `EXCLUDED_PACKAGES`. The helpers are in `testing/docstring_style.py`; its `sphinx_registry` raises on an autodoc option it does not model, so a docs page that adds one (`:no-index:`, `:exclude-members:`, `:inherited-members:`) needs the registry taught first.## Coding Standardsdiff --git a/docs/source/applications/image_augmentations.rst b/docs/source/applications/image_augmentations.rstindex 8fc5f4647..59b94462c 100644--- a/docs/source/applications/image_augmentations.rst+++ b/docs/source/applications/image_augmentations.rst@@ -89,7 +89,7 @@ Video data is a special case of 3D volumetric data that contains both spatial ansometimes referred to as 2.5D rather than 3D. In most applications, augmenting video data requires the sameaugmentation, with the same parameters, to be applied to every frame of a clip.:py:class:`~kornia.augmentation.container.VideoSequential` does exactly that, with the same interface as `nn.Sequential`,-and supports the :math:`(B, C, T, H, W)` and :math:`(B, T, C, H, W)` data formats.+and supports the ``(B, C, T, H, W)`` and ``(B, T, C, H, W)`` data formats... code-block:: pythondiff --git a/docs/source/augmentation.container.rst b/docs/source/augmentation.container.rstindex 424803ded..02b278686 100644--- a/docs/source/augmentation.container.rst+++ b/docs/source/augmentation.container.rst@@ -136,7 +136,7 @@ Video Data AugmentationVideo data is a special case of 3D volumetric data that contains both spatial and temporal information, which issometimes referred to as 2.5D rather than 3D. In most applications, augmenting video data requires the sameaugmentation, with the same parameters, to be applied to every frame of a clip. `VideoSequential` does exactly that,-with the same interface as `nn.Sequential`. It supports the :math:`(B, C, T, H, W)` and :math:`(B, T, C, H, W)`+with the same interface as `nn.Sequential`. It supports the ``(B, C, T, H, W)`` and ``(B, T, C, H, W)``data formats... code-block:: pythondiff --git a/docs/source/color.conversions.rst b/docs/source/color.conversions.rstindex f1ae4138a..2009c010a 100644--- a/docs/source/color.conversions.rst+++ b/docs/source/color.conversions.rst@@ -3,7 +3,7 @@ Color conversion.. currentmodule:: kornia.color-Conversions between color spaces, on float image tensors of shape :math:`(*, C, H, W)`. Most+Conversions between color spaces, on float image tensors of shape ``(*, C, H, W)``. Mostconversions exist as a function and as an ``nn.Module``; each page below documents one color scheme... toctree::diff --git a/docs/source/color.rst b/docs/source/color.rstindex 5222b65a9..268f77f42 100644--- a/docs/source/color.rst+++ b/docs/source/color.rst@@ -12,7 +12,7 @@ Each operation documents its channel order and range.Conventions------------Color tensors are channel-first, :math:`(*, C, H, W)`. Float RGB inputs are unit-range nonlinear sRGB,+Color tensors are channel-first, ``(*, C, H, W)``. Float RGB inputs are unit-range nonlinear sRGB,except that :func:`rgb_to_xyz` takes linear RGB and the ``*rgb255*`` helpers use :math:`[0, 255]`.:func:`rgb_to_linear_rgb` and :func:`linear_rgb_to_rgb` apply the sRGB transfer curve. HLS and HSVhue is measured in radians. The conversion pages define the remaining channel orders and ranges.diff --git a/docs/source/enhance.normalization.rst b/docs/source/enhance.normalization.rstindex 6a169428c..b2af16141 100644--- a/docs/source/enhance.normalization.rst+++ b/docs/source/enhance.normalization.rst@@ -4,7 +4,7 @@ Normalization.. currentmodule:: kornia.enhance:func:`normalize` and :func:`denormalize` treat dimension 0 as batch and dimension 1 as channel;-:func:`normalize_min_max` takes :math:`(*, C, H, W)`. ZCA uses its ``dim`` argument as the sample+:func:`normalize_min_max` takes ``(*, C, H, W)``. ZCA uses its ``dim`` argument as the sampleaxis and flattens all other axes into features.Functionsdiff --git a/docs/source/feature.laf.rst b/docs/source/feature.laf.rstindex 8b385f190..ea64d2266 100644--- a/docs/source/feature.laf.rst+++ b/docs/source/feature.laf.rst@@ -3,7 +3,7 @@ Local affine frames (LAF).. currentmodule:: kornia.feature-A local affine frame is a :math:`(B, N, 2, 3)` tensor describing, for each keypoint, an affine transformation+A local affine frame is a ``(B, N, 2, 3)`` tensor describing, for each keypoint, an affine transformationfrom a canonical patch to the image. Most detectors and descriptors in :mod:`kornia.feature` exchange LAFs.Functionsdiff --git a/docs/source/geometry.bbox.rst b/docs/source/geometry.bbox.rstindex 88f6b8937..b0a1340a0 100644--- a/docs/source/geometry.bbox.rst+++ b/docs/source/geometry.bbox.rst@@ -4,7 +4,7 @@ kornia.geometry.bbox.. meta:::description: The kornia.geometry.bbox module in Kornia provides useful functions for manipulating 2D and 3D bounding boxes. It includes tools for creating, transforming, and operating on bounding boxes, making it easier to handle spatial data in computer vision tasks.-Functional API for 2D and 3D bounding boxes represented as corner tensors of shape :math:`(B, 4, 2)` and :math:`(B, 8, 3)`.+Functional API for 2D and 3D bounding boxes represented as corner tensors of shape ``(B, 4, 2)`` and ``(B, 8, 3)``.For an object-oriented interface with format conversions, see :doc:`geometry.boxes`... automodule:: kornia.geometry.bboxdiff --git a/kornia/augmentation/_2d/geometric/affine.py b/kornia/augmentation/_2d/geometric/affine.pyindex a7af5010b..b0cb2a7f7 100644--- a/kornia/augmentation/_2d/geometric/affine.py+++ b/kornia/augmentation/_2d/geometric/affine.py@@ -66,8 +66,8 @@ class RandomAffine(GeometricAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast it to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.diff --git a/kornia/augmentation/_2d/geometric/center_crop.py b/kornia/augmentation/_2d/geometric/center_crop.pyindex f06c5af01..399c38a4c 100644--- a/kornia/augmentation/_2d/geometric/center_crop.py+++ b/kornia/augmentation/_2d/geometric/center_crop.py@@ -47,7 +47,7 @@ class CenterCrop(GeometricAugmentationBase2D):differentiability.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``- Output: :math:`(B, C, out_h, out_w)`.. note::diff --git a/kornia/augmentation/_2d/geometric/crop.py b/kornia/augmentation/_2d/geometric/crop.pyindex a762e79ba..dc6b1352b 100644--- a/kornia/augmentation/_2d/geometric/crop.py+++ b/kornia/augmentation/_2d/geometric/crop.py@@ -85,12 +85,12 @@ class RandomCrop(GeometricAugmentationBase2D):differentiability.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``- Output: :math:`(B, C, out_h, out_w)`Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.- Additionally, this function accepts another transformation torch.Tensor (:math:`(B, 3, 3)`), then the+ Additionally, this function accepts another transformation torch.Tensor (``(B, 3, 3)``), then theapplied transformation will be merged int to the input transformation torch.Tensor and returned.Convention:diff --git a/kornia/augmentation/_2d/geometric/horizontal_flip.py b/kornia/augmentation/_2d/geometric/horizontal_flip.pyindex 272c9e24b..849a65f20 100644--- a/kornia/augmentation/_2d/geometric/horizontal_flip.py+++ b/kornia/augmentation/_2d/geometric/horizontal_flip.py@@ -32,7 +32,7 @@ class RandomHorizontalFlip(GeometricAugmentationBase2D):.. image:: _static/img/RandomHorizontalFlip.png- Input should be a torch.Tensor of shape (C, H, W) or a batch of tensors :math:`(B, C, H, W)`.+ Input should be a torch.Tensor of shape (C, H, W) or a batch of tensors ``(B, C, H, W)``.If Input is a tuple it is assumed that the first element contains the aforementioned tensors and the second,the corresponding transformation matrix that has been applied to them. In this case the modulewill Horizontally flip the tensors and torch.cat the corresponding transformation matrix to the@@ -45,8 +45,8 @@ class RandomHorizontalFlip(GeometricAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:A selected flip maps ``(x, y)`` to ``(W - 1 - x, y)`` with the exact discretediff --git a/kornia/augmentation/_2d/geometric/pad.py b/kornia/augmentation/_2d/geometric/pad.pyindex b8b4a8f9e..f6fabaa0e 100644--- a/kornia/augmentation/_2d/geometric/pad.py+++ b/kornia/augmentation/_2d/geometric/pad.py@@ -41,8 +41,8 @@ class PadTo(GeometricAugmentationBase2D):shape depends on the input.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``.. note::This function internally uses :func:`torch.nn.functional.pad`.diff --git a/kornia/augmentation/_2d/geometric/perspective.py b/kornia/augmentation/_2d/geometric/perspective.pyindex 3a1a3d4e8..e8cc5f0db 100644--- a/kornia/augmentation/_2d/geometric/perspective.py+++ b/kornia/augmentation/_2d/geometric/perspective.py@@ -45,8 +45,8 @@ class RandomPerspective(GeometricAugmentationBase2D):Preserves area on average. See https://arxiv.org/abs/2104.03308 for further details.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.diff --git a/kornia/augmentation/_2d/geometric/resized_crop.py b/kornia/augmentation/_2d/geometric/resized_crop.pyindex b74e882c1..9c9ce0811 100644--- a/kornia/augmentation/_2d/geometric/resized_crop.py+++ b/kornia/augmentation/_2d/geometric/resized_crop.py@@ -67,12 +67,12 @@ class RandomResizedCrop(GeometricAugmentationBase2D):differentiability.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``- Output: :math:`(B, C, out_h, out_w)`Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.- Additionally, this function accepts another transformation torch.Tensor (:math:`(B, 3, 3)`), then the+ Additionally, this function accepts another transformation torch.Tensor (``(B, 3, 3)``), then theapplied transformation will be merged int to the input transformation torch.Tensor and returned.Convention:diff --git a/kornia/augmentation/_2d/geometric/rotation.py b/kornia/augmentation/_2d/geometric/rotation.pyindex 78c0b6628..22a947fa6 100644--- a/kornia/augmentation/_2d/geometric/rotation.py+++ b/kornia/augmentation/_2d/geometric/rotation.py@@ -49,8 +49,8 @@ class RandomRotation(GeometricAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.@@ -163,8 +163,8 @@ class RandomRotation90(GeometricAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.diff --git a/kornia/augmentation/_2d/geometric/shear.py b/kornia/augmentation/_2d/geometric/shear.pyindex 75ba6f27f..5de60c570 100644--- a/kornia/augmentation/_2d/geometric/shear.py+++ b/kornia/augmentation/_2d/geometric/shear.py@@ -53,8 +53,8 @@ class RandomShear(GeometricAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast it to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.diff --git a/kornia/augmentation/_2d/geometric/translate.py b/kornia/augmentation/_2d/geometric/translate.pyindex ba1762b37..a4e8a7aa4 100644--- a/kornia/augmentation/_2d/geometric/translate.py+++ b/kornia/augmentation/_2d/geometric/translate.py@@ -49,8 +49,8 @@ class RandomTranslate(GeometricAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast it to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- See :class:`~kornia.augmentation.GeometricAugmentationBase2D` for coordinates, defaults and inverse.diff --git a/kornia/augmentation/_2d/geometric/vertical_flip.py b/kornia/augmentation/_2d/geometric/vertical_flip.pyindex 4d4d4e8b2..a4bda18d1 100644--- a/kornia/augmentation/_2d/geometric/vertical_flip.py+++ b/kornia/augmentation/_2d/geometric/vertical_flip.py@@ -38,8 +38,8 @@ class RandomVerticalFlip(GeometricAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:A selected flip maps ``(x, y)`` to ``(x, H - 1 - y)`` with the exact discretediff --git a/kornia/augmentation/_2d/intensity/auto_contrast.py b/kornia/augmentation/_2d/intensity/auto_contrast.pyindex 1dfbc0e5c..9b09e91c1 100644--- a/kornia/augmentation/_2d/intensity/auto_contrast.py+++ b/kornia/augmentation/_2d/intensity/auto_contrast.py@@ -51,8 +51,8 @@ class RandomAutoContrast(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/brightness.py b/kornia/augmentation/_2d/intensity/brightness.pyindex c76e57812..4e59ae0db 100644--- a/kornia/augmentation/_2d/intensity/brightness.py+++ b/kornia/augmentation/_2d/intensity/brightness.py@@ -45,8 +45,8 @@ class RandomBrightness(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- with ``clip_output=True``, input values are clamped into ``[0, 1]`` before the operationdiff --git a/kornia/augmentation/_2d/intensity/channel_dropout.py b/kornia/augmentation/_2d/intensity/channel_dropout.pyindex 9ffb24d02..0dacd5581 100644--- a/kornia/augmentation/_2d/intensity/channel_dropout.py+++ b/kornia/augmentation/_2d/intensity/channel_dropout.py@@ -41,8 +41,8 @@ class RandomChannelDropout(IntensityAugmentationBase2D):to the batch form ``False``. Defaults to False.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(C, H, W)` or :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(C, H, W)`` or ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/color_jiggle.py b/kornia/augmentation/_2d/intensity/color_jiggle.pyindex f18694827..9b54489a5 100644--- a/kornia/augmentation/_2d/intensity/color_jiggle.py+++ b/kornia/augmentation/_2d/intensity/color_jiggle.py@@ -141,8 +141,8 @@ class ColorJiggle(IntensityAugmentationBase2D):The parameter generator still draws an ``order`` entry into ``_params``, and with a fixed order thatentry is ignored, including on replay.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/color_jitter.py b/kornia/augmentation/_2d/intensity/color_jitter.pyindex 0e9949eae..15729b573 100644--- a/kornia/augmentation/_2d/intensity/color_jitter.py+++ b/kornia/augmentation/_2d/intensity/color_jitter.py@@ -89,8 +89,8 @@ class ColorJitter(_PicklableCompileMixin, IntensityAugmentationBase2D):The parameter generator still draws an ``order`` entry into ``_params``, and with a fixed order thatentry is ignored, including on replay.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/contrast.py b/kornia/augmentation/_2d/intensity/contrast.pyindex 55d1010b0..3afa3e39a 100644--- a/kornia/augmentation/_2d/intensity/contrast.py+++ b/kornia/augmentation/_2d/intensity/contrast.py@@ -45,8 +45,8 @@ class RandomContrast(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- with ``clip_output=True``, input values are clamped into ``[0, 1]`` before the operationdiff --git a/kornia/augmentation/_2d/intensity/denormalize.py b/kornia/augmentation/_2d/intensity/denormalize.pyindex 140a95a3b..5267a2cc8 100644--- a/kornia/augmentation/_2d/intensity/denormalize.py+++ b/kornia/augmentation/_2d/intensity/denormalize.py@@ -32,7 +32,7 @@ class Denormalize(IntensityAugmentationBase2D):.. math::\text{input[channel] = (input[channel] * std[channel]) + mean[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:mean: Mean for each channel.@@ -42,7 +42,7 @@ class Denormalize(IntensityAugmentationBase2D):to the batch form (False).Return:- Denormalised tensor with same size as input :math:`(*, C, H, W)`.+ Denormalised tensor with same size as input ``(*, C, H, W)``.Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/dissolving.py b/kornia/augmentation/_2d/intensity/dissolving.pyindex 3ee5a3ad2..70d43cedd 100644--- a/kornia/augmentation/_2d/intensity/dissolving.py+++ b/kornia/augmentation/_2d/intensity/dissolving.py@@ -56,8 +56,8 @@ class RandomDissolving(IntensityAugmentationBase2D):**kwargs: additional arguments for `.from_pretrained` for HF StableDiffusionPipeline.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`.- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``.+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/equalize.py b/kornia/augmentation/_2d/intensity/equalize.pyindex b4e12a7bb..156174a2f 100644--- a/kornia/augmentation/_2d/intensity/equalize.py+++ b/kornia/augmentation/_2d/intensity/equalize.py@@ -37,8 +37,8 @@ class RandomEqualize(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/erasing.py b/kornia/augmentation/_2d/intensity/erasing.pyindex e8f40ca0f..313a09779 100644--- a/kornia/augmentation/_2d/intensity/erasing.py+++ b/kornia/augmentation/_2d/intensity/erasing.py@@ -48,8 +48,8 @@ class RandomErasing(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.@@ -71,7 +71,7 @@ class RandomErasing(IntensityAugmentationBase2D):in the same rectangle, but the mask is filled with ``0`` whatever ``value`` is.Note:- This function accepts another transformation torch.Tensor (:math:`(B, 3, 3)`), then the+ This function accepts another transformation torch.Tensor (``(B, 3, 3)``), then theapplied transformation will be merged int to the input transformation torch.Tensor and returned.Examples:diff --git a/kornia/augmentation/_2d/intensity/gamma.py b/kornia/augmentation/_2d/intensity/gamma.pyindex 93a8e843f..5bf503e16 100644--- a/kornia/augmentation/_2d/intensity/gamma.py+++ b/kornia/augmentation/_2d/intensity/gamma.py@@ -42,8 +42,8 @@ class RandomGamma(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/gaussian_blur.py b/kornia/augmentation/_2d/intensity/gaussian_blur.pyindex c0ebc43cf..725435fef 100644--- a/kornia/augmentation/_2d/intensity/gaussian_blur.py+++ b/kornia/augmentation/_2d/intensity/gaussian_blur.py@@ -54,8 +54,8 @@ class RandomGaussianBlur(_PicklableCompileMixin, IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/gaussian_illumination.py b/kornia/augmentation/_2d/intensity/gaussian_illumination.pyindex a397ef0f9..f2a9c8f2c 100644--- a/kornia/augmentation/_2d/intensity/gaussian_illumination.py+++ b/kornia/augmentation/_2d/intensity/gaussian_illumination.py@@ -68,8 +68,8 @@ class RandomGaussianIllumination(_PicklableCompileMixin, IntensityAugmentationBato the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/grayscale.py b/kornia/augmentation/_2d/intensity/grayscale.pyindex 1693ac4d0..efd0b0b09 100644--- a/kornia/augmentation/_2d/intensity/grayscale.py+++ b/kornia/augmentation/_2d/intensity/grayscale.py@@ -48,8 +48,8 @@ class RandomGrayscale(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/hue.py b/kornia/augmentation/_2d/intensity/hue.pyindex 5e6ee92a3..a92ab1a8c 100644--- a/kornia/augmentation/_2d/intensity/hue.py+++ b/kornia/augmentation/_2d/intensity/hue.py@@ -46,8 +46,8 @@ class RandomHue(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/jpeg.py b/kornia/augmentation/_2d/intensity/jpeg.pyindex 203af47b2..b838c8414 100644--- a/kornia/augmentation/_2d/intensity/jpeg.py+++ b/kornia/augmentation/_2d/intensity/jpeg.py@@ -46,8 +46,8 @@ class RandomJPEG(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``.. note::This function internally uses :func:`kornia.enhance.jpeg_codec_differentiable`.diff --git a/kornia/augmentation/_2d/intensity/linear_illumination.py b/kornia/augmentation/_2d/intensity/linear_illumination.pyindex 228f8400d..43900ed53 100644--- a/kornia/augmentation/_2d/intensity/linear_illumination.py+++ b/kornia/augmentation/_2d/intensity/linear_illumination.py@@ -42,8 +42,8 @@ class RandomLinearIllumination(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clamped@@ -162,8 +162,8 @@ class RandomLinearCornerIllumination(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/motion_blur.py b/kornia/augmentation/_2d/intensity/motion_blur.pyindex ac7d54c4d..6412ac76a 100644--- a/kornia/augmentation/_2d/intensity/motion_blur.py+++ b/kornia/augmentation/_2d/intensity/motion_blur.py@@ -55,8 +55,8 @@ class RandomMotionBlur(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.@@ -86,7 +86,7 @@ class RandomMotionBlur(IntensityAugmentationBase2D)::class:`RandomGaussianBlur` do.Note:- This function accepts another transformation torch.Tensor (:math:`(B, 3, 3)`), then the+ This function accepts another transformation torch.Tensor (``(B, 3, 3)``), then theapplied transformation will be merged int to the input transformation torch.Tensor and returned.Please set ``resample`` to ``'bilinear'`` if more meaningful gradients wanted.diff --git a/kornia/augmentation/_2d/intensity/normalize.py b/kornia/augmentation/_2d/intensity/normalize.pyindex 6563bb638..a8de1ee7b 100644--- a/kornia/augmentation/_2d/intensity/normalize.py+++ b/kornia/augmentation/_2d/intensity/normalize.py@@ -34,7 +34,7 @@ class Normalize(IntensityAugmentationBase2D):.. math::\text{input[channel] = (input[channel] - mean[channel]) / std[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:mean: Mean for each channel.@@ -44,7 +44,7 @@ class Normalize(IntensityAugmentationBase2D):to the batch form (False).Return:- Normalised tensor with same size as input :math:`(*, C, H, W)`.+ Normalised tensor with same size as input ``(*, C, H, W)``.Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/planckian_jitter.py b/kornia/augmentation/_2d/intensity/planckian_jitter.pyindex b37733447..b01563f0e 100644--- a/kornia/augmentation/_2d/intensity/planckian_jitter.py+++ b/kornia/augmentation/_2d/intensity/planckian_jitter.py@@ -115,8 +115,8 @@ class RandomPlanckianJitter(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/posterize.py b/kornia/augmentation/_2d/intensity/posterize.pyindex d54c0d9b5..7656eb46c 100644--- a/kornia/augmentation/_2d/intensity/posterize.py+++ b/kornia/augmentation/_2d/intensity/posterize.py@@ -45,8 +45,8 @@ class RandomPosterize(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/random_rain.py b/kornia/augmentation/_2d/intensity/random_rain.pyindex 92ab7a8a5..4ab57043b 100644--- a/kornia/augmentation/_2d/intensity/random_rain.py+++ b/kornia/augmentation/_2d/intensity/random_rain.py@@ -40,8 +40,8 @@ class RandomRain(IntensityAugmentationBase2D):drop_width: Width of the drop in the image (same for each drop in one image). The absolute sampled valuemust be strictly smaller than the input image width.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/random_snow.py b/kornia/augmentation/_2d/intensity/random_snow.pyindex 0b4913138..2143edbf7 100644--- a/kornia/augmentation/_2d/intensity/random_snow.py+++ b/kornia/augmentation/_2d/intensity/random_snow.py@@ -41,8 +41,8 @@ class RandomSnow(IntensityAugmentationBase2D):keepdim: Keep the output torch.Tensor with the same shape as input. Default: False.Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py b/kornia/augmentation/_2d/intensity/salt_pepper_noise.pyindex 076b4fb68..cc03a3b7c 100644--- a/kornia/augmentation/_2d/intensity/salt_pepper_noise.py+++ b/kornia/augmentation/_2d/intensity/salt_pepper_noise.py@@ -41,8 +41,8 @@ class RandomSaltAndPepperNoise(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Convention:- this operation is range-independent: it does not clamp the input into ``[0, 1]``.diff --git a/kornia/augmentation/_2d/intensity/saturation.py b/kornia/augmentation/_2d/intensity/saturation.pyindex 8ae120009..26a475863 100644--- a/kornia/augmentation/_2d/intensity/saturation.py+++ b/kornia/augmentation/_2d/intensity/saturation.py@@ -44,8 +44,8 @@ class RandomSaturation(IntensityAugmentationBase2D):keepdim: whether to keep the output shape the same as input (True) or broadcast itto the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/sharpness.py b/kornia/augmentation/_2d/intensity/sharpness.pyindex 2ec445686..f07c51430 100644--- a/kornia/augmentation/_2d/intensity/sharpness.py+++ b/kornia/augmentation/_2d/intensity/sharpness.py@@ -45,8 +45,8 @@ class RandomSharpness(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/intensity/solarize.py b/kornia/augmentation/_2d/intensity/solarize.pyindex 688f0a79b..add8cd774 100644--- a/kornia/augmentation/_2d/intensity/solarize.py+++ b/kornia/augmentation/_2d/intensity/solarize.py@@ -44,8 +44,8 @@ class RandomSolarize(IntensityAugmentationBase2D):to the batch form (False).Shape:- - Input: :math:`(C, H, W)` or :math:`(B, C, H, W)`, Optional: :math:`(B, 3, 3)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(C, H, W)`` or ``(B, C, H, W)``, Optional: ``(B, 3, 3)``+ - Output: ``(B, C, H, W)``Convention:- input values are clamped into ``[0, 1]`` before the operation, and the result is clampeddiff --git a/kornia/augmentation/_2d/mix/cutmix.py b/kornia/augmentation/_2d/mix/cutmix.pyindex 935c11283..da7bd1673 100644--- a/kornia/augmentation/_2d/mix/cutmix.py+++ b/kornia/augmentation/_2d/mix/cutmix.py@@ -64,12 +64,12 @@ class RandomCutMixV2(MixAugmentationBaseV2):but will raise a deprecation warning when False.Inputs:- - Input image tensors, shape of :math:`(B, C, H, W)`.- - Raw labels, shape of :math:`(B)`.+ - Input image tensors, shape of ``(B, C, H, W)``.+ - Raw labels, shape of ``(B)``.Returns:Tuple[torch.Tensor, torch.Tensor]:- - Adjusted image, shape of :math:`(B, C, H, W)`.+ - Adjusted image, shape of ``(B, C, H, W)``.- Raw labels, permuted labels and lambdas for each mix, shape of :math:`(num_mix, B, 3)`.Convention:diff --git a/kornia/augmentation/_2d/mix/mixup.py b/kornia/augmentation/_2d/mix/mixup.pyindex 2e0c6a9d9..0f4fdc103 100644--- a/kornia/augmentation/_2d/mix/mixup.py+++ b/kornia/augmentation/_2d/mix/mixup.py@@ -33,7 +33,7 @@ class RandomMixUpV2(MixAugmentationBaseV2):Implementation for `mixup: BEYOND EMPIRICAL RISK MINIMIZATION` :cite:`zhang2018mixup`.The function returns (inputs, labels), in which the inputs is the torch.Tensor that contains the mixup images- while the labels is a :math:`(B, 3)` torch.Tensor that contains (label_batch, label_permuted_batch, lambda) for+ while the labels is a ``(B, 3)`` torch.Tensor that contains (label_batch, label_permuted_batch, lambda) foreach image.The implementation is on top of the following repository:@@ -68,13 +68,13 @@ class RandomMixUpV2(MixAugmentationBaseV2):to the batch form (False).Inputs:- - Input image tensors, shape of :math:`(B, C, H, W)`.- - Label: raw labels, shape of :math:`(B)`.+ - Input image tensors, shape of ``(B, C, H, W)``.+ - Label: raw labels, shape of ``(B)``.Returns:Tuple[torch.Tensor, torch.Tensor]:- - Adjusted image, shape of :math:`(B, C, H, W)`.- - Raw labels, permuted labels and lambdas for each mix, shape of :math:`(B, 3)`.+ - Adjusted image, shape of ``(B, C, H, W)``.+ - Raw labels, permuted labels and lambdas for each mix, shape of ``(B, 3)``.Convention:- With ``data_keys=["input", "class"]``, the class output is ``(B, 3)``: its columns are the originaldiff --git a/kornia/augmentation/_2d/mix/transplantation.py b/kornia/augmentation/_2d/mix/transplantation.pyindex a77098ec7..ecfe09136 100644--- a/kornia/augmentation/_2d/mix/transplantation.py+++ b/kornia/augmentation/_2d/mix/transplantation.py@@ -71,18 +71,18 @@ class RandomTransplantation(MixAugmentationBaseV2)::class:`kornia.augmentation.RandomTransplantation3D` for 3D images.Inputs:- - Segmentation mask torch.Tensor which is used to determine the objects for transplantation: :math:`(B, *)`.+ - Segmentation mask torch.Tensor which is used to determine the objects for transplantation: ``(B, *)``.- (optional) Additional image or mask tensors where the features are transplanted based on the first- segmentation mask: :math:`(B, C, *)` (`DataKey.INPUT`) or :math:`(B, *)` (`DataKey.MASK`).+ segmentation mask: ``(B, C, *)`` (`DataKey.INPUT`) or ``(B, *)`` (`DataKey.MASK`).Returns:torch.Tensor | list[torch.Tensor]:torch.Tensor:- - Augmented mask tensors: :math:`(B, *)`.+ - Augmented mask tensors: ``(B, *)``.list[torch.Tensor]:- - Augmented mask tensors: :math:`(B, *)`.- - Additional augmented image or mask tensors: :math:`(B, C, *)` (`DataKey.INPUT`) or :math:`(B, *)`+ - Augmented mask tensors: ``(B, *)``.+ - Additional augmented image or mask tensors: ``(B, C, *)`` (`DataKey.INPUT`) or ``(B, *)``(`DataKey.MASK`).Convention:diff --git a/kornia/augmentation/_3d/geometric/affine.py b/kornia/augmentation/_3d/geometric/affine.pyindex 25e05901c..53ee878e7 100644--- a/kornia/augmentation/_3d/geometric/affine.py+++ b/kornia/augmentation/_3d/geometric/affine.py@@ -68,8 +68,8 @@ class RandomAffine3D(GeometricAugmentationBase3D):to the batch form (False). Default: False.Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/geometric/center_crop.py b/kornia/augmentation/_3d/geometric/center_crop.pyindex 966d2bdbe..2f0c47fb8 100644--- a/kornia/augmentation/_3d/geometric/center_crop.py+++ b/kornia/augmentation/_3d/geometric/center_crop.py@@ -41,7 +41,7 @@ class CenterCrop3D(GeometricAugmentationBase3D):to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``- Output: :math:`(B, C, out_d, out_h, out_w)`Note:diff --git a/kornia/augmentation/_3d/geometric/crop.py b/kornia/augmentation/_3d/geometric/crop.pyindex 232fe065d..a20fdeb4d 100644--- a/kornia/augmentation/_3d/geometric/crop.py+++ b/kornia/augmentation/_3d/geometric/crop.py@@ -71,7 +71,7 @@ class RandomCrop3D(GeometricAugmentationBase3D):to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``- Output: :math:`(B, C, out_d, out_h, out_w)`Note:diff --git a/kornia/augmentation/_3d/geometric/depthical_flip.py b/kornia/augmentation/_3d/geometric/depthical_flip.pyindex 2a9aa0c80..906d44928 100644--- a/kornia/augmentation/_3d/geometric/depthical_flip.py+++ b/kornia/augmentation/_3d/geometric/depthical_flip.py@@ -27,7 +27,7 @@ from kornia.core.ops import _device_literalclass RandomDepthicalFlip3D(GeometricAugmentationBase3D):r"""Flip 3D volumes along the depth axis, applied per sample with probability ``p`` (default 0.5).- Input should be a tensor of shape :math:`(C, D, H, W)` or a batch of tensors :math:`(*, C, D, H, W)`.+ Input should be a tensor of shape ``(C, D, H, W)`` or a batch of tensors ``(*, C, D, H, W)``.Args:p: probability of applying the transformation to each sample.@@ -36,8 +36,8 @@ class RandomDepthicalFlip3D(GeometricAugmentationBase3D):to the batch form ``False``.Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/geometric/horizontal_flip.py b/kornia/augmentation/_3d/geometric/horizontal_flip.pyindex 05b6a87be..9c32b983d 100644--- a/kornia/augmentation/_3d/geometric/horizontal_flip.py+++ b/kornia/augmentation/_3d/geometric/horizontal_flip.py@@ -34,8 +34,8 @@ class RandomHorizontalFlip3D(GeometricAugmentationBase3D):to the batch form ``False``.Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/geometric/perspective.py b/kornia/augmentation/_3d/geometric/perspective.pyindex 452c545ed..9de342255 100644--- a/kornia/augmentation/_3d/geometric/perspective.py+++ b/kornia/augmentation/_3d/geometric/perspective.py@@ -40,8 +40,8 @@ class RandomPerspective3D(GeometricAugmentationBase3D):to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/geometric/rotation.py b/kornia/augmentation/_3d/geometric/rotation.pyindex b69e26506..527fefc12 100644--- a/kornia/augmentation/_3d/geometric/rotation.py+++ b/kornia/augmentation/_3d/geometric/rotation.py@@ -31,7 +31,7 @@ from kornia.geometry.transform.affwarp import _compute_rotation_matrix3d, _compuclass RandomRotation3D(GeometricAugmentationBase3D):r"""Rotate 3D volumes by a random axis-angle rotation, applied per sample with probability ``p`` (default 0.5).- Input should be a torch.Tensor of shape (C, D, H, W) or a batch of tensors :math:`(B, C, D, H, W)`.+ Input should be a torch.Tensor of shape (C, D, H, W) or a batch of tensors ``(B, C, D, H, W)``.Args:degrees: Range of degrees to select from.@@ -50,8 +50,8 @@ class RandomRotation3D(GeometricAugmentationBase3D):to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/geometric/vertical_flip.py b/kornia/augmentation/_3d/geometric/vertical_flip.pyindex 9ecfe9d6f..736a1eb01 100644--- a/kornia/augmentation/_3d/geometric/vertical_flip.py+++ b/kornia/augmentation/_3d/geometric/vertical_flip.py@@ -27,7 +27,7 @@ from kornia.core.ops import _device_literalclass RandomVerticalFlip3D(GeometricAugmentationBase3D):r"""Flip 3D volumes vertically, applied per sample with probability ``p`` (default 0.5).- Input should be a tensor of shape :math:`(C, D, H, W)` or a batch of tensors :math:`(*, C, D, H, W)`.+ Input should be a tensor of shape ``(C, D, H, W)`` or a batch of tensors ``(*, C, D, H, W)``.Args:p: probability of applying the transformation to each sample.@@ -36,8 +36,8 @@ class RandomVerticalFlip3D(GeometricAugmentationBase3D):to the batch form ``False``.Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/_3d/intensity/equalize.py b/kornia/augmentation/_3d/intensity/equalize.pyindex cdc1cb46e..68f67f684 100644--- a/kornia/augmentation/_3d/intensity/equalize.py+++ b/kornia/augmentation/_3d/intensity/equalize.py@@ -33,8 +33,8 @@ class RandomEqualize3D(IntensityAugmentationBase3D):to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input tensor must be float and normalized into [0, 1].diff --git a/kornia/augmentation/_3d/intensity/motion_blur.py b/kornia/augmentation/_3d/intensity/motion_blur.pyindex abed0a29e..2f79f8283 100644--- a/kornia/augmentation/_3d/intensity/motion_blur.py+++ b/kornia/augmentation/_3d/intensity/motion_blur.py@@ -54,8 +54,8 @@ class RandomMotionBlur3D(IntensityAugmentationBase3D):keepdim: whether to keep the output shape the same as input (True) or broadcast it to the batch form (False).Shape:- - Input: :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(C, D, H, W)`` or ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Note:Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support.diff --git a/kornia/augmentation/container/video.py b/kornia/augmentation/container/video.pyindex 296e6904f..b14adf1e9 100644--- a/kornia/augmentation/container/video.py+++ b/kornia/augmentation/container/video.py@@ -454,8 +454,8 @@ class VideoSequential(ImageSequential):"""Transform bounding boxes.Args:- input: torch.Tensor with shape :math:`(B, T, N, 4, 2)`.- If input is a `Keypoints` type, the internal shape is :math:`(B * T, N, 4, 2)`.+ input: torch.Tensor with shape ``(B, T, N, 4, 2)``.+ If input is a `Keypoints` type, the internal shape is ``(B * T, N, 4, 2)``.params: params for the sequence.extra_args: Optional dictionary of extra arguments with specific options for different input types."""@@ -479,8 +479,8 @@ class VideoSequential(ImageSequential):"""Transform bounding boxes.Args:- input: torch.Tensor with shape :math:`(B, T, N, 4, 2)`.- If input is a `Keypoints` type, the internal shape is :math:`(B * T, N, 4, 2)`.+ input: torch.Tensor with shape ``(B, T, N, 4, 2)``.+ If input is a `Keypoints` type, the internal shape is ``(B * T, N, 4, 2)``.params: params for the sequence.extra_args: Optional dictionary of extra arguments with specific options for different input types."""@@ -507,8 +507,8 @@ class VideoSequential(ImageSequential):"""Transform bounding boxes.Args:- input: torch.Tensor with shape :math:`(B, T, N, 2)`.- If input is a `Keypoints` type, the internal shape is :math:`(B * T, N, 2)`.+ input: torch.Tensor with shape ``(B, T, N, 2)``.+ If input is a `Keypoints` type, the internal shape is ``(B * T, N, 2)``.params: params for the sequence.extra_args: Optional dictionary of extra arguments with specific options for different input types."""@@ -530,8 +530,8 @@ class VideoSequential(ImageSequential):"""Transform bounding boxes.Args:- input: torch.Tensor with shape :math:`(B, T, N, 2)`.- If input is a `Keypoints` type, the internal shape is :math:`(B * T, N, 2)`.+ input: torch.Tensor with shape ``(B, T, N, 2)``.+ If input is a `Keypoints` type, the internal shape is ``(B * T, N, 2)``.params: params for the sequence.extra_args: Optional dictionary of extra arguments with specific options for different input types."""diff --git a/kornia/color/gray.py b/kornia/color/gray.pyindex 503a271d7..bf37f4445 100644--- a/kornia/color/gray.py+++ b/kornia/color/gray.py@@ -39,10 +39,10 @@ def grayscale_to_rgb(image: torch.Tensor) -> torch.Tensor:The singleton channel at axis -3 is repeated into R, G and B. Leading dimensions are preserved.Args:- image: grayscale image torch.Tensor to be converted to RGB with shape :math:`(*,1,H,W)`.+ image: grayscale image torch.Tensor to be converted to RGB with shape ``(*,1,H,W)``.Returns:- RGB version of the image with shape :math:`(*,3,H,W)`.+ RGB version of the image with shape ``(*,3,H,W)``.Example:>>> input = torch.randn(2, 1, 4, 5)@@ -76,12 +76,12 @@ def rgb_to_grayscale(image: torch.Tensor, rgb_weights: Optional[torch.Tensor] =exactly, bit for bit as ``cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)`` does.Args:- image: RGB image to be converted to grayscale with shape :math:`(*,3,H,W)`.+ image: RGB image to be converted to grayscale with shape ``(*,3,H,W)``.rgb_weights: Weights that will be applied on each channel (RGB).The sum of the weights should add up to one.Returns:- grayscale version of the image with shape :math:`(*,1,H,W)`.+ grayscale version of the image with shape ``(*,1,H,W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/color_conversions.html>`__.@@ -141,10 +141,10 @@ def bgr_to_grayscale(image: torch.Tensor) -> torch.Tensor:BGR is channel-first at axis -3. This uses the RGB luma weights after reversing channel order.Args:- image: BGR image to be converted to grayscale with shape :math:`(*,3,H,W)`.+ image: BGR image to be converted to grayscale with shape ``(*,3,H,W)``.Returns:- grayscale version of the image with shape :math:`(*,1,H,W)`.+ grayscale version of the image with shape ``(*,1,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -168,8 +168,8 @@ class GrayscaleToRgb(nn.Module):The image data is assumed to be in the range of (0, 1).Shape:- - image: :math:`(*, 1, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 1, H, W)``+ - output: ``(*, 3, H, W)``reference:https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html@@ -188,12 +188,12 @@ class GrayscaleToRgb(nn.Module):"""Convert a grayscale tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 1, H, W)`.+ image: Input tensor with shape ``(*, 1, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``1`` is a single grayscale channel, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return grayscale_to_rgb(image)@@ -206,8 +206,8 @@ class RgbToGrayscale(nn.Module):The image data is assumed to be in the range of (0, 1).Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 1, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 1, H, W)``reference:https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html@@ -233,12 +233,12 @@ class RgbToGrayscale(nn.Module):"""Convert an RGB tensor to grayscale.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Grayscale tensor with shape :math:`(*, 1, H, W)`, computed with the module's RGB weights.+ Grayscale tensor with shape ``(*, 1, H, W)``, computed with the module's RGB weights."""return rgb_to_grayscale(image, rgb_weights=self.rgb_weights)@@ -251,8 +251,8 @@ class BgrToGrayscale(nn.Module):The image data is assumed to be in the range of (0, 1). First flips to RGB, then converts.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 1, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 1, H, W)``reference:https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html@@ -271,11 +271,11 @@ class BgrToGrayscale(nn.Module):"""Convert a BGR tensor to grayscale.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to BGR channels, and ``H``/``W`` are height and width.Returns:- Grayscale tensor with shape :math:`(*, 1, H, W)`.+ Grayscale tensor with shape ``(*, 1, H, W)``."""return bgr_to_grayscale(image)diff --git a/kornia/color/hls.py b/kornia/color/hls.pyindex a3abc2af9..fd4bb6632 100644--- a/kornia/color/hls.py+++ b/kornia/color/hls.py@@ -40,13 +40,13 @@ def rgb_to_hls(image: torch.Tensor, eps: float = 1e-8) -> torch.Tensor:NOTE: this method cannot be compiled with JIT in pytohrch < 1.7.0Args:- image: RGB image to be converted to HLS with shape :math:`(*, 3, H, W)`.+ image: RGB image to be converted to HLS with shape ``(*, 3, H, W)``.eps: bias added to the chroma and lightness denominators before dividing. The zerodenominators themselves are handled by a safe-substitution guard, so ``eps`` is notwhat keeps the result finite and ``eps=0`` is well defined.Returns:- HLS version of the image with shape :math:`(*, 3, H, W)`.+ HLS version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -111,10 +111,10 @@ def hls_to_rgb(image: torch.Tensor) -> torch.Tensor:Expects H, L, S channels at axis -3 with hue in radians.Args:- image: HLS image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: HLS image to be converted to RGB with shape ``(*, 3, H, W)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -161,8 +161,8 @@ class RgbToHls(nn.Module):HLS version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -178,12 +178,12 @@ class RgbToHls(nn.Module):"""Convert an RGB tensor to HLS.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- HLS tensor with shape :math:`(*, 3, H, W)`.+ HLS tensor with shape ``(*, 3, H, W)``."""return rgb_to_hls(image)@@ -199,8 +199,8 @@ class HlsToRgb(nn.Module):RGB version of the image.Shape:- - input: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - input: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Reference:https://en.wikipedia.org/wiki/HSL_and_HSV@@ -219,11 +219,11 @@ class HlsToRgb(nn.Module):"""Convert an HLS tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to HLS channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return hls_to_rgb(image)diff --git a/kornia/color/hsv.py b/kornia/color/hsv.pyindex 2c0c1c30b..dd5836346 100644--- a/kornia/color/hsv.py+++ b/kornia/color/hsv.py@@ -36,11 +36,11 @@ def rgb_to_hsv(image: torch.Tensor, eps: float = 1e-8) -> torch.Tensor:pixels have hue zero. eps biases the saturation denominator.Args:- image: RGB Image to be converted to HSV with shape of :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to HSV with shape of ``(*, 3, H, W)``.eps: scalar to enforce numarical stability.Returns:- HSV version of the image with shape of :math:`(*, 3, H, W)`.+ HSV version of the image with shape of ``(*, 3, H, W)``.The H channel values are in the range [0, 2pi). S and V are in the range 0..1... note::@@ -97,10 +97,10 @@ def hsv_to_rgb(image: torch.Tensor) -> torch.Tensor:Expects H, S, V channels at axis -3 with hue in radians.Args:- image: HSV Image to be converted to HSV with shape of :math:`(*, 3, H, W)`.+ image: HSV Image to be converted to HSV with shape of ``(*, 3, H, W)``.Returns:- RGB version of the image with shape of :math:`(*, 3, H, W)`.+ RGB version of the image with shape of ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -158,8 +158,8 @@ class RgbToHsv(nn.Module):HSV version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -179,12 +179,12 @@ class RgbToHsv(nn.Module):"""Convert an RGB tensor to HSV.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` is the channel dimension, and ``H``/``W`` are height and width.Returns:- HSV tensor with shape :math:`(*, 3, H, W)`.+ HSV tensor with shape ``(*, 3, H, W)``."""return rgb_to_hsv(image, self.eps)@@ -200,8 +200,8 @@ class HsvToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -217,11 +217,11 @@ class HsvToRgb(nn.Module):"""Convert an HSV tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` is the channel dimension, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return hsv_to_rgb(image)diff --git a/kornia/color/lab.py b/kornia/color/lab.pyindex 8744058d9..e90daab58 100644--- a/kornia/color/lab.py+++ b/kornia/color/lab.py@@ -47,10 +47,10 @@ def rgb_to_lab(image: torch.Tensor) -> torch.Tensor:it to linear RGB. Output channels are L*, a*, b* using D65 / 2Β° reference white.Args:- image: RGB Image to be converted to Lab with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to Lab with shape ``(*, 3, H, W)``.Returns:- Lab version of the image with shape :math:`(*, 3, H, W)`.+ Lab version of the image with shape ``(*, 3, H, W)``.The L channel values are in the range 0..100. a and b are in the range -128..127.Example:@@ -114,11 +114,11 @@ def lab_to_rgb(image: torch.Tensor, clip: bool = True) -> torch.Tensor:false to skip the final [0, 1] clamp of the sRGB output.Args:- image: Lab image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: Lab image to be converted to RGB with shape ``(*, 3, H, W)``.clip: Whether to apply clipping to insure output RGB values in range :math:`[0, 1]`.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`, in :math:`[0, 1]` when ``clip`` is True.+ RGB version of the image with shape ``(*, 3, H, W)``, in :math:`[0, 1]` when ``clip`` is True.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -191,8 +191,8 @@ class RgbToLab(nn.Module):Lab version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -215,12 +215,12 @@ class RgbToLab(nn.Module):"""Convert an RGB tensor to Lab.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Lab tensor with shape :math:`(*, 3, H, W)`.+ Lab tensor with shape ``(*, 3, H, W)``."""return rgb_to_lab(image)@@ -234,8 +234,8 @@ class LabToRgb(nn.Module):RGB version of the image, clipped to :math:`[0, 1]` unless ``clip`` is False.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -258,12 +258,12 @@ class LabToRgb(nn.Module):"""Convert a Lab tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to Lab channels, and ``H``/``W`` are height and width.clip: If ``True``, clamp output values to :math:`[0, 1]`.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return lab_to_rgb(image, clip)diff --git a/kornia/color/luv.py b/kornia/color/luv.pyindex 96c0843b2..a57f9166b 100644--- a/kornia/color/luv.py+++ b/kornia/color/luv.py@@ -47,12 +47,12 @@ def rgb_to_luv(image: torch.Tensor, eps: float = 1e-12) -> torch.Tensor:reference white.Args:- image: RGB Image to be converted to Luv with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to Luv with shape ``(*, 3, H, W)``.eps: For numerical stability when dividing. Half inputs use float32 arithmetic, so the defaultepsilon remains representable without a dtype-dependent floor.Returns:- Luv version of the image with shape :math:`(*, 3, H, W)`.+ Luv version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -115,12 +115,12 @@ def luv_to_rgb(image: torch.Tensor, eps: float = 1e-12) -> torch.Tensor:is nonlinear sRGB.Args:- image: Luv image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: Luv image to be converted to RGB with shape ``(*, 3, H, W)``.eps: For numerical stability when dividing. Half inputs use float32 arithmetic, so the defaultepsilon remains representable without a dtype-dependent floor.Returns:- Luv version of the image with shape :math:`(*, 3, H, W)`.+ Luv version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -183,8 +183,8 @@ class RgbToLuv(nn.Module):Luv version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -207,12 +207,12 @@ class RgbToLuv(nn.Module):"""Convert an RGB tensor to Luv.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Luv tensor with shape :math:`(*, 3, H, W)`.+ Luv tensor with shape ``(*, 3, H, W)``."""return rgb_to_luv(image)@@ -226,8 +226,8 @@ class LuvToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -250,11 +250,11 @@ class LuvToRgb(nn.Module):"""Convert a Luv tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to Luv channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return luv_to_rgb(image)diff --git a/kornia/color/raw.py b/kornia/color/raw.pyindex 5ef8e5497..4c2e26b3e 100644--- a/kornia/color/raw.py+++ b/kornia/color/raw.py@@ -65,11 +65,11 @@ def raw_to_rgb(image: torch.Tensor, cfa: CFA) -> torch.Tensor:cell is RGGB, GRBG, BGGR and GBRG. Height and width must be even.Args:- image: raw image to be converted to RGB with shape :math:`(*,1,H,W)`.+ image: raw image to be converted to RGB with shape ``(*,1,H,W)``.cfa: The configuration of the color filter.Returns:- RGB version of the image with shape :math:`(*,3,H,W)`.+ RGB version of the image with shape ``(*,3,H,W)``.Example:>>> rawinput = torch.randn(2, 1, 4, 6)@@ -204,11 +204,11 @@ def rgb_to_raw(image: torch.Tensor, cfa: CFA) -> torch.Tensor:raw_to_rgb. The inverse conversion requires even height and width.Args:- image: RGB image to be converted to bayer raw with shape :math:`(*,3,H,W)`.+ image: RGB image to be converted to bayer raw with shape ``(*,3,H,W)``.cfa: Which color filter array do we want the output to mimic. I.e. which pixels are red/green/blue.Returns:- raw version of the image with shape :math:`(*,1,H,W)`.+ raw version of the image with shape ``(*,1,H,W)``.Example:>>> rgbinput = torch.rand(2, 3, 4, 6)@@ -260,7 +260,7 @@ def raw_to_rgb_2x2_downscaled(image: torch.Tensor, cfa: CFA) -> torch.Tensor:(H/2, W/2). cfa uses the same OpenCV naming as raw_to_rgb.Args:- image: raw image to be converted to RGB and downscaled with shape :math:`(*,1,H,W)`.+ image: raw image to be converted to RGB and downscaled with shape ``(*,1,H,W)``.cfa: The configuration of the color filter.Returns:@@ -316,8 +316,8 @@ class RawToRgb(nn.Module):The image data is assumed to be in the range of (0, 1).Shape:- - image: :math:`(*, 1, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 1, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> rawinput = torch.rand(2, 1, 4, 6)@@ -337,12 +337,12 @@ class RawToRgb(nn.Module):"""Convert a Bayer raw tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 1, H, W)`.+ image: Input tensor with shape ``(*, 1, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``1`` is a single raw Bayer channel, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)` using this module's CFA pattern.+ RGB tensor with shape ``(*, 3, H, W)`` using this module's CFA pattern."""return raw_to_rgb(image, cfa=self.cfa)@@ -355,8 +355,8 @@ class RgbToRaw(nn.Module):The image data is assumed to be in the range of (0, 1).Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 1, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 1, H, W)``reference:https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html@@ -379,12 +379,12 @@ class RgbToRaw(nn.Module):"""Convert an RGB tensor to Bayer raw.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Raw tensor with shape :math:`(*, 1, H, W)` using this module's CFA pattern.+ Raw tensor with shape ``(*, 1, H, W)`` using this module's CFA pattern."""return rgb_to_raw(image, cfa=self.cfa)@@ -398,7 +398,7 @@ class RawToRgb2x2Downscaled(nn.Module):data is assumed to be in the range of (0, 1).Shape:- - image: :math:`(*, 1, H, W)`+ - image: ``(*, 1, H, W)``- output: :math:`(*, 3, \frac{H}{2}, \frac{W}{2})`Example:@@ -416,11 +416,11 @@ class RawToRgb2x2Downscaled(nn.Module):"""Convert a Bayer raw tensor to downscaled RGB.Args:- image: Input tensor with shape :math:`(*, 1, H, W)`.+ image: Input tensor with shape ``(*, 1, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``1`` is a single raw Bayer channel, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H / 2, W / 2)`.+ RGB tensor with shape ``(*, 3, H / 2, W / 2)``."""return raw_to_rgb_2x2_downscaled(image, cfa=self.cfa)diff --git a/kornia/color/rgb.py b/kornia/color/rgb.pyindex a5f83ec5d..3880e88bb 100644--- a/kornia/color/rgb.py+++ b/kornia/color/rgb.py@@ -35,10 +35,10 @@ def rgb_to_bgr(image: torch.Tensor) -> torch.Tensor:Reverses the three channels at axis -3; leading dimensions are preserved.Args:- image: RGB Image to be converted to BGRof of shape :math:`(*,3,H,W)`.+ image: RGB Image to be converted to BGRof of shape ``(*,3,H,W)``.Returns:- BGR version of the image with shape of shape :math:`(*,3,H,W)`.+ BGR version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -61,10 +61,10 @@ def bgr_to_rgb(image: torch.Tensor) -> torch.Tensor:Reverses the three channels at axis -3; it is its own inverse.Args:- image: BGR Image to be converted to BGR of shape :math:`(*,3,H,W)`.+ image: BGR Image to be converted to BGR of shape ``(*,3,H,W)``.Returns:- RGB version of the image with shape of shape :math:`(*,3,H,W)`.+ RGB version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -87,15 +87,15 @@ def rgb_to_rgba(image: torch.Tensor, alpha_val: Union[float, torch.Tensor]) -> tConvention:Appends alpha as the fourth channel at axis -3. A Python float alpha is broadcast over the image;- a tensor alpha must have shape :math:`(*,1,H,W)` matching the image's leading and spatial axes.+ a tensor alpha must have shape ``(*,1,H,W)`` matching the image's leading and spatial axes.Args:- image: RGB Image to be converted to RGBA of shape :math:`(*,3,H,W)`.+ image: RGB Image to be converted to RGBA of shape ``(*,3,H,W)``.alpha_val (float, torch.Tensor): A float number for the alpha value or a torch.Tensor- of shape :math:`(*,1,H,W)` matching the image's leading and spatial dimensions.+ of shape ``(*,1,H,W)`` matching the image's leading and spatial dimensions.Returns:- RGBA version of the image with shape :math:`(*,4,H,W)`.+ RGBA version of the image with shape ``(*,4,H,W)``... note:: The current functionality is NOT supported by Torchscript.@@ -133,12 +133,12 @@ def bgr_to_rgba(image: torch.Tensor, alpha_val: Union[float, torch.Tensor]) -> tReorders BGR to RGB and appends alpha as the fourth channel at axis -3.Args:- image: BGR Image to be converted to RGBA of shape :math:`(*,3,H,W)`.+ image: BGR Image to be converted to RGBA of shape ``(*,3,H,W)``.alpha_val: A float number for the alpha value or a torch.Tensor- of shape :math:`(*,1,H,W)` matching the image's leading and spatial dimensions.+ of shape ``(*,1,H,W)`` matching the image's leading and spatial dimensions.Returns:- RGBA version of the image with shape :math:`(*,4,H,W)`.+ RGBA version of the image with shape ``(*,4,H,W)``... note:: The current functionality is NOT supported by Torchscript.@@ -172,13 +172,13 @@ def rgba_to_rgb(image: torch.Tensor, background_color: Optional[torch.Tensor] =and background_color is a unit-range RGB color.Args:- image: The RGBA image to be converted, with shape :math:`(*,4,H,W)`.+ image: The RGBA image to be converted, with shape ``(*,4,H,W)``.background_color: An optional background color. It can be a *tuple or list* of 3 floats,- a torch.Tensor of shape :math:`(*,3,H,W)` for a per-pixel background, or a broadcastable- torch.Tensor (e.g., :math:`(*,3,1,1)`). If None, a white background is used.+ a torch.Tensor of shape ``(*,3,H,W)`` for a per-pixel background, or a broadcastable+ torch.Tensor (e.g., ``(*,3,1,1)``). If None, a white background is used.Returns:- The converted RGB image with shape :math:`(*,3,H,W)`.+ The converted RGB image with shape ``(*,3,H,W)``.Example:>>> rgba_image = torch.rand(2, 4, 32, 32)@@ -226,10 +226,10 @@ def rgba_to_bgr(image: torch.Tensor) -> torch.Tensor:Alpha-composites RGBA over white, then reverses the RGB channels at axis -3.Args:- image: RGBA Image to be converted to BGR of shape :math:`(*,4,H,W)`.+ image: RGBA Image to be converted to BGR of shape ``(*,4,H,W)``.Returns:- RGB version of the image with shape :math:`(*,3,H,W)`.+ RGB version of the image with shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 4, 4, 5)@@ -257,10 +257,10 @@ def rgb_to_linear_rgb(image: torch.Tensor) -> torch.Tensor:linear_rgb_to_rgb and the required preparation for rgb_to_xyz.Args:- image: sRGB Image to be converted to linear RGB of shape :math:`(*,3,H,W)`.+ image: sRGB Image to be converted to linear RGB of shape ``(*,3,H,W)``.Returns:- linear RGB version of the image with shape of :math:`(*,3,H,W)`.+ linear RGB version of the image with shape of ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -290,10 +290,10 @@ def linear_rgb_to_rgb(image: torch.Tensor) -> torch.Tensor:Converts linear RGB to nonlinear unit-range sRGB channelwise.Args:- image: linear RGB Image to be converted to sRGB of shape :math:`(*,3,H,W)`.+ image: linear RGB Image to be converted to sRGB of shape ``(*,3,H,W)``.Returns:- sRGB version of the image with shape of shape :math:`(*,3,H,W)`.+ sRGB version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -321,10 +321,10 @@ def normals_to_rgb255(image: torch.Tensor) -> torch.Tensor:Maps normal components from [-1, 1] to RGB255 channels [0, 255], clamping the result.Args:- image: surface normals to be converted to RGB with quantization of shape :math:`(*,3,H,W)`.+ image: surface normals to be converted to RGB with quantization of shape ``(*,3,H,W)``.Returns:- RGB version of the image with shape of shape :math:`(*,3,H,W)`.+ RGB version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -343,10 +343,10 @@ def rgb_to_rgb255(image: torch.Tensor) -> torch.Tensor:Multiplies unit-range RGB values by 255 and clamps the result to [0, 255].Args:- image: RGB Image to be converted to RGB [0, 255] of shape :math:`(*,3,H,W)`.+ image: RGB Image to be converted to RGB [0, 255] of shape ``(*,3,H,W)``.Returns:- RGB version of the image with shape of shape :math:`(*,3,H,W)`.+ RGB version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -364,10 +364,10 @@ def rgb255_to_rgb(image: torch.Tensor) -> torch.Tensor:Divides RGB255 values by 255 without clipping.Args:- image: RGB Image to be converted to RGB of shape :math:`(*,3,H,W)`.+ image: RGB Image to be converted to RGB of shape ``(*,3,H,W)``.Returns:- RGB version of the image with shape of shape :math:`(*,3,H,W)`.+ RGB version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -387,10 +387,10 @@ def rgb255_to_normals(image: torch.Tensor) -> torch.Tensor:Half inputs are computed in float32 and rounded to the input dtype once at return.Args:- image: RGB Image to be converted to surface normals of shape :math:`(*,3,H,W)`.+ image: RGB Image to be converted to surface normals of shape ``(*,3,H,W)``.Returns:- surface normals version of the image with shape of shape :math:`(*,3,H,W)`.+ surface normals version of the image with shape of shape ``(*,3,H,W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -416,8 +416,8 @@ class BgrToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -433,12 +433,12 @@ class BgrToRgb(nn.Module):"""Convert a BGR tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to BGR channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return bgr_to_rgb(image)@@ -454,8 +454,8 @@ class RgbToBgr(nn.Module):BGR version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -471,12 +471,12 @@ class RgbToBgr(nn.Module):"""Convert an RGB tensor to BGR.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- BGR tensor with shape :math:`(*, 3, H, W)`.+ BGR tensor with shape ``(*, 3, H, W)``."""return rgb_to_bgr(image)@@ -490,14 +490,14 @@ class RgbToRgba(nn.Module):Args:alpha_val: A float number for the alpha value or a torch.Tensor- of shape :math:`(*,1,H,W)`.+ of shape ``(*,1,H,W)``.Returns:- torch.Tensor: RGBA version of the image with shape :math:`(*,4,H,W)`.+ torch.Tensor: RGBA version of the image with shape ``(*,4,H,W)``.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 4, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 4, H, W)``.. note:: The current functionality is NOT supported by Torchscript.@@ -522,12 +522,12 @@ class RgbToRgba(nn.Module):"""Convert an RGB tensor to RGBA.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- RGBA tensor with shape :math:`(*, 4, H, W)` using this module's alpha value.+ RGBA tensor with shape ``(*, 4, H, W)`` using this module's alpha value."""return rgb_to_rgba(image, self.alpha_val)@@ -541,14 +541,14 @@ class BgrToRgba(nn.Module):Args:alpha_val: A float number for the alpha value or a torch.Tensor- of shape :math:`(*,1,H,W)`.+ of shape ``(*,1,H,W)``.Returns:- RGBA version of the image with shape :math:`(*,4,H,W)`.+ RGBA version of the image with shape ``(*,4,H,W)``.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 4, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 4, H, W)``.. note:: The current functionality is NOT supported by Torchscript.@@ -573,12 +573,12 @@ class BgrToRgba(nn.Module):"""Append this module's alpha channel to the input tensor.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` is the input channel count, and ``H``/``W`` are height and width.Returns:- RGBA tensor with shape :math:`(*, 4, H, W)`.+ RGBA tensor with shape ``(*, 4, H, W)``."""return bgr_to_rgba(image, self.alpha_val)@@ -594,8 +594,8 @@ class RgbaToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 4, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 4, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 4, 4, 5)@@ -611,12 +611,12 @@ class RgbaToRgb(nn.Module):"""Convert an RGBA tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 4, H, W)`.+ image: Input tensor with shape ``(*, 4, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``4`` corresponds to RGBA channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return rgba_to_rgb(image)@@ -632,8 +632,8 @@ class RgbaToBgr(nn.Module):BGR version of the image.Shape:- - image: :math:`(*, 4, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 4, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 4, 4, 5)@@ -649,12 +649,12 @@ class RgbaToBgr(nn.Module):"""Convert an RGBA tensor to BGR.Args:- image: Input tensor with shape :math:`(*, 4, H, W)`.+ image: Input tensor with shape ``(*, 4, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``4`` corresponds to RGBA channels, and ``H``/``W`` are height and width.Returns:- BGR tensor with shape :math:`(*, 3, H, W)`.+ BGR tensor with shape ``(*, 3, H, W)``."""return rgba_to_bgr(image)@@ -671,8 +671,8 @@ class RgbToLinearRgb(nn.Module):Linear RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -695,12 +695,12 @@ class RgbToLinearRgb(nn.Module):"""Convert an sRGB tensor to linear RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Linear RGB tensor with shape :math:`(*, 3, H, W)`.+ Linear RGB tensor with shape ``(*, 3, H, W)``."""return rgb_to_linear_rgb(image)@@ -716,8 +716,8 @@ class LinearRgbToRgb(nn.Module):sRGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -740,12 +740,12 @@ class LinearRgbToRgb(nn.Module):"""Convert a linear RGB tensor to sRGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- sRGB tensor with shape :math:`(*, 3, H, W)`.+ sRGB tensor with shape ``(*, 3, H, W)``."""return linear_rgb_to_rgb(image)@@ -759,8 +759,8 @@ class NormalsToRgb255(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -773,12 +773,12 @@ class NormalsToRgb255(nn.Module):"""Convert surface normals to RGB values in :math:`[0, 255]`.Args:- image: Input normal map tensor with shape :math:`(*, 3, H, W)`.+ image: Input normal map tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to XYZ normal components, and ``H``/``W`` are height and width.Returns:- RGB tensor in :math:`[0, 255]` with shape :math:`(*, 3, H, W)`.+ RGB tensor in :math:`[0, 255]` with shape ``(*, 3, H, W)``."""return normals_to_rgb255(image)@@ -792,8 +792,8 @@ class RgbToRgb255(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -806,12 +806,12 @@ class RgbToRgb255(nn.Module):"""Convert RGB values from :math:`[0, 1]` to :math:`[0, 255]`.Args:- image: Input RGB tensor with shape :math:`(*, 3, H, W)`.+ image: Input RGB tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- RGB tensor in :math:`[0, 255]` with shape :math:`(*, 3, H, W)`.+ RGB tensor in :math:`[0, 255]` with shape ``(*, 3, H, W)``."""return rgb_to_rgb255(image)@@ -825,8 +825,8 @@ class Rgb255ToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -839,12 +839,12 @@ class Rgb255ToRgb(nn.Module):"""Convert RGB values from :math:`[0, 255]` to :math:`[0, 1]`.Args:- image: Input RGB tensor in :math:`[0, 255]` with shape :math:`(*, 3, H, W)`.+ image: Input RGB tensor in :math:`[0, 255]` with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- RGB tensor in :math:`[0, 1]` with shape :math:`(*, 3, H, W)`.+ RGB tensor in :math:`[0, 1]` with shape ``(*, 3, H, W)``."""return rgb255_to_rgb(image)@@ -858,8 +858,8 @@ class Rgb255ToNormals(nn.Module):surface normals version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Example:>>> input = torch.rand(2, 3, 4, 5)@@ -872,11 +872,11 @@ class Rgb255ToNormals(nn.Module):"""Convert RGB values in :math:`[0, 255]` to surface normals.Args:- image: Input RGB tensor in :math:`[0, 255]` with shape :math:`(*, 3, H, W)`.+ image: Input RGB tensor in :math:`[0, 255]` with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Normal map tensor with shape :math:`(*, 3, H, W)`.+ Normal map tensor with shape ``(*, 3, H, W)``."""return rgb255_to_normals(image)diff --git a/kornia/color/sepia.py b/kornia/color/sepia.pyindex 24f5d6e36..3202976d3 100644--- a/kornia/color/sepia.py+++ b/kornia/color/sepia.py@@ -29,12 +29,12 @@ def sepia_from_rgb(input: torch.Tensor, rescale: bool = True, eps: float = 1e-6)Disable it to keep the raw matrix response.Args:- input: the input tensor with shape :math:`(*, C, H, W)`.+ input: the input tensor with shape ``(*, C, H, W)``.rescale: if True, divide all output channels by one maximum per image.eps: small constant added to the denominator for numerical stability.Returns:- torch.Tensor: sepia-filtered tensor with shape :math:`(*, C, H, W)`.+ torch.Tensor: sepia-filtered tensor with shape ``(*, C, H, W)``.Example:>>> input = torch.ones(3, 1, 1)@@ -75,7 +75,7 @@ class Sepia(nn.Module):eps: small constant added to the denominator for numerical stability.Returns:- torch.Tensor: sepia-filtered tensor with shape :math:`(*, C, H, W)`.+ torch.Tensor: sepia-filtered tensor with shape ``(*, C, H, W)``.Example:>>> input = torch.ones(3, 1, 1)@@ -106,9 +106,9 @@ class Sepia(nn.Module):"""Apply the sepia filter.Args:- input: RGB image tensor with shape :math:`(*, 3, H, W)`.+ input: RGB image tensor with shape ``(*, 3, H, W)``.Returns:- Sepia-filtered tensor with shape :math:`(*, 3, H, W)`.+ Sepia-filtered tensor with shape ``(*, 3, H, W)``."""return sepia_from_rgb(input, rescale=self.rescale, eps=self.eps)diff --git a/kornia/color/utils.py b/kornia/color/utils.pyindex e6368780f..365048f09 100644--- a/kornia/color/utils.py+++ b/kornia/color/utils.py@@ -27,10 +27,10 @@ def _apply_linear_transformation("""Apply a 3x3 linear color transformation with device-aware optimization.Args:- image: Input image tensor with shape :math:`(*, 3, H, W)`.- kernel: Transformation matrix with shape :math:`(3, 3)` applied along the channel+ image: Input image tensor with shape ``(*, 3, H, W)``.+ kernel: Transformation matrix with shape ``(3, 3)`` applied along the channeldimension.- bias: Bias vector with shape :math:`(3,)` to be added to the output.+ bias: Bias vector with shape ``(3,)`` to be added to the output.Returns:Tensor with the same shape as ``image`` containing the transformed values.diff --git a/kornia/color/xyz.py b/kornia/color/xyz.pyindex d88dee135..5464a8da9 100644--- a/kornia/color/xyz.py+++ b/kornia/color/xyz.py@@ -36,10 +36,10 @@ def rgb_to_xyz(image: torch.Tensor) -> torch.Tensor:rgb_to_linear_rgb; nonlinear sRGB values are not linearized here.Args:- image: RGB Image to be converted to XYZ with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to XYZ with shape ``(*, 3, H, W)``.Returns:- XYZ version of the image with shape :math:`(*, 3, H, W)`.+ XYZ version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -73,10 +73,10 @@ def xyz_to_rgb(image: torch.Tensor) -> torch.Tensor:linear_rgb_to_rgb when nonlinear sRGB is required.Args:- image: XYZ Image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: XYZ Image to be converted to RGB with shape ``(*, 3, H, W)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -113,8 +113,8 @@ class RgbToXyz(nn.Module):XYZ version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -133,12 +133,12 @@ class RgbToXyz(nn.Module):"""Convert an RGB tensor to XYZ.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- XYZ tensor with shape :math:`(*, 3, H, W)`.+ XYZ tensor with shape ``(*, 3, H, W)``."""return rgb_to_xyz(image)@@ -152,8 +152,8 @@ class XyzToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -172,11 +172,11 @@ class XyzToRgb(nn.Module):"""Convert an XYZ tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to XYZ channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return xyz_to_rgb(image)diff --git a/kornia/color/ycbcr.py b/kornia/color/ycbcr.pyindex fcc0c4dfb..599dd69f2 100644--- a/kornia/color/ycbcr.py+++ b/kornia/color/ycbcr.py@@ -38,10 +38,10 @@ def rgb_to_ycbcr(image: torch.Tensor) -> torch.Tensor:full-range values.Args:- image: RGB Image to be converted to YCbCr with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to YCbCr with shape ``(*, 3, H, W)``.Returns:- YCbCr version of the image with shape :math:`(*, 3, H, W)`.+ YCbCr version of the image with shape ``(*, 3, H, W)``.Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -73,10 +73,10 @@ def rgb_to_y(image: torch.Tensor) -> torch.Tensor:rgb_to_ycbcr.Args:- image: RGB Image to be converted to Y with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to Y with shape ``(*, 3, H, W)``.Returns:- Y version of the image with shape :math:`(*, 1, H, W)`.+ Y version of the image with shape ``(*, 1, H, W)``.Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -107,10 +107,10 @@ def ycbcr_to_rgb(image: torch.Tensor) -> torch.Tensor:rgb_to_ycbcr. The final RGB result is clamped to [0, 1].Args:- image: YCbCr Image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: YCbCr Image to be converted to RGB with shape ``(*, 3, H, W)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -152,8 +152,8 @@ class RgbToYcbcr(nn.Module):YCbCr version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -169,12 +169,12 @@ class RgbToYcbcr(nn.Module):"""Convert an RGB tensor to YCbCr.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- YCbCr tensor with shape :math:`(*, 3, H, W)`.+ YCbCr tensor with shape ``(*, 3, H, W)``."""return rgb_to_ycbcr(image)@@ -190,8 +190,8 @@ class YcbcrToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -207,11 +207,11 @@ class YcbcrToRgb(nn.Module):"""Convert a YCbCr tensor to RGB.Args:- image: Input tensor with shape :math:`(*, 3, H, W)`.+ image: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to YCbCr channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return ycbcr_to_rgb(image)diff --git a/kornia/color/yuv.py b/kornia/color/yuv.pyindex a57505989..8c9a3bc02 100644--- a/kornia/color/yuv.py+++ b/kornia/color/yuv.py@@ -33,8 +33,8 @@ def rgb_to_yuv(image: torch.Tensor) -> torch.Tensor:.. image:: _static/img/rgb_to_yuv.png- The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of- :math:`(0, 1)` to luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`,+ The image data is assumed to be in the range of :math:`[0, 1]`. The range of the output is of+ :math:`[0, 1]` to luma and the ranges of U and V are :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`,respectively.The YUV model adopted here follows M/PAL values (see@@ -46,10 +46,10 @@ def rgb_to_yuv(image: torch.Tensor) -> torch.Tensor:chroma components centered at zero.Args:- image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to YUV with shape ``(*, 3, H, W)``.Returns:- YUV version of the image with shape :math:`(*, 3, H, W)`.+ YUV version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -78,23 +78,23 @@ def rgb_to_yuv420(image: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:Input need to be padded to be evenly divisible by 2 horizontal and vertical.- The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of :math:`(0, 1)` to- luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]`. The range of the output is of :math:`[0, 1]` to+ luma and the ranges of U and V are :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.The YUV model adopted here follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,items 2.5 and 2.6).Convention:- Returns (Y, UV): Y has shape :math:`(*, 1, H, W)` and UV holds the U and V planes as two- channels, :math:`(*, 2, H/2, W/2)`. Height and width must be even.+ Returns (Y, UV): Y has shape ``(*, 1, H, W)`` and UV holds the U and V planes as two+ channels, ``(*, 2, H/2, W/2)``. Height and width must be even.Args:- image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to YUV with shape ``(*, 3, H, W)``.Returns:- A torch.Tensor containing the Y plane with shape :math:`(*, 1, H, W)`- A torch.Tensor containing the UV planes with shape :math:`(*, 2, H/2, W/2)`+ A torch.Tensor containing the Y plane with shape ``(*, 1, H, W)``+ A torch.Tensor containing the UV planes with shape ``(*, 2, H/2, W/2)``Example:>>> input = torch.rand(2, 3, 4, 6)@@ -128,8 +128,8 @@ def rgb_to_yuv422(image: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:Input width must be evenly divisible by 2; height may be odd.- The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of- :math:`(0, 1)` to luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`,+ The image data is assumed to be in the range of :math:`[0, 1]`. The range of the output is of+ :math:`[0, 1]` to luma and the ranges of U and V are :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`,respectively.The YUV model adopted here follows M/PAL values (see@@ -137,15 +137,15 @@ def rgb_to_yuv422(image: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:items 2.5 and 2.6).Convention:- Returns (Y, UV): Y has shape :math:`(*, 1, H, W)` and UV holds the U and V planes as two- channels, :math:`(*, 2, H, W/2)`. Width must be even.+ Returns (Y, UV): Y has shape ``(*, 1, H, W)`` and UV holds the U and V planes as two+ channels, ``(*, 2, H, W/2)``. Width must be even.Args:- image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.+ image: RGB Image to be converted to YUV with shape ``(*, 3, H, W)``.Returns:- A torch.Tensor containing the Y plane with shape :math:`(*, 1, H, W)`- A torch.Tensor containing the UV planes with shape :math:`(*, 2, H, W/2)`+ A torch.Tensor containing the Y plane with shape ``(*, 1, H, W)``+ A torch.Tensor containing the UV planes with shape ``(*, 2, H, W/2)``Example:>>> input = torch.rand(2, 3, 4, 6)@@ -170,8 +170,8 @@ def rgb_to_yuv422(image: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:def yuv_to_rgb(image: torch.Tensor) -> torch.Tensor:r"""Convert a full-resolution YUV (4:4:4) image of shape ``(*, 3, H, W)`` to RGB.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -186,10 +186,10 @@ def yuv_to_rgb(image: torch.Tensor) -> torch.Tensor:rgb_to_yuv.Args:- image: YUV Image to be converted to RGB with shape :math:`(*, 3, H, W)`.+ image: YUV Image to be converted to RGB with shape ``(*, 3, H, W)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Example:>>> input = torch.rand(2, 3, 4, 5)@@ -227,8 +227,8 @@ def yuv420_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:Input need to be padded to be evenly divisible by 2 horizontal and vertical.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -239,11 +239,11 @@ def yuv420_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:nearest-neighbor replication.Args:- imagey: Y (luma) Image plane to be converted to RGB with shape :math:`(*, 1, H, W)`.- imageuv: UV (chroma) Image planes to be converted to RGB with shape :math:`(*, 2, H/2, W/2)`.+ imagey: Y (luma) Image plane to be converted to RGB with shape ``(*, 1, H, W)``.+ imageuv: UV (chroma) Image planes to be converted to RGB with shape ``(*, 2, H/2, W/2)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Example:>>> inputy = torch.rand(2, 1, 4, 6)@@ -282,8 +282,8 @@ def yuv422_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:Input width must be evenly divisible by 2; height may be odd.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -294,11 +294,11 @@ def yuv422_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:width by nearest-neighbor replication.Args:- imagey: Y (luma) Image plane to be converted to RGB with shape :math:`(*, 1, H, W)`.- imageuv: UV (chroma) Image planes to be converted to RGB with shape :math:`(*, 2, H, W/2)`.+ imagey: Y (luma) Image plane to be converted to RGB with shape ``(*, 1, H, W)``.+ imageuv: UV (chroma) Image planes to be converted to RGB with shape ``(*, 2, H, W/2)``.Returns:- RGB version of the image with shape :math:`(*, 3, H, W)`.+ RGB version of the image with shape ``(*, 3, H, W)``.Example:>>> inputy = torch.rand(2, 1, 4, 6)@@ -335,7 +335,7 @@ class RgbToYuv(nn.Module):See the Convention block on :func:`rgb_to_yuv`.- The image data is assumed to be in the range of :math:`(0, 1)`.+ The image data is assumed to be in the range of :math:`[0, 1]`.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -345,8 +345,8 @@ class RgbToYuv(nn.Module):YUV version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -366,12 +366,12 @@ class RgbToYuv(nn.Module):"""Convert an RGB tensor to YUV.Args:- input: Input tensor with shape :math:`(*, 3, H, W)`.+ input: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- YUV tensor with shape :math:`(*, 3, H, W)`.+ YUV tensor with shape ``(*, 3, H, W)``."""return rgb_to_yuv(input)@@ -383,7 +383,7 @@ class RgbToYuv420(nn.Module):Width and Height must be evenly divisible by 2.- The image data is assumed to be in the range of :math:`(0, 1)`.+ The image data is assumed to be in the range of :math:`[0, 1]`.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -393,8 +393,8 @@ class RgbToYuv420(nn.Module):YUV420 version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 1, H, W)` and :math:`(*, 2, H/2, W/2)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 1, H, W)`` and ``(*, 2, H/2, W/2)``Examples:>>> yuvinput = torch.rand(2, 3, 4, 6)@@ -414,13 +414,13 @@ class RgbToYuv420(nn.Module):"""Convert an RGB tensor to YUV420 planes.Args:- yuvinput: Input tensor with shape :math:`(*, 3, H, W)`.+ yuvinput: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Tuple of ``(y, uv)`` where ``y`` has shape :math:`(*, 1, H, W)` and ``uv`` has- shape :math:`(*, 2, H / 2, W / 2)`. The ``1`` channel is luma and the ``2``+ Tuple of ``(y, uv)`` where ``y`` has shape ``(*, 1, H, W)`` and ``uv`` has+ shape ``(*, 2, H / 2, W / 2)``. The ``1`` channel is luma and the ``2``channels are chroma."""return rgb_to_yuv420(yuvinput)@@ -433,7 +433,7 @@ class RgbToYuv422(nn.Module):Width must be evenly divisible by 2; height may be odd.- The image data is assumed to be in the range of :math:`(0, 1)`.+ The image data is assumed to be in the range of :math:`[0, 1]`.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -443,8 +443,8 @@ class RgbToYuv422(nn.Module):YUV422 version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 1, H, W)` and :math:`(*, 2, H, W/2)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 1, H, W)`` and ``(*, 2, H, W/2)``Examples:>>> yuvinput = torch.rand(2, 3, 4, 6)@@ -464,13 +464,13 @@ class RgbToYuv422(nn.Module):"""Convert an RGB tensor to YUV422 planes.Args:- yuvinput: Input tensor with shape :math:`(*, 3, H, W)`.+ yuvinput: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to RGB channels, and ``H``/``W`` are height and width.Returns:- Tuple of ``(y, uv)`` where ``y`` has shape :math:`(*, 1, H, W)` and ``uv`` has- shape :math:`(*, 2, H, W / 2)`. The ``1`` channel is luma and the ``2`` channels+ Tuple of ``(y, uv)`` where ``y`` has shape ``(*, 1, H, W)`` and ``uv`` has+ shape ``(*, 2, H, W / 2)``. The ``1`` channel is luma and the ``2`` channelsare chroma."""return rgb_to_yuv422(yuvinput)@@ -481,8 +481,8 @@ class YuvToRgb(nn.Module):See the Convention block on :func:`yuv_to_rgb`.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -495,8 +495,8 @@ class YuvToRgb(nn.Module):RGB version of the image.Shape:- - image: :math:`(*, 3, H, W)`- - output: :math:`(*, 3, H, W)`+ - image: ``(*, 3, H, W)``+ - output: ``(*, 3, H, W)``Examples:>>> input = torch.rand(2, 3, 4, 5)@@ -513,12 +513,12 @@ class YuvToRgb(nn.Module):"""Convert a YUV tensor to RGB.Args:- input: Input tensor with shape :math:`(*, 3, H, W)`.+ input: Input tensor with shape ``(*, 3, H, W)``.Here, ``*`` means any number of leading dimensions (for example, batch size),``3`` corresponds to YUV channels, and ``H``/``W`` are height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return yuv_to_rgb(input)@@ -530,8 +530,8 @@ class Yuv420ToRgb(nn.Module):Width and Height must be evenly divisible by 2.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -541,9 +541,9 @@ class Yuv420ToRgb(nn.Module):RGB version of the image.Shape:- - imagey: :math:`(*, 1, H, W)`- - imageuv: :math:`(*, 2, H/2, W/2)`- - output: :math:`(*, 3, H, W)`+ - imagey: ``(*, 1, H, W)``+ - imageuv: ``(*, 2, H/2, W/2)``+ - output: ``(*, 3, H, W)``Examples:>>> inputy = torch.rand(2, 1, 4, 6)@@ -561,13 +561,13 @@ class Yuv420ToRgb(nn.Module):"""Convert YUV420 luma/chroma planes to RGB.Args:- inputy: Luma tensor with shape :math:`(*, 1, H, W)`.- inputuv: Chroma tensor with shape :math:`(*, 2, H / 2, W / 2)`.+ inputy: Luma tensor with shape ``(*, 1, H, W)``.+ inputuv: Chroma tensor with shape ``(*, 2, H / 2, W / 2)``.For both tensors, ``*`` means any number of leading dimensions (for example,batch size), and ``H``/``W`` are the full-resolution height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return yuv420_to_rgb(inputy, inputuv)@@ -579,8 +579,8 @@ class Yuv422ToRgb(nn.Module):Width must be evenly divisible by 2; height may be odd.- The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are- :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.+ The image data is assumed to be in the range of :math:`[0, 1]` for luma (Y). The ranges of U and V are+ :math:`[-0.436, 0.436]` and :math:`[-0.615, 0.615]`, respectively.YUV formula follows M/PAL values (see`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,@@ -590,9 +590,9 @@ class Yuv422ToRgb(nn.Module):RGB version of the image.Shape:- - imagey: :math:`(*, 1, H, W)`- - imageuv: :math:`(*, 2, H, W/2)`- - output: :math:`(*, 3, H, W)`+ - imagey: ``(*, 1, H, W)``+ - imageuv: ``(*, 2, H, W/2)``+ - output: ``(*, 3, H, W)``Examples:>>> inputy = torch.rand(2, 1, 4, 6)@@ -610,12 +610,12 @@ class Yuv422ToRgb(nn.Module):"""Convert YUV422 luma/chroma planes to RGB.Args:- inputy: Luma tensor with shape :math:`(*, 1, H, W)`.- inputuv: Chroma tensor with shape :math:`(*, 2, H, W / 2)`.+ inputy: Luma tensor with shape ``(*, 1, H, W)``.+ inputuv: Chroma tensor with shape ``(*, 2, H, W / 2)``.For both tensors, ``*`` means any number of leading dimensions (for example,batch size), and ``H``/``W`` are the full-resolution height and width.Returns:- RGB tensor with shape :math:`(*, 3, H, W)`.+ RGB tensor with shape ``(*, 3, H, W)``."""return yuv422_to_rgb(inputy, inputuv)diff --git a/kornia/contrib/connected_components.py b/kornia/contrib/connected_components.pyindex b3cdf8ce7..9d3b0074f 100644--- a/kornia/contrib/connected_components.py+++ b/kornia/contrib/connected_components.py@@ -39,7 +39,7 @@ def connected_components(image: torch.Tensor, num_iterations: int = 100) -> torconto SciPy, OpenCV and scikit-image.- Foreground is a value exactly equal to 1: 0.5 and 2 are background. Other values and dtypes are accepted.- The label of a component is 1 plus the largest raster index of its pixels in the batch flattened to- :math:`(N, H, W)`; background is 0. Labels are therefore not contiguous, and an image gets other labels at+ ``(N, H, W)``; background is 0. Labels are therefore not contiguous, and an image gets other labels atanother batch position or transposed. On MPS an image of more than :math:`2^{24}` pixels raises``ValueError``.- ``num_iterations`` is a fixed number of max-pooling steps, not a convergence test, and a label travels one@@ -48,7 +48,7 @@ def connected_components(image: torch.Tensor, num_iterations: int = 100) -> torc- The labels carry no gradient.Args:- image: the binary input image with shape :math:`(*, 1, H, W)`.+ image: the binary input image with shape ``(*, 1, H, W)``.num_iterations: the number of max-pooling steps, at least 1.Return:@@ -119,7 +119,7 @@ def connected_components_union_find(image: torch.Tensor) -> torch.Tensor::func:`connected_components`.Args:- image: Binary image of shape :math:`(*, 1, H, W)`. Boolean, integer and+ image: Binary image of shape ``(*, 1, H, W)``. Boolean, integer andfloating-point tensors are accepted. Only values equal to 1 areforeground, as in :func:`connected_components`.diff --git a/kornia/contrib/diamond_square.py b/kornia/contrib/diamond_square.pyindex fa3758335..24727480d 100644--- a/kornia/contrib/diamond_square.py+++ b/kornia/contrib/diamond_square.py@@ -182,7 +182,7 @@ def diamond_square(``torch.rand`` the map stays in [0, 1] without normalization while ``random_scale`` and ``roughness`` are in[0, 1], and it is flat in mean (0.5 at every pixel) for every ``random_scale``, though its variance variesacross the map.- - ``roughness`` and ``random_scale`` are a float, a 0-d tensor or a :math:`(B,)` tensor with one value per+ - ``roughness`` and ``random_scale`` are a float, a 0-d tensor or a ``(B,)`` tensor with one value persample, and follow ``device`` and ``dtype``; with ``dtype=None`` a tensor keeps its dtype and a float takesthe default dtype. When ``random_fn`` returns the dtype it is asked for, the map has the dtype that``dtype`` (the default dtype for ``None``), ``roughness`` and ``random_scale`` promote to, at every map@@ -202,7 +202,7 @@ def diamond_square(dtype: the torch dtype to place the output map.Returns:- A torch.Tensor with shape :math:`(B,C,H,W)` containing the fractal image.+ A torch.Tensor with shape ``(B,C,H,W)`` containing the fractal image."""KORNIA_CHECK(len(output_size) == 4, "output_size must be (B,C,H,W)")diff --git a/kornia/contrib/distance_transform.py b/kornia/contrib/distance_transform.pyindex 6f39e4559..06f1b3a71 100644--- a/kornia/contrib/distance_transform.py+++ b/kornia/contrib/distance_transform.py@@ -246,7 +246,7 @@ def distance_transform(image: torch.Tensor, kernel_size: int = 3, h: float = 0.32 px apart and 0.579 px in a one-pixel hole, and in a hole towards 0 as ``h`` nears its upper bound.Args:- image: Image or volume with shape :math:`(B,C,H,W)` or :math:`(B,C,D,H,W)`.+ image: Image or volume with shape ``(B,C,H,W)`` or ``(B,C,D,H,W)``.kernel_size: size of the convolution kernel. Must be an odd number of at least 3.h: value that influences the approximation of the min function. The cascade's kernel taps are``exp(-dist/h)``. Accepted: ``h`` large enough that the corner tap (distance@@ -321,8 +321,8 @@ class DistanceTransform(nn.Module):Each channel is processed independently, as in :func:`distance_transform`.Args:- image: Input tensor with shape :math:`(B, C, H, W)` for 2D data or- :math:`(B, C, D, H, W)` for 3D data, where:+ image: Input tensor with shape ``(B, C, H, W)`` for 2D data or+ ``(B, C, D, H, W)`` for 3D data, where:- ``B`` is batch size,- ``C`` is the number of channels,- ``D`` is depth (only for 3D volumes),diff --git a/kornia/contrib/edge_detection.py b/kornia/contrib/edge_detection.pyindex 92f2afd4e..e5036700f 100644--- a/kornia/contrib/edge_detection.py+++ b/kornia/contrib/edge_detection.py@@ -107,16 +107,16 @@ class EdgeDetector(ModelBase, ONNXExportMixin):"""Forward pass of the edge detection model.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`. For a detector from+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``. For a detector from:py:class:`~kornia.contrib.edge_detection.EdgeDetectorBuilder`, the pixel values are in:math:`[0, 1]`.Returns:- A list with one output of shape :math:`(1, 1, H, W)` per input image, resized back to that image's size.+ A list with one output of shape ``(1, 1, H, W)`` per input image, resized back to that image's size.For a detector from :py:class:`~kornia.contrib.edge_detection.EdgeDetectorBuilder`, it holds edgeprobabilities in :math:`[0, 1]`. Under an ONNX export with a ``ResizePostProcessor``, one- :math:`(B, 1, H, W)` tensor at the input's size instead, see :meth:`to_onnx`.+ ``(B, 1, H, W)`` tensor at the input's size instead, see :meth:`to_onnx`.Raises:ValueError: Under an ONNX export through :meth:`to_onnx`, or a direct one on the TorchScript exporter or,@@ -241,8 +241,8 @@ class EdgeDetector(ModelBase, ONNXExportMixin):) -> onnx.ModelProto:"""Export the current edge detection model to an ONNX model file.- The graph takes one :math:`(B, 3, H, W)` tensor. With the pre- and post-processor and a- ``ResizePostProcessor``, it returns the edge maps of the batch as one :math:`(B, 1, H, W)` tensor at the+ The graph takes one ``(B, 3, H, W)`` tensor. With the pre- and post-processor and a+ ``ResizePostProcessor``, it returns the edge maps of the batch as one ``(B, 1, H, W)`` tensor at theinput's size, resized with the post-processor's ``"bilinear"``, ``"bicubic"``, ``"nearest"`` or``"nearest-exact"`` mode: the ``torch.cat`` of the list that :meth:`forward` returns. A subclass of``ResizePostProcessor`` that overrides ``forward`` is exported as its ``forward`` computes. Export throughdiff --git a/kornia/contrib/extract_patches.py b/kornia/contrib/extract_patches.pyindex ca9ac481a..1df0cf93c 100644--- a/kornia/contrib/extract_patches.py+++ b/kornia/contrib/extract_patches.py@@ -136,7 +136,7 @@ class ExtractTensorPatches(nn.Module):r"""nn.Module that extracts patches from tensors and stacks them.In the simplest case, the output value of the operator with input size- :math:`(B, C, H, W)` is :math:`(B, N, C, H_{out}, W_{out})`.+ ``(B, C, H, W)`` is :math:`(B, N, C, H_{out}, W_{out})`.where- :math:`B` is the batch size.@@ -187,14 +187,14 @@ class ExtractTensorPatches(nn.Module):``disable_checks()``.Args:- input: torch.Tensor image where to extract the patches with shape :math:`(B, C, H, W)`.+ input: torch.Tensor image where to extract the patches with shape ``(B, C, H, W)``.window_size: the size of the sliding window and the output patch size.stride: stride of the sliding window.padding: zero padding, or cropping where negative: an int, ``(ph, pw)`` or ``(top, bottom, left, right)``.allow_auto_padding: whether to allow automatic padding if the window and stride do not fit into the image.Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output: :math:`(B, N, C, H_{out}, W_{out})`Returns:@@ -231,7 +231,7 @@ class ExtractTensorPatches(nn.Module):"""Extract sliding-window patches from a batched image tensor.Args:- input: Input tensor with shape :math:`(B, C, H, W)`, where:+ input: Input tensor with shape ``(B, C, H, W)``, where:- ``B`` is the batch size (number of images),- ``C`` is the number of channels,- ``H`` is height,@@ -256,7 +256,7 @@ class CombineTensorPatches(nn.Module):r"""nn.Module that combines patches back into full tensors.In the simplest case, the output value of the operator with input size- :math:`(B, N, C, H_{out}, W_{out})` is :math:`(B, C, H, W)`.+ :math:`(B, N, C, H_{out}, W_{out})` is ``(B, C, H, W)``.where- :math:`B` is the batch size.@@ -318,7 +318,7 @@ class CombineTensorPatches(nn.Module):Shape:- Input: :math:`(B, N, C, H_{out}, W_{out})`- - Output: :math:`(B, C, H, W)`+ - Output: ``(B, C, H, W)``Example:>>> out = extract_tensor_patches(torch.arange(16).view(1, 1, 4, 4), window_size=(2, 2), stride=(2, 2))@@ -360,7 +360,7 @@ class CombineTensorPatches(nn.Module):- ``H_{out}`` and ``W_{out}`` are patch height and width.Returns:- A reconstructed tensor with shape :math:`(B, C, H, W)`, where ``H``+ A reconstructed tensor with shape ``(B, C, H, W)``, where ``H``and ``W`` correspond to ``original_size`` after optional unpadding."""return combine_tensor_patches(@@ -414,7 +414,7 @@ def combine_tensor_patches(covers is 0.Return:- The combined patches in an image torch.Tensor with shape :math:`(B, C, H, W)`.+ The combined patches in an image torch.Tensor with shape ``(B, C, H, W)``.Example:>>> out = extract_tensor_patches(torch.arange(16).view(1, 1, 4, 4), window_size=(2, 2), stride=(2, 2))@@ -596,7 +596,7 @@ def extract_tensor_patches(See the Convention block of :class:`~kornia.contrib.ExtractTensorPatches`.Args:- input: torch.Tensor image where to extract the patches with shape :math:`(B, C, H, W)`.+ input: torch.Tensor image where to extract the patches with shape ``(B, C, H, W)``.window_size: the size of the sliding window and the output patch size.stride: stride of the sliding window.padding: zero padding, or cropping where negative: an int, ``(ph, pw)`` or ``(top, bottom, left, right)``.diff --git a/kornia/contrib/face_detection.py b/kornia/contrib/face_detection.pyindex 149256faf..99aa5b3e3 100644--- a/kornia/contrib/face_detection.py+++ b/kornia/contrib/face_detection.py@@ -48,7 +48,7 @@ class FaceDetectorResult:Args:data: the detections returned by :py:class:`kornia.contrib.FaceDetector`, one row of 15 values per face with- shape :math:`(15,)` or :math:`(N, 15)`: the box ``xmin, ymin, xmax, ymax``, five ``(x, y)`` landmarks+ shape ``(15,)`` or ``(N, 15)``: the box ``xmin, ymin, xmax, ymax``, five ``(x, y)`` landmarks(see :py:class:`kornia.contrib.FaceKeypoint`) and the score."""@@ -160,7 +160,7 @@ class FaceDetector(nn.Module):keep_top_k: the maximum number of detections to return after the nms.Return:- A list of B tensors with shape :math:`(N,15)` to be used with :py:class:`kornia.contrib.FaceDetectorResult`.+ A list of B tensors with shape ``(N,15)`` to be used with :py:class:`kornia.contrib.FaceDetectorResult`.Example:>>> img = torch.rand(1, 3, 320, 320) * 255 # RGB in [0, 255]@@ -195,7 +195,7 @@ class FaceDetector(nn.Module):"""Preprocess input images before feeding them to YuNet.Args:- image: Batch of RGB images with pixel values in :math:`[0, 255]` and shape :math:`(B, 3, H, W)`, where:+ image: Batch of RGB images with pixel values in :math:`[0, 255]` and shape ``(B, 3, H, W)``, where:- ``B`` is batch size,- ``3`` is the RGB channel dimension,- ``H`` is image height,@@ -205,7 +205,7 @@ class FaceDetector(nn.Module):The same images in BGR channel order, still in :math:`[0, 255]`: the input YuNet was trained on.Raises:- ValueError: If the image is not of shape :math:`(*, 3, H, W)`.+ ValueError: If the image is not of shape ``(*, 3, H, W)``."""return rgb_to_bgr(image)@@ -220,7 +220,7 @@ class FaceDetector(nn.Module):Returns:A list with one tensor per batch element. Each tensor is shaped- :math:`(N, 15)`, where ``N`` is the number of detections kept after+ ``(N, 15)``, where ``N`` is the number of detections kept afterconfidence filtering and non-maximum suppression (NMS).The 15 values per detection are:@@ -270,7 +270,7 @@ class FaceDetector(nn.Module):r"""Detect faces in a given batch of images.Args:- image: batch of RGB images with pixel values in :math:`[0, 255]` and shape :math:`(B,3,H,W)`.+ image: batch of RGB images with pixel values in :math:`[0, 255]` and shape ``(B,3,H,W)``.Return:List[torch.Tensor]: list with the boxes found on each image. :math:`Bx(N,15)`.diff --git a/kornia/contrib/image_stitching.py b/kornia/contrib/image_stitching.pyindex 8622275a8..59ed420e7 100644--- a/kornia/contrib/image_stitching.py+++ b/kornia/contrib/image_stitching.py@@ -31,7 +31,7 @@ class ImageStitcher(nn.Module):"""Stitch images with overlapping fields of view.Convention:- - The images are RGB, :math:`(B, 3, H, W)`, all of one height, ordered left to right. ``matcher`` is a+ - The images are RGB, ``(B, 3, H, W)``, all of one height, ordered left to right. ``matcher`` is a:class:`~kornia.feature.LoFTR` or a :class:`~kornia.feature.LocalFeatureMatcher`, which gets grayscalecopies; any other matcher raises ``NotImplementedError``.- The panorama is in the first image's pixel frame and has its height: content that maps left of its first@@ -83,8 +83,8 @@ class ImageStitcher(nn.Module):"""Estimate homography by the matched keypoints.Args:- keypoints1: matched keypoint set from an image, shaped as :math:`(N, 2)`.- keypoints2: matched keypoint set from the other image, shaped as :math:`(N, 2)`.+ keypoints1: matched keypoint set from an image, shaped as ``(N, 2)``.+ keypoints2: matched keypoint set from the other image, shaped as ``(N, 2)``."""if self.estimator == "vanilla":@@ -201,9 +201,9 @@ class ImageStitcher(nn.Module):"""Stitch two images into a shared panorama frame.Args:- images_left: Reference image tensor, shaped :math:`(B, C, H, W_l)`.+ images_left: Reference image tensor, shaped ``(B, C, H, W_l)``.images_right: Image tensor to be warped onto the reference frame,- shaped :math:`(B, C, H, W_r)`.+ shaped ``(B, C, H, W_r)``.mask_left: Optional validity mask for ``images_left`` with the sameshape as ``images_left``.mask_right: Optional validity mask for ``images_right`` with the same@@ -258,7 +258,7 @@ class ImageStitcher(nn.Module):Args:*imgs: Ordered image tensors from left to right. Each tensor is expectedto share a common height and overlap with the next image.- Each tensor is RGB, :math:`(B, 3, H, W)`.+ Each tensor is RGB, ``(B, 3, H, W)``.Returns:A single panorama tensor obtained by stitching all provided imagesdiff --git a/kornia/contrib/kmeans.py b/kornia/contrib/kmeans.pyindex 678a5f959..dd235a878 100644--- a/kornia/contrib/kmeans.py+++ b/kornia/contrib/kmeans.py@@ -99,7 +99,7 @@ class KMeans:"""Return the current cluster centers.Returns:- A tensor with shape :math:`(C, D)`:+ A tensor with shape ``(C, D)``:- ``C`` is the number of clusters.- ``D`` is the feature dimension of each sample.@@ -121,7 +121,7 @@ class KMeans:"""Return cluster labels assigned during the most recent ``fit`` call.Returns:- A 1D tensor with shape :math:`(N,)`, where ``N`` is the number of+ A 1D tensor with shape ``(N,)``, where ``N`` is the number ofsamples given to :meth:`fit`. Each value is the cluster indexnearest to the corresponding sample in the final centers, matching:meth:`predict` on the training data even when fitting stops early.diff --git a/kornia/contrib/object_detection.py b/kornia/contrib/object_detection.pyindex cba5289dd..7e8e7ecff 100644--- a/kornia/contrib/object_detection.py+++ b/kornia/contrib/object_detection.py@@ -97,7 +97,7 @@ def results_from_detections("""Convert a detection torch.Tensor to a list of :py:class:`ObjectDetectorResult`.Args:- detections: torch.Tensor with shape :math:`(D, 6)`, where :math:`D` is the number of+ detections: torch.Tensor with shape ``(D, 6)``, where :math:`D` is the number ofdetections in the given image,:math:`6` represents class id, score, and `xywh` bounding box.format: detection format.@@ -168,11 +168,11 @@ class ObjectDetector(ModelBase, ONNXExportMixin):"""Detect objects in a given list of images.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``.Returns:- list of detections found in each image. For item in a batch, shape is :math:`(D, 6)`,+ list of detections found in each image. For item in a batch, shape is ``(D, 6)``,where :math:`D` is thenumber of detections in the given image, :math:`6` represents class id, score, and `xywh` bounding box.diff --git a/kornia/contrib/super_resolution.py b/kornia/contrib/super_resolution.pyindex 20f75bbe1..25aba45f4 100644--- a/kornia/contrib/super_resolution.py+++ b/kornia/contrib/super_resolution.py@@ -151,8 +151,8 @@ class SuperResolution(ModelBase[SuperResolutionConfig], ONNXExportMixin):"""Forward pass of the super resolution model.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``.Returns:output torch.Tensor.diff --git a/kornia/contrib/visual_prompter.py b/kornia/contrib/visual_prompter.pyindex 224af6f78..08259f731 100644--- a/kornia/contrib/visual_prompter.py+++ b/kornia/contrib/visual_prompter.py@@ -55,7 +55,7 @@ class VisualPrompter:At the moment, we just support the SAM model. The model is loaded based on the given config.- The prompter holds one image at a time: :meth:`set_image` takes a :math:`(3, H, W)` or :math:`(1, 3, H, W)` image,+ The prompter holds one image at a time: :meth:`set_image` takes a ``(3, H, W)`` or ``(1, 3, H, W)`` image,and :meth:`predict` then answers prompts on it. To segment a batch of images, each with its own prompts, use:meth:`kornia.models.sam.Sam.forward`.@@ -200,7 +200,7 @@ class VisualPrompter:it with the preprocess method.Args:- image: One RGB image, shape :math:`(3, H, W)` or :math:`(1, 3, H, W)`, in the dtype of the model. Normally+ image: One RGB image, shape ``(3, H, W)`` or ``(1, 3, H, W)``, in the dtype of the model. Normallyimages with range of [0-1], the model preprocess F.normalize the pixel values with the mean and stddefined in its initialization. A batch of more than one image raises; use:meth:`kornia.models.sam.Sam.forward` for batches.@@ -382,17 +382,17 @@ class VisualPrompter:"""Predict masks for the given image based on the input prompts.Args:- keypoints: Point prompts to the model. Each point is in (X,Y) in pixels. Shape :math:`(K, N, 2)`. Where+ keypoints: Point prompts to the model. Each point is in (X,Y) in pixels. Shape ``(K, N, 2)``. Where`N` is the number of points and `K` the number of prompts.keypoints_labels: Labels for the point prompts. 1 indicates a foreground point and 0 indicates a background- point. Shape :math:`(K, N)`. Where `N` is the number of points, and `K` the number of+ point. Shape ``(K, N)``. Where `N` is the number of points, and `K` the number ofprompts. Required with `keypoints`.- boxes: Box prompts to the model, one per prompt: a torch.Tensor in xyxy mode, shape :math:`(K, 4)` or- :math:`(1, K, 4)`, whose corners are taken as given, or a :class:`~kornia.geometry.boxes.Boxes` of- shape :math:`(K, 4, 2)` or :math:`(1, K, 4, 2)`, read through ``to_tensor(mode="xyxy")``. `K` is+ boxes: Box prompts to the model, one per prompt: a torch.Tensor in xyxy mode, shape ``(K, 4)`` or+ ``(1, K, 4)``, whose corners are taken as given, or a :class:`~kornia.geometry.boxes.Boxes` of+ shape ``(K, 4, 2)`` or ``(1, K, 4, 2)``, read through ``to_tensor(mode="xyxy")``. `K` isthe number of prompts.masks: A low resolution mask input to the model, typically coming from a previous prediction- iteration. Has shape :math:`(K, 1, H, W)`, where for SAM, H=W=256.+ iteration. Has shape ``(K, 1, H, W)``, where for SAM, H=W=256.multimask_output: If true, the model will return three masks. For ambiguous input prompts (such as asingle click), this will often produce better masks than a single prediction. If onlya single mask is needed, the model's predicted quality score can be used to select thediff --git a/kornia/core/check.py b/kornia/core/check.pyindex 140fad9d0..a41c12041 100644--- a/kornia/core/check.py+++ b/kornia/core/check.py@@ -836,7 +836,7 @@ def KORNIA_CHECK_IS_COLOR(x: torch.Tensor, msg: Optional[CheckMessage] = None, rraises: bool indicating whether an exception should be raised upon failure.Raises:- ImageError: if the input tensor does not have a shape :math:`(3,H,W)` and raises is True.+ ImageError: if the input tensor does not have a shape ``(3,H,W)`` and raises is True.Note:Checks can be disabled in Python mode using `disable_checks()` or the KORNIA_CHECKS@@ -874,7 +874,7 @@ def KORNIA_CHECK_IS_GRAY(x: torch.Tensor, msg: Optional[CheckMessage] = None, raraises: bool indicating whether an exception should be raised upon failure.Raises:- ImageError: if the tensor does not have a shape :math:`(1,H,W)` or :math:`(H,W)` and raises is True.+ ImageError: if the tensor does not have a shape ``(1,H,W)`` or ``(H,W)`` and raises is True.Note:Checks can be disabled in Python mode using `disable_checks()` or the KORNIA_CHECKS@@ -912,7 +912,7 @@ def KORNIA_CHECK_IS_COLOR_OR_GRAY(x: torch.Tensor, msg: Optional[CheckMessage] =raises: bool indicating whether an exception should be raised upon failure.Raises:- ImageError: if the tensor does not have a shape :math:`(1,H,W)` or :math:`(3,H,W)` and raises is True.+ ImageError: if the tensor does not have a shape ``(1,H,W)`` or ``(3,H,W)`` and raises is True.Note:Checks can be disabled in Python mode using `disable_checks()` or the KORNIA_CHECKS@@ -950,7 +950,7 @@ def KORNIA_CHECK_IS_IMAGE() -> bool:"""Check whether a tensor is a color or gray image with values in [0, 1] for float or [0, 2 ** bits - 1] for int.- The shape must be :math:`(*, 3, H, W)` or :math:`(*, 1, H, W)`. A NaN value fails the range check, and an empty+ The shape must be ``(*, 3, H, W)`` or ``(*, 1, H, W)``. A NaN value fails the range check, and an emptyimage passes it.Args:@@ -1075,7 +1075,7 @@ def KORNIA_CHECK_LAF(laf: torch.Tensor, raises: bool = True) -> bool:"""Check whether a Local Affine Frame (laf) has a valid shape.Convention:- - Only the shape :math:`(B, N, 2, 3)` is checked: any dtype and any values pass, ``N = 0`` included. Use+ - Only the shape ``(B, N, 2, 3)`` is checked: any dtype and any values pass, ``N = 0`` included. Use:func:`~kornia.feature.laf_is_valid` to check the values.- With ``raises=False``, a wrong shape returns ``False`` instead of raising.@@ -1084,7 +1084,7 @@ def KORNIA_CHECK_LAF(laf: torch.Tensor, raises: bool = True) -> bool:raises: bool indicating whether an exception should be raised upon failure.Raises:- ShapeError: if the input laf does not have a shape :math:`(B,N,2,3)` and raises is True.+ ShapeError: if the input laf does not have a shape ``(B,N,2,3)`` and raises is True.Note:Checks can be disabled in Python mode using `disable_checks()` or the KORNIA_CHECKSdiff --git a/kornia/core/mixin/image_module.py b/kornia/core/mixin/image_module.pyindex 8f41499b0..f04c36c05 100644--- a/kornia/core/mixin/image_module.py+++ b/kornia/core/mixin/image_module.py@@ -96,8 +96,8 @@ class ImageModuleMixIn:This modules accepts multiple input and output data types, provides end-to-end visualization, file saving features.Note that this MixIn fits the classes that return one image tensor only.- Non-tensor inputs are converted by :meth:`to_tensor`: a NumPy array of shape :math:`(H, W)`, :math:`(H, W, C)`- or :math:`(B, H, W, C)`, a PIL image or an image path becomes a :math:`(C, H, W)` or :math:`(B, C, H, W)` tensor.+ Non-tensor inputs are converted by :meth:`to_tensor`: a NumPy array of shape ``(H, W)``, ``(H, W, C)``+ or ``(B, H, W, C)``, a PIL image or an image path becomes a ``(C, H, W)`` or ``(B, C, H, W)`` tensor.An integer image is scaled by the maximum of its dtype (``uint8`` by 255, ``uint16`` by 65535; a signed image keepsits negative values), a ``bool`` image becomes 0 and 1, and a floating image keeps its values. Tensors pass throughunchanged. For an :class:`torch.nn.Module` with state, converted inputs use the device of its first parameter (or@@ -267,9 +267,9 @@ class ImageModuleMixIn:def to_tensor(self, x: Any) -> torch.Tensor:"""Convert input to tensor.- Supports image path, numpy array, PIL image, and raw tensor. A NumPy array of shape :math:`(H, W)`,- :math:`(H, W, C)` or :math:`(B, H, W, C)` becomes :math:`(C, H, W)` or :math:`(B, C, H, W)`, with one channel- for :math:`(H, W)`; a PIL image converts like its NumPy array, except that a palette image (mode ``P`` or+ Supports image path, numpy array, PIL image, and raw tensor. A NumPy array of shape ``(H, W)``,+ ``(H, W, C)`` or ``(B, H, W, C)`` becomes ``(C, H, W)`` or ``(B, C, H, W)``, with one channel+ for ``(H, W)``; a PIL image converts like its NumPy array, except that a palette image (mode ``P`` or``PA``) is converted to RGB, or RGBA when it has transparency, first. A path is loaded with:func:`kornia.io.load_image` as ``ImageLoadType.UNCHANGED``, which keeps 16-bit data and alpha, except thatan 8-bit palette PNG converts like its PIL image, to RGB, or RGBA when it has a ``tRNS`` chunk. An integer image@@ -338,10 +338,10 @@ class ImageModuleMixIn:def to_numpy(self, x: Any) -> "np.array":"""Convert input to numpy array.- A :math:`(C, H, W)` or :math:`(B, C, H, W)` tensor becomes a channels-last :math:`(H, W, C)` or- :math:`(B, H, W, C)` array with the same values, the layout :meth:`to_tensor` accepts, so a floating array+ A ``(C, H, W)`` or ``(B, C, H, W)`` tensor becomes a channels-last ``(H, W, C)`` or+ ``(B, H, W, C)`` array with the same values, the layout :meth:`to_tensor` accepts, so a floating arrayconverts back to the same tensor. A tensor of any other rank keeps its shape. Every 3-D or 4-D tensor is taken- to be an image, so a non-image element of a tuple output, such as a :math:`(B, N, 4)` box tensor, is moved to+ to be an image, so a non-image element of a tuple output, such as a ``(B, N, 4)`` box tensor, is moved tochannels-last too. :class:`~kornia.augmentation.container.AugmentationSequential` knows its outputs: itconverts its images and masks only, and rejects ``output_type="numpy"`` / ``"pil"`` when its data keys holdboxes, keypoints or labels. A ``bfloat16`` tensor becomes a ``float32`` array, since NumPy has no ``bfloat16``.@@ -372,7 +372,7 @@ class ImageModuleMixIn:"""Convert input to PIL image.A floating image is clamped to ``[0, 1]`` and rounded to 8 bits on the CPU; a ``uint8`` image keeps its- values. A one-channel image becomes a mode ``"L"`` image, and a :math:`(B, C, H, W)` batch a list of images.+ values. A one-channel image becomes a mode ``"L"`` image, and a ``(B, C, H, W)`` batch a list of images.Other integer and ``bool`` images convert only with one channel (PIL modes ``"I"``, ``"I;16"`` and ``"1"``).Args:diff --git a/kornia/core/ops.py b/kornia/core/ops.pyindex 083026be7..df0c42c59 100644--- a/kornia/core/ops.py+++ b/kornia/core/ops.py@@ -79,14 +79,14 @@ def eye_like(n: int, input: torch.Tensor, shared_memory: bool = False) -> torch.r"""Return a 2-D tensor with ones on the diagonal and zeros elsewhere with the same batch size as the input.Args:- n: the number of rows :math:`(N)`, a positive integer: an ``int``, a NumPy integer or a 0-d integer tensor.+ n: the number of rows :math:`N`, a positive integer: an ``int``, a NumPy integer or a 0-d integer tensor.A ``float`` or a ``bool`` is rejected.input: image tensor that will determine the batch size of the output matrix.- The expected shape is :math:`(B, *)`.+ The expected shape is ``(B, *)``.shared_memory: when set, all samples in the batch will share the same memory.Returns:- The identity matrix with the same batch size as the input :math:`(B, N, N)`.+ The identity matrix with the same batch size as the input ``(B, N, N)``.Raises:TypeCheckError: if ``n`` is not an integer.@@ -111,14 +111,14 @@ def vec_like(n: int, tensor: torch.Tensor, shared_memory: bool = False) -> torchr"""Return a 2-D tensor with a vector containing zeros with the same batch size as the input.Args:- n: the number of rows :math:`(N)`, a positive integer: an ``int``, a NumPy integer or a 0-d integer tensor.+ n: the number of rows :math:`N`, a positive integer: an ``int``, a NumPy integer or a 0-d integer tensor.A ``float`` or a ``bool`` is rejected.tensor: image tensor that will determine the batch size of the output matrix.- The expected shape is :math:`(B, *)`.+ The expected shape is ``(B, *)``.shared_memory: when set, all samples in the batch will share the same memory.Returns:- The vector with the same batch size as the input :math:`(B, N, 1)`.+ The vector with the same batch size as the input ``(B, N, 1)``.Raises:TypeCheckError: if ``n`` is not an integer.diff --git a/kornia/core/utils.py b/kornia/core/utils.pyindex eb20deb20..7def1b06e 100644--- a/kornia/core/utils.py+++ b/kornia/core/utils.py@@ -591,12 +591,12 @@ def safe_solve_with_mask(B: torch.Tensor, A: torch.Tensor) -> Tuple[torch.Tensorany parameter they share with an invalid one) stays finite.Args:- B: right-hand side of shape :math:`(*, N, K)` or :math:`(*, N)`.- A: square matrices of shape :math:`(*, N, N)`.+ B: right-hand side of shape ``(*, N, K)`` or ``(*, N)``.+ A: square matrices of shape ``(*, N, N)``.Returns:- The solution :math:`(*, N, K)`, the LU factor of the solved matrices :math:`(*, N, N)` and the- validity mask :math:`(*)`.+ The solution ``(*, N, K)``, the LU factor of the solved matrices ``(*, N, N)`` and the+ validity mask ``(*)``."""# Based on https://github.com/pytorch/pytorch/issues/31546#issuecomment-694135622KORNIA_CHECK_IS_TENSOR(B, "B must be torch.Tensor")@@ -647,10 +647,10 @@ def safe_inverse_with_mask(A: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]share with an invalid one) stays finite.Args:- A: square matrices of shape :math:`(*, N, N)`.+ A: square matrices of shape ``(*, N, N)``.Returns:- The inverse :math:`(*, N, N)` and the validity mask :math:`(*)`.+ The inverse ``(*, N, N)`` and the validity mask ``(*)``."""KORNIA_CHECK_IS_TENSOR(A, "A must be torch.Tensor")diff --git a/kornia/enhance/adjust.py b/kornia/enhance/adjust.pyindex 61d81c77a..828a163ae 100644--- a/kornia/enhance/adjust.py+++ b/kornia/enhance/adjust.py@@ -157,12 +157,12 @@ def adjust_saturation_with_gray_subtraction(image: torch.Tensor, factor: Union[fthis is just a convenience function to have compatibility with PilArgs:- image: Image/torch.Tensor to be adjusted in the shape of :math:`(*, 3, H, W)`.+ image: Image/torch.Tensor to be adjusted in the shape of ``(*, 3, H, W)``.factor: How much to adjust the saturation. 0 will give a blackand white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.Return:- Adjusted image in the shape of :math:`(*, 3, H, W)`.+ Adjusted image in the shape of ``(*, 3, H, W)``.Example:>>> x = torch.ones(1, 3, 3, 3)@@ -216,12 +216,12 @@ def adjust_saturation(image: torch.Tensor, factor: Union[float, torch.Tensor]) -The image is expected to be an RGB image in the range of [0, 1].Args:- image: Image/torch.Tensor to be adjusted in the shape of :math:`(*, 3, H, W)`.+ image: Image/torch.Tensor to be adjusted in the shape of ``(*, 3, H, W)``.factor: How much to adjust the saturation. 0 will give a blackand white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.Return:- Adjusted image in the shape of :math:`(*, 3, H, W)`.+ Adjusted image in the shape of ``(*, 3, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/image_enhancement.html>`__.@@ -323,14 +323,14 @@ def adjust_hue(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torchThe image is expected to be an RGB image in the range of [0, 1].Args:- image: Image to be adjusted in the shape of :math:`(*, 3, H, W)`.+ image: Image to be adjusted in the shape of ``(*, 3, H, W)``.factor: How much to shift the hue channel. Should be in [-PI, PI]. PIand -PI give complete reversal of hue channel in HSV space in positive and negativedirection respectively. 0 means no shift. Therefore, both -PI and PI will give animage with complementary colors while 0 gives the original image.Return:- Adjusted image in the shape of :math:`(*, 3, H, W)`.+ Adjusted image in the shape of ``(*, 3, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/image_enhancement.html>`__.@@ -372,14 +372,14 @@ def adjust_gamma(The input image is expected to be in the range of [0, 1].Args:- input: Image to be adjusted in the shape of :math:`(*, H, W)`.+ input: Image to be adjusted in the shape of ``(*, H, W)``.gamma: Non negative real number, same as y\gammay in the equation.gamma larger than 1 make the shadows darker, while gamma smaller than 1 makedark regions lighter.gain: The constant multiplier.Return:- Adjusted image in the shape of :math:`(*, H, W)`.+ Adjusted image in the shape of ``(*, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/image_enhancement.html>`__.@@ -505,7 +505,7 @@ def adjust_contrast(image: torch.Tensor, factor: Union[float, torch.Tensor], clihttps://scikit-image.org/docs/dev/auto_examples/color_exposure/plot_log_gamma.html#sphx-glr-auto-examples-color-exposure-plot-log-gamma-pyArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.factor: Contrast adjust factor per elementin the batch. 0 generates a completely black image, 1 does not modifythe input image while any other non-negative number modify the@@ -513,7 +513,7 @@ def adjust_contrast(image: torch.Tensor, factor: Union[float, torch.Tensor], cliclip_output: whether to clip the output image with range of [0, 1].Return:- Adjusted image in the shape of :math:`(*, H, W)`.+ Adjusted image in the shape of ``(*, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/image_enhancement.html>`__.@@ -573,13 +573,13 @@ def adjust_contrast_with_mean_subtraction(image: torch.Tensor, factor: Union[flodefinition of image contrast adjustment consider using :func:`kornia.enhance.adjust_gamma`.Args:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.factor: Contrast adjust factor per elementin the batch. 0 gives a uniform image at the mean gray level, 1 does not modifythe input image and a larger factor increases the contrast.Return:- Adjusted image in the shape of :math:`(*, H, W)`.+ Adjusted image in the shape of ``(*, H, W)``.Example:>>> import torch@@ -641,14 +641,14 @@ def adjust_brightness(https://scikit-image.org/docs/dev/auto_examples/color_exposure/plot_log_gamma.html#sphx-glr-auto-examples-color-exposure-plot-log-gamma-pyArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.factor: Brightness adjust factor per element in the batch. It's recommended tobound the factor by [0, 1]. 0 does not modify the input image while any othernumber modify the brightness.clip_output: Whether to clip output to be in [0,1].Return:- Adjusted torch.Tensor in the shape of :math:`(*, H, W)`.+ Adjusted torch.Tensor in the shape of ``(*, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/image_enhancement.html>`__.@@ -702,14 +702,14 @@ def adjust_brightness_accumulative(The input image and factor is expected to be in the range of [0, 1].Args:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.factor: Brightness factor per element in the batch. The image is multiplied by it, so ``1``leaves an image in ``[0, 1]`` unchanged, ``0`` gives a black image and a factor above ``1``brightens it.clip_output: Whether to clip output to be in [0,1].Return:- Adjusted torch.Tensor in the shape of :math:`(*, H, W)`.+ Adjusted torch.Tensor in the shape of ``(*, H, W)``.Example:>>> x = torch.ones(1, 1, 2, 2)@@ -759,13 +759,13 @@ def adjust_sigmoid(image: torch.Tensor, cutoff: float = 0.5, gain: float = 10, ihttp://markfairchild.org/PDFs/PAP07.pdfArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.cutoff: The cutoff of sigmoid function.gain: The multiplier of sigmoid function.inv: If is set to True the function will return the inverse sigmoid correction.Returns:- Adjusted torch.Tensor in the shape of :math:`(*, H, W)`.+ Adjusted torch.Tensor in the shape of ``(*, H, W)``.Example:>>> x = torch.ones(1, 1, 2, 2)@@ -793,13 +793,13 @@ def adjust_log(image: torch.Tensor, gain: float = 1, inv: bool = False, clip_out[1]: http://www.ece.ucsb.edu/Faculty/Manjunath/courses/ece178W03/EnhancePart1.pdfArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.gain: The multiplier of logarithmic function.inv: If is set to True the function will return the inverse logarithmic correction.clip_output: Whether to clip the output image with range of [0, 1].Returns:- Adjusted torch.Tensor in the shape of :math:`(*, H, W)`.+ Adjusted torch.Tensor in the shape of ``(*, H, W)``.Example:>>> x = torch.zeros(1, 1, 2, 2)@@ -872,7 +872,7 @@ def solarize(``[0.3, 0.4, 0.2, 0.0]``. The value of 'addition' is in the closed range [-0.5, 0.5].Args:- input: image torch.Tensor with shapes like :math:`(*, C, H, W)` to solarize.+ input: image torch.Tensor with shapes like ``(*, C, H, W)`` to solarize.thresholds: solarize thresholds.If int or one element torch.Tensor, input will be solarized across the whole batch.If 1-d torch.Tensor, input will be solarized element-wise, len(thresholds) == len(input).@@ -882,7 +882,7 @@ def solarize(If 1-d torch.Tensor, additions will be added element-wisely, len(additions) == len(input).Returns:- The solarized images with shape :math:`(*, C, H, W)`.+ The solarized images with shape ``(*, C, H, W)``... note::The range check on ``additions`` reads a float or a CPU tensor during the call and raises@@ -967,7 +967,7 @@ def posterize(input: torch.Tensor, bits: Union[int, torch.Tensor]) -> torch.TensNon-differentiable function, ``torch.uint8`` involved.Args:- input: image torch.Tensor with shape :math:`(*, C, H, W)` to posterize.+ input: image torch.Tensor with shape ``(*, C, H, W)`` to posterize.bits: number of high bits. Must be in range [0, 8].If int or one-element torch.Tensor, the same bits value is used across the whole batch.A 1-d tensor with multiple elements specifies one value per sample, not per channel;@@ -978,7 +978,7 @@ def posterize(input: torch.Tensor, bits: Union[int, torch.Tensor]) -> torch.Tensmatch the corresponding leading dimensions of the normalized ``(B, C, H, W)`` input.Returns:- Image with reduced color channels with shape :math:`(*, C, H, W)`.+ Image with reduced color channels with shape ``(*, C, H, W)``.Example:>>> x = torch.rand(1, 6, 3, 3)@@ -1072,7 +1072,7 @@ def sharpness(input: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.https://github.com/tensorflow/tpu/blob/master/models/official/efficientnet/autoaugment.py#L326Args:- input: image torch.Tensor with shape :math:`(*, C, H, W)` to sharpen.+ input: image torch.Tensor with shape ``(*, C, H, W)`` to sharpen.factor: blend factor between the smoothed copy and the input. ``0`` returns the smoothed image,``1`` returns the input, and a factor above ``1`` sharpens. It is not validated: ``0`` andnegative factors are accepted and extrapolate past the smoothed image.@@ -1082,7 +1082,7 @@ def sharpness(input: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.when ``B`` is greater than one.Returns:- Sharpened image or images with shape :math:`(*, C, H, W)`.+ Sharpened image or images with shape ``(*, C, H, W)``.Example:>>> x = torch.rand(1, 1, 5, 5)@@ -1218,10 +1218,10 @@ def equalize(input: torch.Tensor) -> torch.Tensor:https://github.com/tensorflow/tpu/blob/5f71c12a020403f863434e96982a840578fdd127/models/official/efficientnet/autoaugment.py#L355Args:- input: image torch.Tensor to equalize with shape :math:`(*, C, H, W)`.+ input: image torch.Tensor to equalize with shape ``(*, C, H, W)``.Returns:- Equalized image torch.Tensor with shape :math:`(*, C, H, W)`.+ Equalized image torch.Tensor with shape ``(*, C, H, W)``... note::The input is expected as a floating-point image in :math:`[0, 1]`, and each channel is equalized from@@ -1260,14 +1260,14 @@ def equalize3d(input: torch.Tensor) -> torch.Tensor:https://github.com/tensorflow/tpu/blob/master/models/official/efficientnet/autoaugment.py#L352Args:- input: image torch.Tensor with shape :math:`(*, C, D, H, W)` to equalize.+ input: image torch.Tensor with shape ``(*, C, D, H, W)`` to equalize.Returns:Equalized volume with the same shape as the input... note::The input is expected as a floating-point volume in :math:`[0, 1]`, and each channel's whole- :math:`(D, H, W)` volume is equalized from one 256-bin histogram. The lookup step is an integer+ ``(D, H, W)`` volume is equalized from one 256-bin histogram. The lookup step is an integerdivision by 255, so a volume with no more than 255 voxels per channel is returned unchanged up tofloating-point roundoff; just above that, whether it changes depends on the values. An integer orboolean volume raises :exc:`~kornia.core.exceptions.TypeCheckError`, as for :func:`equalize`. Values@@ -1334,8 +1334,8 @@ class AdjustSaturation(nn.Module):and white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.Shape:- - Input: Image/torch.Tensor to be adjusted in the shape of :math:`(*, 3, H, W)`.- - Output: Adjusted image in the shape of :math:`(*, 3, H, W)`.+ - Input: Image/torch.Tensor to be adjusted in the shape of ``(*, 3, H, W)``.+ - Output: Adjusted image in the shape of ``(*, 3, H, W)``.Example:>>> x = torch.ones(1, 3, 3, 3)@@ -1371,7 +1371,7 @@ class AdjustSaturation(nn.Module):"""Adjust RGB saturation using the module's configured factor.Args:- input: Input RGB tensor, typically shaped :math:`(*, 3, H, W)`.+ input: Input RGB tensor, typically shaped ``(*, 3, H, W)``.Returns:Saturation-adjusted tensor with the same shape as ``input``.@@ -1395,8 +1395,8 @@ class AdjustSaturationWithGraySubtraction(nn.Module):and white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.Shape:- - Input: Image/torch.Tensor to be adjusted in the shape of :math:`(*, 3, H, W)`.- - Output: Adjusted image in the shape of :math:`(*, 3, H, W)`.+ - Input: Image/torch.Tensor to be adjusted in the shape of ``(*, 3, H, W)``.+ - Output: Adjusted image in the shape of ``(*, 3, H, W)``.Example:>>> x = torch.ones(1, 3, 3, 3)@@ -1435,7 +1435,7 @@ class AdjustSaturationWithGraySubtraction(nn.Module):which follows PIL-like saturation behavior.Args:- input: Input image tensor, typically shaped :math:`(*, 3, H, W)`.+ input: Input image tensor, typically shaped ``(*, 3, H, W)``.Returns:Saturation-adjusted tensor with the same shape as ``input``.@@ -1461,8 +1461,8 @@ class AdjustHue(nn.Module):image with complementary colors while 0 gives the original image.Shape:- - Input: Image/torch.Tensor to be adjusted in the shape of :math:`(*, 3, H, W)`.- - Output: Adjusted image in the shape of :math:`(*, 3, H, W)`.+ - Input: Image/torch.Tensor to be adjusted in the shape of ``(*, 3, H, W)``.+ - Output: Adjusted image in the shape of ``(*, 3, H, W)``.Example:>>> x = torch.ones(1, 3, 3, 3)@@ -1498,7 +1498,7 @@ class AdjustHue(nn.Module):Args:input: Input RGB tensor in the expected image range, usually shaped- :math:`(*, 3, H, W)`.+ ``(*, 3, H, W)``.Returns:Hue-adjusted tensor with the same shape as ``input``.@@ -1521,8 +1521,8 @@ class AdjustGamma(nn.Module):gain: The constant multiplier.Shape:- - Input: Image to be adjusted in the shape of :math:`(*, N)`.- - Output: Adjusted image in the shape of :math:`(*, N)`.+ - Input: Image to be adjusted in the shape of ``(*, N)``.+ - Output: Adjusted image in the shape of ``(*, N)``.Example:>>> x = torch.ones(1, 1, 3, 3)@@ -1549,7 +1549,7 @@ class AdjustGamma(nn.Module):Args:input: Input tensor to correct, commonly image-shaped- :math:`(*, C, H, W)`.+ ``(*, C, H, W)``.Returns:Gamma-corrected tensor with the same shape as ``input``.@@ -1573,8 +1573,8 @@ class AdjustContrast(nn.Module):brightness by this factor.Shape:- - Input: Image/Input to be adjusted in the shape of :math:`(*, N)`.- - Output: Adjusted image in the shape of :math:`(*, N)`.+ - Input: Image/Input to be adjusted in the shape of ``(*, N)``.+ - Output: Adjusted image in the shape of ``(*, N)``.Example:>>> x = torch.ones(1, 1, 3, 3)@@ -1598,7 +1598,7 @@ class AdjustContrast(nn.Module):"""Adjust contrast using the configured contrast factor.Args:- input: Input tensor to adjust, typically shaped :math:`(*, C, H, W)`.+ input: Input tensor to adjust, typically shaped ``(*, C, H, W)``.Returns:Contrast-adjusted tensor with the same shape as ``input``.@@ -1623,8 +1623,8 @@ class AdjustContrastWithMeanSubtraction(nn.Module):the input image and a larger factor increases the contrast.Shape:- - Input: Image/Input to be adjusted in the shape of :math:`(*, N)`.- - Output: Adjusted image in the shape of :math:`(*, N)`.+ - Input: Image/Input to be adjusted in the shape of ``(*, N)``.+ - Output: Adjusted image in the shape of ``(*, N)``.Example:>>> x = torch.ones(1, 1, 3, 3)@@ -1651,7 +1651,7 @@ class AdjustContrastWithMeanSubtraction(nn.Module):applies PIL-like contrast behavior.Args:- input: Input tensor to adjust, typically shaped :math:`(*, C, H, W)`.+ input: Input tensor to adjust, typically shaped ``(*, C, H, W)``.Returns:Contrast-adjusted tensor with the same shape as ``input``.@@ -1674,8 +1674,8 @@ class AdjustBrightness(nn.Module):brightness.Shape:- - Input: Image/Input to be adjusted in the shape of :math:`(*, N)`.- - Output: Adjusted image in the shape of :math:`(*, N)`.+ - Input: Image/Input to be adjusted in the shape of ``(*, N)``.+ - Output: Adjusted image in the shape of ``(*, N)``.Example:>>> x = torch.ones(1, 1, 3, 3)@@ -1699,7 +1699,7 @@ class AdjustBrightness(nn.Module):"""Adjust image brightness using the configured brightness factor.Args:- input: Input tensor to adjust, commonly shaped :math:`(*, C, H, W)`.+ input: Input tensor to adjust, commonly shaped ``(*, C, H, W)``.Returns:Brightness-adjusted tensor with the same shape as ``input``.@@ -1720,7 +1720,7 @@ class AdjustSigmoid(nn.Module):http://markfairchild.org/PDFs/PAP07.pdfArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.cutoff: The cutoff of sigmoid function.gain: The multiplier of sigmoid function.inv: If is set to True the function will return the negative sigmoid correction.@@ -1744,7 +1744,7 @@ class AdjustSigmoid(nn.Module):Args:image: Input image tensor to remap, typically shaped- :math:`(*, C, H, W)` or :math:`(*, H, W)`.+ ``(*, C, H, W)`` or ``(*, H, W)``.Returns:Tensor with sigmoid correction applied, preserving input shape.@@ -1764,7 +1764,7 @@ class AdjustLog(nn.Module):[1]: http://www.ece.ucsb.edu/Faculty/Manjunath/courses/ece178W03/EnhancePart1.pdfArgs:- image: Image to be adjusted in the shape of :math:`(*, H, W)`.+ image: Image to be adjusted in the shape of ``(*, H, W)``.gain: The multiplier of logarithmic function.inv: If is set to True the function will return the inverse logarithmic correction.clip_output: Whether to clip the output image with range of [0, 1].@@ -1788,7 +1788,7 @@ class AdjustLog(nn.Module):Args:image: Input image tensor to transform, typically shaped- :math:`(*, C, H, W)` or :math:`(*, H, W)`.+ ``(*, C, H, W)`` or ``(*, H, W)``.Returns:Log-corrected tensor with the same shape as ``image``.@@ -1812,8 +1812,8 @@ class AdjustBrightnessAccumulative(nn.Module):and a factor above ``1`` brightens it.Shape:- - Input: Image/Input to be adjusted in the shape of :math:`(*, N)`.- - Output: Adjusted image in the shape of :math:`(*, N)`.+ - Input: Image/Input to be adjusted in the shape of ``(*, N)``.+ - Output: Adjusted image in the shape of ``(*, N)``.Example:>>> x = torch.ones(1, 1, 3, 3)@@ -1837,7 +1837,7 @@ class AdjustBrightnessAccumulative(nn.Module):"""Adjust brightness with accumulative (PIL-like) behavior.Args:- input: Input tensor to adjust, commonly shaped :math:`(*, C, H, W)`.+ input: Input tensor to adjust, commonly shaped ``(*, C, H, W)``.Returns:Brightness-adjusted tensor with the same shape as ``input``.diff --git a/kornia/enhance/equalization.py b/kornia/enhance/equalization.pyindex c6bb557f0..ee6522c56 100644--- a/kornia/enhance/equalization.py+++ b/kornia/enhance/equalization.py@@ -196,7 +196,7 @@ def _spread_residual(residual: torch.Tensor, num_bins: int) -> torch.Tensor:by tens of levels.Args:- residual: residual per tile, shape :math:`(T,)`, below ``num_bins``.+ residual: residual per tile, shape ``(T,)``, below ``num_bins``.num_bins: number of histogram bins.Returns:@@ -500,7 +500,7 @@ def equalize_clahe(values are not rounded to 8-bit integers.Args:- input: images tensor to equalize with values in the range [0, 1] and shape :math:`(*, C, H, W)`.+ input: images tensor to equalize with values in the range [0, 1] and shape ``(*, C, H, W)``.clip_limit: threshold value for contrast limiting. If 0 clipping is disabled.grid_size: number of tiles to be cropped in each direction (GH, GW). Each image axis must be largerthan its grid size; otherwise a ``ValueError`` names the smallest image the grid admits.diff --git a/kornia/enhance/histogram.py b/kornia/enhance/histogram.pyindex 9dfdea33b..7211a957f 100644--- a/kornia/enhance/histogram.py+++ b/kornia/enhance/histogram.py@@ -123,7 +123,7 @@ def histogram(x: torch.Tensor, bins: torch.Tensor, bandwidth: torch.Tensor, epsiThe calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter.Args:- x: Input torch.Tensor to compute the histogram with shape :math:`(B, D)`.+ x: Input torch.Tensor to compute the histogram with shape ``(B, D)``.bins: The bin centers, with shape :math:`(N_{bins})`.bandwidth: Gaussian smoothing factor with shape shape [1].epsilon: A scalar, for numerical stability.@@ -165,8 +165,8 @@ def histogram2d(The calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter.Args:- x1: Input torch.Tensor to compute the histogram with shape :math:`(B, D)`.- x2: Input torch.Tensor to compute the histogram with shape :math:`(B, D)`.+ x1: Input torch.Tensor to compute the histogram with shape ``(B, D)``.+ x2: Input torch.Tensor to compute the histogram with shape ``(B, D)``.bins: The bin centers, with shape :math:`(N_{bins})`.bandwidth: Gaussian smoothing factor with shape shape [1].epsilon: A scalar, for numerical stability. Default: 1e-10.@@ -262,7 +262,7 @@ def image_histogram2d(Args:image: Input torch.Tensor to compute the histogram with shape- :math:`(H, W)`, :math:`(C, H, W)` or :math:`(B, C, H, W)`.+ ``(H, W)``, ``(C, H, W)`` or ``(B, C, H, W)``.min: Lower end of the interval (inclusive).max: Upper end of the interval (inclusive). Ignored when:attr:`centers` is specified.diff --git a/kornia/enhance/integral.py b/kornia/enhance/integral.pyindex 84a9916c7..d3e390143 100644--- a/kornia/enhance/integral.py+++ b/kornia/enhance/integral.py@@ -37,11 +37,11 @@ def integral_tensor(input: torch.Tensor, dim: Optional[Tuple[int, ...]] = None)and within the dimensions of the input torch.Tensor.Args:- input: the input torch.Tensor with shape :math:`(*, D)`. Where D is the number of dimensions.+ input: the input torch.Tensor with shape ``(*, D)``. Where D is the number of dimensions.dim: the dimension to be summed.Returns:- Integral torch.Tensor for the input torch.Tensor with shape :math:`(*, D)`.+ Integral torch.Tensor for the input torch.Tensor with shape ``(*, D)``.Examples:>>> input = torch.ones(3, 5)@@ -86,10 +86,10 @@ def integral_image(image: torch.Tensor) -> torch.Tensor:This particular version sums over the last two dimensions.Args:- image: the input image torch.Tensor with shape :math:`(*, H, W)`.+ image: the input image torch.Tensor with shape ``(*, H, W)``.Returns:- Integral torch.Tensor for the input image torch.Tensor with shape :math:`(*, H, W)`.+ Integral torch.Tensor for the input image torch.Tensor with shape ``(*, H, W)``.Examples:>>> input = torch.ones(1, 5, 5)@@ -114,14 +114,14 @@ class IntegralTensor(nn.Module):See :func:`integral_tensor` for axis order and validation behavior.Args:- image: the input torch.Tensor with shape :math:`(B,C,H,W)`.+ image: the input torch.Tensor with shape ``(B,C,H,W)``.Returns:- Integral torch.Tensor for the input torch.Tensor with shape :math:`(B,C,H,W)`.+ Integral torch.Tensor for the input torch.Tensor with shape ``(B,C,H,W)``.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.ones(3, 5)@@ -162,14 +162,14 @@ class IntegralImage(nn.Module):This particular version sums over the last two dimensions.Args:- image: the input image torch.Tensor with shape :math:`(B,C,H,W)`.+ image: the input image torch.Tensor with shape ``(B,C,H,W)``.Returns:- Integral torch.Tensor for the input image torch.Tensor with shape :math:`(B,C,H,W)`.+ Integral torch.Tensor for the input image torch.Tensor with shape ``(B,C,H,W)``.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.ones(1, 5, 5)@@ -188,7 +188,7 @@ class IntegralImage(nn.Module):Args:input: Tensor whose last two dimensions represent spatial axes,- typically shaped :math:`(*, H, W)`.+ typically shaped ``(*, H, W)``.Returns:A tensor of the same shape as ``input`` where each location storesdiff --git a/kornia/enhance/jpeg.py b/kornia/enhance/jpeg.pyindex 5842cc9a0..c806b7411 100644--- a/kornia/enhance/jpeg.py+++ b/kornia/enhance/jpeg.py@@ -167,10 +167,10 @@ def _patchify_8x8(input: torch.Tensor) -> torch.Tensor:"""Extract non-overlapping 8 x 8 patches from the given input image.Args:- input (torch.Tensor): Input image of the shape :math:`(B, H, W)`.+ input (torch.Tensor): Input image of the shape ``(B, H, W)``.Returns:- output (torch.Tensor): Image patchify of the shape :math:`(B, N, 8, 8)`.+ output (torch.Tensor): Image patchify of the shape ``(B, N, 8, 8)``."""# Get input shape@@ -184,12 +184,12 @@ def _unpatchify_8x8(input: torch.Tensor, H: int, W: int) -> torch.Tensor:"""Reverse non-overlapping 8 x 8 patching.Args:- input (torch.Tensor): Input image of the shape :math:`(B, N, 8, 8)`.+ input (torch.Tensor): Input image of the shape ``(B, N, 8, 8)``.H: height of resulting torch.Tensor.W: width of resulting torch.Tensor.Returns:- output (torch.Tensor): Image patchify of the shape :math:`(B, H, W)`.+ output (torch.Tensor): Image patchify of the shape ``(B, H, W)``."""# Get input shape@@ -203,10 +203,10 @@ def _dct_8x8(input: torch.Tensor) -> torch.Tensor:"""Perform an 8 x 8 discrete cosine transform.Args:- input (torch.Tensor): Patched input torch.tensor of the shape :math:`(B, N, 8, 8)`.+ input (torch.Tensor): Patched input torch.tensor of the shape ``(B, N, 8, 8)``.Returns:- output (torch.Tensor): DCT output torch.tensor of the shape :math:`(B, N, 8, 8)`.+ output (torch.Tensor): DCT output torch.tensor of the shape ``(B, N, 8, 8)``."""# Get dtype and device@@ -222,10 +222,10 @@ def _idct_8x8(input: torch.Tensor) -> torch.Tensor:"""Perform an 8 x 8 inverse discrete cosine transform.Args:- input (torch.Tensor): Patched input torch.tensor of the shape :math:`(B, N, 8, 8)`.+ input (torch.Tensor): Patched input torch.tensor of the shape ``(B, N, 8, 8)``.Returns:- output (torch.Tensor): IDCT output torch.tensor of the shape :math:`(B, N, 8, 8)`.+ output (torch.Tensor): IDCT output torch.tensor of the shape ``(B, N, 8, 8)``."""dtype = input.dtype@@ -290,12 +290,12 @@ def _quantize("""Perform quantization.Args:- input (torch.Tensor): Input torch.tensor of the shape :math:`(B, N, 8, 8)`.- jpeg_quality (torch.Tensor): Compression strength to be applied, shape is :math:`(B)`.- quantization_table (torch.Tensor): Quantization table of the shape :math:`(1, 8, 8)` or :math:`(B, 8, 8)`.+ input (torch.Tensor): Input torch.tensor of the shape ``(B, N, 8, 8)``.+ jpeg_quality (torch.Tensor): Compression strength to be applied, shape is ``(B)``.+ quantization_table (torch.Tensor): Quantization table of the shape ``(1, 8, 8)`` or ``(B, 8, 8)``.Returns:- output (torch.Tensor): Quantized output torch.tensor of the shape :math:`(B, N, 8, 8)`.+ output (torch.Tensor): Quantized output torch.tensor of the shape ``(B, N, 8, 8)``."""# Scale quantization table@@ -319,12 +319,12 @@ def _dequantize("""Perform dequantization.Args:- input (torch.Tensor): Input torch.tensor of the shape :math:`(B, N, 8, 8)`.- jpeg_quality (torch.Tensor): Compression strength to be applied, shape is :math:`(B)`.- quantization_table (torch.Tensor): Quantization table of the shape :math:`(1, 8, 8)` or :math:`(B, 8, 8)`.+ input (torch.Tensor): Input torch.tensor of the shape ``(B, N, 8, 8)``.+ jpeg_quality (torch.Tensor): Compression strength to be applied, shape is ``(B)``.+ quantization_table (torch.Tensor): Quantization table of the shape ``(1, 8, 8)`` or ``(B, 8, 8)``.Returns:- output (torch.Tensor): Quantized output torch.tensor of the shape :math:`(B, N, 8, 8)`.+ output (torch.Tensor): Quantized output torch.tensor of the shape ``(B, N, 8, 8)``."""# Scale quantization table@@ -342,12 +342,12 @@ def _chroma_subsampling(input_ycbcr: torch.Tensor) -> tuple[torch.Tensor, torch."""Implement chroma subsampling.Args:- input_ycbcr (torch.Tensor): YCbCr input torch.tensor of the shape :math:`(B, 3, H, W)`.+ input_ycbcr (torch.Tensor): YCbCr input torch.tensor of the shape ``(B, 3, H, W)``.Returns:- output_y (torch.Tensor): Y component (not-subsampled), shape is :math:`(B, H, W)`.- output_cb (torch.Tensor): Cb component (subsampled), shape is :math:`(B, H // 2, W // 2)`.- output_cr (torch.Tensor): Cr component (subsampled), shape is :math:`(B, H // 2, W // 2)`.+ output_y (torch.Tensor): Y component (not-subsampled), shape is ``(B, H, W)``.+ output_cb (torch.Tensor): Cb component (subsampled), shape is ``(B, H // 2, W // 2)``.+ output_cr (torch.Tensor): Cr component (subsampled), shape is ``(B, H // 2, W // 2)``."""# Get components@@ -378,10 +378,10 @@ def _chroma_upsampling(input_c: torch.Tensor) -> torch.Tensor:"""Perform chroma upsampling.Args:- input_c (torch.Tensor): Cb or Cr component to be upsampled of the shape :math:`(B, H, W)`.+ input_c (torch.Tensor): Cb or Cr component to be upsampled of the shape ``(B, H, W)``.Returns:- output_c (torch.Tensor): Upsampled C(b or r) component of the shape :math:`(B, H * 2, W * 2)`.+ output_c (torch.Tensor): Upsampled C(b or r) component of the shape ``(B, H * 2, W * 2)``."""# Upsample component. The size is explicit: ``rescale`` computes it with float arithmetic, which freezes the@@ -396,7 +396,7 @@ def _chroma_upsampling(input_c: torch.Tensor) -> torch.Tensor:def _split_cb_cr(input_cb_cr: torch.Tensor, n_patches: int) -> tuple[torch.Tensor, torch.Tensor]:- """Split the concatenated Cb and Cr patches of the shape :math:`(B, 2N, 8, 8)` into two :math:`(B, N, 8, 8)`.+ """Split the concatenated Cb and Cr patches of the shape :math:`(B, 2N, 8, 8)` into two ``(B, N, 8, 8)``.This is ``chunk(2, dim=1)`` with the half size passed in: ``chunk`` exports as a ``SplitToSequence`` with asymbolic size, which the ONNX optimizer cannot fold when the image size is dynamic.@@ -413,15 +413,15 @@ def _jpeg_encode("""Perform JPEG encoding.Args:- image_rgb (torch.Tensor): RGB input images of the shape :math:`(B, 3, H, W)`.- jpeg_quality (torch.Tensor): Compression strength of the shape :math:`(B)`.+ image_rgb (torch.Tensor): RGB input images of the shape ``(B, 3, H, W)``.+ jpeg_quality (torch.Tensor): Compression strength of the shape ``(B)``.quantization_table_y (torch.Tensor): Quantization table for Y channel.quantization_table_c (torch.Tensor): Quantization table for C channels.Returns:- y_encoded (torch.Tensor): Encoded Y component of the shape :math:`(B, N, 8, 8)`.- cb_encoded (torch.Tensor): Encoded Cb component of the shape :math:`(B, N, 8, 8)`.- cr_encoded (torch.Tensor): Encoded Cr component of the shape :math:`(B, N, 8, 8)`.+ y_encoded (torch.Tensor): Encoded Y component of the shape ``(B, N, 8, 8)``.+ cb_encoded (torch.Tensor): Encoded Cb component of the shape ``(B, N, 8, 8)``.+ cr_encoded (torch.Tensor): Encoded Cr component of the shape ``(B, N, 8, 8)``."""# Convert RGB image to YCbCr.@@ -467,17 +467,17 @@ def _jpeg_decode("""Perform JPEG decoding.Args:- input_y (torch.Tensor): Compressed Y component of the shape :math:`(B, N, 8, 8)`.- input_cb (torch.Tensor): Compressed Cb component of the shape :math:`(B, N, 8, 8)`.- input_cr (torch.Tensor): Compressed Cr component of the shape :math:`(B, N, 8, 8)`.- jpeg_quality (torch.Tensor): Compression strength of the shape :math:`(B)`.+ input_y (torch.Tensor): Compressed Y component of the shape ``(B, N, 8, 8)``.+ input_cb (torch.Tensor): Compressed Cb component of the shape ``(B, N, 8, 8)``.+ input_cr (torch.Tensor): Compressed Cr component of the shape ``(B, N, 8, 8)``.+ jpeg_quality (torch.Tensor): Compression strength of the shape ``(B)``.H (int): Original image height.W (int): Original image width.quantization_table_y (torch.Tensor): Quantization table for Y channel.quantization_table_c (torch.Tensor): Quantization table for C channels.Returns:- rgb_decoded (torch.Tensor): Decompressed RGB image of the shape :math:`(B, 3, H, W)`.+ rgb_decoded (torch.Tensor): Decompressed RGB image of the shape ``(B, 3, H, W)``."""# Dequantize inputs@@ -512,7 +512,7 @@ def _perform_padding(image: torch.Tensor) -> tuple[torch.Tensor, int, int]:"""Pad a given image to be dividable by 16.Args:- image: Image of the shape :math:`(*, 3, H, W)`.+ image: Image of the shape ``(*, 3, H, W)``.Returns:image_padded: Padded image of the shape :math:`(*, 3, H_{new}, W_{new})`.@@ -590,13 +590,13 @@ def jpeg_codec_differentiable(quantization table.Shape:- - input: :math:`(*, 3, H, W)`.- - jpeg_quality: :math:`(1)` or :math:`(B)` (if used batch dim. needs to match w/ input).- - quantization_table_y: :math:`(8, 8)` or :math:`(B, 8, 8)` (if used batch dim. needs to match w/ input).- - quantization_table_c: :math:`(8, 8)` or :math:`(B, 8, 8)` (if used batch dim. needs to match w/ input).+ - input: ``(*, 3, H, W)``.+ - jpeg_quality: ``(1)`` or ``(B)`` (if used batch dim. needs to match w/ input).+ - quantization_table_y: ``(8, 8)`` or ``(B, 8, 8)`` (if used batch dim. needs to match w/ input).+ - quantization_table_c: ``(8, 8)`` or ``(B, 8, 8)`` (if used batch dim. needs to match w/ input).Return:- JPEG coded image of the shape :math:`(B, 3, H, W)`+ JPEG coded image of the shape ``(B, 3, H, W)``Example:To perform JPEG coding with the standard quantization tables just provide a JPEG quality@@ -794,10 +794,10 @@ class JPEGCodecDifferentiable(nn.Module):quantization table.Shape:- - quantization_table_y: :math:`(8, 8)` or :math:`(B, 8, 8)` (if used batch dim. needs to match w/ image_rgb).- - quantization_table_c: :math:`(8, 8)` or :math:`(B, 8, 8)` (if used batch dim. needs to match w/ image_rgb).- - image_rgb: :math:`(*, 3, H, W)`.- - jpeg_quality: :math:`(1)` or :math:`(B)` (if used batch dim. needs to match w/ image_rgb).+ - quantization_table_y: ``(8, 8)`` or ``(B, 8, 8)`` (if used batch dim. needs to match w/ image_rgb).+ - quantization_table_c: ``(8, 8)`` or ``(B, 8, 8)`` (if used batch dim. needs to match w/ image_rgb).+ - image_rgb: ``(*, 3, H, W)``.+ - jpeg_quality: ``(1)`` or ``(B)`` (if used batch dim. needs to match w/ image_rgb).Example:You can use the differentiable JPEG module with standard quantization tables by@@ -861,7 +861,7 @@ class JPEGCodecDifferentiable(nn.Module):the codec computes in before encoding/decoding.Args:- image_rgb: Input RGB tensor with shape :math:`(*, 3, H, W)`.+ image_rgb: Input RGB tensor with shape ``(*, 3, H, W)``.jpeg_quality: JPEG quality factor with shape (1,) or (N,), N being the number of images.Returns:diff --git a/kornia/enhance/normalize.py b/kornia/enhance/normalize.pyindex 57ee5cd89..146e28b62 100644--- a/kornia/enhance/normalize.py+++ b/kornia/enhance/normalize.py@@ -51,15 +51,15 @@ class Normalize(nn.Module):.. math::\text{input[channel] = (input[channel] - mean[channel]) / std[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:mean: Mean for each channel.std: Standard deviations for each channel.Shape:- - Input: Image torch.Tensor of size :math:`(B, C, *)`.- - Output: Normalised torch.Tensor with same size as input :math:`(B, C, *)`.+ - Input: Image torch.Tensor of size ``(B, C, *)``.+ - Output: Normalised torch.Tensor with same size as input ``(B, C, *)``.Note:An integer or bool input is converted to torch's default floating dtype first; see :func:`normalize`.@@ -103,7 +103,7 @@ class Normalize(nn.Module):``mean`` and ``std`` values stored in the module constructor.Args:- input: Tensor to normalize, typically with shape :math:`(*, C, ...)`,+ input: Tensor to normalize, typically with shape ``(*, C, ...)``,where ``*`` represents optional leading dimensions (for examplebatch) and ``C`` is the channel dimension.@@ -140,15 +140,15 @@ def normalize(data: torch.Tensor, mean: torch.Tensor, std: torch.Tensor) -> torc.. math::\text{input[channel] = (input[channel] - mean[channel]) / std[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:- data: Image torch.Tensor of size :math:`(B, C, *)`.+ data: Image torch.Tensor of size ``(B, C, *)``.mean: Mean for each channel.std: Standard deviations for each channel.Return:- Normalised torch.Tensor with same size as input :math:`(B, C, *)`.+ Normalised torch.Tensor with same size as input ``(B, C, *)``.Note:An integer or bool ``data`` is converted to torch's default floating dtype (float32 unless changed) before@@ -230,15 +230,15 @@ class Denormalize(nn.Module):.. math::\text{input[channel] = (input[channel] * std[channel]) + mean[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:mean: Mean for each channel.std: Standard deviations for each channel.Shape:- - Input: Image torch.Tensor of size :math:`(B, C, *)`.- - Output: Denormalised torch.Tensor with same size as input :math:`(B, C, *)`.+ - Input: Image torch.Tensor of size ``(B, C, *)``.+ - Output: Denormalised torch.Tensor with same size as input ``(B, C, *)``.Note:An integer or bool input is converted to torch's default floating dtype first; see :func:`denormalize`.@@ -278,7 +278,7 @@ class Denormalize(nn.Module):``mean`` and ``std`` parameters.Args:- input: Tensor to denormalize, commonly shaped :math:`(*, C, ...)`+ input: Tensor to denormalize, commonly shaped ``(*, C, ...)``with channel dimension ``C``.Returns:@@ -315,15 +315,15 @@ def denormalize(data: torch.Tensor, mean: Union[torch.Tensor, float], std: Union.. math::\text{input[channel] = (input[channel] * std[channel]) + mean[channel]}- Where `mean` is :math:`(M_1, ..., M_n)` and `std` :math:`(S_1, ..., S_n)` for `n` channels,+ Where `mean` is :math:`(M_1, \ldots, M_n)` and `std` :math:`(S_1, \ldots, S_n)` for `n` channels,Args:- data: Image torch.Tensor of size :math:`(B, C, *)`.+ data: Image torch.Tensor of size ``(B, C, *)``.mean: Mean for each channel.std: Standard deviations for each channel.Return:- Denormalised torch.Tensor with same size as input :math:`(B, C, *)`.+ Denormalised torch.Tensor with same size as input ``(B, C, *)``.Note:An integer or bool ``data`` is converted to torch's default floating dtype (float32 unless changed) before@@ -415,13 +415,13 @@ def normalize_min_max(where :math:`a` is :math:`\text{min_val}` and :math:`b` is :math:`\text{max_val}`.Args:- input: The image torch.Tensor to be normalised with shape :math:`(*, C, H, W)`.+ input: The image torch.Tensor to be normalised with shape ``(*, C, H, W)``.min_val: The minimum value for the new range.max_val: The maximum value for the new range.eps: Float number to avoid zero division.Returns:- The normalised image torch.Tensor with same shape as input :math:`(*, C, H, W)`.+ The normalised image torch.Tensor with same shape as input ``(*, C, H, W)``.Example:>>> x = torch.rand(1, 5, 3, 3)diff --git a/kornia/enhance/rescale.py b/kornia/enhance/rescale.pyindex f3d3b8ae8..bbd74a7a3 100644--- a/kornia/enhance/rescale.py+++ b/kornia/enhance/rescale.py@@ -49,7 +49,7 @@ class Rescale(nn.Module):Args:input: Tensor to be rescaled. In image workflows this is commonly- shaped as :math:`(*, C, H, W)`, where ``*`` denotes optional+ shaped as ``(*, C, H, W)``, where ``*`` denotes optionalleading dimensions (for example batch), ``C`` is channel count,and ``H``/``W`` are spatial dimensions.diff --git a/kornia/enhance/threshold.py b/kornia/enhance/threshold.pyindex f26aff12a..8aafeeb92 100644--- a/kornia/enhance/threshold.py+++ b/kornia/enhance/threshold.py@@ -194,7 +194,7 @@ class Threshold(Module):Args:input: Input tensor to threshold. Typical image inputs are shaped- :math:`(*, C, H, W)`, but any tensor shape supported by+ ``(*, C, H, W)``, but any tensor shape supported by:func:`threshold` is accepted.Returns:diff --git a/kornia/feature/adalam/adalam.py b/kornia/feature/adalam/adalam.pyindex bd00655d0..373e28ab0 100644--- a/kornia/feature/adalam/adalam.py+++ b/kornia/feature/adalam/adalam.py@@ -88,21 +88,21 @@ def match_adalam(normalized coordinates, so inverse confidence stays finite even for an exact fit.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.- lafs1: LAFs of a shape :math:`(1, B1, 2, 3)`.- lafs2: LAFs of a shape :math:`(1, B2, 2, 3)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.+ lafs1: LAFs of a shape ``(1, B1, 2, 3)``.+ lafs2: LAFs of a shape ``(1, B2, 2, 3)``.config: dict with AdaLAM configdm: torch.Tensor containing the non-negative distances (not squared) from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`. Smaller is better.+ to each descriptor in desc2, shape of ``(B1, B2)``. Smaller is better.hw1: size of the first image, ``(H, W)`` or ``(W, H)``.hw2: size of the second image, ``(H, W)`` or ``(W, H)``.Return:- - Inverse local RANSAC confidence of each match, float32, shape of :math:`(B3, 1)`; see the Convention+ - Inverse local RANSAC confidence of each match, float32, shape of ``(B3, 1)``; see the Conventionblock.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: :math:`(B3, 2)`,+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: ``(B3, 2)``,where 0 <= B3 <= B1."""diff --git a/kornia/feature/adalam/core.py b/kornia/feature/adalam/core.pyindex 6592227b9..5a2d277cb 100644--- a/kornia/feature/adalam/core.py+++ b/kornia/feature/adalam/core.py@@ -69,8 +69,8 @@ def _no_match(dm: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:"""Output empty tensors.Returns:- - Descriptor distance of matching descriptors, shape of :math:`(0, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of :math:`(0, 2)`.+ - Descriptor distance of matching descriptors, shape of ``(0, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of ``(0, 2)``."""dists = torch.empty(0, 1, device=dm.device, dtype=dm.dtype)diff --git a/kornia/feature/affine_shape.py b/kornia/feature/affine_shape.pyindex 5323170ad..9a3e59adb 100644--- a/kornia/feature/affine_shape.py+++ b/kornia/feature/affine_shape.py@@ -90,10 +90,10 @@ class PatchAffineShapeEstimator(nn.Module):"""Run forward.Args:- patch: :math:`(B, 1, H, W)`+ patch: ``(B, 1, H, W)``Returns:- torch.Tensor: ellipse_shape :math:`(B, 1, 3)`+ torch.Tensor: ellipse_shape ``(B, 1, 3)``"""KORNIA_CHECK_SHAPE(patch, ["B", "1", "H", "W"])@@ -231,11 +231,11 @@ class LAFAffineShapeEstimator(nn.Module):"""Run forward.Args:- laf: :math:`(B, N, 2, 3)`- img: :math:`(B, 1, H, W)`+ laf: ``(B, N, 2, 3)``+ img: ``(B, 1, H, W)``Returns:- LAF_out: :math:`(B, N, 2, 3)`+ LAF_out: ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(laf)@@ -334,11 +334,11 @@ class LAFAffNetShapeEstimator(nn.Module):"""Run forward.Args:- laf: :math:`(B, N, 2, 3)`- img: :math:`(B, 1, H, W)`+ laf: ``(B, N, 2, 3)``+ img: ``(B, 1, H, W)``Returns:- LAF_out: :math:`(B, N, 2, 3)`+ LAF_out: ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(laf)diff --git a/kornia/feature/aliked/aliked.py b/kornia/feature/aliked/aliked.pyindex caab70a77..d10aaac5e 100644--- a/kornia/feature/aliked/aliked.py+++ b/kornia/feature/aliked/aliked.py@@ -775,7 +775,7 @@ class ALIKED(nn.Module):running statistics on every call, and a single small image raises; call ``.eval()`` for inference.:meth:`from_pretrained` returns the trained model in evaluation mode.- ``images`` are RGB in :math:`[0, 1]`, the range of the pretrained weights, and the network applies no- normalisation; a :math:`(B, 1, H, W)` image is repeated to three channels. Any ``H`` and ``W`` work: the+ normalisation; a ``(B, 1, H, W)`` image is repeated to three channels. Any ``H`` and ``W`` work: theimage is replicate-padded around its centre to multiples of 32 and the maps are cropped back, so the paddingdoes not move the keypoints.- :meth:`forward` returns one :class:`ALIKEDFeatures` per image. Its keypoints are sub-pixel ``(x, y)`` in the@@ -794,7 +794,7 @@ class ALIKED(nn.Module):- ``image_size`` holds the valid ``(W, H)`` of each image of a batch padded at the bottom and right to acommon size: maxima closer than ``nms_radius`` pixels to that image's last valid row or column are dropped.- :meth:`forward_laf` returns padded tensors like :class:`~kornia.feature.LocalFeature`, but ``N`` is the- largest keypoint count in the batch and the responses are :math:`(B, N, 1)`. Its ``mask`` multiplies the+ largest keypoint count in the batch and the responses are ``(B, N, 1)``. Its ``mask`` multiplies thescore map, and it takes no ``image_size``.- Known defects: on CPU, float16 and bfloat16 score and feature maps go to torch's ``grid_sample`` withoutan upcast: the half-precision kernel can return wrong values, NaN or overflow, and where torch has none the@@ -1003,7 +1003,7 @@ class ALIKED(nn.Module):batched tensors.Args:- img: image to extract features with shape :math:`(B,C,H,W)`.+ img: image to extract features with shape ``(B,C,H,W)``.mask: optional spatial mask ``(B, 1, H, W)`` with values in``[0, 1]``; the score map is multiplied by this mask beforekeypoint detection so that features are suppressed in masked@@ -1015,9 +1015,9 @@ class ALIKED(nn.Module):call entirely (useful when only keypoint positions are needed).Returns:- - Detected local affine frames with shape :math:`(B,N,2,3)`.- - Response function values for corresponding LAFs with shape :math:`(B,N,1)`.- - Local descriptors of shape :math:`(B,N,D)`.+ - Detected local affine frames with shape ``(B,N,2,3)``.+ - Response function values for corresponding LAFs with shape ``(B,N,1)``.+ - Local descriptors of shape ``(B,N,D)``."""if img.shape[1] == 1:diff --git a/kornia/feature/dedode/decoder.py b/kornia/feature/dedode/decoder.pyindex 36700c4da..d4ab6c68e 100644--- a/kornia/feature/dedode/decoder.py+++ b/kornia/feature/dedode/decoder.py@@ -43,7 +43,7 @@ class Decoder(nn.Module):r"""Run this DeDoDe module forward.Args:- features: Encoded feature map with shape :math:`(B, C, H, W)`, or concatenated with context.+ features: Encoded feature map with shape ``(B, C, H, W)``, or concatenated with context.context: Optional context feature map from previous scale, shape:math:`(B, C_{\text{ctx}}, H, W)`, or ``None``.scale: String key selecting the decoder layer for this scale (e.g. ``"8"``, ``"4"``, ``"2"``, ``"1"``).diff --git a/kornia/feature/dedode/dedode.py b/kornia/feature/dedode/dedode.pyindex 6d795dfe4..7895ebc2a 100644--- a/kornia/feature/dedode/dedode.py+++ b/kornia/feature/dedode/dedode.py@@ -153,7 +153,7 @@ class DeDoDe(nn.Module):"""Detect and describe keypoints in the input images.Args:- images: A torch.Tensor of shape :math:`(B, 3, H, W)` containing the RGB input images in the range+ images: A torch.Tensor of shape ``(B, 3, H, W)`` containing the RGB input images in the range:math:`[0, 1]`.n: The number of keypoints to detect.apply_imagenet_normalization: Whether to apply ImageNet normalization to the input images. Pass@@ -163,12 +163,12 @@ class DeDoDe(nn.Module):keypoints are never reported in it.Returns:- keypoints: A torch.Tensor of shape :math:`(B, N, 2)` containing the detected keypoints in the image range,+ keypoints: A torch.Tensor of shape ``(B, N, 2)`` containing the detected keypoints in the image range,unlike `.detect()` function.- scores: A torch.Tensor of shape :math:`(B, N)` containing the scores of the detected keypoints.+ scores: A torch.Tensor of shape ``(B, N)`` containing the scores of the detected keypoints.- descriptions: A torch.Tensor of shape :math:`(B, N, DIM)` containing the descriptions+ descriptions: A torch.Tensor of shape ``(B, N, DIM)`` containing the descriptionsof the detected keypoints. DIM is 256 for both B and G."""@@ -201,7 +201,7 @@ class DeDoDe(nn.Module):detector is only used at inference time and its statistics must be frozen.Args:- images: A torch.Tensor of shape :math:`(B, 3, H, W)` containing the RGB input images in the range+ images: A torch.Tensor of shape ``(B, 3, H, W)`` containing the RGB input images in the range:math:`[0, 1]`.n: The number of keypoints to detect.apply_imagenet_normalization: Whether to apply ImageNet normalization to the input images. Pass@@ -213,9 +213,9 @@ class DeDoDe(nn.Module):crop_w: The width of the crop to be used for detection. If None, the full image is used.Returns:- keypoints: A torch.Tensor of shape :math:`(B, N, 2)` containing the detected keypoints,+ keypoints: A torch.Tensor of shape ``(B, N, 2)`` containing the detected keypoints,normalized to the range :math:`[-1, 1]`.- scores: A torch.Tensor of shape :math:`(B, N)` containing the scores of the detected keypoints.+ scores: A torch.Tensor of shape ``(B, N)`` containing the scores of the detected keypoints."""KORNIA_CHECK_SHAPE(images, ["B", "3", "H", "W"])@@ -250,9 +250,9 @@ class DeDoDe(nn.Module):descriptor is only used at inference time and its statistics must be frozen.Args:- images: A torch.Tensor of shape :math:`(B, 3, H, W)` containing the RGB input images in the range+ images: A torch.Tensor of shape ``(B, 3, H, W)`` containing the RGB input images in the range:math:`[0, 1]`.- keypoints: An optional torch.Tensor of shape :math:`(B, N, 2)` containing the detected keypoints.+ keypoints: An optional torch.Tensor of shape ``(B, N, 2)`` containing the detected keypoints.apply_imagenet_normalization: Whether to apply ImageNet normalization to the input images. Pass``False`` if they are already ImageNet-normalized.pad_if_not_divisible: Zero-pad the (normalised) image on the bottom and right so that H and W are@@ -263,9 +263,9 @@ class DeDoDe(nn.Module):crop_w: The width of the crop to be used for description. If None, the full image is used.Returns:- descriptions: A torch.Tensor of shape :math:`(B, N, DIM)` containing the descriptions+ descriptions: A torch.Tensor of shape ``(B, N, DIM)`` containing the descriptionsof the detected keypoints.- If the dense descriptors are requested, the shape is :math:`(B, DIM, H, W)`.+ If the dense descriptors are requested, the shape is ``(B, DIM, H, W)``."""KORNIA_CHECK_SHAPE(images, ["B", "3", "H", "W"])diff --git a/kornia/feature/dedode/descriptor.py b/kornia/feature/dedode/descriptor.pyindex 9cca7e41c..0fc75d85f 100644--- a/kornia/feature/dedode/descriptor.py+++ b/kornia/feature/dedode/descriptor.py@@ -40,10 +40,10 @@ class DeDoDeDescriptor(nn.Module):"""Run this DeDoDe module forward.Args:- images: Input image batch with shape :math:`(B, C, H, W)`.+ images: Input image batch with shape ``(B, C, H, W)``.Returns:- Dense descriptor map with shape :math:`(B, D, H, W)`.+ Dense descriptor map with shape ``(B, D, H, W)``."""features, sizes = self.encoder(images)context = Nonediff --git a/kornia/feature/dedode/detector.py b/kornia/feature/dedode/detector.pyindex 49f919746..ee92eb440 100644--- a/kornia/feature/dedode/detector.py+++ b/kornia/feature/dedode/detector.py@@ -40,10 +40,10 @@ class DeDoDeDetector(nn.Module):"""Run this DeDoDe module forward.Args:- images: Input image batch with shape :math:`(B, C, H, W)`.+ images: Input image batch with shape ``(B, C, H, W)``.Returns:- Keypoint detection logits with shape :math:`(B, 1, H, W)`.+ Keypoint detection logits with shape ``(B, 1, H, W)``."""dtype = images.dtypefeatures, sizes = self.encoder(images)diff --git a/kornia/feature/dedode/encoder.py b/kornia/feature/dedode/encoder.pyindex 9c51e238b..7f651f3b8 100644--- a/kornia/feature/dedode/encoder.py+++ b/kornia/feature/dedode/encoder.py@@ -51,7 +51,7 @@ class VGG19(nn.Module):"""Run this DeDoDe module forward.Args:- x: Input image tensor with shape :math:`(B, 3, H, W)` (BGR or RGB).+ x: Input image tensor with shape ``(B, 3, H, W)`` (BGR or RGB).**kwargs: Additional keyword arguments accepted for compatibility with the shared encoder interface. Theyare not used by this VGG19 batch-normalized backbone wrapper.@@ -102,11 +102,11 @@ class FrozenDINOv2(nn.Module):backbone is cast to the dtype and device of ``x``, so the features come back in the dtype of ``x``.Args:- x: Input image tensor with shape :math:`(B, 3, H, W)`.+ x: Input image tensor with shape ``(B, 3, H, W)``.Returns:Tuple of ``([features_16], [(H//14, W//14)])`` where ``features_16`` has shape- :math:`(B, 1024, H/14, W/14)`.+ ``(B, 1024, H/14, W/14)``."""B, _C, H, W = x.shapeuse_amp = self.amp and x.is_cuda@@ -140,7 +140,7 @@ class VGG_DINOv2(nn.Module):"""Run this DeDoDe module forward.Args:- x: Input image tensor with shape :math:`(B, 3, H, W)`.+ x: Input image tensor with shape ``(B, 3, H, W)``.Returns:Tuple of combined ``(features, sizes)`` lists from the VGG19 and DINOv2 encoders.diff --git a/kornia/feature/dedode/transformer/dinov2.py b/kornia/feature/dedode/transformer/dinov2.pyindex ad8161874..622744a69 100644--- a/kornia/feature/dedode/transformer/dinov2.py+++ b/kornia/feature/dedode/transformer/dinov2.py@@ -209,7 +209,7 @@ class DinoVisionTransformer(nn.Module):"""Interpolate positional encodings to the current patch grid.Args:- x: Token sequence with class token prepended, shape :math:`(B, N+1, D)`.+ x: Token sequence with class token prepended, shape ``(B, N+1, D)``.w: Image width in pixels.h: Image height in pixels.@@ -245,11 +245,11 @@ class DinoVisionTransformer(nn.Module):"""Prepare image patch tokens before transformer encoding.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`.- masks: Optional boolean mask tensor with shape :math:`(B, N)` for masked patch tokens.+ x: Input image tensor with shape ``(B, C, H, W)``.+ masks: Optional boolean mask tensor with shape ``(B, N)`` for masked patch tokens.Returns:- Token sequence with class token, positional embeddings, and optional masks, shape :math:`(B, N+1, D)`.+ Token sequence with class token, positional embeddings, and optional masks, shape ``(B, N+1, D)``."""_B, _nc, w, h = x.shapex = self.patch_embed(x)@@ -263,8 +263,8 @@ class DinoVisionTransformer(nn.Module):"""Compute transformer features for one image tensor.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`.- masks: Optional boolean mask tensor with shape :math:`(B, N)` or ``None``.+ x: Input image tensor with shape ``(B, C, H, W)``.+ masks: Optional boolean mask tensor with shape ``(B, N)`` or ``None``.Returns:Feature dictionary with keys ``x_norm_clstoken``, ``x_norm_patchtokens``, ``x_prenorm``, and ``masks``.@@ -319,9 +319,9 @@ class DinoVisionTransformer(nn.Module):"""Return selected intermediate transformer layer outputs.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`.+ x: Input image tensor with shape ``(B, C, H, W)``.n: Number of last transformer blocks to return, or explicit list of block indices.- reshape: If ``True``, reshape patch tokens from :math:`(B, N, D)` to :math:`(B, D, H_p, W_p)`.+ reshape: If ``True``, reshape patch tokens from ``(B, N, D)`` to ``(B, D, H_p, W_p)``.return_class_token: If ``True``, return ``(patch_tokens, class_token)`` tuples.norm: If ``True``, apply layer normalization to each output.diff --git a/kornia/feature/dedode/transformer/layers/attention.py b/kornia/feature/dedode/transformer/layers/attention.pyindex c5de21c80..6836bd29f 100644--- a/kornia/feature/dedode/transformer/layers/attention.py+++ b/kornia/feature/dedode/transformer/layers/attention.py@@ -63,11 +63,11 @@ class Attention(nn.Module):"""Run this DeDoDe module forward.Args:- x: Input token sequence with shape :math:`(B, N, C)`, where ``B`` is batch size,+ x: Input token sequence with shape ``(B, N, C)``, where ``B`` is batch size,``N`` is number of tokens (patches + class token), and ``C`` is the embedding dimension.Returns:- Attention output with shape :math:`(B, N, C)`.+ Attention output with shape ``(B, N, C)``."""B, N, C = x.shapeqkv = self.qkv(x).reshape(B, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)@@ -95,11 +95,11 @@ class MemEffAttention(Attention):"""Run this DeDoDe module forward.Args:- x: Input token sequence with shape :math:`(B, N, C)`.+ x: Input token sequence with shape ``(B, N, C)``.attn_bias: Unsupported; must be ``None``.Returns:- Attention output with shape :math:`(B, N, C)`.+ Attention output with shape ``(B, N, C)``."""if attn_bias is not None:raise NotImplementedError("attn_bias is not supported")diff --git a/kornia/feature/dedode/transformer/layers/block.py b/kornia/feature/dedode/transformer/layers/block.pyindex 14f0b5b3f..e22db0e1b 100644--- a/kornia/feature/dedode/transformer/layers/block.py+++ b/kornia/feature/dedode/transformer/layers/block.py@@ -108,11 +108,11 @@ class Block(nn.Module):"""Run this DeDoDe module forward.Args:- x: Input token sequence with shape :math:`(B, N, C)`, where ``B`` is batch size,+ x: Input token sequence with shape ``(B, N, C)``, where ``B`` is batch size,``N`` is token count, and ``C`` is embedding dimension.Returns:- Output token sequence with the same shape :math:`(B, N, C)`.+ Output token sequence with the same shape ``(B, N, C)``."""def attn_residual_func(x: Tensor) -> Tensor:@@ -179,7 +179,7 @@ class NestedTensorBlock(Block):"""Run this DeDoDe module forward.Args:- x_or_x_list: A single token tensor with shape :math:`(B, N, C)`.+ x_or_x_list: A single token tensor with shape ``(B, N, C)``.Returns:Output token tensor with the same shape as the input.diff --git a/kornia/feature/dedode/transformer/layers/layer_scale.py b/kornia/feature/dedode/transformer/layers/layer_scale.pyindex 2db080f3b..6d9b701db 100644--- a/kornia/feature/dedode/transformer/layers/layer_scale.py+++ b/kornia/feature/dedode/transformer/layers/layer_scale.py@@ -52,9 +52,9 @@ class LayerScale(nn.Module):"""Run this DeDoDe module forward.Args:- x: Input token tensor with shape :math:`(B, N, C)`.+ x: Input token tensor with shape ``(B, N, C)``.Returns:- Tensor with the same shape :math:`(B, N, C)` scaled element-wise by the learnable ``gamma`` parameter.+ Tensor with the same shape ``(B, N, C)`` scaled element-wise by the learnable ``gamma`` parameter."""return x.mul_(self.gamma) if self.inplace else x * self.gammadiff --git a/kornia/feature/dedode/transformer/layers/patch_embed.py b/kornia/feature/dedode/transformer/layers/patch_embed.pyindex bd149e003..8487af0da 100644--- a/kornia/feature/dedode/transformer/layers/patch_embed.py+++ b/kornia/feature/dedode/transformer/layers/patch_embed.py@@ -88,12 +88,12 @@ class PatchEmbed(nn.Module):r"""Run this DeDoDe module forward.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`. ``H`` and ``W`` must be+ x: Input image tensor with shape ``(B, C, H, W)``. ``H`` and ``W`` must bemultiples of the patch height and width respectively.Returns:- Patch embeddings with shape :math:`(B, N_p, D)` when ``flatten_embedding=True``,- or :math:`(B, H_p, W_p, D)` when ``flatten_embedding=False``, where+ Patch embeddings with shape ``(B, N_p, D)`` when ``flatten_embedding=True``,+ or ``(B, H_p, W_p, D)`` when ``flatten_embedding=False``, where:math:`N_p = H_p \times W_p`."""_, _, H, W = x.shapediff --git a/kornia/feature/dedode/vgg.py b/kornia/feature/dedode/vgg.pyindex e0a50f5f0..916df42e9 100644--- a/kornia/feature/dedode/vgg.py+++ b/kornia/feature/dedode/vgg.py@@ -63,7 +63,7 @@ class VGG(nn.Module):r"""Run this DeDoDe module forward.Args:- x: Input image tensor with shape :math:`(B, 3, H, W)`.+ x: Input image tensor with shape ``(B, 3, H, W)``.Returns:Classification logits with shape :math:`(B, \text{num\_classes})`.diff --git a/kornia/feature/defmo.py b/kornia/feature/defmo.pyindex f72a4a0dc..b02eedc8d 100644--- a/kornia/feature/defmo.py+++ b/kornia/feature/defmo.py@@ -106,7 +106,7 @@ class Bottleneck(nn.Module):"""Run the bottleneck residual block.Args:- x: Feature tensor with shape :math:`(B, C, H, W)`, where ``B`` is batch+ x: Feature tensor with shape ``(B, C, H, W)``, where ``B`` is batchsize, ``C`` is channel count, and ``H``/``W`` are spatial dimensions.Returns:@@ -258,10 +258,10 @@ class ResNet(nn.Module):"""Run the ResNet backbone and classification head.Args:- x: Input image or feature tensor with shape :math:`(B, C, H, W)`.+ x: Input image or feature tensor with shape ``(B, C, H, W)``.Returns:- Tensor with shape :math:`(B, N)`, where ``N`` is ``num_classes``.+ Tensor with shape ``(B, N)``, where ``N`` is ``num_classes``."""return self._forward_impl(x)@@ -290,7 +290,7 @@ class EncoderDeFMO(nn.Module):"""Encode blurred-image and background inputs into latent features.Args:- input_data: Tensor with shape :math:`(B, 6, H, W)`. The 6 channels usually+ input_data: Tensor with shape ``(B, 6, H, W)``. The 6 channels usuallyconcatenate RGB blurred input and RGB background estimate.Returns:@@ -342,7 +342,7 @@ class RenderingDeFMO(nn.Module):Args:latent: Latent feature tensor from :class:`EncoderDeFMO` with shape- :math:`(B, C, H, W)`.+ ``(B, C, H, W)``.Returns:Tensor with shape :math:`(B, T, 4, H_{out}, W_{out})`, where ``T`` is the@@ -376,10 +376,10 @@ class DeFMO(nn.Module):of Fast Moving Objects". See :cite:`DeFMO2021` for more details.Convention:- - The input is :math:`(B, 6, H, W)`: the RGB channels of the blurred image, then those of the background+ - The input is ``(B, 6, H, W)``: the RGB channels of the blurred image, then those of the backgroundestimate, in :math:`[0, 1]` for the pretrained weights. ``H`` and ``W`` that are multiples of 16 give anoutput of the same size; other sizes give an output rounded up to the next multiples of 16.- - The output is :math:`(B, 24, 4, H, W)`: 24 sub-frames in time order, sub-frame ``k`` rendered at the time+ - The output is ``(B, 24, 4, H, W)``: 24 sub-frames in time order, sub-frame ``k`` rendered at the time``k / 23``, each with red, green, blue and alpha channels in :math:`[0, 1]` after a sigmoid.Args:@@ -416,11 +416,11 @@ class DeFMO(nn.Module):"""Deblur a fast-moving object into a sequence of RGBA sub-frames.Args:- input_data: Tensor with shape :math:`(B, 6, H, W)` containing the blurred+ input_data: Tensor with shape ``(B, 6, H, W)`` containing the blurredRGB image concatenated with an RGB background estimate.Returns:- Tensor with shape :math:`(B, T, 4, H, W)`, where ``T`` is the number of+ Tensor with shape ``(B, T, 4, H, W)``, where ``T`` is the number oftemporal sub-frames and 4 stores red, green, blue, and alpha channels."""latent = self.encoder(input_data)diff --git a/kornia/feature/disk/_unets/blocks.py b/kornia/feature/disk/_unets/blocks.pyindex 0dcb34bd3..abe6179ca 100644--- a/kornia/feature/disk/_unets/blocks.py+++ b/kornia/feature/disk/_unets/blocks.py@@ -32,7 +32,7 @@ class TrivialUpsample(nn.Module):"""Run this DISK component forward.Args:- x: Input feature map with shape :math:`(B, C, H, W)`.+ x: Input feature map with shape ``(B, C, H, W)``.Returns:Upsampled feature map with shape :math:`(B, C, 2H, 2W)`.@@ -50,10 +50,10 @@ class TrivialDownsample(nn.Module):"""Run this DISK component forward.Args:- x: Input feature map with shape :math:`(B, C, H, W)`.+ x: Input feature map with shape ``(B, C, H, W)``.Returns:- Downsampled feature map with shape :math:`(B, C, H/2, W/2)`.+ Downsampled feature map with shape ``(B, C, H/2, W/2)``."""return F.avg_pool2d(x, 2)diff --git a/kornia/feature/disk/detector.py b/kornia/feature/disk/detector.pyindex 7b12379ec..eab117f17 100644--- a/kornia/feature/disk/detector.py+++ b/kornia/feature/disk/detector.py@@ -30,7 +30,7 @@ def heatmap_to_keypoints("""Detect keypoints as the strict local maxima of a heatmap, in raster order.Args:- heatmap: detection logits of shape :math:`(B, 1, H, W)`.+ heatmap: detection logits of shape ``(B, 1, H, W)``.n: the maximum number of keypoints per image, counted among the maxima above ``score_threshold``. An imagewith ``n`` such maxima or fewer keeps all of them; with more, its ``n`` strongest, where maxima tied at the``n``-th score are taken in raster order (row by row, then column by column) until ``n`` are kept.diff --git a/kornia/feature/disk/disk.py b/kornia/feature/disk/disk.pyindex aa8f0317f..8734e86a5 100644--- a/kornia/feature/disk/disk.py+++ b/kornia/feature/disk/disk.py@@ -49,7 +49,7 @@ class DISK(nn.Module):.. image:: _static/img/disk_outdoor_depth.jpgConvention:- - ``images`` are RGB, :math:`(B, 3, H, W)`, which the U-Net sees as given, without normalisation. With the+ - ``images`` are RGB, ``(B, 3, H, W)``, which the U-Net sees as given, without normalisation. With thedefault U-Net, a common positive gain of the input, such as :math:`[0, 255]` instead of :math:`[0, 1]`,changes the outputs only through the instance norms' ``eps``, which weighs more the lower the image'scontrast. At ordinary contrast the maps barely change, though a keypoint can still swap where scores nearly@@ -74,7 +74,7 @@ class DISK(nn.Module):desc_dim: The dimension of the descriptor.unet: The U-Net to use. If None, a default U-Net is used. Kornia doesn't provide the training code for DISKso this is only useful when using a custom checkpoint trained using the code released with the paper.- The unet should take as input a torch.Tensor of shape :math:`(B, C, H, W)` and output+ The unet should take as input a torch.Tensor of shape ``(B, C, H, W)`` and outputa torch.Tensor of shape:math:`(B, \mathrm{desc\_dim} + 1, H, W)`.@@ -113,11 +113,11 @@ class DISK(nn.Module):.. image:: _static/img/DISK.pngArgs:- images: The image to detect features in. Shape :math:`(B, 3, H, W)`.+ images: The image to detect features in. Shape ``(B, 3, H, W)``.Returns:A tuple of dense detection scores and descriptors.- Shapes are :math:`(B, 1, H, W)` and :math:`(B, D, H, W)`, where+ Shapes are ``(B, 1, H, W)`` and ``(B, D, H, W)``, where:math:`D` is the descriptor dimension."""@@ -144,7 +144,7 @@ class DISK(nn.Module):"""Detect features in an image, returning keypoint locations, descriptors and detection scores.Args:- images: The image to detect features in. Shape :math:`(B, 3, H, W)`.+ images: The image to detect features in. Shape ``(B, 3, H, W)``.n: The maximum number of keypoints per image, counted among the maxima above ``score_threshold``. Animage with ``n`` such maxima or fewer keeps all of them; with more, its ``n`` strongest, where maximatied at the ``n``-th score are taken in raster order. If None, all keypoints are returned.diff --git a/kornia/feature/disk/structs.py b/kornia/feature/disk/structs.pyindex 73c3aaf61..654714d07 100644--- a/kornia/feature/disk/structs.py+++ b/kornia/feature/disk/structs.py@@ -35,9 +35,9 @@ class DISKFeatures:Convention block gives their frame and order.Args:- keypoints: torch.Tensor of shape :math:`(N, 2)`, where :math:`N` is the number of keypoints.- descriptors: torch.Tensor of shape :math:`(N, D)`, where :math:`D` is the descriptor dimension.- detection_scores: torch.Tensor of shape :math:`(N,)`, the detection heatmap value at each keypoint: a raw+ keypoints: torch.Tensor of shape ``(N, 2)``, where :math:`N` is the number of keypoints.+ descriptors: torch.Tensor of shape ``(N, D)``, where :math:`D` is the descriptor dimension.+ detection_scores: torch.Tensor of shape ``(N,)``, the detection heatmap value at each keypoint: a rawlogit of the network, not a log-probability."""diff --git a/kornia/feature/hardnet.py b/kornia/feature/hardnet.pyindex 76e22ca28..697175d4b 100644--- a/kornia/feature/hardnet.py+++ b/kornia/feature/hardnet.py@@ -72,8 +72,8 @@ class HardNet(nn.Module):torch.Tensor: HardNet descriptor of the patches.Shape:- - Input: :math:`(B, 1, 32, 32)`- - Output: :math:`(B, 128)`+ - Input: ``(B, 1, 32, 32)``+ - Output: ``(B, 128)``Examples:>>> input = torch.rand(16, 1, 32, 32)@@ -134,10 +134,10 @@ class HardNet(nn.Module):"""Compute HardNet descriptors for grayscale 32x32 patches.Args:- input: Grayscale patch tensor of shape :math:`(B, 1, 32, 32)`.+ input: Grayscale patch tensor of shape ``(B, 1, 32, 32)``.Returns:- L2-normalized descriptor tensor with shape :math:`(B, 128)`.+ L2-normalized descriptor tensor with shape ``(B, 128)``."""KORNIA_CHECK_SHAPE(input, ["B", "1", "32", "32"])x_norm: torch.Tensor = self._normalize_input(input)@@ -169,8 +169,8 @@ class HardNet8(nn.Module):torch.Tensor: HardNet8 descriptor of the patches.Shape:- - Input: :math:`(B, 1, 32, 32)`- - Output: :math:`(B, 128)`+ - Input: ``(B, 1, 32, 32)``+ - Output: ``(B, 128)``Examples:>>> input = torch.rand(16, 1, 32, 32)@@ -251,10 +251,10 @@ class HardNet8(nn.Module):"""Compute HardNet8 descriptors with PCA projection.Args:- input: Grayscale patch tensor of shape :math:`(B, 1, 32, 32)`.+ input: Grayscale patch tensor of shape ``(B, 1, 32, 32)``.Returns:- L2-normalized descriptor tensor with shape :math:`(B, 128)`, after the PCA projection.+ L2-normalized descriptor tensor with shape ``(B, 128)``, after the PCA projection."""KORNIA_CHECK_SHAPE(input, ["B", "1", "32", "32"])x_norm: torch.Tensor = self._normalize_input(input)diff --git a/kornia/feature/hynet.py b/kornia/feature/hynet.pyindex 4ef6258d2..4e3dc1041 100644--- a/kornia/feature/hynet.py+++ b/kornia/feature/hynet.py@@ -233,7 +233,7 @@ class HyNet(nn.Module):HyNet descriptor of the patches.Shape:- - Input: :math:`(B, 1, 32, 32)`+ - Input: ``(B, 1, 32, 32)``- Output: :math:`(B, \text{dim\_desc})`Note:diff --git a/kornia/feature/integrated.py b/kornia/feature/integrated.pyindex 772653e5a..a57a25ad3 100644--- a/kornia/feature/integrated.py+++ b/kornia/feature/integrated.py@@ -61,7 +61,7 @@ def _in_sift_layout(descriptors: torch.Tensor, layout: str) -> torch.Tensor:def _lightglue_keypoint_scale_ori(lafs: torch.Tensor, feature_name: str) -> Tuple[torch.Tensor, torch.Tensor]:- r"""Return the keypoint scales and orientations, shape :math:`(1, N)`, that LightGlue takes for ``lafs``.+ 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 whoseorientation is the image angle of the frame's x-axis in :math:`(-\pi, \pi]`: the negative of the LAF@@ -148,13 +148,13 @@ def get_laf_descriptors(final BatchNorm statistics in float32 for float16 images. The module keeps its device, dtype andparameters, 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 :math:`(B, 0, D)` result, ``D`` as wide as a non-empty result, and a warning.+ - 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 throughit.Args:- img: image features with shape :math:`(B,C,H,W)`.- lafs: local affine frames :math:`(B,N,2,3)`.+ img: image features with shape ``(B,C,H,W)``.+ lafs: local affine frames ``(B,N,2,3)``.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.@@ -162,7 +162,7 @@ def get_laf_descriptors(then converted to grayscale.Returns:- Local descriptors of shape :math:`(B,N,D)` where :math:`D` is descriptor size.+ Local descriptors of shape ``(B,N,D)`` where :math:`D` is descriptor size."""KORNIA_CHECK_LAF(lafs)@@ -237,11 +237,11 @@ class LAFDescriptor(nn.Module):r"""Describe the given LAFs with :func:`~kornia.feature.get_laf_descriptors`.Args:- img: image features with shape :math:`(B,C,H,W)`.- lafs: local affine frames :math:`(B,N,2,3)`.+ img: image features with shape ``(B,C,H,W)``.+ lafs: local affine frames ``(B,N,2,3)``.Returns:- Local descriptors of shape :math:`(B,N,D)` where :math:`D` is descriptor size.+ 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)@@ -253,7 +253,7 @@ class LocalFeature(nn.Module):Convention:- ``forward`` runs the detector, multiplies the shape ``A`` of every LAF by ``scaling_coef``(:func:`~kornia.feature.scale_laf`) and describes the scaled LAFs. It returns ``(lafs, responses, descs)``- with shapes :math:`(B, N, 2, 3)`, :math:`(B, N)` and :math:`(B, N, D)`: the scaled LAFs, in the frame of+ with shapes ``(B, N, 2, 3)``, ``(B, N)`` and ``(B, N, D)``: the scaled LAFs, in the frame of:func:`~kornia.feature.laf_from_center_scale_ori` (see :ref:`Local features <local-features-conventions>`),the detector's responses and one descriptor per LAF. ``scaling_coef`` leaves the centres and the responsesunchanged.@@ -297,14 +297,14 @@ class LocalFeature(nn.Module):"""Run forward.Args:- img: image to extract features with shape :math:`(B,C,H,W)`.- mask: a mask saying where a detection may be, shape :math:`(B,1,H,W)` with the spatial size of the+ 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 theimage. It is forwarded to the detector unchanged; see the detector for its semantics.Returns:- - Detected local affine frames with shape :math:`(B,N,2,3)`.- - Response function values for corresponding lafs with shape :math:`(B,N)`.- - Local descriptors of shape :math:`(B,N,D)` where :math:`D` is descriptor size.+ - 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.@@ -360,7 +360,7 @@ class SIFTFeature(_SIFTFeature):Convention:- A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of one grayscale- image per call, :math:`(1, 1, H, W)`. The detector is a :class:`~kornia.feature.MultiResolutionDetector` on+ image per call, ``(1, 1, H, W)``. The detector is a :class:`~kornia.feature.MultiResolutionDetector` onthe 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@@ -434,7 +434,7 @@ class SIFTFeatureScaleSpace(LocalFeature):Convention:- A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale- images :math:`(B, 1, H, W)`; the pyramid backend converts an RGB image to grayscale first.+ 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 wellas maxima, then ``LAFOrienter(19)`` unless ``upright``, and :class:`~kornia.feature.SIFTDescriptor` on 41 x@@ -531,7 +531,7 @@ class GFTTAffNetHardNet(LocalFeature):Convention:A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale- images :math:`(B, 1, H, W)`: a :class:`~kornia.feature.ScaleSpaceDetector` with the+ 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 affineshape 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.@@ -568,7 +568,7 @@ class HesAffNetHardNet(LocalFeature):Convention:A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of grayscale- images :math:`(B, 1, H, W)`: a :class:`~kornia.feature.ScaleSpaceDetector` with the+ 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 affineshape 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.@@ -633,7 +633,7 @@ class DoGHardNet(LocalFeature)::class:`~kornia.feature.HardNet` describes them on 32 x 32 patches.- These are the frames the ``"doghardnet"`` weights of :class:`~kornia.feature.LightGlueMatcher` expect: passthe LAFs and descriptors, without the padded slots, to ``LightGlueMatcher("doghardnet")``.- - The image must have one channel, :math:`(B, 1, H, W)`: convert a color image with+ - The image must have one channel, ``(B, 1, H, W)``: convert a color image with:func:`~kornia.color.rgb_to_grayscale` first.Args:@@ -667,7 +667,7 @@ class DoGAffNetHardNet(LocalFeature):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, thesquare root of their determinant, is again 12 sigma. Pass the LAFs and descriptors, without the padded slots,- to ``LightGlueMatcher("dog_affnet_hardnet")``. The image must have one channel, :math:`(B, 1, H, W)`.+ to ``LightGlueMatcher("dog_affnet_hardnet")``. The image must have one channel, ``(B, 1, H, W)``.Args:num_features: the number of features to detect.@@ -699,7 +699,7 @@ class KeyNetHardNet(LocalFeature):Convention:A :class:`~kornia.feature.LocalFeature`, whose Convention block gives the output contract, of one grayscale- image per call, :math:`(1, 1, H, W)`: a :class:`~kornia.feature.KeyNetDetector`, whose LAFs get their+ image per call, ``(1, 1, H, W)``: a :class:`~kornia.feature.KeyNetDetector`, whose LAFs get theirorientation 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.@@ -837,29 +837,29 @@ class LocalFeatureMatcher(nn.Module):data: dictionary containing the input data in the following format:Keyword Args:- image0: left image with shape :math:`(N, 1, H1, W1)`.- image1: right image with shape :math:`(N, 1, H2, W2)`.+ image0: left image with shape ``(N, 1, H1, W1)``.+ image1: right image with shape ``(N, 1, H2, W2)``.mask0 (optional): left image mask. '0' suppresses detection, with shape- :math:`(N, H1, W1)` or :math:`(N, 1, H1, W1)`.+ ``(N, H1, W1)`` or ``(N, 1, H1, W1)``.mask1 (optional): right image mask. '0' suppresses detection, with shape- :math:`(N, H2, W2)` or :math:`(N, 1, H2, W2)`.- lafs0 (optional): pre-extracted LAFs of image0, :math:`(N, M0, 2, 3)`. When ``lafs0`` and+ ``(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, :math:`(N, M0, D)`.- lafs1 (optional): pre-extracted LAFs of image1, :math:`(N, M1, 2, 3)`; with ``descriptors1``, as for image0.- descriptors1 (optional): pre-extracted descriptors of image1, :math:`(N, M1, D)`.+ 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 :math:`(NC, 2)`.- - ``keypoints1``, matching keypoints from image1 :math:`(NC, 2)`.- - ``confidence``, ``1 - descriptor distance`` :math:`(NC)`. This lies in :math:`[0, 1]`+ - ``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 theconfidence has no lower bound in general -- it goes at least down to -1, the valuereached by unit-norm descriptors, whose distance tops out at 2.0.- - ``lafs0``, matching LAFs from image0 :math:`(1, NC, 2, 3)`.- - ``lafs1``, matching LAFs from image1 :math:`(1, NC, 2, 3)`.- - ``batch_indexes``, batch indexes for the keypoints and lafs :math:`(NC)`.+ - ``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]@@ -1042,17 +1042,17 @@ class LightGlueMatcher(GeometryAwareDescriptorMatcher):"""Run forward.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.- lafs1: LAFs of a shape :math:`(1, B1, 2, 3)`.- lafs2: LAFs of a shape :math:`(1, B2, 2, 3)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.+ 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 :math:`(B3, 1)`.+ - 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 :math:`(B3, 2)` where :math:`0 <= B3 <= B1`.+ shape of ``(B3, 2)`` where :math:`0 <= B3 <= B1`."""if (desc1.shape[0] < 2) or (desc2.shape[0] < 2):diff --git a/kornia/feature/keynet.py b/kornia/feature/keynet.pyindex 727a6ee30..ef0a5ca21 100644--- a/kornia/feature/keynet.py+++ b/kornia/feature/keynet.py@@ -160,8 +160,8 @@ class KeyNet(nn.Module):KeyNet response score.Shape:- - Input: :math:`(B, 1, H, W)`- - Output: :math:`(B, 1, H, W)`+ - Input: ``(B, 1, H, W)``+ - Output: ``(B, 1, H, W)``"""diff --git a/kornia/feature/laf.py b/kornia/feature/laf.pyindex 9d4f41ff3..fb1326ecb 100644--- a/kornia/feature/laf.py+++ b/kornia/feature/laf.py@@ -50,10 +50,10 @@ def get_laf_scale(LAF: torch.Tensor) -> torch.Tensor:range does not overflow; the scale is returned in the LAF dtype.Args:- LAF: :math:`(B, N, 2, 3)`+ LAF: ``(B, N, 2, 3)``Returns:- scale :math:`(B, N, 1, 1)`+ scale ``(B, N, 1, 1)``Example:>>> input = torch.ones(1, 5, 2, 3) # BxNx2x3@@ -82,10 +82,10 @@ def laf_is_valid(laf: torch.Tensor) -> torch.Tensor:or bfloat16 LAF is formed in that dtype, where it can overflow.Args:- laf: :math:`(B, N, 2, 3)`.+ laf: ``(B, N, 2, 3)``.Returns:- validity mask :math:`(B, N)`.+ validity mask ``(B, N)``.Example:>>> laf = torch.eye(2, 3).view(1, 1, 2, 3)@@ -113,10 +113,10 @@ def laf_is_filled(laf: torch.Tensor) -> torch.Tensor:maximum at exactly zero.Args:- laf: :math:`(B, N, 2, 3)`.+ laf: ``(B, N, 2, 3)``.Returns:- mask of the slots a detection filled :math:`(B, N)`.+ mask of the slots a detection filled ``(B, N)``.Example:>>> laf = torch.tensor([[[[2., 0., 5.], [0., 3., 7.]], [[0., 0., 0.], [0., 0., 0.]]]])@@ -136,10 +136,10 @@ def get_laf_center(LAF: torch.Tensor) -> torch.Tensor::ref:`Local features <local-features-conventions>`.Args:- LAF: :math:`(B, N, 2, 3)`+ LAF: ``(B, N, 2, 3)``Returns:- xy :math:`(B, N, 2)`+ xy ``(B, N, 2)``Example:>>> input = torch.ones(1, 5, 2, 3) # BxNx2x3@@ -157,10 +157,10 @@ def get_laf_orientation(LAF: torch.Tensor) -> torch.Tensor:See the Convention block on :func:`~kornia.feature.laf_from_center_scale_ori`, which defines the orientation.Args:- LAF: :math:`(B, N, 2, 3)`+ LAF: ``(B, N, 2, 3)``Returns:- angle in degrees :math:`(B, N, 1)`+ angle in degrees ``(B, N, 1)``Example:>>> input = torch.ones(1, 5, 2, 3) # BxNx2x3@@ -182,11 +182,11 @@ def rotate_laf(LAF: torch.Tensor, angles_degrees: torch.Tensor) -> torch.Tensor::func:`~kornia.feature.make_upright` returns are kept.Args:- LAF: :math:`(B, N, 2, 3)`- angles_degrees: :math:`(B, N, 1)` in degrees.+ LAF: ``(B, N, 2, 3)``+ angles_degrees: ``(B, N, 1)`` in degrees.Returns:- LAF oriented with angles :math:`(B, N, 2, 3)`+ LAF oriented with angles ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(LAF)@@ -205,11 +205,11 @@ def set_laf_orientation(LAF: torch.Tensor, angles_degrees: torch.Tensor) -> torccurrent orientation, so the orientation reads back as ``angles_degrees`` wrapped into ``[-180, 180]``.Args:- LAF: :math:`(B, N, 2, 3)`- angles_degrees: :math:`(B, N, 1)` in degrees.+ LAF: ``(B, N, 2, 3)``+ angles_degrees: ``(B, N, 1)`` in degrees.Returns:- LAF oriented with angles :math:`(B, N, 2, 3)`+ LAF oriented with angles ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(LAF)@@ -224,7 +224,7 @@ def laf_from_center_scale_ori(r"""Create a LAF from keypoint center, scale and orientation.Convention:- - A LAF is a :math:`(B, N, 2, 3)` tensor ``[A | c]``, with the centre ``c = (x, y)`` and ``A`` in pixels.+ - A LAF is a ``(B, N, 2, 3)`` tensor ``[A | c]``, with the centre ``c = (x, y)`` and ``A`` in pixels.``A`` maps the patch frame onto the image: its first column is the image of the patch's x axis and itssecond column that of the patch's y axis. :ref:`Local features <local-features-conventions>` gives thepixel frame, the patch that :func:`~kornia.feature.extract_patches_from_pyramid` samples and the@@ -240,12 +240,12 @@ def laf_from_center_scale_ori(orientation.Args:- xy: :math:`(B, N, 2)`.- scale: :math:`(B, N, 1, 1)`. If not provided, scale = 1.0 is assumed- ori: angle in degrees :math:`(B, N, 1)`. If not provided orientation = 0 is assumed+ xy: ``(B, N, 2)``.+ scale: ``(B, N, 1, 1)``. If not provided, scale = 1.0 is assumed+ ori: angle in degrees ``(B, N, 1)``. If not provided orientation = 0 is assumedReturns:- LAF :math:`(B, N, 2, 3)`+ LAF ``(B, N, 2, 3)``Example:>>> xy = torch.tensor([[[5.0, 7.0]]])@@ -275,15 +275,15 @@ def scale_laf(laf: torch.Tensor, scale_coef: Union[float, torch.Tensor]) -> torc- The result is ``[k A | c]`` for ``k = scale_coef``, a product taken elementwise: the centre is kept. With onecoefficient per LAF, the scale is multiplied by ``|k|``, and a negative ``k`` also turns the frame by 180degrees.- - ``scale_coef`` is a ``float`` or a tensor that broadcasts against :math:`(B, N, 2, 2)`, such as one- coefficient per LAF in a :math:`(B, N, 1, 1)` tensor; an ``int`` is rejected.+ - ``scale_coef`` is a ``float`` or a tensor that broadcasts against ``(B, N, 2, 2)``, such as one+ coefficient per LAF in a ``(B, N, 1, 1)`` tensor; an ``int`` is rejected.Args:- laf: :math:`(B, N, 2, 3)`+ laf: ``(B, N, 2, 3)``scale_coef: broadcastable torch.Tensor or float.Returns:- LAF :math:`(B, N, 2, 3)`+ LAF ``(B, N, 2, 3)``Raises:TypeError: if ``scale_coef`` is neither a ``float`` nor a tensor.@@ -321,11 +321,11 @@ def make_upright(laf: torch.Tensor, eps: float = 1e-9) -> torch.Tensor:overflow; the result is returned in the LAF dtype.Args:- laf: :math:`(B, N, 2, 3)`+ laf: ``(B, N, 2, 3)``eps: for safe division.Returns:- laf: :math:`(B, N, 2, 3)`+ laf: ``(B, N, 2, 3)``Example:>>> input = torch.ones(1, 5, 2, 3) # BxNx2x3@@ -375,7 +375,7 @@ def ellipse_to_laf(ells: torch.Tensor) -> torch.Tensor:symmetric inverse square root (the two differ by a rotation). Either one maps the unit circle onto theellipse; the lower-triangular one is what :func:`~kornia.feature.make_upright` returns, up to itsstabilizers, for any LAF of that region.- - The conversion checks only the shape :math:`(B, N, 5)`; it does not check the ellipse values and does not+ - The conversion checks only the shape ``(B, N, 5)``; it does not check the ellipse values and does notraise on them. An ellipse that is degenerate or indefinite (``a``, ``c`` or ``a * c - b * b`` not positive)is not a bounded region; its LAF has ``inf`` or ``nan`` entries, or huge finite ones where rounding leaves``a - b * b / c`` barely positive. Rounding also works the other way: a nearly singular valid ellipse can@@ -386,10 +386,10 @@ def ellipse_to_laf(ells: torch.Tensor) -> torch.Tensor:See also https://github.com/vlfeat/vlfeat/blob/master/toolbox/sift/vl_frame2oell.mArgs:- ells: torch.Tensor :math:`(B, N, 5)` of ellipses in Oxford format [x y a b c].+ ells: torch.Tensor ``(B, N, 5)`` of ellipses in Oxford format [x y a b c].Returns:- LAF :math:`(B, N, 2, 3)`+ LAF ``(B, N, 2, 3)``Example:>>> input = torch.ones(1, 10, 5) # BxNx5@@ -429,7 +429,7 @@ def laf_to_boundary_points(LAF: torch.Tensor, n_pts: int = 50) -> torch.Tensor:axis, and so close the outline of the region.Args:- LAF: :math:`(B, N, 2, 3)`+ LAF: ``(B, N, 2, 3)``n_pts: number of points to output, the centre included.Returns:@@ -463,7 +463,7 @@ def get_laf_pts_to_draw(LAF: torch.Tensor, img_idx: int = 0) -> Tuple[List[int],"""Return list for drawing LAFs (local features).Args:- LAF: :math:`(B, N, 2, 3)`+ LAF: ``(B, N, 2, 3)``img_idx: which points to output.Returns:@@ -502,11 +502,11 @@ def denormalize_laf(LAF: torch.Tensor, images: torch.Tensor) -> torch.Tensor:See the Convention block on :func:`~kornia.feature.normalize_laf`, which this inverts.Args:- LAF: :math:`(B, N, 2, 3)`- images: :math:`(B, CH, H, W)`+ LAF: ``(B, N, 2, 3)``+ images: ``(B, CH, H, W)``Returns:- the denormalized LAF: :math:`(B, N, 2, 3)`, scale in pixels+ the denormalized LAF: ``(B, N, 2, 3)``, scale in pixels"""KORNIA_CHECK_LAF(LAF)@@ -549,11 +549,11 @@ def normalize_laf(LAF: torch.Tensor, images: torch.Tensor) -> torch.Tensor:pixel ``x`` to ``(x + 0.5) W' / W - 0.5`` instead, so the two disagree away from the image centre.Args:- LAF: :math:`(B, N, 2, 3)`- images: :math:`(B, CH, H, W)`+ LAF: ``(B, N, 2, 3)``+ images: ``(B, CH, H, W)``Returns:- the normalized LAF: :math:`(B, N, 2, 3)`+ the normalized LAF: ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(LAF)@@ -573,12 +573,12 @@ def generate_patch_grid_from_normalized_LAF(img: torch.Tensor, LAF: torch.Tensor"""Generate affine grid.Args:- img: image torch.Tensor of shape :math:`(B, CH, H, W)`.- LAF: laf with shape :math:`(B, N, 2, 3)`.+ img: image torch.Tensor of shape ``(B, CH, H, W)``.+ LAF: laf with shape ``(B, N, 2, 3)``.PS: patch size to be extracted.Returns:- grid :math:`(B*N, PS, PS, 2)`+ grid ``(B*N, PS, PS, 2)``"""KORNIA_CHECK_LAF(LAF)@@ -609,7 +609,7 @@ def _clamp_grid_to_pixel_centers(grid: torch.Tensor, h: int, w: int) -> torch.Teexactly.Args:- grid: sampling grid :math:`(..., 2)` with any leading batch dimensions, last dimension ordered+ grid: sampling grid ``(..., 2)`` with any leading batch dimensions, last dimension ordered``(x, y)``. Only 2-D sampling is handled; a 3-D grid would need a third bound from thedepth of the sampled volume.h: height of the sampled image.@@ -686,13 +686,13 @@ def _pyramid_atlas_fits(atlas_bytes: int, budget: int = 128 * 1024 * 1024) -> bodef _sample_patches(img: torch.Tensor, grid: torch.Tensor, h: int, w: int) -> torch.Tensor:r"""Sample one patch per LAF with a single ``grid_sample`` call.- The per-LAF grids :math:`(B, N, PS, PS, 2)` are folded to :math:`(B, N \cdot PS, PS, 2)` so+ The per-LAF grids ``(B, N, PS, PS, 2)`` are folded to :math:`(B, N \cdot PS, PS, 2)` soone call covers the whole batch, without a Python loop over B or a ``(B*N, CH, H, W)`` inputcopy. ``grid`` must already live on ``img``'s device: the extractors move a cross-device LAFto the image's device up front, so the grid is built there.Returns:- patches :math:`(B, N, CH, PS, PS)` as a permuted view; assigning it or calling+ patches ``(B, N, CH, PS, PS)`` as a permuted view; assigning it or calling``.contiguous()`` makes the copy."""B, N, PS = grid.size(0), grid.size(1), grid.size(2)@@ -711,12 +711,12 @@ def _pyramid_grid_frame(nlaf: torch.Tensor, h: int, w: int) -> Tuple[torch.Tenso:math:`(2x + 1) / w - 1`. One grid therefore serves every pyramid level.Args:- nlaf: normalized LAFs :math:`(B, N, 2, 3)` (``normalize_laf``'s frame).+ nlaf: normalized LAFs ``(B, N, 2, 3)`` (``normalize_laf``'s frame).h: input height.w: input width.Returns:- ``k`` of shape :math:`(2,)` and ``t`` of shape :math:`(B, N, 2)`, in ``nlaf``'s dtype and device.+ ``k`` of shape ``(2,)`` and ``t`` of shape ``(B, N, 2)``, in ``nlaf``'s dtype and device."""# `denormalize_laf`'s extents: a singleton axis counts as one pixel.wf, hf = float(max(w - 1, 1)), float(max(h - 1, 1))@@ -806,14 +806,14 @@ def extract_patches_simple(same positions, always from ``img`` itself: a LAF larger than the patch is not smoothed first, so it aliases.Args:- img: images, LAFs are detected in :math:`(B, CH, H, W)`.- laf: :math:`(B, N, 2, 3)`.+ img: images, LAFs are detected in ``(B, CH, H, W)``.+ laf: ``(B, N, 2, 3)``.PS: patch size.normalize_lafs_before_extraction: if True, lafs are normalized to image size; if False, ``laf`` must alreadybe in the frame that :func:`~kornia.feature.normalize_laf` gives for ``img``.Returns:- patches with shape :math:`(B, N, CH, PS,PS)`.+ patches with shape ``(B, N, CH, PS,PS)``."""KORNIA_CHECK_LAF(laf)@@ -873,14 +873,14 @@ def extract_patches_from_pyramid(in at least ``float32``. A LAF with a non-finite entry gives a zero patch.Args:- img: images, LAFs are detected in :math:`(B, CH, H, W)`.- laf: :math:`(B, N, 2, 3)`.+ img: images, LAFs are detected in ``(B, CH, H, W)``.+ laf: ``(B, N, 2, 3)``.PS: patch size.normalize_lafs_before_extraction: if True, lafs are normalized to image size; if False, ``laf`` must alreadybe in the frame that :func:`~kornia.feature.normalize_laf` gives for ``img``.Returns:- patches with shape :math:`(B, N, CH, PS,PS)`.+ patches with shape ``(B, N, CH, PS,PS)``."""KORNIA_CHECK_LAF(laf)@@ -1023,12 +1023,12 @@ def laf_is_inside_image(laf: torch.Tensor, images: torch.Tensor, border: int = 0included; combine the mask with :func:`~kornia.feature.laf_is_filled` to drop the padding.Args:- laf: :math:`(B, N, 2, 3)`.- images: images, lafs are detected in :math:`(B, CH, H, W)`.+ laf: ``(B, N, 2, 3)``.+ images: images, lafs are detected in ``(B, CH, H, W)``.border: additional border.Returns:- mask with shape :math:`(B, N)`.+ mask with shape ``(B, N)``."""KORNIA_CHECK_LAF(laf)@@ -1053,10 +1053,10 @@ def laf_to_three_points(laf: torch.Tensor) -> torch.Tensor:length. :func:`~kornia.feature.laf_from_three_points` is the inverse.Args:- laf: :math:`(B, N, 2, 3)`.+ laf: ``(B, N, 2, 3)``.Returns:- threepts :math:`(B, N, 2, 3)`.+ threepts ``(B, N, 2, 3)``."""KORNIA_CHECK_LAF(laf)@@ -1071,10 +1071,10 @@ def laf_from_three_points(threepts: torch.Tensor) -> torch.Tensor:``threepts`` are the images of the patch points ``(1, 0)``, ``(0, 1)`` and ``(0, 0)``, in that order.Args:- threepts: :math:`(B, N, 2, 3)`.+ threepts: ``(B, N, 2, 3)``.Returns:- laf :math:`(B, N, 2, 3)`.+ laf ``(B, N, 2, 3)``."""KORNIA_CHECK_SHAPE(threepts, ["B", "N", "2", "3"])@@ -1095,11 +1095,11 @@ def perspective_transform_lafs(trans_01: torch.Tensor, lafs_1: torch.Tensor) ->two differ, the more so the larger the LAF.Args:- trans_01: torch.Tensor for perspective transformations of shape :math:`(B, 3, 3)`.- lafs_1: torch.Tensor of lafs of shape :math:`(B, N, 2, 3)`.+ trans_01: torch.Tensor for perspective transformations of shape ``(B, 3, 3)``.+ lafs_1: torch.Tensor of lafs of shape ``(B, N, 2, 3)``.Returns:- the transformed LAFs in frame 0, of shape :math:`(B, N, 2, 3)`.+ the transformed LAFs in frame 0, of shape ``(B, N, 2, 3)``.Examples:>>> rng = torch.manual_seed(0)diff --git a/kornia/feature/lightglue.py b/kornia/feature/lightglue.pyindex f22c48409..8bb403ef8 100644--- a/kornia/feature/lightglue.py+++ b/kornia/feature/lightglue.py@@ -150,17 +150,17 @@ class Attention(nn.Module):"""Apply multi-head attention to query, key, and value tensors.Args:- q: Query tensor with shape :math:`(B, H, N_q, D_h)`, where ``B`` is batch size,+ q: Query tensor with shape ``(B, H, N_q, D_h)``, where ``B`` is batch size,``H`` is the number of attention heads, ``N_q`` is the number of query tokens,and ``D_h`` is the per-head descriptor dimension.- k: Key tensor with shape :math:`(B, H, N_k, D_h)`, where ``N_k`` is the number+ k: Key tensor with shape ``(B, H, N_k, D_h)``, where ``N_k`` is the numberof key tokens.- v: Value tensor with shape :math:`(B, H, N_k, D_h)`.+ v: Value tensor with shape ``(B, H, N_k, D_h)``.mask: Optional boolean attention mask. ``True`` entries mark token pairs thatare allowed to attend to each other.Returns:- Attention output with shape :math:`(B, H, N_q, D_h)`.+ Attention output with shape ``(B, H, N_q, D_h)``."""if self.allow_flash and q.device.type == "cuda":# use torch 2.0 scaled_dot_product_attention with flash@@ -214,7 +214,7 @@ class SelfBlock(nn.Module):"""Update descriptors from one image using self-attention.Args:- x: Descriptor tensor with shape :math:`(B, N, D)`, where ``B`` is batch size,+ x: Descriptor tensor with shape ``(B, N, D)``, where ``B`` is batch size,``N`` is the number of local features, and ``D`` is descriptor dimension.encoding: Positional encoding tensor aligned with ``x`` and used for rotaryposition embedding inside attention.@@ -282,11 +282,11 @@ class CrossBlock(nn.Module):"""Exchange information between two images using cross-attention.Args:- x0: Descriptor tensor from the first image with shape :math:`(B, M, D)`,+ x0: Descriptor tensor from the first image with shape ``(B, M, D)``,where ``M`` is the number of local features in image 0.- x1: Descriptor tensor from the second image with shape :math:`(B, N, D)`,+ x1: Descriptor tensor from the second image with shape ``(B, N, D)``,where ``N`` is the number of local features in image 1.- mask: Optional boolean mask with shape :math:`(B, H, M, N)` or a broadcastable+ mask: Optional boolean mask with shape ``(B, H, M, N)`` or a broadcastableequivalent, marking valid descriptor pairs.Returns:@@ -340,8 +340,8 @@ class TransformerLayer(nn.Module):"""Run one LightGlue transformer layer over two descriptor sets.Args:- desc0: Descriptor tensor from image 0 with shape :math:`(B, M, D)`.- desc1: Descriptor tensor from image 1 with shape :math:`(B, N, D)`.+ desc0: Descriptor tensor from image 0 with shape ``(B, M, D)``.+ desc1: Descriptor tensor from image 1 with shape ``(B, N, D)``.encoding0: Positional encoding for ``desc0``.encoding1: Positional encoding for ``desc1``.mask0: Optional validity mask for descriptors in image 0.@@ -369,8 +369,8 @@ class TransformerLayer(nn.Module):"""Run the transformer layer with explicit descriptor validity masks.Args:- desc0: Descriptor tensor from image 0 with shape :math:`(B, M, D)`.- desc1: Descriptor tensor from image 1 with shape :math:`(B, N, D)`.+ desc0: Descriptor tensor from image 0 with shape ``(B, M, D)``.+ desc1: Descriptor tensor from image 1 with shape ``(B, N, D)``.encoding0: Positional encoding for image 0 descriptors.encoding1: Positional encoding for image 1 descriptors.mask0: Boolean mask for valid image 0 descriptors.@@ -428,11 +428,11 @@ class MatchAssignment(nn.Module):"""Estimate how likely each descriptor is to obtain a valid match.Args:- desc: Descriptor tensor with shape :math:`(B, N, D)`, where ``N`` is the+ desc: Descriptor tensor with shape ``(B, N, D)``, where ``N`` is thenumber of local features.Returns:- Matchability probabilities with shape :math:`(B, N)`.+ Matchability probabilities with shape ``(B, N)``."""return torch.sigmoid(self.matchability(desc)).squeeze(-1)@@ -1014,8 +1014,8 @@ class LightGlue(nn.Module):"""Evaluate the early-stopping condition of every pair in a batch.Args:- confidences0: Token confidences of image 0, shape :math:`(B, M)`.- confidences1: Token confidences of image 1, shape :math:`(B, N)`.+ confidences0: Token confidences of image 0, shape ``(B, M)``.+ confidences1: Token confidences of image 1, shape ``(B, N)``.layer_index: Index of the layer that computed the confidences.num_points: Number of keypoints of one pair that the unconfident points are counted against.diff --git a/kornia/feature/lightglue_onnx/lightglue.py b/kornia/feature/lightglue_onnx/lightglue.pyindex e6da979ee..42537028b 100644--- a/kornia/feature/lightglue_onnx/lightglue.py+++ b/kornia/feature/lightglue_onnx/lightglue.py@@ -129,23 +129,23 @@ class OnnxLightGlue:``data`` (``dict``):``image0`` (``dict``):- ``keypoints`` (`float32`): :math:`(1, M, 2)`+ ``keypoints`` (`float32`): ``(1, M, 2)``- ``descriptors`` (`float32`): :math:`(1, M, D)`+ ``descriptors`` (`float32`): ``(1, M, D)``- ``image``: :math:`(1, C, H, W)` or ``image_size``: :math:`(1, 2)`+ ``image``: ``(1, C, H, W)`` or ``image_size``: ``(1, 2)````image1`` (``dict``):- ``keypoints`` (`float32`): :math:`(1, N, 2)`+ ``keypoints`` (`float32`): ``(1, N, 2)``- ``descriptors`` (`float32`): :math:`(1, N, D)`+ ``descriptors`` (`float32`): ``(1, N, D)``- ``image``: :math:`(1, C, H, W)` or ``image_size``: :math:`(1, 2)`+ ``image``: ``(1, C, H, W)`` or ``image_size``: ``(1, 2)````output`` (``dict``):- ``matches`` (`int64`): :math:`(S, 2)`+ ``matches`` (`int64`): ``(S, 2)``- ``scores`` (`float32`): :math:`(S)`+ ``scores`` (`float32`): ``(S)``"""# Input validation.diff --git a/kornia/feature/loftr/backbone/resnet_fpn.py b/kornia/feature/loftr/backbone/resnet_fpn.pyindex 7a0c4650e..19868c9dc 100644--- a/kornia/feature/loftr/backbone/resnet_fpn.py+++ b/kornia/feature/loftr/backbone/resnet_fpn.py@@ -134,11 +134,11 @@ class ResNetFPN_8_2(nn.Module):"""Run this LoFTR component forward.Args:- x: Input grayscale image tensor with shape :math:`(B, 1, H, W)`.+ x: Input grayscale image tensor with shape ``(B, 1, H, W)``.Returns:- List containing coarse feature map with shape :math:`(B, C_c, H/8, W/8)`- and fine feature map with shape :math:`(B, C_f, H/2, W/2)`.+ List containing coarse feature map with shape ``(B, C_c, H/8, W/8)``+ and fine feature map with shape ``(B, C_f, H/2, W/2)``."""# ResNet Backbonex0 = self.relu(self.bn1(self.conv1(x)))@@ -227,11 +227,11 @@ class ResNetFPN_16_4(nn.Module):"""Run this LoFTR component forward.Args:- x: Input grayscale image tensor with shape :math:`(B, 1, H, W)`.+ x: Input grayscale image tensor with shape ``(B, 1, H, W)``.Returns:- List containing coarse feature map with shape :math:`(B, C_c, H/16, W/16)`- and fine feature map with shape :math:`(B, C_f, H/4, W/4)`.+ List containing coarse feature map with shape ``(B, C_c, H/16, W/16)``+ and fine feature map with shape ``(B, C_f, H/4, W/4)``."""# ResNet Backbonex0 = self.relu(self.bn1(self.conv1(x)))diff --git a/kornia/feature/loftr/loftr.py b/kornia/feature/loftr/loftr.pyindex 3fc509d0a..9b78dcbd3 100644--- a/kornia/feature/loftr/loftr.py+++ b/kornia/feature/loftr/loftr.py@@ -84,7 +84,7 @@ class LoFTR(nn.Module):Feature Matching with Transformers". See :cite:`LoFTR2021` for more details.Convention:- - ``image0`` and ``image1`` are grayscale :math:`(N, 1, H, W)` images in :math:`[0, 1]`, the input of the+ - ``image0`` and ``image1`` are grayscale ``(N, 1, H, W)`` images in :math:`[0, 1]`, the input of thepretrained models. With the default ``config``, whose ``resolution`` (8, 2) every pretrained model uses,the two images can differ in size, and their heights and widths do not need to be multiples of 8 (thereference implementation expects multiples of 8).@@ -161,7 +161,7 @@ class LoFTR(nn.Module):match an image against many others without running the backbone again for every pair.Args:- image: grayscale images with shape :math:`(N, 1, H, W)`.+ image: grayscale images with shape ``(N, 1, H, W)``.Returns:- ``coarse``, position-encoded 1/8-resolution features@@ -209,18 +209,18 @@ class LoFTR(nn.Module):data: dictionary containing the input data in the following format:Keyword Args:- image0: left image with shape :math:`(N, 1, H1, W1)`.- image1: right image with shape :math:`(N, 1, H2, W2)`.+ image0: left image with shape ``(N, 1, H1, W1)``.+ image1: right image with shape ``(N, 1, H2, W2)``.features0 (optional): instead of ``image0``, its :meth:`extract_features` output.features1 (optional): instead of ``image1``, its :meth:`extract_features` output.- mask0 (optional): left image mask. '0' indicates a padded position :math:`(N, H1, W1)`.- mask1 (optional): right image mask. '0' indicates a padded position :math:`(N, H2, W2)`.+ mask0 (optional): left image mask. '0' indicates a padded position ``(N, H1, W1)``.+ mask1 (optional): right image mask. '0' indicates a padded position ``(N, H2, W2)``.Returns:- - ``keypoints0``, matching keypoints from image0 :math:`(NC, 2)`.- - ``keypoints1``, matching keypoints from image1 :math:`(NC, 2)`.- - ``confidence``, the coarse matching score, see the Convention block :math:`(NC)`.- - ``batch_indexes``, batch index of each match :math:`(NC)`.+ - ``keypoints0``, matching keypoints from image0 ``(NC, 2)``.+ - ``keypoints1``, matching keypoints from image1 ``(NC, 2)``.+ - ``confidence``, the coarse matching score, see the Convention block ``(NC)``.+ - ``batch_indexes``, batch index of each match ``(NC)``."""# Pixel strides of the coarse and the fine feature map, (8, 2) by default. Every stride-2 stage of the backbonediff --git a/kornia/feature/loftr/loftr_module/fine_preprocess.py b/kornia/feature/loftr/loftr_module/fine_preprocess.pyindex ee803b7f5..340e2eb70 100644--- a/kornia/feature/loftr/loftr_module/fine_preprocess.py+++ b/kornia/feature/loftr/loftr_module/fine_preprocess.py@@ -78,12 +78,12 @@ class FinePreprocess(nn.Module):"""Run this LoFTR component forward.Args:- feat_f0: Fine feature map of the first image with shape :math:`(B, C_f, H_f, W_f)`.- feat_f1: Fine feature map of the second image with shape :math:`(B, C_f, H_f, W_f)`.+ feat_f0: Fine feature map of the first image with shape ``(B, C_f, H_f, W_f)``.+ feat_f1: Fine feature map of the second image with shape ``(B, C_f, H_f, W_f)``.feat_c0: Coarse feature map or transformed tokens of the first image with shape- :math:`(B, C_c, H_c, W_c)` or :math:`(N_c, C_c)`.+ ``(B, C_c, H_c, W_c)`` or ``(N_c, C_c)``.feat_c1: Coarse feature map or transformed tokens of the second image with shape- :math:`(B, C_c, H_c, W_c)` or :math:`(N_c, C_c)`.+ ``(B, C_c, H_c, W_c)`` or ``(N_c, C_c)``.data: Dictionary containing coarse match metadata and indices, and the pixel strides ``stride_c`` and``stride_f`` of the coarse and the fine feature maps.diff --git a/kornia/feature/loftr/utils/fine_matching.py b/kornia/feature/loftr/utils/fine_matching.pyindex 692c9fe55..d07ebf6be 100644--- a/kornia/feature/loftr/utils/fine_matching.py+++ b/kornia/feature/loftr/utils/fine_matching.py@@ -101,7 +101,7 @@ class FineMatching(nn.Module):"""Extract fine-level correspondences from the refined matching heatmap.Args:- coords_normed: Normalized coordinate offsets with shape :math:`(M, 2)`.+ coords_normed: Normalized coordinate offsets with shape ``(M, 2)``.data: Dictionary containing image features, keypoints, descriptors, and image sizes for matching.Returns:diff --git a/kornia/feature/matching.py b/kornia/feature/matching.pyindex 0374f7f27..70d38f14e 100644--- a/kornia/feature/matching.py+++ b/kornia/feature/matching.py@@ -70,10 +70,10 @@ def _get_lazy_distance_matrix("""Check validity of provided distance matrix, or calculates L2-distance matrix if dm is not provided.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.dm_: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``."""if dm_ is None:@@ -88,8 +88,8 @@ def _no_match(dm: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:"""Output empty tensors.Returns:- - Descriptor distance of matching descriptors, shape of :math:`(0, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of :math:`(0, 2)`.+ - Descriptor distance of matching descriptors, shape of ``(0, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of ``(0, 2)``."""dists = torch.empty(0, 1, device=dm.device, dtype=dm.dtype)@@ -104,8 +104,8 @@ def match_nn(Convention:- Every ``match_*`` function returns ``(dists, idxs)``, one row per match. ``idxs`` is an int64- :math:`(M, 2)` tensor of ``(index in desc1, index in desc2)`` rows (:func:`match_smnn_batched` adds the- batch index as a first column). ``dists`` is :math:`(M, 1)`, in the dtype of ``dm`` when it is given and in+ ``(M, 2)`` tensor of ``(index in desc1, index in desc2)`` rows (:func:`match_smnn_batched` adds the+ batch index as a first column). ``dists`` is ``(M, 1)``, in the dtype of ``dm`` when it is given and inthe descriptor dtype otherwise, except that :func:`match_adalam` returns float32. Lower values are better,and what they are depends on the function:@@ -126,21 +126,21 @@ def match_nn(:func:`match_nn` and :func:`match_mnn` accept any matrix in which smaller is better and return itsentries, while the ratio tests divide its entries, so they need non-negative values, and squareddistances need ``th ** 2``.- - An empty desc1 or desc2 gives a :math:`(0, 1)` and a :math:`(0, 2)` tensor (:math:`(0, 3)` for+ - An empty desc1 or desc2 gives a ``(0, 1)`` and a ``(0, 2)`` tensor (``(0, 3)`` for:func:`match_smnn_batched`). The ratio tests need a second neighbour: :func:`match_snn` and:func:`match_fginn` return no match unless desc2 has two rows, and :func:`match_smnn`,:func:`match_smnn_batched` and :func:`match_adalam`, which scores its putative matches by the same ratio,need two rows in both.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.dm: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``.Returns:- - Descriptor distance of matching descriptors, shape of :math:`(B1, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of :math:`(B1, 2)`.+ - Descriptor distance of matching descriptors, shape of ``(B1, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of ``(B1, 2)``."""KORNIA_CHECK_SHAPE(desc1, ["B", "DIM"])@@ -164,14 +164,14 @@ def match_mnn(nearest neighbour of the other.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.dm: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``.Return:- - Descriptor distance of matching descriptors, shape of :math:`(B3, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of :math:`(B3, 2)`,+ - Descriptor distance of matching descriptors, shape of ``(B3, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2, shape of ``(B3, 2)``,where 0 <= B3 <= min(B1, B2)"""@@ -208,15 +208,15 @@ def match_snn(distance.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.th: distance ratio threshold.dm: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``.Return:- - Ratio of the nearest to the second-nearest distance of each match, shape of :math:`(B3, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: :math:`(B3, 2)`,+ - Ratio of the nearest to the second-nearest distance of each match, shape of ``(B3, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: ``(B3, 2)``,where 0 <= B3 <= B1."""@@ -252,16 +252,16 @@ def match_smnn(- ``th`` defaults to 0.95, where :func:`match_snn` and :func:`match_fginn` default to 0.8.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.th: distance ratio threshold.dm: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``.Return:- - The larger of the two distance ratios of each match, shape of :math:`(B3, 1)`.+ - The larger of the two distance ratios of each match, shape of ``(B3, 1)``.- Long torch.Tensor indexes of matching descriptors in desc1 and desc2,- shape of :math:`(B3, 2)` where 0 <= B3 <= B1.+ shape of ``(B3, 2)`` where 0 <= B3 <= B1."""KORNIA_CHECK_SHAPE(desc1, ["B", "DIM"])@@ -312,17 +312,17 @@ def match_smnn_batched(slightly from those of :func:`match_smnn` on the half-precision descriptors.Args:- desc1: First descriptors, shape :math:`(B, N, D)`.- desc2: Second descriptors, shape :math:`(B, M, D)`.+ desc1: First descriptors, shape ``(B, N, D)``.+ desc2: Second descriptors, shape ``(B, M, D)``.th: Inclusive distance-ratio threshold.- dm: Optional precomputed L2 distances, shape :math:`(B, N, M)`.- mask1: Optional boolean mask of valid first descriptors, shape :math:`(B, N)`.- mask2: Optional boolean mask of valid second descriptors, shape :math:`(B, M)`.+ dm: Optional precomputed L2 distances, shape ``(B, N, M)``.+ mask1: Optional boolean mask of valid first descriptors, shape ``(B, N)``.+ mask2: Optional boolean mask of valid second descriptors, shape ``(B, M)``.Masks allow padding variable-length pairs; padding never becomes a neighbor.Returns:- - Ratios, shape :math:`(K, 1)`, with the input device and dtype.- - Long indices, shape :math:`(K, 3)`: ``(batch_index, index_in_desc1, index_in_desc2)``.+ - Ratios, shape ``(K, 1)``, with the input device and dtype.+ - Long indices, shape ``(K, 3)``: ``(batch_index, index_in_desc1, index_in_desc2)``.Indices refer to the original padded tensors, sorted by batch and first-descriptor index.A pair with fewer than two valid descriptors on either side contributes no matches.@@ -445,23 +445,23 @@ def match_fginn(- Only the centres of ``lafs2`` are read, and ``spatial_th`` is in their units: pixels for LAFs in pixels.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.- lafs1: LAFs of a shape :math:`(1, B1, 2, 3)`. Accepted for API symmetry with+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.+ lafs1: LAFs of a shape ``(1, B1, 2, 3)``. Accepted for API symmetry with:func:`~kornia.feature.match_adalam` but not read by this function -- only``lafs2`` feeds the geometric check.- lafs2: LAFs of a shape :math:`(1, B2, 2, 3)`.+ lafs2: LAFs of a shape ``(1, B2, 2, 3)``.th: distance ratio threshold.spatial_th: minimal distance between the ``lafs2`` centres of the 1st and the 2nd nearest neighbor, in theunits of those centres.mutual: also perform mutual nearest neighbor check.dm: torch.Tensor containing the distances from each descriptor in desc1- to each descriptor in desc2, shape of :math:`(B1, B2)`.+ to each descriptor in desc2, shape of ``(B1, B2)``.Return:- Ratio of the nearest to the second-neighbour distance of each match, see the Convention block, shape of- :math:`(B3, 1)`.- - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: :math:`(B3, 2)`,+ ``(B3, 1)``.+ - Long torch.Tensor indexes of matching descriptors in desc1 and desc2. Shape: ``(B3, 2)``,where 0 <= B3 <= B1."""@@ -539,13 +539,13 @@ class DescriptorMatcher(nn.Module):"""Run forward.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.Returns:- - ``dists`` of the matching function, see :func:`~kornia.feature.match_nn`, shape of :math:`(B3, 1)`.+ - ``dists`` of the matching function, see :func:`~kornia.feature.match_nn`, shape of ``(B3, 1)``.- Long torch.Tensor indexes of matching descriptors in desc1 and desc2,- shape of :math:`(B3, 2)` where :math:`0 <= B3 <= B1`.+ shape of ``(B3, 2)`` where :math:`0 <= B3 <= B1`."""if self.match_mode == "nn":@@ -672,17 +672,17 @@ class DescriptorMatcherWithSteerer(nn.Module):"""Run forward.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.normalize: bool to decide whether to F.normalize descriptors to unit norm.subset_size: If set, the subset size to use for determining optimalnumber of rotations. Smaller subset size leads to faster but lessaccurate matching. Only used when `self.steer_mode` is `"global"`.Returns:- - Descriptor distance of matching descriptors, shape of :math:`(B3, 1)`.+ - Descriptor distance of matching descriptors, shape of ``(B3, 1)``.- Long torch.Tensor indexes of matching descriptors in desc1 and desc2,- shape of :math:`(B3, 2)` where :math:`0 <= B3 <= B1`.+ shape of ``(B3, 2)`` where :math:`0 <= B3 <= B1`.- Number of global rotations from desc1 to desc2, in terms of `self.steerer_order`(will be `None` if `self.steer_mode` is `local`).@@ -766,15 +766,15 @@ class GeometryAwareDescriptorMatcher(nn.Module):"""Run forward.Args:- desc1: Batch of descriptors of a shape :math:`(B1, D)`.- desc2: Batch of descriptors of a shape :math:`(B2, D)`.- lafs1: LAFs of a shape :math:`(1, B1, 2, 3)`.- lafs2: LAFs of a shape :math:`(1, B2, 2, 3)`.+ desc1: Batch of descriptors of a shape ``(B1, D)``.+ desc2: Batch of descriptors of a shape ``(B2, D)``.+ lafs1: LAFs of a shape ``(1, B1, 2, 3)``.+ lafs2: LAFs of a shape ``(1, B2, 2, 3)``.Returns:- - ``dists`` of the matching function, see :func:`~kornia.feature.match_nn`, shape of :math:`(B3, 1)`.+ - ``dists`` of the matching function, see :func:`~kornia.feature.match_nn`, shape of ``(B3, 1)``.- Long torch.Tensor indexes of matching descriptors in desc1 and desc2,- shape of :math:`(B3, 2)` where :math:`0 <= B3 <= B1`.+ shape of ``(B3, 2)`` where :math:`0 <= B3 <= B1`."""if self.match_mode == "fginn":diff --git a/kornia/feature/mkd.py b/kornia/feature/mkd.pyindex bb051a121..2a357ecdd 100644--- a/kornia/feature/mkd.py+++ b/kornia/feature/mkd.py@@ -91,11 +91,11 @@ class MKDGradients(nn.Module):"""Compute gradient magnitude and orientation channels for grayscale patches.Args:- x: Patch tensor with shape :math:`(B, 1, H, W)`, where ``B`` is batch size,+ x: Patch tensor with shape ``(B, 1, H, W)``, where ``B`` is batch size,``1`` is the grayscale channel, and ``H``/``W`` are patch height and width.Returns:- Tensor with shape :math:`(B, 2, H, W)`. Channel 0 stores gradient magnitude,+ Tensor with shape ``(B, 2, H, W)``. Channel 0 stores gradient magnitude,and channel 1 stores gradient orientation in radians."""if not isinstance(x, torch.Tensor):@@ -164,11 +164,11 @@ class VonMisesKernel(nn.Module):"""Embed orientation values with the Von Mises kernel basis.Args:- x: Orientation tensor with shape :math:`(B, 1, H, W)`, where values are+ x: Orientation tensor with shape ``(B, 1, H, W)``, where values areangular orientations in radians.Returns:- Kernel embedding with shape :math:`(B, D, H, W)`, where ``D`` is the+ Kernel embedding with shape ``(B, D, H, W)``, where ``D`` is thenumber of channels produced by the configured coefficient list."""if not isinstance(x, torch.Tensor):@@ -235,11 +235,11 @@ class EmbedGradients(nn.Module):"""Embed gradient magnitude and orientation into kernel descriptor channels.Args:- grads: Gradient tensor with shape :math:`(B, 2, H, W)`. Channel 0 contains+ grads: Gradient tensor with shape ``(B, 2, H, W)``. Channel 0 containsmagnitudes, and channel 1 contains orientations.Returns:- Embedded gradient tensor with shape :math:`(B, D, H, W)`, where ``D`` is+ Embedded gradient tensor with shape ``(B, D, H, W)``, where ``D`` isthe number of channels produced by the orientation kernel."""if not isinstance(grads, torch.Tensor):@@ -370,11 +370,11 @@ class ExplicitSpacialEncoding(nn.Module):"""Apply explicit spatial encoding to embedded patch features.Args:- x: Feature map with shape :math:`(B, C, H, W)`, where ``C`` must match+ x: Feature map with shape ``(B, C, H, W)``, where ``C`` must match``in_dims`` and ``H``/``W`` are expected to match ``fmap_size``.Returns:- Encoded descriptor tensor with shape :math:`(B, D)`, where ``D`` is the+ Encoded descriptor tensor with shape ``(B, D)``, where ``D`` is theflattened spatial-kernel descriptor dimension."""if not isinstance(x, torch.Tensor):@@ -531,11 +531,11 @@ class Whitening(nn.Module):"""Whiten and L2-normalize local descriptors.Args:- x: Descriptor tensor with shape :math:`(N, D)`, where ``N`` is the number+ x: Descriptor tensor with shape ``(N, D)``, where ``N`` is the numberof descriptors and ``D`` is the input descriptor dimension.Returns:- Whitened descriptor tensor with shape :math:`(N, O)`, where ``O`` is+ Whitened descriptor tensor with shape ``(N, O)``, where ``O`` is``output_dims``."""if not isinstance(x, torch.Tensor):@@ -582,7 +582,7 @@ class MKDDescriptor(nn.Module):Shape:- Input: :math:`(B, 1, \text{patch\_size}, \text{patch\_size})`.- - Output: :math:`(B, D)`, with :math:`D` as in the Convention block.+ - Output: ``(B, D)``, with :math:`D` as in the Convention block.Examples:>>> patches = torch.rand(23, 1, 32, 32)@@ -665,7 +665,7 @@ class MKDDescriptor(nn.Module):patches: Grayscale patch tensor with shape ``(B, 1, patch_size, patch_size)``.Returns:- Descriptor tensor with shape :math:`(B, D)`, with ``D`` as in the class's Convention block.+ Descriptor tensor with shape ``(B, D)``, with ``D`` as in the class's Convention block.Raises:ShapeError: if ``patches`` is not ``(B, 1, patch_size, patch_size)``.@@ -743,7 +743,7 @@ class SimpleKD(nn.Module):"""Run the example kernel-descriptor pipeline.Args:- x: Grayscale patch tensor with shape :math:`(B, 1, H, W)`.+ x: Grayscale patch tensor with shape ``(B, 1, H, W)``.Returns:Descriptor tensor produced by smoothing, gradient extraction, spatialdiff --git a/kornia/feature/orientation.py b/kornia/feature/orientation.pyindex 521e8a131..73258a7dd 100644--- a/kornia/feature/orientation.py+++ b/kornia/feature/orientation.py@@ -48,11 +48,11 @@ class PassLAF(nn.Module):"""Run forward.Args:- laf: :math:`(B, N, 2, 3)`+ laf: ``(B, N, 2, 3)``img: not used.Returns:- LAF, unchanged :math:`(B, N, 2, 3)`+ LAF, unchanged ``(B, N, 2, 3)``"""return laf@@ -111,10 +111,10 @@ class PatchDominantGradientOrientation(nn.Module):"""Run forward.Args:- patch: :math:`(B, 1, H, W)`+ patch: ``(B, 1, H, W)``Returns:- angle in radians: :math:`(B)`+ angle in radians: ``(B)``"""KORNIA_CHECK_SHAPE(patch, ["B", "1", "H", "W"])@@ -275,10 +275,10 @@ class OriNet(nn.Module):"""Run forward.Args:- patch: :math:`(B, 1, H, W)`+ patch: ``(B, 1, H, W)``Returns:- angle in radians: :math:`(B)`+ angle in radians: ``(B)``"""xy = self.features(self._normalize_input(patch)).view(-1, 2)@@ -329,11 +329,11 @@ class LAFOrienter(nn.Module):"""Run forward.Args:- laf: :math:`(B, N, 2, 3)`- img: :math:`(B, 1, H, W)`+ laf: ``(B, N, 2, 3)``+ img: ``(B, 1, H, W)``Returns:- LAF_out: :math:`(B, N, 2, 3)`+ LAF_out: ``(B, N, 2, 3)``"""KORNIA_CHECK_LAF(laf)diff --git a/kornia/feature/responses.py b/kornia/feature/responses.pyindex 1c51e41f9..79f4cf768 100644--- a/kornia/feature/responses.py+++ b/kornia/feature/responses.py@@ -75,15 +75,15 @@ def harris_response(- ``k`` is not validated.Args:- input: input image with shape :math:`(B, C, H, W)`.+ input: input image with shape ``(B, C, H, W)``.k: the Harris detector free parameter.grads_mode: can be ``'sobel'`` for standalone use or ``'diff'`` for use on Gaussian pyramid.- sigmas: per-image scales with shape :math:`(B)`. The response of image ``b`` is multiplied by+ sigmas: per-image scales with shape ``(B)``. The response of image ``b`` is multiplied by``sigmas[b] ** 4``, so that non-maxima suppression can compare the levels of a scale pyramid, as in`vlfeat <https://github.com/vlfeat/vlfeat/blob/master/vl/covdet.c>`_.Return:- the response map per channel with shape :math:`(B, C, H, W)`.+ the response map per channel with shape ``(B, C, H, W)``.Example:>>> input = torch.tensor([[[@@ -162,13 +162,13 @@ def gftt_response(decay with blur depends on the image structure, including the corner geometry.Args:- input: input image with shape :math:`(B, C, H, W)`.+ input: input image with shape ``(B, C, H, W)``.grads_mode: can be ``'sobel'`` for standalone use or ``'diff'`` for use on Gaussian pyramid.- sigmas: per-image scales with shape :math:`(B)`. The response of image ``b`` is multiplied by+ sigmas: per-image scales with shape ``(B)``. The response of image ``b`` is multiplied by``sigmas[b] ** 4``, so that non-maxima suppression can compare the levels of a scale pyramid.Return:- the response map per channel with shape :math:`(B, C, H, W)`.+ the response map per channel with shape ``(B, C, H, W)``.Example:>>> input = torch.tensor([[[@@ -252,17 +252,17 @@ def hessian_response(- Multiplying the image by ``c`` multiplies the response by ``c ** 2``, and an offset does not change it.Args:- input: input image with shape :math:`(B, C, H, W)`.+ input: input image with shape ``(B, C, H, W)``.grads_mode: can be ``'sobel'`` for standalone use or ``'diff'`` for use on Gaussian pyramid.- sigmas: per-image scales with shape :math:`(B)`. The response of image ``b`` is multiplied by+ sigmas: per-image scales with shape ``(B)``. The response of image ``b`` is multiplied by``sigmas[b] ** 4``, so that non-maxima suppression can compare the levels of a scale pyramid.Return:- the response map per channel with shape :math:`(B, C, H, W)`.+ the response map per channel with shape ``(B, C, H, W)``.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.tensor([[[@@ -316,10 +316,10 @@ def dog_response(input: torch.Tensor) -> torch.Tensor::math:`L(k\sigma) - L(\sigma)`: negative at a bright blob, positive at a dark one.Args:- input: a given the gaussian 5d torch.Tensor :math:`(B, C, D, H, W)`.+ input: a given the gaussian 5d torch.Tensor ``(B, C, D, H, W)``.Return:- the response map per channel with shape :math:`(B, C, D-1, H, W)`.+ the response map per channel with shape ``(B, C, D-1, H, W)``."""KORNIA_CHECK_SHAPE(input, ["B", "C", "L", "H", "W"])@@ -339,12 +339,12 @@ def dog_response_single(input: torch.Tensor, sigma1: float = 1.0, sigma2: floatswapping them flips the sign.Args:- input: a given the gaussian 4d torch.Tensor :math:`(B, C, H, W)`.+ input: a given the gaussian 4d torch.Tensor ``(B, C, H, W)``.sigma1: lower gaussian sigmasigma2: bigger gaussian sigmaReturn:- the response map per channel with shape :math:`(B, C, H, W)`.+ the response map per channel with shape ``(B, C, H, W)``."""KORNIA_CHECK_SHAPE(input, ["B", "C", "H", "W"])@@ -359,7 +359,7 @@ class BlobDoG(nn.Module):r"""Compute Difference-of-Gaussian responses of a (B, C, D, H, W) scale stack; the module form of dog_response.Convention:- Returns :func:`~kornia.feature.dog_response` of the :math:`(B, C, D, H, W)` scale stack; see its Convention+ Returns :func:`~kornia.feature.dog_response` of the ``(B, C, D, H, W)`` scale stack; see its Conventionblock. ``sigmas`` is ignored."""@@ -373,7 +373,7 @@ class BlobDoG(nn.Module):"""Compute Difference-of-Gaussians response maps.Args:- input: Input scale stack of shape :math:`(B, C, D, H, W)`.+ input: Input scale stack of shape ``(B, C, D, H, W)``.sigmas: Unused in this wrapper; kept for API compatibility.Returns:@@ -404,7 +404,7 @@ class BlobDoGSingle(nn.Module):"""Compute single-scale Difference-of-Gaussians response.Args:- input: Input tensor of shape :math:`(B, C, H, W)`.+ input: Input tensor of shape ``(B, C, H, W)``.sigmas: Unused in this wrapper; kept for API compatibility.Returns:@@ -441,7 +441,7 @@ class CornerHarris(nn.Module):"""Compute Harris corner response for each input channel.Args:- input: Input tensor of shape :math:`(B, C, H, W)`.+ input: Input tensor of shape ``(B, C, H, W)``.sigmas: Optional per-image scales forwarded to :func:`harris_response`, which multiplies theresponse by ``sigmas ** 4``.@@ -471,7 +471,7 @@ class CornerGFTT(nn.Module):"""Compute Shi-Tomasi (GFTT) corner response maps.Args:- input: Input tensor of shape :math:`(B, C, H, W)`.+ input: Input tensor of shape ``(B, C, H, W)``.sigmas: Optional per-image scales forwarded to :func:`gftt_response`, which multiplies theresponse by ``sigmas ** 4``.@@ -502,7 +502,7 @@ class BlobHessian(nn.Module):"""Compute Hessian determinant-like blob responses.Args:- input: Input tensor of shape :math:`(B, C, H, W)`.+ input: Input tensor of shape ``(B, C, H, W)``.sigmas: Optional per-image scales forwarded to :func:`hessian_response`, which multiplies theresponse by ``sigmas ** 4``.diff --git a/kornia/feature/scale_space_detector.py b/kornia/feature/scale_space_detector.pyindex d97cd0627..5873cf332 100644--- a/kornia/feature/scale_space_detector.py+++ b/kornia/feature/scale_space_detector.py@@ -265,7 +265,7 @@ class ScaleSpaceDetector(nn.Module):With a built-in ``subpix_module`` both signs are refined in one stacked call, whichroughly doubles the peak memory of the refinement step: the response volume and itsthree coordinate maps are materialised for ``2B`` images at once.- scale_space_response: if True, ``resp_module`` gets each whole octave :math:`(B, C, L, H, W)` with its+ scale_space_response: if True, ``resp_module`` gets each whole octave ``(B, C, L, H, W)`` with itssigmas :math:`(B \cdot L)` and returns a :math:`(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 :math:`(B \cdot L, C, H, W)` images, :math:`L = n_{levels} + 2`, with their sigmas@@ -772,8 +772,8 @@ class MultiResolutionDetector(nn.Module):- Detections are maxima of the response above ``score_threshold``. For a signed response whose minima arefeatures 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 :math:`(H_l, W_l)`, without a- sub-pixel step. It is reported at :math:`(u W / W_l, v H / H_l)` of the :math:`(H, W)` input, in the frame+ - 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 :math:`(u W / W_l, v H / H_l)` of the ``(H, W)`` input, in the frameof :func:`~kornia.feature.laf_from_center_scale_ori` (see :ref:`Local features <local-features-conventions>`),and not at the level pixel's centre :math:`((u + 0.5) W / W_l - 0.5, (v + 0.5) H / H_l - 0.5)`; the Key.Netreference maps it the same way.@@ -882,7 +882,7 @@ class MultiResolutionDetector(nn.Module):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 ``(u * factor[0], v * factor[1])``.- mask: Optional mask with shape :math:`(1, 1, H, W)` at the *original* image resolution, saying where a+ mask: Optional mask with shape ``(1, 1, H, W)`` at the *original* image resolution, saying where adetection may be. It is resampled onto this level conservatively and applied to the non-maximasuppression output, so a zero region drops every maximum within one level pixel of it and afloating-point weight scales the score. Keyword-only.diff --git a/kornia/feature/sift/pyramid.py b/kornia/feature/sift/pyramid.pyindex 6ae3ca111..21a8000ac 100644--- a/kornia/feature/sift/pyramid.py+++ b/kornia/feature/sift/pyramid.py@@ -109,8 +109,8 @@ class SIFTDescriptorFromPyramid(nn.Module):bins), which is remapped to ``num_ang_bins`` in each local frame.Shape:- - image: :math:`(B, 1, H, W)`- - lafs: :math:`(B, N, 2, 3)` in image pixel coordinates+ - image: ``(B, 1, H, W)``+ - lafs: ``(B, N, 2, 3)`` in image pixel coordinates- descriptors: :math:`(B, N, num_ang_bins * num_spatial_bins^2)`"""diff --git a/kornia/feature/siftdesc.py b/kornia/feature/siftdesc.pyindex 76af4d5d1..b7b44296b 100644--- a/kornia/feature/siftdesc.py+++ b/kornia/feature/siftdesc.py@@ -590,7 +590,7 @@ class DenseSIFTDescriptor(nn.Module):"""Compute dense SIFT descriptors over a full image grid.Args:- input: Grayscale image tensor with shape :math:`(B, 1, H, W)`.+ input: Grayscale image tensor with shape ``(B, 1, H, W)``.Returns:Dense descriptor map tensor with channel dimensiondiff --git a/kornia/feature/sold2/backbones.py b/kornia/feature/sold2/backbones.pyindex 12f00a921..a311afd73 100644--- a/kornia/feature/sold2/backbones.py+++ b/kornia/feature/sold2/backbones.py@@ -67,10 +67,10 @@ class HourglassBackbone(nn.Module):"""Run this SOLD2 backbone component forward.Args:- input_images: Input image batch with shape :math:`(B, C, H, W)`.+ input_images: Input image batch with shape ``(B, C, H, W)``.Returns:- Feature map with shape :math:`(B, 256, H/4, W/4)`.+ Feature map with shape ``(B, 256, H/4, W/4)``."""return self.net(input_images)@@ -99,10 +99,10 @@ class MultitaskHead(nn.Module):"""Run this SOLD2 backbone component forward.Args:- x: Input feature tensor with shape :math:`(B, C, H, W)`.+ x: Input feature tensor with shape ``(B, C, H, W)``.Returns:- Concatenated predictions from all heads with shape :math:`(B, 5, H, W)`.+ Concatenated predictions from all heads with shape ``(B, 5, H, W)``."""return torch.cat([head(x) for head in self.heads], dim=1)@@ -133,7 +133,7 @@ class Bottleneck2D(nn.Module):r"""Run this SOLD2 backbone component forward.Args:- x: Input feature tensor with shape :math:`(B, C, H, W)`.+ x: Input feature tensor with shape ``(B, C, H, W)``.Returns:Residual block output tensor with shape :math:`(B, 2 \times \text{planes}, H', W')`.@@ -209,10 +209,10 @@ class Hourglass(nn.Module):"""Run this SOLD2 backbone component forward.Args:- x: Input feature tensor with shape :math:`(B, C, H, W)`.+ x: Input feature tensor with shape ``(B, C, H, W)``.Returns:- Hourglass output feature tensor with shape :math:`(B, C, H, W)`.+ Hourglass output feature tensor with shape ``(B, C, H, W)``."""return self._hour_glass_forward(self.depth, x)@@ -287,10 +287,10 @@ class HourglassNet(nn.Module):"""Run this SOLD2 backbone component forward.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`.+ x: Input image tensor with shape ``(B, C, H, W)``.Returns:- Output feature map of the last stack with shape :math:`(B, 256, H/4, W/4)`.+ Output feature map of the last stack with shape ``(B, 256, H/4, W/4)``."""out = []x = self.conv1(x)@@ -353,10 +353,10 @@ class SuperpointDecoder(nn.Module):"""Run this SOLD2 backbone component forward.Args:- input_features: Input feature map with shape :math:`(B, C, H/4, W/4)`.+ input_features: Input feature map with shape ``(B, C, H/4, W/4)``.Returns:- Junction heatmap prediction with shape :math:`(B, H, W)`.+ Junction heatmap prediction with shape ``(B, H, W)``."""feat = self.relu(self.convPa(input_features))semi = self.convPb(feat)@@ -424,10 +424,10 @@ class PixelShuffleDecoder(nn.Module):"""Run this SOLD2 backbone component forward.Args:- input_features: Input feature map with shape :math:`(B, C, H/4, W/4)`.+ input_features: Input feature map with shape ``(B, C, H/4, W/4)``.Returns:- Line heatmap prediction with shape :math:`(B, H, W)`.+ Line heatmap prediction with shape ``(B, H, W)``."""# Iterate til output blockout = input_features@@ -461,10 +461,10 @@ class SuperpointDescriptor(nn.Module):"""Run this SOLD2 backbone component forward.Args:- input_features: Input feature map with shape :math:`(B, C, H/4, W/4)`.+ input_features: Input feature map with shape ``(B, C, H/4, W/4)``.Returns:- Semi-dense descriptors with shape :math:`(B, 128, H/4, W/4)`.+ Semi-dense descriptors with shape ``(B, 128, H/4, W/4)``."""feat = self.relu(self.convPa(input_features))return self.convPb(feat)@@ -509,7 +509,7 @@ class SOLD2Net(nn.Module):"""Run this SOLD2 backbone component forward.Args:- input_images: Input image batch with shape :math:`(B, 1, H, W)`.+ input_images: Input image batch with shape ``(B, 1, H, W)``.Returns:Dictionary containing predicted junction heatmap, line heatmap, and optional descriptors.diff --git a/kornia/feature/sold2/sold2.py b/kornia/feature/sold2/sold2.pyindex 751c59bb8..5f43da44f 100644--- a/kornia/feature/sold2/sold2.py+++ b/kornia/feature/sold2/sold2.py@@ -46,9 +46,9 @@ class SOLD2(nn.Module):Convention:- :meth:`forward` takes the input and returns the heatmaps and the ``(row, col)`` line segments of:class:`~kornia.feature.SOLD2_detector`, whose Convention block gives their frame and order, and also- ``dense_desc``, :math:`(B, 128, H / 4, W / 4)`, which is not normalized.+ ``dense_desc``, ``(B, 128, H / 4, W / 4)``, which is not normalized.- ``match`` takes segments as :meth:`forward` returns them and the descriptor map of one image each. It- returns an int64 tensor :math:`(N_1,)`: for each segment of ``line_seg1``, the index of its match in+ returns an int64 tensor ``(N_1,)``: for each segment of ``line_seg1``, the index of its match in``line_seg2``, or ``-1``. It is int64 also when either set of segments is empty: an empty tensor when``line_seg1`` is, ``-1`` for every segment of ``line_seg1`` when ``line_seg2`` is.- Known defects: on CPU, ``match`` passes float16 and bfloat16 descriptor maps to torch's ``grid_sample``@@ -108,13 +108,13 @@ class SOLD2(nn.Module):"""Run forward.Args:- img: batched images with shape :math:`(B, 1, H, W)`.+ img: batched images with shape ``(B, 1, H, W)``.Returns:line_segments: list of N line segments in each of the B images :math:`List[(N, 2, 2)]`.- junction_heatmap: raw junction heatmap of shape :math:`(B, H, W)`.- line_heatmap: raw line heatmap of shape :math:`(B, H, W)`.- dense_desc: the semi-dense descriptor map of shape :math:`(B, 128, H/4, W/4)`.+ junction_heatmap: raw junction heatmap of shape ``(B, H, W)``.+ line_heatmap: raw line heatmap of shape ``(B, H, W)``.+ dense_desc: the semi-dense descriptor map of shape ``(B, 128, H/4, W/4)``."""KORNIA_CHECK_SHAPE(img, ["B", "1", "H", "W"])diff --git a/kornia/feature/sold2/sold2_detector.py b/kornia/feature/sold2/sold2_detector.pyindex aee2e6e69..1b6cb8951 100644--- a/kornia/feature/sold2/sold2_detector.py+++ b/kornia/feature/sold2/sold2_detector.py@@ -41,10 +41,10 @@ class SOLD2_detector(nn.Module):Occlusion-aware Line Detector and Descriptor". See :cite:`SOLD22021` for more details.Convention:- - The input is a grayscale image :math:`(B, 1, H, W)`, in :math:`[0, 1]` for the pretrained weights, with+ - The input is a grayscale image ``(B, 1, H, W)``, in :math:`[0, 1]` for the pretrained weights, with``H`` and ``W`` multiples of 8; other sizes raise an error or give heatmaps of another size.- ``junction_heatmap`` and ``line_heatmap`` are :math:`(B, H, W)`.- - ``line_segments`` holds one :math:`(N, 2, 2)` tensor per image: the two endpoints of each segment as+ ``junction_heatmap`` and ``line_heatmap`` are ``(B, H, W)``.+ - ``line_segments`` holds one ``(N, 2, 2)`` tensor per image: the two endpoints of each segment as``(row, col)`` in the pixel frame of :func:`~kornia.feature.laf_from_center_scale_ori`(see :ref:`Local features <local-features-conventions>`), so ``flip(-1)`` gives ``(x, y)``. The endpointsof a segment, and the segments by their first endpoint, are in raster order: the smaller row first or, on@@ -119,12 +119,12 @@ class SOLD2_detector(nn.Module):"""Run forward.Args:- img: batched images with shape :math:`(B, 1, H, W)`.+ img: batched images with shape ``(B, 1, H, W)``.Returns:line_segments: list of N line segments in each of the B images :math:`List[(N, 2, 2)]`.- junction_heatmap: raw junction heatmap of shape :math:`(B, H, W)`.- line_heatmap: raw line heatmap of shape :math:`(B, H, W)`.+ junction_heatmap: raw junction heatmap of shape ``(B, H, W)``.+ line_heatmap: raw line heatmap of shape ``(B, H, W)``."""KORNIA_CHECK_SHAPE(img, ["B", "1", "H", "W"])@@ -602,13 +602,13 @@ def prob_to_junctions(prob: torch.Tensor, dist: float, prob_thresh: float = 0.01from the junction indices is the one with the smaller row or, on the same row, the smaller column.Args:- prob: junction probability map with shape :math:`(H, W)`.+ prob: junction probability map with shape ``(H, W)``.dist: suppression distance in pixels.prob_thresh: minimum probability of a junction.top_k: number of junctions to keep; ``0`` keeps all.Returns:- Junction locations in ``(row, col)`` order with shape :math:`(N, 2)`.+ Junction locations in ``(row, col)`` order with shape ``(N, 2)``."""# Extract the junctionsjunctions = torch.stack(torch.where(prob >= prob_thresh), -1).float()diff --git a/kornia/feature/sosnet.py b/kornia/feature/sosnet.pyindex f2ab44778..734a2f166 100644--- a/kornia/feature/sosnet.py+++ b/kornia/feature/sosnet.py@@ -48,8 +48,8 @@ class SOSNet(nn.Module):pretrained: Download and set pretrained weights to the model.Shape:- - Input: :math:`(B, 1, 32, 32)`- - Output: :math:`(B, 128)`+ - Input: ``(B, 1, 32, 32)``+ - Output: ``(B, 128)``Note:With float16 weights, the final BatchNorm keeps its running statistics in float32.@@ -101,11 +101,11 @@ class SOSNet(nn.Module):"""Compute SOSNet descriptors for grayscale 32x32 patches.Args:- input: Input tensor with shape :math:`(B, 1, 32, 32)`.+ input: Input tensor with shape ``(B, 1, 32, 32)``.eps: Small constant added before normalization for stability.Returns:- Descriptor tensor with shape :math:`(B, 128)`.+ Descriptor tensor with shape ``(B, 128)``."""KORNIA_CHECK_SHAPE(input, ["B", "1", "32", "32"])descr = self.layers(input)diff --git a/kornia/feature/tfeat.py b/kornia/feature/tfeat.pyindex c6ca72954..f62d09980 100644--- a/kornia/feature/tfeat.py+++ b/kornia/feature/tfeat.py@@ -58,8 +58,8 @@ class TFeat(nn.Module):torch.Tensor: TFeat descriptor of the patches.Shape:- - Input: :math:`(B, 1, 32, 32)`- - Output: :math:`(B, 128)`+ - Input: ``(B, 1, 32, 32)``+ - Output: ``(B, 128)``Examples:>>> input = torch.rand(16, 1, 32, 32)@@ -91,10 +91,10 @@ class TFeat(nn.Module):"""Compute TFeat descriptors for grayscale 32x32 patches.Args:- input: Input tensor with shape :math:`(B, 1, 32, 32)`.+ input: Input tensor with shape ``(B, 1, 32, 32)``.Returns:- Descriptor tensor with shape :math:`(B, 128)`.+ Descriptor tensor with shape ``(B, 128)``."""KORNIA_CHECK_SHAPE(input, ["B", "1", "32", "32"])x = self.features(input)diff --git a/kornia/feature/xfeat.py b/kornia/feature/xfeat.pyindex 9030d6de5..4f0b55289 100644--- a/kornia/feature/xfeat.py+++ b/kornia/feature/xfeat.py@@ -92,12 +92,12 @@ class XFeatModel(nn.Module):Implements the architecture from"XFeat: Accelerated Features for Lightweight Image Matching", CVPR 2024.- Input: float image tensor :math:`(B, C, H, W)` (grayscale or RGB, any channel count).+ Input: float image tensor ``(B, C, H, W)`` (grayscale or RGB, any channel count).Output:- - ``feats``: dense descriptors :math:`(B, 64, H/8, W/8)`.- - ``keypoints``: keypoint logits :math:`(B, 65, H/8, W/8)`.- - ``heatmap``: reliability map :math:`(B, 1, H/8, W/8)`.+ - ``feats``: dense descriptors ``(B, 64, H/8, W/8)``.+ - ``keypoints``: keypoint logits ``(B, 65, H/8, W/8)``.+ - ``heatmap``: reliability map ``(B, 1, H/8, W/8)``.Convention:- The channels are averaged and the result is instance-normalised, so any channel count is accepted and an@@ -200,13 +200,13 @@ class XFeatModel(nn.Module):"""Run the XFeat backbone.Args:- x: image tensor of shape :math:`(B, C, H, W)`.+ x: image tensor of shape ``(B, C, H, W)``.Returns:Tuple of:- - feats: dense descriptors :math:`(B, 64, H/8, W/8)`.- - keypoints: keypoint logits :math:`(B, 65, H/8, W/8)`.- - heatmap: reliability map :math:`(B, 1, H/8, W/8)`.+ - feats: dense descriptors ``(B, 64, H/8, W/8)``.+ - keypoints: keypoint logits ``(B, 65, H/8, W/8)``.+ - heatmap: reliability map ``(B, 1, H/8, W/8)``."""with torch.no_grad():x = x.mean(dim=1, keepdim=True)@@ -247,9 +247,9 @@ class InterpolateSparse2d(nn.Module):``False``.Shape:- - Input ``x``: :math:`(B, C, H, W)`.- - Input ``pos``: :math:`(B, N, 2)` integer or float (x, y) coordinates.- - Output: :math:`(B, N, C)`.+ - Input ``x``: ``(B, C, H, W)``.+ - Input ``pos``: ``(B, N, 2)`` integer or float (x, y) coordinates.+ - Output: ``(B, N, C)``."""def __init__(self, mode: str = "bicubic", align_corners: bool = False) -> None:@@ -271,13 +271,13 @@ class InterpolateSparse2d(nn.Module):"""Sample ``x`` at positions ``pos``.Args:- x: feature map :math:`(B, C, H, W)`.- pos: sampling positions :math:`(B, N, 2)` in pixel coordinates.+ x: feature map ``(B, C, H, W)``.+ pos: sampling positions ``(B, N, 2)`` in pixel coordinates.H: height used for coordinate normalisation.W: width used for coordinate normalisation.Returns:- Sampled features :math:`(B, N, C)`.+ Sampled features ``(B, N, C)``."""grid = self.normgrid(pos, H, W).unsqueeze(-2).to(x.dtype)# align_corners=False is intentional: the pretrained XFeat weights were trained@@ -305,7 +305,7 @@ class XFeat(nn.Module):running statistics on every call, and matching a single small image pair raises; call ``.eval()`` forinference. :meth:`from_pretrained` returns the trained model in evaluation mode. The inference methodsrun under ``torch.inference_mode``.- - The image is :math:`(B, C, H, W)` with any channel count. Each extraction resizes the image it gets+ - The image is ``(B, C, H, W)`` with any channel count. Each extraction resizes the image it getsbilinearly to :math:`(H', W')`: ``H`` and ``W`` rounded down to multiples of 32, with a minimum of 32.:class:`XFeatModel` then averages the channels and instance-normalises the result, so an affine change of theintensities with a positive gain changes its maps only through the norm's ``eps``, which weighs more the@@ -421,7 +421,7 @@ class XFeat(nn.Module):@staticmethoddef _create_xy(h: int, w: int, device: torch.device) -> torch.Tensor:- """Create a grid of (x, y) pixel coordinates of shape :math:`(H*W, 2)`."""+ """Create a grid of (x, y) pixel coordinates of shape ``(H*W, 2)``."""y, x = torch.meshgrid(torch.arange(h, device=device), torch.arange(w, device=device), indexing="ij")return torch.cat([x[..., None], y[..., None]], -1).reshape(-1, 2)@@ -572,16 +572,16 @@ class XFeat(nn.Module):"""Detect sparse keypoints and compute descriptors.Args:- x: image tensor of shape :math:`(B, C, H, W)`.+ x: image tensor of shape ``(B, C, H, W)``.top_k: number of keypoints to keep (overrides ``self.top_k``).detection_threshold: the heatmap value to exceed (overrides ``self.detection_threshold``).Returns:List of length ``B``. Each element is a dict with:- - ``'keypoints'``: :math:`(N, 2)` keypoints in (x, y) pixel coordinates.- - ``'scores'``: :math:`(N,)` keypoint heatmap value times reliability, in descending order.- - ``'descriptors'``: :math:`(N, 64)` L2-normalised descriptors.+ - ``'keypoints'``: ``(N, 2)`` keypoints in (x, y) pixel coordinates.+ - ``'scores'``: ``(N,)`` keypoint heatmap value times reliability, in descending order.+ - ``'descriptors'``: ``(N, 64)`` L2-normalised descriptors."""if top_k is None:top_k = self.top_k@@ -630,7 +630,7 @@ class XFeat(nn.Module):"""Detect keypoints and compute dense coarse descriptors.Args:- x: image tensor of shape :math:`(B, C, H, W)`.+ x: image tensor of shape ``(B, C, H, W)``.top_k: number of features to keep (overrides ``self.top_k``). A value below 1 keeps every cell. With``multiscale=True`` the budget is split between the scales, ``int(0.2 * top_k)`` for the 0.6xextraction and the rest for the 1.3x one, so the result never exceeds a positive ``top_k``; a scale@@ -641,9 +641,9 @@ class XFeat(nn.Module):Returns:Dict with:- - ``'keypoints'``: :math:`(B, K, 2)` coarse keypoints.- - ``'descriptors'``: :math:`(B, K, 64)` coarse descriptors.- - ``'scales'``: :math:`(B, K)` extraction scale per keypoint.+ - ``'keypoints'``: ``(B, K, 2)`` coarse keypoints.+ - ``'descriptors'``: ``(B, K, 64)`` coarse descriptors.+ - ``'scales'``: ``(B, K)`` extraction scale per keypoint."""if top_k is None:top_k = self.top_k@@ -667,13 +667,13 @@ class XFeat(nn.Module):"""Detect, describe and mutually match keypoints from two images.Args:- img1: first image tensor of shape :math:`(1, C, H, W)`.- img2: second image tensor of shape :math:`(1, C, H, W)`.+ img1: first image tensor of shape ``(1, C, H, W)``.+ img2: second image tensor of shape ``(1, C, H, W)``.top_k: number of top keypoints to use.min_cossim: minimum cosine similarity threshold. Use ``-1`` to disable.Returns:- Tuple ``(mkpts0, mkpts1)`` of matched keypoints, each :math:`(N, 2)`.+ Tuple ``(mkpts0, mkpts1)`` of matched keypoints, each ``(N, 2)``."""if top_k is None:top_k = self.top_k@@ -692,14 +692,14 @@ class XFeat(nn.Module):"""Extract coarse features, match pairs and refine matches (XFeat*).Args:- im_set1: batch of images :math:`(B, C, H, W)`.- im_set2: batch of images :math:`(B, C, H, W)`.+ im_set1: batch of images ``(B, C, H, W)``.+ im_set2: batch of images ``(B, C, H, W)``.top_k: number of top features to use.Returns:- If ``B != 1``: list of :math:`(N, 4)` tensors with ``(x1, y1, x2, y2)`` matches, one per pair; an empty+ If ``B != 1``: list of ``(N, 4)`` tensors with ``(x1, y1, x2, y2)`` matches, one per pair; an emptybatch gives an empty list.- If ``B == 1``: tuple of :math:`(N, 2)` matched keypoint tensors.+ If ``B == 1``: tuple of ``(N, 2)`` matched keypoint tensors."""if top_k is None:top_k = self.top_kdiff --git a/kornia/filters/bilateral.py b/kornia/filters/bilateral.pyindex 6dfa90377..f51d7eec9 100644--- a/kornia/filters/bilateral.py+++ b/kornia/filters/bilateral.py@@ -353,14 +353,14 @@ def bilateral_blur(up the weighted values in a different order, so they agree to rounding.Arguments:- input: the input torch.Tensor with shape :math:`(B,C,H,W)`.+ input: the input torch.Tensor with shape ``(B,C,H,W)``.kernel_size: the size of the kernel. Each entry must be a positive odd integer.sigma_color: the standard deviation for intensity/color Gaussian kernel.Smaller values preserve more edges. It must be positive. A float is shared by the batch; a- torch.Tensor has shape :math:`(1,)`, shared by the batch, or :math:`(B,)`, one value per sample.+ torch.Tensor has shape ``(1,)``, shared by the batch, or ``(B,)``, one value per sample.sigma_space: the standard deviation for spatial Gaussian kernel.This is similar to ``sigma`` in :func:`gaussian_blur2d()`. A tuple of two floats is shared by the batch;- a torch.Tensor has shape :math:`(1, 2)`, shared by the batch, or :math:`(B, 2)`, one row per sample.+ a torch.Tensor has shape ``(1, 2)``, shared by the batch, or ``(B, 2)``, one row per sample.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,``'replicate'`` or ``'circular'``. Default: ``'reflect'``.@@ -368,7 +368,7 @@ def bilateral_blur(difference. Only ``'l1'`` or ``'l2'`` is allowed. Default: ``'l1'``.Returns:- the blurred torch.Tensor with shape :math:`(B, C, H, W)`.+ the blurred torch.Tensor with shape ``(B, C, H, W)``.Raises:BaseError: if an entry of ``kernel_size`` is even or not positive.@@ -406,21 +406,21 @@ def joint_bilateral_blur(- See the Convention block on :func:`~kornia.filters.bilateral_blur`; the colour distances are taken in``guidance``, and ``input`` is what gets averaged.- ``input`` comes first and ``guidance`` second, the opposite of :func:`~kornia.filters.guided_blur`.- - ``guidance`` may have its own channel count; its batch size and :math:`(H, W)` must equal ``input``'s.+ - ``guidance`` may have its own channel count; its batch size and ``(H, W)`` must equal ``input``'s.- ``guidance`` is cast to the dtype of a floating ``input``, so the output keeps ``input``'s dtype. An integer``input`` is filtered in float32, as by :func:`~kornia.filters.bilateral_blur`, and its ``guidance`` iscast to float32.Arguments:- input: the input torch.Tensor with shape :math:`(B,C,H,W)`.- guidance: the guidance torch.Tensor with shape :math:`(B,C_g,H,W)`.+ input: the input torch.Tensor with shape ``(B,C,H,W)``.+ guidance: the guidance torch.Tensor with shape ``(B,C_g,H,W)``.kernel_size: the size of the kernel. Each entry must be a positive odd integer.sigma_color: the standard deviation for intensity/color Gaussian kernel.Smaller values preserve more edges. It must be positive. A float is shared by the batch; a- torch.Tensor has shape :math:`(1,)`, shared by the batch, or :math:`(B,)`, one value per sample.+ torch.Tensor has shape ``(1,)``, shared by the batch, or ``(B,)``, one value per sample.sigma_space: the standard deviation for spatial Gaussian kernel.This is similar to ``sigma`` in :func:`gaussian_blur2d()`. A tuple of two floats is shared by the batch;- a torch.Tensor has shape :math:`(1, 2)`, shared by the batch, or :math:`(B, 2)`, one row per sample.+ a torch.Tensor has shape ``(1, 2)``, shared by the batch, or ``(B, 2)``, one row per sample.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,``'replicate'`` or ``'circular'``. Default: ``'reflect'``.@@ -428,7 +428,7 @@ def joint_bilateral_blur(difference. Only ``'l1'`` or ``'l2'`` is allowed. Default: ``'l1'``.Returns:- the blurred torch.Tensor with shape :math:`(B, C, H, W)`.+ the blurred torch.Tensor with shape ``(B, C, H, W)``.Raises:BaseError: if an entry of ``kernel_size`` is even or not positive.@@ -489,10 +489,10 @@ class BilateralBlur(_BilateralBlur):kernel_size: the size of the kernel. Each entry must be a positive odd integer.sigma_color: the standard deviation for intensity/color Gaussian kernel.Smaller values preserve more edges. It must be positive. A float is shared by the batch; a- torch.Tensor has shape :math:`(1,)`, shared by the batch, or :math:`(B,)`, one value per sample.+ torch.Tensor has shape ``(1,)``, shared by the batch, or ``(B,)``, one value per sample.sigma_space: the standard deviation for spatial Gaussian kernel.This is similar to ``sigma`` in :func:`gaussian_blur2d()`. A tuple of two floats is shared by the batch;- a torch.Tensor has shape :math:`(1, 2)`, shared by the batch, or :math:`(B, 2)`, one row per sample.+ a torch.Tensor has shape ``(1, 2)``, shared by the batch, or ``(B, 2)``, one row per sample.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,``'replicate'`` or ``'circular'``. Default: ``'reflect'``.@@ -503,8 +503,8 @@ class BilateralBlur(_BilateralBlur):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Raises:BaseError: if an entry of ``kernel_size`` is even or not positive; raised from the constructor.@@ -531,13 +531,13 @@ class BilateralBlur(_BilateralBlur):suppressed even if they are spatially close.Args:- input: Input image tensor with shape :math:`(B, C, H, W)`,+ input: Input image tensor with shape ``(B, C, H, W)``,where :math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the image height, and :math:`W` is theimage width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the+ Tensor with shape ``(B, C, H, W)`` containing theedge-preserving smoothed image. The output keeps the layout anddevice of ``input``, and the dtype of a floating ``input`` unless atensor ``sigma_space`` of a wider dtype promotes it, while reducing@@ -563,10 +563,10 @@ class JointBilateralBlur(_BilateralBlur):kernel_size: the size of the kernel. Each entry must be a positive odd integer.sigma_color: the standard deviation for intensity/color Gaussian kernel.Smaller values preserve more edges. It must be positive. A float is shared by the batch; a- torch.Tensor has shape :math:`(1,)`, shared by the batch, or :math:`(B,)`, one value per sample.+ torch.Tensor has shape ``(1,)``, shared by the batch, or ``(B,)``, one value per sample.sigma_space: the standard deviation for spatial Gaussian kernel.This is similar to ``sigma`` in :func:`gaussian_blur2d()`. A tuple of two floats is shared by the batch;- a torch.Tensor has shape :math:`(1, 2)`, shared by the batch, or :math:`(B, 2)`, one row per sample.+ a torch.Tensor has shape ``(1, 2)``, shared by the batch, or ``(B, 2)``, one row per sample.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,``'replicate'`` or ``'circular'``. Default: ``'reflect'``.@@ -577,8 +577,8 @@ class JointBilateralBlur(_BilateralBlur):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`, :math:`(B, C_g, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``, ``(B, C_g, H, W)``+ - Output: ``(B, C, H, W)``Raises:BaseError: if an entry of ``kernel_size`` is even or not positive; raised from the constructor.@@ -607,7 +607,7 @@ class JointBilateralBlur(_BilateralBlur):signal, such as a depth map, mask, or noisy feature image.Args:- input: Tensor to smooth with shape :math:`(B, C, H, W)`, where+ input: Tensor to smooth with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number of inputchannels, :math:`H` is the height, and :math:`W` is the width.guidance: Tensor used to compute range weights. Its batch and@@ -616,7 +616,7 @@ class JointBilateralBlur(_BilateralBlur):different representation.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the filtered+ Tensor with shape ``(B, C, H, W)`` containing the filtered``input`` values. Edges present in ``guidance`` reduce mixingacross boundaries, while smooth regions are averaged more strongly."""diff --git a/kornia/filters/blur.py b/kornia/filters/blur.pyindex b96385ca8..aff6027f1 100644--- a/kornia/filters/blur.py+++ b/kornia/filters/blur.py@@ -132,7 +132,7 @@ def box_blur(:func:`~kornia.filters.filter2d`.Args:- input: the image to blur with shape :math:`(B,C,H,W)`.+ input: the image to blur with shape ``(B,C,H,W)``.kernel_size: the blurring kernel size.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``, ``'replicate'`` or ``'circular'``.@@ -142,7 +142,7 @@ def box_blur(absolute values stays below the dtype's largest finite value; beyond it the result can be ``inf`` or NaN.Returns:- the blurred torch.Tensor with shape :math:`(B,C,H,W)`.+ the blurred torch.Tensor with shape ``(B,C,H,W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/filtering_operators.html>`__.@@ -206,8 +206,8 @@ class BoxBlur(nn.Module):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Example:>>> input = torch.rand(2, 4, 5, 7)@@ -267,12 +267,12 @@ class BoxBlur(nn.Module):dimensional passes.Args:- input: Image or feature tensor with shape :math:`(B, C, H, W)`,+ input: Image or feature tensor with shape ``(B, C, H, W)``,where :math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the locally+ Tensor with shape ``(B, C, H, W)`` containing the locallyaveraged result. The output keeps the same batch, channel, andspatial layout as ``input``; border pixels are handled according tothe configured border mode.diff --git a/kornia/filters/blur_pool.py b/kornia/filters/blur_pool.pyindex f484335cb..7e9295ba8 100644--- a/kornia/filters/blur_pool.py+++ b/kornia/filters/blur_pool.py@@ -52,7 +52,7 @@ class BlurPool2D(nn.Module):stride: stride for pooling.Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output: :math:`(B, C, H_{out}, W_{out})`, where.. math::@@ -85,7 +85,7 @@ class BlurPool2D(nn.Module):content is subsampled directly.Args:- input: Feature map tensor with shape :math:`(B, C, H, W)`, where+ input: Feature map tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the input height, and :math:`W` is theinput width.@@ -121,7 +121,7 @@ class MaxBlurPool2D(nn.Module)::class:`DeprecationWarning`; it will be removed in a future release.Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output: :math:`(B, C, H_{out}, W_{out})`, where.. math::@@ -170,7 +170,7 @@ class MaxBlurPool2D(nn.Module):shifts while still reducing the feature resolution.Args:- input: Feature map tensor with shape :math:`(B, C, H, W)`, where+ input: Feature map tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the channel count,:math:`H` is the height, and :math:`W` is the width.@@ -222,7 +222,7 @@ class EdgeAwareBlurPool2D(nn.Module):maps where edges should remain sharp after downsampling.Args:- input: Feature map tensor with shape :math:`(B, C, H, W)`, where+ input: Feature map tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the input height, and :math:`W` is theinput width.@@ -232,7 +232,7 @@ class EdgeAwareBlurPool2D(nn.Module):Returns:Edge-aware blurred tensor with the shape of ``input``,- :math:`(B, C, H, W)`.+ ``(B, C, H, W)``."""_check_floating_feature_map(input, "EdgeAwareBlurPool2D")if epsilon is None:@@ -269,7 +269,7 @@ def blur_pool2d(input: torch.Tensor, kernel_size: tuple[int, int] | int, stride:stride: stride for pooling.Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output: :math:`(B, C, H_{out}, W_{out})`, where.. math::@@ -457,7 +457,7 @@ def edge_aware_blur_pool2d(logarithm and can form edges, and ``input = -epsilon`` gives ``-inf``, an edge against any value above it.Args:- input: the input image to blur with shape :math:`(B, C, H, W)`.+ input: the input image to blur with shape ``(B, C, H, W)``.kernel_size: the size of the square binomial blur kernel.edge_threshold: intensity ratio between pixels 4 apart above which a pixel counts as an edge and keeps itsvalue. It must be greater than 1.@@ -465,7 +465,7 @@ def edge_aware_blur_pool2d(epsilon: for numerical stability.Returns:- The blurred torch.Tensor of shape :math:`(B, C, H, W)`.+ The blurred torch.Tensor of shape ``(B, C, H, W)``."""KORNIA_CHECK_SHAPE(input, ["B", "C", "H", "W"])diff --git a/kornia/filters/canny.py b/kornia/filters/canny.pyindex a71f77183..c0d57880d 100644--- a/kornia/filters/canny.py+++ b/kornia/filters/canny.py@@ -129,7 +129,7 @@ def canny(Convention:- A 3-channel input is converted with :func:`~kornia.color.rgb_to_grayscale`, which reads channel 0 as- red. Both outputs are :math:`(B, 1, H, W)`, in the input's dtype for a floating input and in float32 for+ red. Both outputs are ``(B, 1, H, W)``, in the input's dtype for a floating input and in float32 foran integer one, which is processed in float32 on its own scale.- The image is blurred with ``gaussian_blur2d(input, kernel_size, sigma)``; the Convention block on:func:`~kornia.filters.gaussian_blur2d` gives the order of both pairs, and ``kernel_size=1`` skips the@@ -164,7 +164,7 @@ def canny(is converted with the floating weights rather than rounded to an integer grey.Args:- input: input image torch.Tensor with shape :math:`(B,C,H,W)`, with :math:`C` equal to 1, or to 3 for an RGB+ input: input image torch.Tensor with shape ``(B,C,H,W)``, with :math:`C` equal to 1, or to 3 for an RGBimage, which is converted to grayscale.low_threshold: lower threshold for the hysteresis procedure, in the units of the magnitude above. It must bepositive and at most ``high_threshold``.@@ -176,8 +176,8 @@ def canny(eps: regularization number to avoid NaN during backprop.Returns:- - the gradient magnitude after non-maximum suppression, shape of :math:`(B,1,H,W)`.- - the canny edge detection filtered by thresholds and hysteresis, shape of :math:`(B,1,H,W)`.+ - the gradient magnitude after non-maximum suppression, shape of ``(B,1,H,W)``.+ - the canny edge detection filtered by thresholds and hysteresis, shape of ``(B,1,H,W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/canny.html>`__.@@ -337,8 +337,8 @@ class Canny(nn.Module):eps: regularization number to avoid NaN during backprop.Returns:- - the gradient magnitude after non-maximum suppression, shape of :math:`(B,1,H,W)`.- - the canny edge detection filtered by thresholds and hysteresis, shape of :math:`(B,1,H,W)`.+ - the gradient magnitude after non-maximum suppression, shape of ``(B,1,H,W)``.+ - the canny edge detection filtered by thresholds and hysteresis, shape of ``(B,1,H,W)``.Example:>>> input = torch.rand(5, 3, 4, 4)@@ -400,7 +400,7 @@ class Canny(nn.Module):pixels.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the image height, and :math:`W` is theimage width. :math:`C` must be 1, or 3 for an RGB image, which isdiff --git a/kornia/filters/dissolving.py b/kornia/filters/dissolving.pyindex 20a2432dd..0a5f00e30 100644--- a/kornia/filters/dissolving.py+++ b/kornia/filters/dissolving.py@@ -289,7 +289,7 @@ class StableDiffusionDissolving(ImageModule):Args:input: Image tensor passed to the wrapped dissolving model. Theexpected shape follows the model wrapper, typically- :math:`(B, C, H, W)`, where :math:`B` is the batch size,+ ``(B, C, H, W)``, where :math:`B` is the batch size,:math:`C` is the channel count, :math:`H` is the image height,and :math:`W` is the image width.step_number: Integer diffusion timestep used by the dissolvingdiff --git a/kornia/filters/filter.py b/kornia/filters/filter.pyindex e226e067e..1d28e7f44 100644--- a/kornia/filters/filter.py+++ b/kornia/filters/filter.py@@ -110,7 +110,7 @@ def filter2d(Args:input: the input tensor with shape of- :math:`(B, C, H, W)`.+ ``(B, C, H, W)``.kernel: the kernel to be convolved with the inputtensor. The kernel shape must be :math:`(1, kH, kW)` or :math:`(B, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -123,7 +123,7 @@ def filter2d(or true convolution (kernel is flipped). 2 modes available ``'corr'`` or ``'conv'``.Return:- the filtered tensor. With ``padding='same'`` it has the input's shape :math:`(B, C, H, W)`. With+ the filtered tensor. With ``padding='same'`` it has the input's shape ``(B, C, H, W)``. With``padding='valid'`` it has shape :math:`(B, C, H - kH + 1, W - kW + 1)`, and its pixel ``(0, 0)`` is the``'same'`` output at the anchor ``(a_y, a_x)``.@@ -226,7 +226,7 @@ def filter2d_separable(Args:input: the input tensor with shape of- :math:`(B, C, H, W)`.+ ``(B, C, H, W)``.kernel_x: the kernel to be convolved with the inputtensor. The kernel shape must be :math:`(1, kW)` or :math:`(B, kW)`.kernel_y: the kernel to be convolved with the input@@ -240,7 +240,7 @@ def filter2d_separable(Return:the filtered tensor, of the shape :func:`~kornia.filters.filter2d` returns for the same ``padding``:- :math:`(B, C, H, W)` with ``padding='same'``.+ ``(B, C, H, W)`` with ``padding='same'``.Example:>>> input = torch.tensor([[[@@ -285,7 +285,7 @@ def filter3d(Args:input: the input tensor with shape of- :math:`(B, C, D, H, W)`.+ ``(B, C, D, H, W)``.kernel: the kernel to be convolved with the inputtensor. The kernel shape must be :math:`(1, kD, kH, kW)` or :math:`(B, kD, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -297,7 +297,7 @@ def filter3d(Return:the convolved tensor of same size and numbers of channels- as the input with shape :math:`(B, C, D, H, W)`.+ as the input with shape ``(B, C, D, H, W)``.Example:>>> input = torch.tensor([[[@@ -423,7 +423,7 @@ def fft_conv(:func:`~kornia.filters.filter2d`.Args:- input: Input tensor of shape :math:`(B, C, H, W)`.+ input: Input tensor of shape ``(B, C, H, W)``.kernel: Convolution kernel of shape :math:`(1, kH, kW)`, shared by thewhole batch, or :math:`(B, kH, kW)`, where each batch elementprovides one kernel, which is shared across all channels of the@@ -442,7 +442,7 @@ def fft_conv(Returns:Tensor: The filtered tensor. If ``padding='same'``, the output shape- is :math:`(B, C, H, W)`. If ``padding='valid'``, the output shape is+ is ``(B, C, H, W)``. If ``padding='valid'``, the output shape is:math:`(B, C, H - kH + 1, W - kW + 1)`.Note:@@ -577,7 +577,7 @@ def correlate2d(.. seealso:: :func:`convolve2d`, :func:`filter2d`Args:- input: the input tensor with shape of :math:`(B, C, H, W)`.+ input: the input tensor with shape of ``(B, C, H, W)``.kernel: the kernel to be correlated with the input tensor.The kernel shape must be :math:`(1, kH, kW)` or :math:`(B, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -586,7 +586,7 @@ def correlate2d(padding: This defines the type of padding. 2 modes available ``'same'`` or ``'valid'``.Return:- the correlated tensor. With ``padding='same'`` it has the input's shape :math:`(B, C, H, W)`. With+ the correlated tensor. With ``padding='same'`` it has the input's shape ``(B, C, H, W)``. With``padding='valid'`` it has shape :math:`(B, C, H - kH + 1, W - kW + 1)`.Example:@@ -626,7 +626,7 @@ def convolve2d(.. seealso:: :func:`correlate2d`, :func:`filter2d`Args:- input: the input tensor with shape of :math:`(B, C, H, W)`.+ input: the input tensor with shape of ``(B, C, H, W)``.kernel: the kernel to be convolved with the input tensor.The kernel shape must be :math:`(1, kH, kW)` or :math:`(B, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -635,7 +635,7 @@ def convolve2d(padding: This defines the type of padding. 2 modes available ``'same'`` or ``'valid'``.Return:- the convolved tensor. With ``padding='same'`` it has the input's shape :math:`(B, C, H, W)`. With+ the convolved tensor. With ``padding='same'`` it has the input's shape ``(B, C, H, W)``. With``padding='valid'`` it has shape :math:`(B, C, H - kH + 1, W - kW + 1)`.Example:@@ -673,7 +673,7 @@ def correlate3d(.. seealso:: :func:`convolve3d`, :func:`filter3d`Args:- input: the input tensor with shape of :math:`(B, C, D, H, W)`.+ input: the input tensor with shape of ``(B, C, D, H, W)``.kernel: the kernel to be correlated with the input tensor.The kernel shape must be :math:`(1, kD, kH, kW)` or :math:`(B, kD, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -681,7 +681,7 @@ def correlate3d(normalized: If True, kernel will be L1 normalized.Return:- the correlated tensor, with the input's shape :math:`(B, C, D, H, W)`.+ the correlated tensor, with the input's shape ``(B, C, D, H, W)``.Example:Correlation applies the kernel as given. A single tap at the kernel's first corner, index ``(0, 0, 0)`` in@@ -715,7 +715,7 @@ def convolve3d(.. seealso:: :func:`correlate3d`, :func:`filter3d`Args:- input: the input tensor with shape of :math:`(B, C, D, H, W)`.+ input: the input tensor with shape of ``(B, C, D, H, W)``.kernel: the kernel to be convolved with the input tensor.The kernel shape must be :math:`(1, kD, kH, kW)` or :math:`(B, kD, kH, kW)`.border_type: the padding mode to be applied before convolving.@@ -723,7 +723,7 @@ def convolve3d(normalized: If True, kernel will be L1 normalized.Return:- the convolved tensor, with the input's shape :math:`(B, C, D, H, W)`.+ the convolved tensor, with the input's shape ``(B, C, D, H, W)``.Example:Convolution flips the kernel along all three axes, which moves a tap at the kernel's first corner, indexdiff --git a/kornia/filters/gaussian.py b/kornia/filters/gaussian.pyindex 5e2fddd8f..b502e8cbc 100644--- a/kornia/filters/gaussian.py+++ b/kornia/filters/gaussian.py@@ -115,10 +115,10 @@ def gaussian_blur2d(:func:`~kornia.filters.filter2d`; ``sigma`` is cast to float32 as well.Arguments:- input: the input torch.Tensor with shape :math:`(B,C,H,W)`.+ input: the input torch.Tensor with shape ``(B,C,H,W)``.kernel_size: the size of the kernel. Can be an integer or tuple of two integers (height, width).sigma: the standard deviation of the kernel. Can be a tuple of two floats or a torch.Tensor- with shape :math:`(1, 2)`, shared by the batch, or :math:`(B, 2)`, one row per sample.+ with shape ``(1, 2)``, shared by the batch, or ``(B, 2)``, one row per sample.Values must be positive; the note below says when that is checked.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,@@ -126,7 +126,7 @@ def gaussian_blur2d(separable: run as composition of two 1d-convolutions. Default: ``True``.Returns:- the blurred torch.Tensor with shape :math:`(B, C, H, W)`.+ the blurred torch.Tensor with shape ``(B, C, H, W)``.Raises:~kornia.core.exceptions.TypeCheckError: if input is not a torch.Tensor.@@ -272,8 +272,8 @@ class GaussianBlur2d(nn.Module):the blurred torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples::@@ -317,12 +317,12 @@ class GaussianBlur2d(nn.Module):of the approximation.Args:- input: Image or feature tensor with shape :math:`(B, C, H, W)`,+ input: Image or feature tensor with shape ``(B, C, H, W)``,where :math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the smoothed+ Tensor with shape ``(B, C, H, W)`` containing the smoothedresult. The output keeps the same channel layout as ``input`` whilereducing high-frequency noise and fine texture."""diff --git a/kornia/filters/guided.py b/kornia/filters/guided.pyindex e14058409..bb081aa29 100644--- a/kornia/filters/guided.py+++ b/kornia/filters/guided.py@@ -215,8 +215,8 @@ def guided_blur(dtype of the rule above.Arguments:- guidance: the guidance torch.Tensor with shape :math:`(B,C_g,H,W)`.- input: the input torch.Tensor with shape :math:`(B,C_i,H,W)`.+ guidance: the guidance torch.Tensor with shape ``(B,C_g,H,W)``.+ input: the input torch.Tensor with shape ``(B,C_i,H,W)``.kernel_size: the size of the kernel.eps: regularization parameter. Smaller values preserve more edges.border_type: the padding mode to be applied before convolving.@@ -234,7 +234,7 @@ def guided_blur(large windows. Default: FalseReturns:- the blurred torch.Tensor with same shape as `input` :math:`(B, C_i, H, W)`.+ the blurred torch.Tensor with same shape as `input` ``(B, C_i, H, W)``.Raises:TypeCheckError: if ``subsample`` is not an integer (NumPy integers are accepted).@@ -330,8 +330,8 @@ class GuidedBlur(nn.Module):BaseError: if ``subsample`` is not positive, or is a ``bool``. Both are raised by the constructor.Shape:- - Input: :math:`(B, C_g, H, W)`, :math:`(B, C_i, H, W)`- - Output: :math:`(B, C_i, H, W)`+ - Input: ``(B, C_g, H, W)``, ``(B, C_i, H, W)``+ - Output: ``(B, C_i, H, W)``Examples:>>> guidance = torch.rand(2, 3, 5, 5)@@ -379,17 +379,17 @@ class GuidedBlur(nn.Module):in the filtered result.Args:- guidance: Guidance tensor with shape :math:`(B, C_g, H, W)`, where+ guidance: Guidance tensor with shape ``(B, C_g, H, W)``, where:math:`B` is the batch size, :math:`C_g` is the number ofguidance channels, :math:`H` is the height, and :math:`W` isthe width.- input: Tensor to filter with shape :math:`(B, C_i, H, W)`, where+ input: Tensor to filter with shape ``(B, C_i, H, W)``, where:math:`C_i` is the number of channels in the signal beingsmoothed. Its batch and spatial dimensions must equal thoseof ``guidance``.Returns:- Tensor with shape :math:`(B, C_i, H, W)` containing the+ Tensor with shape ``(B, C_i, H, W)`` containing theedge-aware filtered version of ``input``."""return guided_blur(diff --git a/kornia/filters/in_range.py b/kornia/filters/in_range.pyindex c66723e63..ccc5144a9 100644--- a/kornia/filters/in_range.py+++ b/kornia/filters/in_range.py@@ -111,14 +111,14 @@ def in_range(an empty mask.Args:- input: The input torch.Tensor to be filtered in the shape of :math:`(*, *, H, W)`.+ input: The input torch.Tensor to be filtered in the shape of ``(*, *, H, W)``.lower: The lower bounds of the filter (inclusive).upper: The upper bounds of the filter (inclusive).return_mask: If is true, the filtered mask is returned, otherwise the filtered input image.Returns:- A binary mask :math:`(*, 1, H, W)` of input indicating whether elements are within the range- or filtered input image :math:`(*, *, H, W)`.+ A binary mask ``(*, 1, H, W)`` of input indicating whether elements are within the range+ or filtered input image ``(*, *, H, W)``.Raises:TypeError: If `lower` or `upper` is neither a tuple nor a torch.Tensor, if one is a tuple and the other a@@ -141,14 +141,14 @@ def in_range(length, such as (W,) when W is neither C nor 1, raises. When W == C, a (W,) bound is the (C,) bound, not aper-column one.- - Any other torch.Tensor with at most four dimensions is aligned with the input :math:`(B, C, H, W)` from the+ - Any other torch.Tensor with at most four dimensions is aligned with the input ``(B, C, H, W)`` from thelast dimension, and every dimension must be 1 or the input's. For example (1, C, 1, 1) and (C, 1, 1) applythe same per-channel bound to all batches, (B, C, H, W), (C, H, W) and (H, W) give a different bound at eachpixel, and a 0-d torch.Tensor applies one bound everywhere.- Each torch.Tensor bound is checked on its own, so a mis-shaped one raises whatever the other bound is.- The input is read as :math:`(B, C, H, W)`: a 3-D input is :math:`(1, C, H, W)`, a 2-D input is- :math:`(1, 1, H, W)`, and for more than four dimensions the leading dimensions are flattened into B.+ The input is read as ``(B, C, H, W)``: a 3-D input is ``(1, C, H, W)``, a 2-D input is+ ``(1, 1, H, W)``, and for more than four dimensions the leading dimensions are flattened into B.Examples:>>> rng = torch.manual_seed(1)@@ -226,8 +226,8 @@ class InRange(nn.Module):return_mask: If is true, the filtered mask is returned, otherwise the filtered input image.Returns:- A binary mask :math:`(*, 1, H, W)` of input indicating whether elements are within the range- or filtered input image :math:`(*, *, H, W)`.+ A binary mask ``(*, 1, H, W)`` of input indicating whether elements are within the range+ or filtered input image ``(*, *, H, W)``... note::View complete documentation in :func:`kornia.filters.in_range`.@@ -266,12 +266,12 @@ class InRange(nn.Module):Args:input: Tensor to test against the configured bounds. For images the- usual shape is :math:`(B, C, H, W)`, where :math:`B` is the+ usual shape is ``(B, C, H, W)``, where :math:`B` is thebatch size, :math:`C` is the number of channels, :math:`H` isthe height, and :math:`W` is the width.Returns:- If ``self.return_mask`` is ``True``, a :math:`(B, 1, H, W)` mask of+ If ``self.return_mask`` is ``True``, a ``(B, 1, H, W)`` mask ofthe pixels whose every channel lies within the inclusive range.Otherwise, a tensor with values outside the range removed accordingto :func:`in_range`.diff --git a/kornia/filters/kernels.py b/kornia/filters/kernels.pyindex 84a8f2ca3..ce44d7419 100644--- a/kornia/filters/kernels.py+++ b/kornia/filters/kernels.py@@ -154,10 +154,10 @@ def gaussian(Args:window_size: the size which drives the filter amount.- sigma: gaussian standard deviation. If a tensor, should be in a shape :math:`(B, 1)`.+ sigma: gaussian standard deviation. If a tensor, should be in a shape ``(B, 1)``.mean: Mean of the Gaussian function (center); see the Convention block for an even``window_size``. If not provided, it defaults to ``window_size // 2``. A Python ``int`` is- treated as its ``float``. If a tensor, should be in a shape :math:`(B, 1)`.+ treated as its ``float``. If a tensor, should be in a shape ``(B, 1)``.device: This value will be used if sigma is an int or float. Device desired to compute.dtype: This value will be used if sigma is an int or float. Dtype desired for compute.@@ -238,7 +238,7 @@ def gaussian_discrete_erf(Adapted from: https://github.com/Project-MONAI/MONAI/blob/master/monai/networks/layers/convutils.pyArgs:window_size: the size which drives the filter amount.- sigma: gaussian standard deviation. If a tensor, should be in a shape :math:`(B, 1)`+ sigma: gaussian standard deviation. If a tensor, should be in a shape ``(B, 1)``device: This value will be used if sigma is an int or float. Device desired to compute.dtype: This value will be used if sigma is an int or float. Dtype desired for compute.@@ -385,7 +385,7 @@ def gaussian_discrete(Adapted from: https://github.com/Project-MONAI/MONAI/blob/master/monai/networks/layers/convutils.pyArgs:window_size: the size which drives the filter amount. It must be odd.- sigma: gaussian standard deviation. If a tensor, should be in a shape :math:`(B, 1)`+ sigma: gaussian standard deviation. If a tensor, should be in a shape ``(B, 1)``device: This value will be used if sigma is an int or float. Device desired to compute.dtype: This value will be used if sigma is an int or float. Dtype desired for compute.@@ -652,7 +652,7 @@ def get_sobel_kernel2d(*, device: Optional[torch.device] = None, dtype: OptionalConvention:See the Convention block on :func:`~kornia.filters.get_spatial_gradient_kernel2d`; this is- ``get_spatial_gradient_kernel2d('sobel', 1)``, of shape :math:`(2, 3, 3)`.+ ``get_spatial_gradient_kernel2d('sobel', 1)``, of shape ``(2, 3, 3)``."""kernel_x = get_sobel_kernel_3x3(device=device, dtype=dtype)kernel_y = kernel_x.transpose(0, 1)@@ -664,7 +664,7 @@ def get_diff_kernel2d(*, device: Optional[torch.device] = None, dtype: Optional[Convention:See the Convention block on :func:`~kornia.filters.get_spatial_gradient_kernel2d`; this is- ``get_spatial_gradient_kernel2d('diff', 1)``, of shape :math:`(2, 3, 3)`.+ ``get_spatial_gradient_kernel2d('diff', 1)``, of shape ``(2, 3, 3)``."""kernel_x = get_diff_kernel_3x3(device=device, dtype=dtype)kernel_y = kernel_x.transpose(0, 1)@@ -720,8 +720,8 @@ def get_spatial_gradient_kernel2d(dtype: tensor dtype desired to create the kernelReturns:- the kernels with shape :math:`(2, 3, 3)` for ``order=1``, and :math:`(3, 5, 5)` (Sobel) or- :math:`(3, 3, 3)` (diff) for ``order=2``.+ the kernels with shape ``(2, 3, 3)`` for ``order=1``, and ``(3, 5, 5)`` (Sobel) or+ ``(3, 3, 3)`` (diff) for ``order=2``."""KORNIA_CHECK(mode.lower() in {"sobel", "diff"}, f"Mode should be `sobel` or `diff`. Got {mode}")@@ -768,7 +768,7 @@ def get_spatial_gradient_kernel3d(dtype: tensor dtype desired to create the kernelReturns:- the kernels with shape :math:`(3, 1, 3, 3, 3)` for ``order=1`` and :math:`(6, 1, 3, 3, 3)` for ``order=2``.+ the kernels with shape ``(3, 1, 3, 3, 3)`` for ``order=1`` and ``(6, 1, 3, 3, 3)`` for ``order=2``."""KORNIA_CHECK(mode.lower() in {"sobel", "diff"}, f"Mode should be `sobel` or `diff`. Got {mode}")@@ -804,7 +804,7 @@ def get_gaussian_kernel1d(:func:`~kornia.filters.get_gaussian_discrete_kernel1d` is the discrete Gaussian.- ``force_even=True`` also accepts an even ``kernel_size``, and in a floating ``dtype`` the kernel is thensymmetric about the middle of the window, ``(kernel_size - 1) / 2``.- - A tensor ``sigma`` of shape :math:`(B, 1)` gives one kernel per row.+ - A tensor ``sigma`` of shape ``(B, 1)`` gives one kernel per row.- A Python integer ``sigma`` is treated as its floating-point equivalent. With ``dtype=None``, both usethe default floating-point dtype.- An integer or bool ``dtype`` raises: the taps are fractional, and an integer ``dtype`` would also@@ -866,7 +866,7 @@ def get_gaussian_discrete_kernel1d(Args:kernel_size: filter size. It should be odd and positive.- sigma: gaussian standard deviation. If a tensor, should be in a shape :math:`(B, 1)`+ sigma: gaussian standard deviation. If a tensor, should be in a shape ``(B, 1)``force_even: accepted for parity with the other Gaussian builders. The discrete Gaussian needs an odd``kernel_size`` either way.device: This value will be used if sigma is an int or float. Device desired to compute.@@ -912,7 +912,7 @@ def get_gaussian_erf_kernel1d(Args:kernel_size: filter size. It should be odd and positive.- sigma: gaussian standard deviation. If a tensor, should be in a shape :math:`(B, 1)`+ sigma: gaussian standard deviation. If a tensor, should be in a shape ``(B, 1)``force_even: overrides requirement for odd kernel size.device: This value will be used if sigma is an int or float. Device desired to compute.dtype: This value will be used if sigma is an int or float. Dtype desired for compute.@@ -949,7 +949,7 @@ def get_gaussian_kernel2d(See the Convention block on :func:`~kornia.filters.get_gaussian_kernel1d`. ``kernel_size`` is``(k_y, k_x)`` and ``sigma`` is :math:`(\sigma_y, \sigma_x)`, y first as in the output:math:`(B, k_y, k_x)`, which is the outer product of the two 1d kernels. A tensor ``sigma`` of shape- :math:`(B, 2)` gives one kernel per row.+ ``(B, 2)`` gives one kernel per row.Args:kernel_size: filter sizes in the y and x direction. Sizes should be odd and positive.@@ -1013,7 +1013,7 @@ def get_gaussian_kernel3d(See the Convention block on :func:`~kornia.filters.get_gaussian_kernel1d`. ``kernel_size`` is``(k_z, k_y, k_x)`` and ``sigma`` is :math:`(\sigma_z, \sigma_y, \sigma_x)`, z first as in the output:math:`(B, k_z, k_y, k_x)`, which is the outer product of the three 1d kernels. A tensor ``sigma`` of shape- :math:`(B, 3)` gives one kernel per row.+ ``(B, 3)`` gives one kernel per row.Args:kernel_size: filter sizes in the z, y and x direction. Sizes should be odd and positive.diff --git a/kornia/filters/kernels_geometry.py b/kornia/filters/kernels_geometry.pyindex 7b7b8e8f4..80c987e7d 100644--- a/kornia/filters/kernels_geometry.py+++ b/kornia/filters/kernels_geometry.py@@ -45,7 +45,7 @@ def get_motion_kernel2d(- The rotation resamples the line with ``mode``: ``'nearest'`` copies each pixel from the nearest tap, so thenumber of taps changes with the angle (3 at 45 degrees, 7 at 25 for a size-5 line), and ``'bilinear'``spreads the weight off the line.- - A floating tensor ``angle`` of shape :math:`(B,)` gives :math:`(B, k, k)` in its dtype. A tensor+ - A floating tensor ``angle`` of shape ``(B,)`` gives :math:`(B, k, k)` in its dtype. A tensor``direction`` must match it in length, dtype and device; a float ``direction`` is not broadcast, so itraises for ``B > 1``.- With ``'nearest'``, each pixel copies the tap nearest to its source under the inverse rotation, picked@@ -181,7 +181,7 @@ def get_motion_kernel3d(Args:kernel_size: motion kernel width, height and depth, an odd integer of at least 3.angle: Rodrigues axis-angle vector ``(rx, ry, rz)`` in degrees, not Euler angles.- If tensor, it must be :math:`(B, 3)`.+ If tensor, it must be ``(B, 3)``.If tuple, it must be ``(rx, ry, rz)``.direction: forward/backward direction of the motion blur.Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle),diff --git a/kornia/filters/laplacian.py b/kornia/filters/laplacian.pyindex 2f781bfdd..2f2ec662c 100644--- a/kornia/filters/laplacian.py+++ b/kornia/filters/laplacian.py@@ -80,7 +80,7 @@ def laplacian(:func:`~kornia.filters.filter2d`.Args:- input: the input image tensor with shape :math:`(B, C, H, W)`.+ input: the input image tensor with shape ``(B, C, H, W)``.kernel_size: the size of the kernel. It should be odd and positive, and at least 3 along one axis.border_type: the padding mode to be applied before convolving.The expected modes are: ``'constant'``, ``'reflect'``,@@ -94,7 +94,7 @@ def laplacian(execution returns a finite response.Return:- the Laplacian response with shape :math:`(B, C, H, W)`.+ the Laplacian response with shape ``(B, C, H, W)``.Raises:BaseError: if a size is even or not positive, if ``kernel_size`` is a sequence of other than 2 sizes, or if@@ -176,8 +176,8 @@ class Laplacian(nn.Module)::func:`~kornia.filters.laplacian` checks it when called.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.rand(2, 4, 5, 5)@@ -215,12 +215,12 @@ class Laplacian(nn.Module):detail.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the Laplacian+ Tensor with shape ``(B, C, H, W)`` containing the Laplacianresponse for each batch item and channel. Positive and negativevalues represent opposite directions of local curvature."""diff --git a/kornia/filters/median.py b/kornia/filters/median.pyindex 3a5ff5e51..fa9abea9b 100644--- a/kornia/filters/median.py+++ b/kornia/filters/median.py@@ -129,14 +129,14 @@ def median_blur(input: torch.Tensor, kernel_size: tuple[int, int] | int, border_values, so the result equals that of ``input.float()`` exactly.Args:- input: the input image with shape :math:`(B,C,H,W)`.+ input: the input image with shape ``(B,C,H,W)``.kernel_size: the blurring kernel size. Each entry must be a positive odd integer.border_type: the padding mode to be applied before filtering.The expected modes are: `'constant'`, `'reflect'`, `'replicate'` or `'circular'`.Default: `'reflect'`.Returns:- the blurred input torch.Tensor with shape :math:`(B,C,H,W)`.+ the blurred input torch.Tensor with shape ``(B,C,H,W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/filtering_operators.html>`__.@@ -232,8 +232,8 @@ class MedianBlur(nn.Module):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Example:>>> input = torch.rand(2, 4, 5, 7)@@ -259,12 +259,12 @@ class MedianBlur(nn.Module):simple mean filter.Args:- input: Image or feature tensor with shape :math:`(B, C, H, W)`,+ input: Image or feature tensor with shape ``(B, C, H, W)``,where :math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the median-+ Tensor with shape ``(B, C, H, W)`` containing the median-filtered result for each channel independently."""return median_blur(input, self.kernel_size, self.border_type)diff --git a/kornia/filters/motion.py b/kornia/filters/motion.pyindex 21f8a0d3a..d6d3fe7f0 100644--- a/kornia/filters/motion.py+++ b/kornia/filters/motion.py@@ -76,8 +76,8 @@ class MotionBlur(nn.Module):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.rand(2, 4, 5, 7)@@ -111,12 +111,12 @@ class MotionBlur(nn.Module):biased, or backward-biased along that line.Args:- x: Image tensor with shape :math:`(B, C, H, W)`, where :math:`B`+ x: Image tensor with shape ``(B, C, H, W)``, where :math:`B`is the batch size, :math:`C` is the number of channels,:math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the directional+ Tensor with shape ``(B, C, H, W)`` containing the directionalblur response. The output uses the same batch, channel, and spatiallayout as ``x``."""@@ -133,7 +133,7 @@ class MotionBlur3D(nn.Module):kernel_size: motion kernel width, height and depth, an odd integer of at least 3.angle: Components of one Rodrigues axis-angle vector ``(rx, ry, rz)`` in degrees, not Euler angles; see:func:`~kornia.filters.get_motion_kernel3d`. A scalar sets all three components to the same value;- a three-element sequence sets each component, and a tensor must have shape :math:`(B, 3)`.+ a three-element sequence sets each component, and a tensor must have shape ``(B, 3)``.direction: forward/backward direction of the motion blur.Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle),while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to a@@ -150,8 +150,8 @@ class MotionBlur3D(nn.Module):the blurred input torch.Tensor.Shape:- - Input: :math:`(B, C, D, H, W)`- - Output: :math:`(B, C, D, H, W)`+ - Input: ``(B, C, D, H, W)``+ - Output: ``(B, C, D, H, W)``Examples:>>> input = torch.rand(2, 4, 5, 7, 9)@@ -205,13 +205,13 @@ class MotionBlur3D(nn.Module):movement can be modeled in three spatial dimensions.Args:- x: Volume tensor with shape :math:`(B, C, D, H, W)`, where+ x: Volume tensor with shape ``(B, C, D, H, W)``, where:math:`B` is the batch size, :math:`C` is the channel count,:math:`D` is the depth, :math:`H` is the height, and:math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, D, H, W)` containing the blurred+ Tensor with shape ``(B, C, D, H, W)`` containing the blurredvolume. The output keeps the same dimensional order as ``x``."""return motion_blur3d(x, self.kernel_size, self.angle, self.direction, self.border_type, mode=self.mode)@@ -235,15 +235,15 @@ def motion_blur(side on which the streak of a bright point is heaviest), ``mode``, the tensor shapes and the border modes.Args:- input: the input torch.Tensor with shape :math:`(B, C, H, W)`.+ input: the input torch.Tensor with shape ``(B, C, H, W)``.kernel_size: motion kernel width and height, an odd integer of at least 3.angle (Union[torch.Tensor, float]): angle of the motion blur in degrees (anti-clockwise rotation).- If torch.Tensor, it must be :math:`(B,)`.+ If torch.Tensor, it must be ``(B,)``.direction : forward/backward direction of the motion blur.Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle),while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to auniformly (but still angled) motion blur.- If torch.Tensor, it must be :math:`(B,)`.+ If torch.Tensor, it must be ``(B,)``.border_type: the padding mode to be applied before convolving. The expected modes are:``'constant'``, ``'reflect'``, ``'replicate'`` or ``'circular'``. Default: ``'reflect'``, which leavesa constant image constant like :func:`~kornia.filters.box_blur` and@@ -253,7 +253,7 @@ def motion_blur(mode: interpolation mode for rotating the kernel. ``'bilinear'`` or ``'nearest'``.Return:- the blurred image with shape :math:`(B, C, H, W)`.+ the blurred image with shape ``(B, C, H, W)``.Example:>>> input = torch.randn(1, 3, 80, 90).repeat(2, 1, 1, 1)@@ -290,15 +290,15 @@ def motion_blur3d(decreasing ``D``.Args:- input: the input torch.Tensor with shape :math:`(B, C, D, H, W)`.+ input: the input torch.Tensor with shape ``(B, C, D, H, W)``.kernel_size: motion kernel width, height and depth, an odd integer of at least 3.angle: ``(yaw, pitch, roll)``, one Rodrigues axis-angle vector ``(rx, ry, rz)`` in degrees, not Euler- angles; see :func:`~kornia.filters.get_motion_kernel3d`. If torch.Tensor, it must be :math:`(B, 3)`.+ angles; see :func:`~kornia.filters.get_motion_kernel3d`. If torch.Tensor, it must be ``(B, 3)``.direction: forward/backward direction of the motion blur.Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle),while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to auniformly (but still angled) motion blur.- If torch.Tensor, it must be :math:`(B,)`.+ If torch.Tensor, it must be ``(B,)``.border_type: the padding mode to be applied before convolving. The expected modes are:``'constant'``, ``'reflect'``, ``'replicate'`` or ``'circular'``. Default: ``'replicate'``, whichleaves a constant volume constant like :func:`~kornia.filters.filter3d`, at any volume size@@ -308,7 +308,7 @@ def motion_blur3d(mode: interpolation mode for rotating the kernel. ``'bilinear'`` or ``'nearest'``.Return:- the blurred image with shape :math:`(B, C, D, H, W)`.+ the blurred image with shape ``(B, C, D, H, W)``.Example:>>> input = torch.randn(1, 3, 120, 80, 90).repeat(2, 1, 1, 1, 1)diff --git a/kornia/filters/otsu_thresholding.py b/kornia/filters/otsu_thresholding.pyindex 7ee089f2e..859531f7a 100644--- a/kornia/filters/otsu_thresholding.py+++ b/kornia/filters/otsu_thresholding.py@@ -381,7 +381,7 @@ def otsu_threshold(r"""Apply automatic image thresholding using Otsu algorithm to the input tensor.Convention:- - One threshold is returned per plane over the last two axes: a :math:`(B, C, H, W)` input gives ``B * C``+ - One threshold is returned per plane over the last two axes: a ``(B, C, H, W)`` input gives ``B * C``thresholds, flattened, and a tensor of at most two dimensions is one plane.- Each plane is histogrammed on its own range, ``nbins`` bins between its minimum and its maximum, not over afixed :math:`[0, 1]` or :math:`[0, 255]`. The threshold is the upper edge of the selected histogram bin,diff --git a/kornia/filters/sobel.py b/kornia/filters/sobel.pyindex 513f04379..098bc17a6 100644--- a/kornia/filters/sobel.py+++ b/kornia/filters/sobel.py@@ -51,7 +51,7 @@ def spatial_gradient(input: torch.Tensor, mode: str = "sobel", order: int = 1, n:func:`~kornia.filters.filter2d` and :func:`~kornia.filters.laplacian`, whose default is ``'reflect'``.Args:- input: input image torch.Tensor with shape :math:`(B, C, H, W)`.+ input: input image torch.Tensor with shape ``(B, C, H, W)``.mode: derivatives modality, can be: `sobel` or `diff`, case-insensitive.order: the order of the derivatives.normalized: if ``True``, scale the kernels so that every output channel estimates the derivative@@ -59,8 +59,8 @@ def spatial_gradient(input: torch.Tensor, mode: str = "sobel", order: int = 1, nsurfaces for ``order=2``. If ``False``, return the raw kernel responses.Return:- the derivatives of the input feature map, with shape :math:`(B, C, 2, H, W)` holding- :math:`(dx, dy)` for ``order=1`` and :math:`(B, C, 3, H, W)` holding :math:`(dxx, dxy, dyy)`+ the derivatives of the input feature map, with shape ``(B, C, 2, H, W)`` holding+ :math:`(dx, dy)` for ``order=1`` and ``(B, C, 3, H, W)`` holding :math:`(dxx, dxy, dyy)`for ``order=2``... note::@@ -130,13 +130,13 @@ def spatial_gradient3d(input: torch.Tensor, mode: str = "diff", order: int = 1)as :func:`~kornia.filters.filter3d` does (`#5155 <https://github.com/kornia/kornia/issues/5155>`_).Args:- input: input features torch.Tensor with shape :math:`(B, C, D, H, W)`.+ input: input features torch.Tensor with shape ``(B, C, D, H, W)``.mode: derivatives modality, case-insensitive; only ``'diff'`` is implemented.order: the order of the derivatives.Return:- the spatial gradients of the input feature map with shape :math:`(B, C, 3, D, H, W)` holding- :math:`(dx, dy, dz)` for ``order=1`` or :math:`(B, C, 6, D, H, W)` holding+ the spatial gradients of the input feature map with shape ``(B, C, 3, D, H, W)`` holding+ :math:`(dx, dy, dz)` for ``order=1`` or ``(B, C, 6, D, H, W)`` holding:math:`(dxx, dyy, dzz, dxy, dyz, dxz)` for ``order=2``.Examples:@@ -203,12 +203,12 @@ def sobel(input: torch.Tensor, normalized: bool = True, eps: float = 1e-6) -> todefault, not 0.Args:- input: the input image with shape :math:`(B,C,H,W)`.+ input: the input image with shape ``(B,C,H,W)``.normalized: if True, L1 norm of the kernel is set to 1.eps: regularization number to avoid NaN during backprop.Return:- the sobel edge gradient magnitudes map with shape :math:`(B,C,H,W)`.+ the sobel edge gradient magnitudes map with shape ``(B,C,H,W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/filtering_edges.html>`__.@@ -251,8 +251,8 @@ class SpatialGradient(nn.Module):the derivatives of the input feature map.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, 2, H, W)` for ``order=1`` and :math:`(B, C, 3, H, W)` for ``order=2``+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, 2, H, W)`` for ``order=1`` and ``(B, C, 3, H, W)`` for ``order=2``Examples:>>> input = torch.rand(1, 3, 4, 4)@@ -281,16 +281,16 @@ class SpatialGradient(nn.Module):derivatives describe how that slope changes.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:Gradient tensor from :func:`spatial_gradient`. For first-order- derivatives the shape is :math:`(B, C, 2, H, W)`, where+ derivatives the shape is ``(B, C, 2, H, W)``, wherethe derivative axis of size ``2`` stores the response along:math:`x` (width) and :math:`y` (height). For second-order- derivatives it is :math:`(B, C, 3, H, W)`, holding+ derivatives it is ``(B, C, 3, H, W)``, holding:math:`(dxx, dxy, dyy)`."""return spatial_gradient(input, self.mode, self.order, self.normalized)@@ -310,8 +310,8 @@ class SpatialGradient3d(nn.Module):the spatial gradients of the input feature map.Shape:- - Input: :math:`(B, C, D, H, W)`. D, H, W are spatial dimensions, gradient is calculated w.r.t to them.- - Output: :math:`(B, C, 3, D, H, W)` or :math:`(B, C, 6, D, H, W)`+ - Input: ``(B, C, D, H, W)``. D, H, W are spatial dimensions, gradient is calculated w.r.t to them.+ - Output: ``(B, C, 3, D, H, W)`` or ``(B, C, 6, D, H, W)``Examples:>>> input = torch.rand(1, 4, 2, 4, 4)@@ -342,7 +342,7 @@ class SpatialGradient3d(nn.Module):or feature maps with an explicit depth dimension.Args:- input: Volume tensor with shape :math:`(B, C, D, H, W)`, where+ input: Volume tensor with shape ``(B, C, D, H, W)``, where:math:`B` is the batch size, :math:`C` is the channel count,:math:`D` is the depth, :math:`H` is the height, and:math:`W` is the width.@@ -369,8 +369,8 @@ class Sobel(nn.Module):the sobel edge gradient magnitudes map.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``Examples:>>> input = torch.rand(1, 3, 4, 4)@@ -395,12 +395,12 @@ class Sobel(nn.Module):boundaries.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the height, and :math:`W` is the width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the gradient+ Tensor with shape ``(B, C, H, W)`` containing the gradientmagnitude for each channel. The ``self.eps`` value is used by theunderlying function to keep magnitude computation numericallystable near zero.diff --git a/kornia/filters/unsharp.py b/kornia/filters/unsharp.pyindex 40aa35204..8a410bb42 100644--- a/kornia/filters/unsharp.py+++ b/kornia/filters/unsharp.py@@ -47,7 +47,7 @@ def unsharp_mask(:func:`~kornia.enhance.sharpness`.Args:- input: the input torch.Tensor with shape :math:`(B,C,H,W)`.+ input: the input torch.Tensor with shape ``(B,C,H,W)``.kernel_size: the size of the kernel.sigma: the standard deviation of the kernel.border_type: the padding mode to be applied before convolving.@@ -55,7 +55,7 @@ def unsharp_mask(``'replicate'`` or ``'circular'``. Default: ``'reflect'``.Returns:- the sharpened torch.Tensor with shape :math:`(B,C,H,W)`.+ the sharpened torch.Tensor with shape ``(B,C,H,W)``.Examples:>>> input = torch.rand(2, 4, 5, 5)@@ -86,11 +86,11 @@ class UnsharpMask(nn.Module):``'replicate'`` or ``'circular'``. Default: ``'reflect'``.Returns:- the sharpened torch.Tensor with shape :math:`(B,C,H,W)`.+ the sharpened torch.Tensor with shape ``(B,C,H,W)``.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H, W)``.. note::See a working example `here <https://www.kornia.org/tutorials/nbs/unsharp_mask.html>`__.@@ -124,13 +124,13 @@ class UnsharpMask(nn.Module):keeping the tensor layout unchanged.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofchannels, :math:`H` is the image height, and :math:`W` is theimage width.Returns:- Tensor with shape :math:`(B, C, H, W)` containing the sharpened+ Tensor with shape ``(B, C, H, W)`` containing the sharpenedimage. The spatial scale of sharpening is set by the configuredGaussian kernel size and sigma; the amount is fixed."""diff --git a/kornia/geometry/bbox.py b/kornia/geometry/bbox.pyindex 05d4dc6ae..f0fc3b904 100644--- a/kornia/geometry/bbox.py+++ b/kornia/geometry/bbox.py@@ -59,7 +59,7 @@ def validate_bbox(boxes: torch.Tensor) -> bool:Convention:Vertices are inclusive, in clockwise top-left, top-right, bottom-right, bottom-left order (see- :func:`infer_bbox_shape`). Accepts :math:`(B, 4, 2)` and :math:`(B, N, 4, 2)`. Returns ``False``, without+ :func:`infer_bbox_shape`). Accepts ``(B, 4, 2)`` and ``(B, N, 4, 2)``. Returns ``False``, withoutraising, for an invalid shape or when the top and bottom edge vectors differ by more than ``1e-4``. Rightangles, positive area and direction are not checked, so any parallelogram in cyclic vertex order passes.@@ -69,7 +69,7 @@ def validate_bbox(boxes: torch.Tensor) -> bool:Args:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape- of :math:`(B, 4, 2)` or :math:`(B, N, 4, 2)`, where each box is defined in the+ of ``(B, 4, 2)`` or ``(B, N, 4, 2)``, where each box is defined in thefollowing ``clockwise`` order: top-left, top-right, bottom-right, bottom-left. The coordinates must be inthe x, y order.@@ -112,7 +112,7 @@ def validate_bbox3d(boxes: torch.Tensor) -> bool:Convention:Vertices are inclusive, front-top-left, front-top-right, front-bottom-right, front-bottom-left, then the- same four back vertices. Accepts :math:`(B, 8, 3)` and :math:`(B, N, 8, 3)`; another shape, or unequal+ same four back vertices. Accepts ``(B, 8, 3)`` and ``(B, N, 8, 3)``; another shape, or unequalextents of the four edges parallel to an axis, raises ``AssertionError``. Right angles and positiveextent are not checked. A non-finite coordinate returns ``False``. Under graph capture only the shape ischecked.@@ -123,7 +123,7 @@ def validate_bbox3d(boxes: torch.Tensor) -> bool:Args:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape- of :math:`(B, 8, 3)` or :math:`(B, N, 8, 3)`, where each box is defined in the following ``clockwise``+ of ``(B, 8, 3)`` or ``(B, N, 8, 3)``, where each box is defined in the following ``clockwise``order: front-top-left, front-top-right, front-bottom-right, front-bottom-left, back-top-left,back-top-right, back-bottom-right, back-bottom-left. The coordinates must be in the x, y, z order.@@ -202,15 +202,15 @@ def infer_bbox_shape(boxes: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:Args:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have shape- :math:`(N, 4, 2)`, where each box is defined in the following ``clockwise`` order: top-left, top-right,+ ``(N, 4, 2)``, where each box is defined in the following ``clockwise`` order: top-left, top-right,bottom-right, bottom-left. The coordinates must be in the x, y order.Raises:- ShapeError: if ``boxes`` does not have shape :math:`(N, 4, 2)`.+ ShapeError: if ``boxes`` does not have shape ``(N, 4, 2)``.Returns:- - Bounding box heights, shape of :math:`(N,)`.- - Bounding box widths, shape of :math:`(N,)`.+ - Bounding box heights, shape of ``(N,)``.+ - Bounding box widths, shape of ``(N,)``.Example:>>> boxes = torch.tensor([[@@ -244,7 +244,7 @@ def infer_bbox_shape3d(boxes: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor,example ``width = boxes[:, 1, 0] - boxes[:, 0, 0] + 1``), so another vertex order can give a negativeextent. Pass the ``'vertices_plus'``export of :class:`~kornia.geometry.boxes.Boxes3D`; ``'vertices'`` reads one larger per axis.- :math:`(B, N, 8, 3)` input raises :class:`~kornia.core.exceptions.ShapeError`; flatten it first.+ ``(B, N, 8, 3)`` input raises :class:`~kornia.core.exceptions.ShapeError`; flatten it first... warning::The ``+1`` is `#3934 <https://github.com/kornia/kornia/issues/3934>`_ and the exclusive-export trap@@ -254,14 +254,14 @@ def infer_bbox_shape3d(boxes: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor,Args:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape- of :math:`(B, 8, 3)`, where each box is defined in the following ``clockwise`` order: front-top-left,+ of ``(B, 8, 3)``, where each box is defined in the following ``clockwise`` order: front-top-left,front-top-right, front-bottom-right, front-bottom-left, back-top-left, back-top-right, back-bottom-right,back-bottom-left. The coordinates must be in the x, y, z order.Returns:- - Bounding box depths, shape of :math:`(B,)`.- - Bounding box heights, shape of :math:`(B,)`.- - Bounding box widths, shape of :math:`(B,)`.+ - Bounding box depths, shape of ``(B,)``.+ - Bounding box heights, shape of ``(B,)``.+ - Bounding box widths, shape of ``(B,)``.Example:>>> boxes = torch.tensor([[[ 0, 1, 2],@@ -321,7 +321,7 @@ def bbox_to_mask((bottom-right) are read. A pixel is covered when ``xmin <= x <= xmax`` and ``ymin <= y <= ymax`` on theunrounded values, i.e. inclusively: pass the ``'vertices_plus'`` export of:class:`~kornia.geometry.boxes.Boxes`. The mask has the input dtype and no gradient path.- :math:`(B, N, 4, 2)` raises :class:`~kornia.core.exceptions.ShapeError`.+ ``(B, N, 4, 2)`` raises :class:`~kornia.core.exceptions.ShapeError`... warning::The ``(width, height)`` form is deprecated in favour of ``size=(height, width)``:@@ -332,7 +332,7 @@ def bbox_to_mask(Args:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape- of :math:`(B, 4, 2)`, where each box is defined in the following ``clockwise`` order: top-left, top-right,+ of ``(B, 4, 2)``, where each box is defined in the following ``clockwise`` order: top-left, top-right,bottom-right and bottom-left. The coordinates must be in the x, y order.width: deprecated since 0.9.1; pass ``size=(height, width)`` instead. Width of the masked image.height: deprecated since 0.9.1; pass ``size=(height, width)`` instead. Height of the masked image.@@ -342,7 +342,7 @@ def bbox_to_mask(the output mask tensor, shape of :math:`(B, height, width)` and dtype of ``boxes``.Raises:- ShapeError: if ``boxes`` does not have shape :math:`(B, 4, 2)`.+ ShapeError: if ``boxes`` does not have shape ``(B, 4, 2)``.ValueError: if ``size`` is passed together with ``width`` or ``height``.TypeError: if neither ``size`` nor both ``width`` and ``height`` are given.@@ -428,7 +428,7 @@ def bbox_to_mask3d(boxes: torch.Tensor, size: tuple[int, int, int]) -> torch.Tendtype, with a channel axis that :func:`bbox_to_mask` does not have(:meth:`kornia.geometry.boxes.Boxes3D.to_mask` returns :math:`(N, depth, height, width)`). The bounds aretruncated toward zero and compared inclusively: pass the ``'vertices_plus'`` export. There is no- gradient path. :math:`(B, N, 8, 3)` input raises :class:`~kornia.core.exceptions.ShapeError`.+ gradient path. ``(B, N, 8, 3)`` input raises :class:`~kornia.core.exceptions.ShapeError`... warning::For fractional coordinates the truncation differs from :func:`bbox_to_mask` and@@ -438,7 +438,7 @@ def bbox_to_mask3d(boxes: torch.Tensor, size: tuple[int, int, int]) -> torch.TenArgs:boxes: a tensor containing the coordinates of the bounding boxes to be extracted. The tensor must have the shape- of :math:`(B, 8, 3)`, where each box is defined in the following ``clockwise`` order: front-top-left,+ of ``(B, 8, 3)``, where each box is defined in the following ``clockwise`` order: front-top-left,front-top-right, front-bottom-right, front-bottom-left, back-top-left, back-top-right, back-bottom-right,back-bottom-left. The coordinates must be in the x, y, z order.size: depth, height and width of the masked image.@@ -528,14 +528,14 @@ def bbox_generator(Args:x_start: a tensor containing the x coordinates of the bounding boxes to be extracted. Shape must be a scalar- tensor or :math:`(B,)`.+ tensor or ``(B,)``.y_start: a tensor containing the y coordinates of the bounding boxes to be extracted. Shape must be a scalar- tensor or :math:`(B,)`.- width: widths of the bounding boxes. Shape must be a scalar tensor or :math:`(B,)`.- height: heights of the bounding boxes. Shape must be a scalar tensor or :math:`(B,)`.+ tensor or ``(B,)``.+ width: widths of the bounding boxes. Shape must be a scalar tensor or ``(B,)``.+ height: heights of the bounding boxes. Shape must be a scalar tensor or ``(B,)``.Returns:- the bounding box tensor, shape of :math:`(B, 4, 2)`.+ the bounding box tensor, shape of ``(B, 4, 2)``.Examples:>>> x_start = torch.tensor([0, 1])@@ -607,17 +607,17 @@ def bbox_generator3d(Args:x_start: a tensor containing the x coordinates of the bounding boxes to be extracted. Shape must be a scalar- tensor or :math:`(B,)`.+ tensor or ``(B,)``.y_start: a tensor containing the y coordinates of the bounding boxes to be extracted. Shape must be a scalar- tensor or :math:`(B,)`.+ tensor or ``(B,)``.z_start: a tensor containing the z coordinates of the bounding boxes to be extracted. Shape must be a scalar- tensor or :math:`(B,)`.- width: widths of the bounding boxes. Shape must be a scalar tensor or :math:`(B,)`.- height: heights of the bounding boxes. Shape must be a scalar tensor or :math:`(B,)`.- depth: depths of the bounding boxes. Shape must be a scalar tensor or :math:`(B,)`.+ tensor or ``(B,)``.+ width: widths of the bounding boxes. Shape must be a scalar tensor or ``(B,)``.+ height: heights of the bounding boxes. Shape must be a scalar tensor or ``(B,)``.+ depth: depths of the bounding boxes. Shape must be a scalar tensor or ``(B,)``.Returns:- the 3d bounding box tensor :math:`(B, 8, 3)`.+ the 3d bounding box tensor ``(B, 8, 3)``.Examples:>>> x_start = torch.tensor([0, 3])@@ -693,11 +693,11 @@ def transform_bbox(transformed cyclic order.Args:- trans_mat: The transformation matrix to be applied, with supported shape :math:`(B, 3, 3)`.- For boxes shaped :math:`(N, 4)`, ``B`` is one or ``N``. For boxes shaped- :math:`(B, N, 4)` or :math:`(B, N, 4, 2)`, it is one or the boxes' ``B``.- boxes: The boxes to be transformed with a common shape of :math:`(N, 4)` or batched as :math:`(B, N, 4)`, the- polygon shape of :math:`(B, N, 4, 2)` is also supported.+ trans_mat: The transformation matrix to be applied, with supported shape ``(B, 3, 3)``.+ For boxes shaped ``(N, 4)``, ``B`` is one or ``N``. For boxes shaped+ ``(B, N, 4)`` or ``(B, N, 4, 2)``, it is one or the boxes' ``B``.+ boxes: The boxes to be transformed with a common shape of ``(N, 4)`` or batched as ``(B, N, 4)``, the+ polygon shape of ``(B, N, 4, 2)`` is also supported.mode: The format in which the boxes are provided. If set to 'xyxy' the boxes are assumed to be in the format``xmin, ymin, xmax, ymax``. If set to 'xywh' the boxes are assumed to be in the format``xmin, ymin, width, height``@@ -753,8 +753,8 @@ def nms(boxes: torch.Tensor, scores: torch.Tensor, iou_threshold: float) -> torcArgs:boxes: tensor containing exclusive ``xyxy`` bounding boxes with shape- :math:`(N, 4)`, ordered as ``(x_1, y_1, x_2, y_2)``.- scores: tensor containing the scores associated to each bounding box with shape :math:`(N,)`.+ ``(N, 4)``, ordered as ``(x_1, y_1, x_2, y_2)``.+ scores: tensor containing the scores associated to each bounding box with shape ``(N,)``.iou_threshold: the threshold to discard the overlapping boxes.Returns:diff --git a/kornia/geometry/boxes.py b/kornia/geometry/boxes.pyindex 7ac829e0e..0671073c4 100644--- a/kornia/geometry/boxes.py+++ b/kornia/geometry/boxes.py@@ -58,8 +58,8 @@ def _transform_boxes(boxes: torch.Tensor, M: torch.Tensor) -> torch.Tensor:Args:boxes: 2D quadrilaterals or 3D hexahedrons in kornia format.- M: the transformation matrix of shape :math:`(3, 3)` or :math:`(B, 3, 3)` for 2D and :math:`(4, 4)` or- :math:`(B, 4, 4)` for 3D hexahedron.+ M: the transformation matrix of shape ``(3, 3)`` or ``(B, 3, 3)`` for 2D and ``(4, 4)`` or+ ``(B, 4, 4)`` for 3D hexahedron."""M = _cast_to_floating_point(M)@@ -210,7 +210,7 @@ class Boxes:r"""2D boxes containing N or BxN boxes.Args:- boxes: 2D boxes, shape of :math:`(N, 4, 2)`, :math:`(B, N, 4, 2)` or a list of :math:`(N, 4, 2)`.+ boxes: 2D boxes, shape of ``(N, 4, 2)``, ``(B, N, 4, 2)`` or a list of ``(N, 4, 2)``.See below for more details.raise_if_not_floating_point: flag to control floating point casting behaviour when `boxes` is not afloating point tensor. True to raise an error when `boxes` isn't a floating point tensor, False@@ -220,8 +220,8 @@ class Boxes:convert ``boxes``; use :meth:`from_tensor` to import another representation.Convention:- - A box is a quadrilateral of four floating-point ``(x, y)`` vertices, :math:`(N, 4, 2)` or- :math:`(B, N, 4, 2)`, built in clockwise top-left, top-right, bottom-right, bottom-left order;+ - A box is a quadrilateral of four floating-point ``(x, y)`` vertices, ``(N, 4, 2)`` or+ ``(B, N, 4, 2)``, built in clockwise top-left, top-right, bottom-right, bottom-left order;:meth:`transform_boxes` can make it an arbitrary (rotated) quadrilateral.- The stored form is **inclusive** (``'vertices_plus'``): ``width = xmax - xmin + 1``. The exclusive``'xyxy'``, ``'xywh'`` and ``'vertices'`` modes are converted by :meth:`from_tensor` and@@ -321,9 +321,9 @@ class Boxes:Returns:Shape of :attr:`data`. For unbatched boxes this is usually- :math:`(N, 4, 2)`, where :math:`N` is the number of boxes, ``4``+ ``(N, 4, 2)``, where :math:`N` is the number of boxes, ``4``is the number of corner vertices, and ``2`` stores ``(x, y)``.- For batched boxes the shape is usually :math:`(B, N, 4, 2)`, where+ For batched boxes the shape is usually ``(B, N, 4, 2)``, where:math:`B` is the batch size."""return self.data.shape@@ -334,8 +334,8 @@ class Boxes:See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.Returns:- - Boxes heights, shape of :math:`(N,)` or :math:`(B,N)`.- - Boxes widths, shape of :math:`(N,)` or :math:`(B,N)`.+ - Boxes heights, shape of ``(N,)`` or ``(B,N)``.+ - Boxes widths, shape of ``(N,)`` or ``(B,N)``.Example:>>> boxes_xyxy = torch.tensor([[[1,1,2,2],[1,1,3,2]]])@@ -353,13 +353,13 @@ class Boxes:See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.- For batched boxes, if the current instance holds :math:`(B, N, 4, 2)` and- the incoming boxes holds :math:`(B, M, 4, 2)`, the merge results in- :math:`(B, N + M, 4, 2)`.+ For batched boxes, if the current instance holds ``(B, N, 4, 2)`` and+ the incoming boxes holds ``(B, M, 4, 2)``, the merge results in+ ``(B, N + M, 4, 2)``.- For unbatched boxes, if the current instance holds :math:`(N, 4, 2)` and- the incoming boxes holds :math:`(M, 4, 2)`, the merge results in- :math:`(N + M, 4, 2)`.+ For unbatched boxes, if the current instance holds ``(N, 4, 2)`` and+ the incoming boxes holds ``(M, 4, 2)``, the merge results in+ ``(N + M, 4, 2)``.Args:boxes: 2D boxes.@@ -440,7 +440,7 @@ class Boxes:Args:indices: Index tuple or list accepted by ``Tensor.index_put_``.The indices address entries in the stored tensor, commonly- shaped :math:`(B, N, 4, 2)` or :math:`(N, 4, 2)`.+ shaped ``(B, N, 4, 2)`` or ``(N, 4, 2)``.values: Replacement coordinates. If a :class:`Boxes` object ispassed, its coordinates and filtering validity are copied. Raw tensor writeschange only coordinates and preserve the existing filtering validity.@@ -483,13 +483,13 @@ class Boxes:``padding_size`` is ordered as ``(left, right, top, bottom)``. Only``left`` and ``top`` change the coordinate origin; this method returns``self`` after adding those two values to every vertex. Both the batched- :math:`(B, N, 4, 2)` and the unbatched :math:`(N, 4, 2)` container are+ ``(B, N, 4, 2)`` and the unbatched ``(N, 4, 2)`` container aresupported; the unbatched form carries a single image, so ``padding_size``must have exactly one row.Args:padding_size: Per-batch padding in ``(left, right, top, bottom)``- order, shaped :math:`(B, 4)`. A single row broadcasts across the+ order, shaped ``(B, 4)``. A single row broadcasts across thebatch."""@@ -508,13 +508,13 @@ class Boxes:``padding_size`` is ordered as ``(left, right, top, bottom)``. Only``left`` and ``top`` change the coordinate origin; this method returns``self`` after subtracting those two values from every vertex. Both the- batched :math:`(B, N, 4, 2)` and the unbatched :math:`(N, 4, 2)` container+ batched ``(B, N, 4, 2)`` and the unbatched ``(N, 4, 2)`` containerare supported; the unbatched form carries a single image, so``padding_size`` must have exactly one row.Args:padding_size: Per-batch padding in ``(left, right, top, bottom)``- order, shaped :math:`(B, 4)`. A single row broadcasts across the+ order, shaped ``(B, 4)``. A single row broadcasts across thebatch."""@@ -541,10 +541,10 @@ class Boxes:outside the bounds collapses onto the boundary instead of being removed.Args:- topleft: Required tensor of shape :math:`(B, 2)` containing the minimum+ topleft: Required tensor of shape ``(B, 2)`` containing the minimum``x`` and ``y`` coordinate allowed for each batch item. A singlerow broadcasts across the batch.- botright: Required tensor of shape :math:`(B, 2)` containing the maximum+ botright: Required tensor of shape ``(B, 2)`` containing the maximum``x`` and ``y`` coordinate allowed for each batch item. A singlerow broadcasts across the batch.inplace: If ``True``, clamp this object in place. Otherwise, return@@ -653,7 +653,7 @@ class Boxes:``width * height`` of :meth:`get_boxes_shape`: `#4010 <https://github.com/kornia/kornia/issues/4010>`_.Returns:- Area for each box, shaped :math:`(N,)` or :math:`(B, N)`.+ Area for each box, shaped ``(N,)`` or ``(B, N)``."""coords = self._data.flatten(0, 1) if self._data.ndim == 4 else self._data# calculate centroid of the box@@ -676,23 +676,23 @@ class Boxes:See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.Args:- boxes: 2D boxes, shape of :math:`(N, 4)`, :math:`(B, N, 4)`, :math:`(N, 4, 2)` or- :math:`(B, N, 4, 2)`, a nested numeric list with one of those shapes, or a list of- :math:`(N, 4)` or :math:`(N, 4, 2)` tensors matching ``mode``. Integer input is cast to ``float32``,+ boxes: 2D boxes, shape of ``(N, 4)``, ``(B, N, 4)``, ``(N, 4, 2)`` or+ ``(B, N, 4, 2)``, a nested numeric list with one of those shapes, or a list of+ ``(N, 4)`` or ``(N, 4, 2)`` tensors matching ``mode``. Integer input is cast to ``float32``,or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.mode: The format in which the boxes are provided:- * 'xyxy': ``xmin, ymin, xmax, ymax`` with exclusive extent. With shape :math:`(N, 4)`,- :math:`(B, N, 4)`.- * 'xyxy_plus': ``xmin, ymin, xmax, ymax`` with inclusive extent. With shape :math:`(N, 4)`,- :math:`(B, N, 4)`.- * 'xywh': ``xmin, ymin, width, height`` with exclusive extent. With shape :math:`(N, 4)`,- :math:`(B, N, 4)`.+ * 'xyxy': ``xmin, ymin, xmax, ymax`` with exclusive extent. With shape ``(N, 4)``,+ ``(B, N, 4)``.+ * 'xyxy_plus': ``xmin, ymin, xmax, ymax`` with inclusive extent. With shape ``(N, 4)``,+ ``(B, N, 4)``.+ * 'xywh': ``xmin, ymin, width, height`` with exclusive extent. With shape ``(N, 4)``,+ ``(B, N, 4)``.* 'vertices': boxes are defined by their vertices points in the following ``clockwise`` order:*top-left, top-right, bottom-right, bottom-left*. Vertices coordinates are in (x,y) order. This is- the exclusive input form. With shape :math:`(N, 4, 2)`, :math:`(B, N, 4, 2)`.- * 'vertices_plus': the inclusive stored vertex form. With shape :math:`(N, 4, 2)`,- :math:`(B, N, 4, 2)`.+ the exclusive input form. With shape ``(N, 4, 2)``, ``(B, N, 4, 2)``.+ * 'vertices_plus': the inclusive stored vertex form. With shape ``(N, 4, 2)``,+ ``(B, N, 4, 2)``.validate_boxes: Reject a non-finite coordinate in every mode: ``ValueError`` for the ``'xy*'`` modes,which also reject non-positive extents in each mode's convention, and ``RuntimeError`` from@@ -769,8 +769,8 @@ class Boxes:Boxes tensor in the ``mode`` format, or a list of tensors when the object was created from a list and``as_padded_sequence=False``. The tensor shape depends on the ``mode`` value:- * 'vertices' or 'vertices_plus': :math:`(N, 4, 2)` or :math:`(B, N, 4, 2)`.- * Any other value: :math:`(N, 4)` or :math:`(B, N, 4)`.+ * 'vertices' or 'vertices_plus': ``(N, 4, 2)`` or ``(B, N, 4, 2)``.+ * Any other value: ``(N, 4)`` or ``(B, N, 4)``.Examples:>>> boxes_xyxy = torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]])@@ -933,7 +933,7 @@ class Boxes:See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.Args:- M: The transformation matrix to be applied, shape of :math:`(3, 3)` or :math:`(B, 3, 3)`.+ M: The transformation matrix to be applied, shape of ``(3, 3)`` or ``(B, 3, 3)``.inplace: do transform in-place and return self.Returns:@@ -976,7 +976,7 @@ class Boxes::class:`NotImplementedError`.Args:- size: translate size for x, y direction, shape of :math:`(B, 2)`.+ size: translate size for x, y direction, shape of ``(B, 2)``.method: only "warp" is supported.inplace: do transform in-place and return self.@@ -997,8 +997,8 @@ class Boxes:Returns:Tensor storing four vertices per box in ``(x, y)`` order. The- common shapes are :math:`(N, 4, 2)` for unbatched boxes and- :math:`(B, N, 4, 2)` for batched boxes, where :math:`B` is batch+ common shapes are ``(N, 4, 2)`` for unbatched boxes and+ ``(B, N, 4, 2)`` for batched boxes, where :math:`B` is batchsize and :math:`N` is the number of boxes."""return self._data@@ -1066,7 +1066,7 @@ class VideoBoxes(Boxes):r"""2D boxes with an explicit temporal channel for video sequences.Accepts and returns box corners for a batch of videos as- :math:`(B, T, N, 4, 2)` in ``vertices_plus`` mode. Internally the corners+ ``(B, T, N, 4, 2)`` in ``vertices_plus`` mode. Internally the cornersare stored flattened as :math:`(B \cdot T, N, 4, 2)`.:class:`~kornia.augmentation.AugmentationSequential` uses this wrapper whenthe pipeline contains a video sequential so that ``to_tensor`` restores the@@ -1075,17 +1075,17 @@ class VideoBoxes(Boxes):See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.Convention:- - :meth:`from_tensor` stores :math:`(B, T, N, 4, 2)` input unchanged as :math:`(B \cdot T, N, 4, 2)`+ - :meth:`from_tensor` stores ``(B, T, N, 4, 2)`` input unchanged as :math:`(B \cdot T, N, 4, 2)```'vertices_plus'`` data, with no mode or conversion; integer input is cast to ``float32``,or ``float64`` when that is the default dtype. Another shape or a list raises ``ValueError``.``validate_boxes=True`` rejects a non-finite coordinate as:meth:`Boxes.from_tensor` does for ``'vertices_plus'``.- :meth:`to_tensor` accepts every :class:`Boxes` mode and restores the temporal axis- (``to_tensor('xyxy')`` is :math:`(B, T, N, 4)`).+ (``to_tensor('xyxy')`` is ``(B, T, N, 4)``).- Indexing selects the video batch axis while preserving the temporal axis. An integer index returns aone-video :class:`VideoBoxes` so :meth:`to_tensor` keeps the shape :math:`(1, T, \ldots)`. Indexassignment, ``video_boxes[key] = other``, writes the same whole videos.- - A transformation matrix is :math:`(B \cdot T, 3, 3)`; a :math:`(3, 3)` matrix raises ``ValueError``+ - A transformation matrix is :math:`(B \cdot T, 3, 3)`; a ``(3, 3)`` matrix raises ``ValueError``unless :math:`B \cdot T = 1`.- :meth:`transform_boxes`, :meth:`translate`, :meth:`clamp`, :meth:`filter_boxes_by_area` and:meth:`merge` return a new :class:`VideoBoxes`; :meth:`pad`, :meth:`unpad`, :meth:`to` and@@ -1103,7 +1103,7 @@ class VideoBoxes(Boxes):r"""Create :class:`VideoBoxes` from a video box tensor.Args:- boxes: Box corners with shape :math:`(B, T, N, 4, 2)` in+ boxes: Box corners with shape ``(B, T, N, 4, 2)`` in``vertices_plus`` order (top-left, top-right, bottom-right,bottom-left), stored unchanged; integer input is cast to``float32``, or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.@@ -1119,7 +1119,7 @@ class VideoBoxes(Boxes):Raises:ValueError: If ``boxes`` is a list or does not have shape- :math:`(B, T, N, 4, 2)`.+ ``(B, T, N, 4, 2)``."""if isinstance(boxes, (list,)) or (boxes.dim() != 5 or boxes.shape[-2:] != torch.Size([4, 2])):raise ValueError("Input box type is not yet supported. Please input an `BxTxNx4x2` tensor directly.")@@ -1173,7 +1173,7 @@ class VideoBoxes(Boxes):``None``, uses the stored mode (``vertices_plus`` by default).as_padded_sequence: Forwarded to :meth:`Boxes.to_tensor`. It onlychanges the result of a list-backed container; a- :class:`VideoBoxes` built from a :math:`(B, T, N, 4, 2)` tensor+ :class:`VideoBoxes` built from a ``(B, T, N, 4, 2)`` tensoris not list-backed, so the value makes no difference there. Thekeyword is accepted because the inherited :meth:`get_boxes_shape`and :meth:`to_mask` pass it.@@ -1209,7 +1209,7 @@ class Boxes3D:r"""3D boxes containing N or BxN boxes.Args:- boxes: 3D boxes, shape of :math:`(N,8,3)` or :math:`(B,N,8,3)`. See below for more details.+ boxes: 3D boxes, shape of ``(N,8,3)`` or ``(B,N,8,3)``. See below for more details.raise_if_not_floating_point: flag to control floating point casting behaviour when `boxes` is not a floatingpoint tensor. True to raise an error when `boxes` isn't a floating point tensor, False to cast to``float32``, or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.@@ -1218,10 +1218,10 @@ class Boxes3D:Convention:- A box is a `hexahedron <https://en.wikipedia.org/wiki/Hexahedron>`_ of eight floating-point- ``(x, y, z)`` vertices, :math:`(N, 8, 3)` or :math:`(B, N, 8, 3)`: front-top-left, front-top-right,+ ``(x, y, z)`` vertices, ``(N, 8, 3)`` or ``(B, N, 8, 3)``: front-top-left, front-top-right,front-bottom-right, front-bottom-left, then the same four back vertices.- The stored form is **inclusive** (``depth = zmax - zmin + 1``), as for :class:`Boxes`. :meth:`from_tensor`- takes :math:`(N, 6)` or :math:`(B, N, 6)` in ``'xyzxyz'``, ``'xyzwhd'`` (exclusive) or+ takes ``(N, 6)`` or ``(B, N, 6)`` in ``'xyzxyz'``, ``'xyzwhd'`` (exclusive) or``'xyzxyz_plus'``; the vertex modes exist for :meth:`to_tensor` only. Modes are case-insensitive.- :meth:`to_tensor` exports the ``amin``/``amax`` axis-aligned bounding box and defaults to ``'xyzxyz'``whatever the stored label.@@ -1284,9 +1284,9 @@ class Boxes3D:Returns:Shape of :attr:`data`. For unbatched boxes this is usually- :math:`(N, 8, 3)`, where :math:`N` is the number of boxes, ``8`` is+ ``(N, 8, 3)``, where :math:`N` is the number of boxes, ``8`` isthe number of cuboid corners, and ``3`` stores ``(x, y, z)``. For- batched boxes the shape is usually :math:`(B, N, 8, 3)`.+ batched boxes the shape is usually ``(B, N, 8, 3)``."""return self.data.shape@@ -1296,9 +1296,9 @@ class Boxes3D:See the Convention block on :class:`~kornia.geometry.boxes.Boxes3D`.Returns:- - Boxes depths, shape of :math:`(N,)` or :math:`(B,N)`.- - Boxes heights, shape of :math:`(N,)` or :math:`(B,N)`.- - Boxes widths, shape of :math:`(N,)` or :math:`(B,N)`.+ - Boxes depths, shape of ``(N,)`` or ``(B,N)``.+ - Boxes heights, shape of ``(N,)`` or ``(B,N)``.+ - Boxes widths, shape of ``(N,)`` or ``(B,N)``.Example:>>> boxes_xyzxyz = torch.tensor([[ 0, 1, 2, 10, 21, 32], [3, 4, 5, 43, 54, 65]])@@ -1318,7 +1318,7 @@ class Boxes3D:See the Convention block on :class:`~kornia.geometry.boxes.Boxes3D`.Args:- boxes: 3D boxes, shape of :math:`(N,6)` or :math:`(B,N,6)`. Integer input is cast to+ boxes: 3D boxes, shape of ``(N,6)`` or ``(B,N,6)``. Integer input is cast to``float32``, or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.mode: The format in which the 3D boxes are provided, matched case-insensitively.@@ -1429,8 +1429,8 @@ class Boxes3D:Returns:3D Boxes tensor in the ``mode`` format. The shape depends with the ``mode`` value:- * 'vertices' or 'vertices_plus': :math:`(N, 8, 3)` or :math:`(B, N, 8, 3)`.- * Any other value: :math:`(N, 6)` or :math:`(B, N, 6)`.+ * 'vertices' or 'vertices_plus': ``(N, 8, 3)`` or ``(B, N, 8, 3)``.+ * Any other value: ``(N, 6)`` or ``(B, N, 6)``.Note:The ``amin``/``amax`` reduction ties on every face of an axis-aligned box (4 vertices share each@@ -1595,7 +1595,7 @@ class Boxes3D:See the Convention block on :class:`~kornia.geometry.boxes.Boxes3D`.Args:- M: The transformation matrix to be applied, shape of :math:`(4, 4)` or :math:`(B, 4, 4)`, where ``B``+ M: The transformation matrix to be applied, shape of ``(4, 4)`` or ``(B, 4, 4)``, where ``B``must equal the box batch size and an unbatched box counts as one.inplace: do transform in-place and return self.@@ -1634,7 +1634,7 @@ class Boxes3D:Returns:Tensor containing eight 3D corner coordinates per box, usually- shaped :math:`(N, 8, 3)` or :math:`(B, N, 8, 3)`.+ shaped ``(N, 8, 3)`` or ``(B, N, 8, 3)``."""return self._datadiff --git a/kornia/geometry/calibration/distort.py b/kornia/geometry/calibration/distort.pyindex e336f5084..f2a2d7188 100644--- a/kornia/geometry/calibration/distort.py+++ b/kornia/geometry/calibration/distort.py@@ -30,7 +30,7 @@ def tilt_projection(taux: torch.Tensor, tauy: torch.Tensor, return_inverse: bool``return_inverse=False`` returns ``Pz @ R`` (OpenCV's tilt projection) and ``return_inverse=True`` itsinverse, the branch :func:`~kornia.geometry.calibration.undistort_points` applies. Zero angles give``eye(3)``.- - scalar angles return :math:`(3, 3)`; otherwise a trailing singleton angle axis, if present, is+ - scalar angles return ``(3, 3)``; otherwise a trailing singleton angle axis, if present, isconsumed and the remaining dimensions are the batch shape.Args:@@ -40,7 +40,7 @@ def tilt_projection(taux: torch.Tensor, tauy: torch.Tensor, return_inverse: boolReturns:torch.Tensor: Tilt projection matrix, or the inverse tilt projection matrix when ``return_inverse`` is- True, with shape :math:`(3, 3)` for scalar angles or :math:`(*, 3, 3)` for non-scalar angles, where a+ True, with shape ``(3, 3)`` for scalar angles or ``(*, 3, 3)`` for non-scalar angles, where atrailing singleton angle-component axis is omitted from :math:`*`."""@@ -124,8 +124,8 @@ def distort_points(- matching leading dimensions of ``points``, ``K`` and ``dist`` are preserved.Args:- points: Input image points with shape :math:`(*, N, 2)`.- K: Intrinsic camera matrix with shape :math:`(*, 3, 3)`.+ points: Input image points with shape ``(*, N, 2)``.+ K: Intrinsic camera matrix with shape ``(*, 3, 3)``.dist: Distortion coefficients:math:`(k_1,k_2,p_1,p_2[,k_3[,k_4,k_5,k_6[,s_1,s_2,s_3,s_4[,\tau_x,\tau_y]]]])`. This isa vector with 4, 5, 8, 12 or 14 elements with shape :math:`(*, n)`.@@ -133,10 +133,10 @@ def distort_points(:math:`z = 1` plane -- the opposite of what the argument order suggests, since ``K`` is the onethat maps the distorted normalized point back to pixels. By default it is the same as ``K``, inwhich case both steps use the same camera; a different matrix rescales and shifts the **input**,- not the result. Shape: :math:`(*, 3, 3)`. Default: None.+ not the result. Shape: ``(*, 3, 3)``. Default: None.Returns:- Distorted 2D points with shape :math:`(*, N, 2)`.+ Distorted 2D points with shape ``(*, N, 2)``.Example:>>> points = torch.rand(1, 1, 2)diff --git a/kornia/geometry/calibration/pnp.py b/kornia/geometry/calibration/pnp.pyindex 2b87ea626..f31243502 100644--- a/kornia/geometry/calibration/pnp.py+++ b/kornia/geometry/calibration/pnp.py@@ -33,14 +33,14 @@ def _mean_isotropic_scale_normalize(r"""Normalize points.Args:- points : torch.Tensor containing the points to be normalized with shape :math:`(B, N, D)`.+ points : torch.Tensor containing the points to be normalized with shape ``(B, N, D)``.eps : Small value to avoid division by zero error.- weights : Optional non-negative per-point weights with shape :math:`(B, N)` for the mean and the scale.+ weights : Optional non-negative per-point weights with shape ``(B, N)`` for the mean and the scale.A point with weight zero does not affect the normalization.Returns:- Tuple containing the normalized points in the shape :math:`(B, N, D)` and the transformation matrix- in the shape :math:`(B, D+1, D+1)`.+ Tuple containing the normalized points in the shape ``(B, N, D)`` and the transformation matrix+ in the shape ``(B, D+1, D+1)``."""KORNIA_CHECK_SHAPE(points, ["B", "N", "D"])@@ -93,10 +93,10 @@ def solve_pnp_dlt(twisted cubic. However, this function does not check for this condition.Convention:- - the returned :math:`(B, 3, 4)` matrix is the **world-to-camera** ``[R | t]``: it maps a world point+ - the returned ``(B, 3, 4)`` matrix is the **world-to-camera** ``[R | t]``: it maps a world pointinto the camera frame (``X_cam = X_world + (1, 0, 0)`` gives ``t = (+1, 0, 0)``), not acamera-to-world pose.- - ``intrinsics`` is the :math:`(B, 3, 3)` ``K``; the :math:`(B, 4, 4)` matrix that a+ - ``intrinsics`` is the ``(B, 3, 3)`` ``K``; the ``(B, 4, 4)`` matrix that a``PinholeCamera`` stores is rejected.- ``weights`` scales the two rows each point contributes to the homogeneous linear system, and thenormalization and the degeneracy check use the same weighting. A uniform ``weights`` leaves the answer@@ -107,18 +107,18 @@ def solve_pnp_dlt(- a caller's autocast region does not change the result: float32 inputs are solved in float32.Args:- world_points : A torch.Tensor with shape :math:`(B, N, 3)` representing+ world_points : A torch.Tensor with shape ``(B, N, 3)`` representingthe points in the world space.- img_points : A torch.Tensor with shape :math:`(B, N, 2)` representing+ img_points : A torch.Tensor with shape ``(B, N, 2)`` representingthe points in the image space.- intrinsics : A torch.Tensor with shape :math:`(B, 3, 3)` representing+ intrinsics : A torch.Tensor with shape ``(B, 3, 3)`` representingthe intrinsic matrices.- weights : A torch.Tensor with shape :math:`(B, N)` representing the+ weights : A torch.Tensor with shape ``(B, N)`` representing theweights for each point. If None, all points are considered to be equally important.svd_eps : A small float value to avoid numerical precision issues.Returns:- A torch.Tensor with shape :math:`(B, 3, 4)` representing the estimated world to+ A torch.Tensor with shape ``(B, 3, 4)`` representing the estimated world tocamera transformation matrices (also known as the extrinsic matrices).Example:diff --git a/kornia/geometry/calibration/undistort.py b/kornia/geometry/calibration/undistort.pyindex 4eaebc2f4..ccbe3fba7 100644--- a/kornia/geometry/calibration/undistort.py+++ b/kornia/geometry/calibration/undistort.py@@ -57,8 +57,8 @@ def undistort_points(`#4285 <https://github.com/kornia/kornia/issues/4285>`_.Args:- points: Input image points with shape :math:`(*, N, 2)`.- K: Intrinsic camera matrix with shape :math:`(*, 3, 3)`.+ points: Input image points with shape ``(*, N, 2)``.+ K: Intrinsic camera matrix with shape ``(*, 3, 3)``.dist: Distortion coefficients:math:`(k_1,k_2,p_1,p_2[,k_3[,k_4,k_5,k_6[,s_1,s_2,s_3,s_4[,\tau_x,\tau_y]]]])`. This isa vector with 4, 5, 8, 12 or 14 elements with shape :math:`(*, n)`.@@ -67,11 +67,11 @@ def undistort_points(:math:`z = 1` plane -- the mirror image of the two roles in:func:`~kornia.geometry.calibration.distort_points`. By default it is the same as ``K``, in whichcase both steps use the same camera; a different matrix rescales and shifts the **result**.- Shape: :math:`(*, 3, 3)`. Default: None.+ Shape: ``(*, 3, 3)``. Default: None.num_iters: Number of undistortion iterations. Default: 5.Returns:- Undistorted 2D points with shape :math:`(*, N, 2)`.+ Undistorted 2D points with shape ``(*, N, 2)``.Example:>>> _ = torch.manual_seed(0)@@ -169,21 +169,21 @@ def undistort_image(image: torch.Tensor, K: torch.Tensor, dist: torch.Tensor) ->Convention:- the leading dimensions of ``image`` (in front of ``C, H, W``), ``K`` (in front of :math:`3 \times 3`)and ``dist`` (in front of its ``n`` coefficients) must match exactly; the one exception is the- legacy unbatched call, a :math:`(1, C, H, W)` image with a :math:`(3, 3)` ``K`` and an :math:`(n,)`+ legacy unbatched call, a ``(1, C, H, W)`` image with a ``(3, 3)`` ``K`` and an :math:`(n,)```dist``.- the sampling map applies :func:`~kornia.geometry.calibration.distort_points` to the integer pixelcentres (see :class:`~kornia.geometry.camera.pinhole.PinholeCamera`) and is resampled bilinearly witha fixed ``align_corners=True``, so all-zero coefficients return the input only to rounding.Args:- image: Input image with shape :math:`(*, C, H, W)`.- K: Intrinsic camera matrix with shape :math:`(*, 3, 3)`.+ image: Input image with shape ``(*, C, H, W)``.+ K: Intrinsic camera matrix with shape ``(*, 3, 3)``.dist: Distortion coefficients:math:`(k_1,k_2,p_1,p_2[,k_3[,k_4,k_5,k_6[,s_1,s_2,s_3,s_4[,\tau_x,\tau_y]]]])`. This isa vector with 4, 5, 8, 12 or 14 elements with shape :math:`(*, n)`.Returns:- Undistorted image with shape :math:`(*, C, H, W)`.+ Undistorted image with shape ``(*, C, H, W)``.Example:>>> img = torch.rand(1, 3, 5, 5)diff --git a/kornia/geometry/camera/distortion_affine.py b/kornia/geometry/camera/distortion_affine.pyindex f5d6e9d29..418d6baba 100644--- a/kornia/geometry/camera/distortion_affine.py+++ b/kornia/geometry/camera/distortion_affine.py@@ -37,7 +37,7 @@ def distort_points_affine(projected_points_in_camera_z1_plane: torch.Tensor, parpixel, and ``params`` is the flat vector ``[fx, fy, cx, cy]``; the result is in pixels (integer pixelcentres; see :class:`~kornia.geometry.camera.pinhole.PinholeCamera`).- :func:`~kornia.geometry.calibration.distort_points` is the same camera parametrized by a- :math:`(*, 3, 3)` ``K`` and an OpenCV coefficient vector; it takes a **pixel** input instead.+ ``(*, 3, 3)`` ``K`` and an OpenCV coefficient vector; it takes a **pixel** input instead.- :func:`undistort_points_affine` is the closed-form inverse.Args:@@ -122,7 +122,7 @@ def dx_distort_points_affine(projected_points_in_camera_z1_plane: torch.Tensor,\begin{bmatrix} f_x & 0 \\ 0 & f_y \end{bmatrix}Convention:- - the result is the :math:`(..., 2, 2)` Jacobian of :func:`distort_points_affine` with respect to the+ - the result is the ``(..., 2, 2)`` Jacobian of :func:`distort_points_affine` with respect to the**point**: rows are the output components ``(u, v)``, columns the input components ``(x, y)``.- the map is affine, so that Jacobian is ``diag(fx, fy)`` and does not depend on the point.- ``...`` is the broadcast of the points' and the params' leading shapes, as indiff --git a/kornia/geometry/camera/distortion_kannala_brandt.py b/kornia/geometry/camera/distortion_kannala_brandt.pyindex a4f1bf59a..bbdd2c74a 100644--- a/kornia/geometry/camera/distortion_kannala_brandt.py+++ b/kornia/geometry/camera/distortion_kannala_brandt.py@@ -203,7 +203,7 @@ def dx_distort_points_kannala_brandt(r"""Return the analytic Jacobian of the Kannala-Brandt distortion model.Convention:- - the result has shape :math:`(..., 2, 2)` and is laid out like the Jacobian that+ - the result has shape ``(..., 2, 2)`` and is laid out like the Jacobian that:func:`~kornia.geometry.camera.dx_distort_points_affine` returns: rows are the output components``(u, v)``, columns the input components ``(x, y)``.- for squared radii ``<= 1e-8`` the forward function uses its affine branch, so the Jacobian there isdiff --git a/kornia/geometry/camera/perspective.py b/kornia/geometry/camera/perspective.pyindex 17a1b90cc..2d9d25377 100644--- a/kornia/geometry/camera/perspective.py+++ b/kornia/geometry/camera/perspective.py@@ -32,9 +32,9 @@ def project_points(point_3d: torch.Tensor, camera_matrix: torch.Tensor) -> torchSee the Convention block on :class:`~kornia.geometry.camera.pinhole.PinholeCamera`.Convention:- - ``point_3d`` is a **camera-frame** point and ``camera_matrix`` the :math:`(*, 3, 3)` ``K``; the+ - ``point_3d`` is a **camera-frame** point and ``camera_matrix`` the ``(*, 3, 3)`` ``K``; thefunction takes no extrinsics, so it does not move between frames.- - the input must be at least rank 2: an unbatched :math:`(3,)` point raises :class:`ValueError`.+ - the input must be at least rank 2: an unbatched ``(3,)`` point raises :class:`ValueError`... warning::At ``abs(z) <= 1e-8`` the divide is skipped and ``K`` is applied to the undivided point, giving the@@ -44,12 +44,12 @@ def project_points(point_3d: torch.Tensor, camera_matrix: torch.Tensor) -> torchArgs:point_3d: tensor containing the 3d points to be projected- to the camera plane. The shape of the tensor can be :math:`(*, 3)`.+ to the camera plane. The shape of the tensor can be ``(*, 3)``.camera_matrix: tensor containing the intrinsics camera- matrix. The tensor shape must be :math:`(*, 3, 3)`.+ matrix. The tensor shape must be ``(*, 3, 3)``.Returns:- tensor of (u, v) cam coordinates with shape :math:`(*, 2)`.+ tensor of (u, v) cam coordinates with shape ``(*, 2)``.Example:>>> _ = torch.manual_seed(0)@@ -85,17 +85,17 @@ def unproject_points(Args:point_2d: tensor containing the 2d points to be projected to- the camera frame. The shape of the tensor can be :math:`(*, 2)`.+ the camera frame. The shape of the tensor can be ``(*, 2)``.depth: tensor containing the depth value of each 2d- points. The tensor shape must be equal to point2d :math:`(*, 1)`.+ points. The tensor shape must be equal to point2d ``(*, 1)``.camera_matrix: tensor containing the intrinsics camera- matrix. The tensor shape must be :math:`(*, 3, 3)`.+ matrix. The tensor shape must be ``(*, 3, 3)``.normalize: whether to normalize the pointcloud. Thismust be set to `True` when the depth is represented as the Euclideanray length from the camera position.Returns:- tensor of (x, y, z) camera coordinates with shape :math:`(*, 3)`.+ tensor of (x, y, z) camera coordinates with shape ``(*, 3)``.Example:>>> _ = torch.manual_seed(0)diff --git a/kornia/geometry/camera/pinhole.py b/kornia/geometry/camera/pinhole.pyindex 03fac4b24..34036fc6d 100644--- a/kornia/geometry/camera/pinhole.py+++ b/kornia/geometry/camera/pinhole.py@@ -38,8 +38,8 @@ class PinholeCamera:r"""Class that represents a Pinhole Camera model.Convention:- - ``intrinsics`` is the :math:`(B, 4, 4)` calibration matrix whose top-left :math:`3 \times 3` block is- ``[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]``, and ``extrinsics`` the :math:`(B, 4, 4)` **world-to-camera**+ - ``intrinsics`` is the ``(B, 4, 4)`` calibration matrix whose top-left :math:`3 \times 3` block is+ ``[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]``, and ``extrinsics`` the ``(B, 4, 4)`` **world-to-camera**transform ``[R | t]`` (OpenCV / COLMAP semantics): :meth:`project` takes **world** points, computes``K (R X + t)`` and returns pixels, while :meth:`unproject` takes pixels and a camera-frame depth andreturns **world** points. The functional API takes a ``3x3`` ``K`` and no extrinsics, so it works in@@ -57,7 +57,7 @@ class PinholeCamera:.. warning:::meth:`scale` and :meth:`scale_` rescale the principal point as ``cx' = s * cx`` (the half-pixel rule),which disagrees with the integer pixel centres above:- `#4263 <https://github.com/kornia/kornia/issues/4263>`_. :math:`(B, N, 4, 4)` storage is+ `#4263 <https://github.com/kornia/kornia/issues/4263>`_. ``(B, N, 4, 4)`` storage isdeprecated and will be rejected in a future release:`#4266 <https://github.com/kornia/kornia/issues/4266>`_. The ``intrinsics`` form is not validated, but:meth:`project`, :meth:`unproject`, :meth:`intrinsics_inverse` and@@ -65,14 +65,14 @@ class PinholeCamera:zero-padded ``K`` behaves like its homogeneous embedding.Args:- intrinsics: torch.Tensor with shape :math:`(B, 4, 4)`- containing the full 4x4 camera calibration matrix. Pass :math:`(B, 4, 4)`:- :math:`(B, N, 4, 4)` is deprecated, and :meth:`project` and :meth:`unproject` never supported it.+ intrinsics: torch.Tensor with shape ``(B, 4, 4)``+ containing the full 4x4 camera calibration matrix. Pass ``(B, 4, 4)``:+ ``(B, N, 4, 4)`` is deprecated, and :meth:`project` and :meth:`unproject` never supported it.``PinholeCamerasList`` still stores that layout internally.- extrinsics: torch.Tensor with shape :math:`(B, 4, 4)`+ extrinsics: torch.Tensor with shape ``(B, 4, 4)``containing the full 4x4 rotation-translation matrix, checked by the same predicate.- height: torch.Tensor with shape :math:`(B)` containing the image height.- width: torch.Tensor with shape :math:`(B)` containing the image width.+ height: torch.Tensor with shape ``(B)`` containing the image height.+ width: torch.Tensor with shape ``(B)`` containing the image width... note::We assume that the class attributes are in batch form in order to take@@ -146,7 +146,7 @@ class PinholeCamera:r"""The full 4x4 intrinsics matrix.Returns:- torch.Tensor of shape :math:`(B, 4, 4)`.+ torch.Tensor of shape ``(B, 4, 4)``."""if not self._check_valid_params(self._intrinsics, "intrinsics"):@@ -158,7 +158,7 @@ class PinholeCamera:r"""The full 4x4 extrinsics matrix.Returns:- torch.Tensor of shape :math:`(B, 4, 4)`.+ torch.Tensor of shape ``(B, 4, 4)``."""if not self._check_valid_params(self._extrinsics, "extrinsics"):@@ -180,7 +180,7 @@ class PinholeCamera:r"""Return the focal length in the x-direction.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.intrinsics[..., 0, 0]@@ -190,7 +190,7 @@ class PinholeCamera:r"""Return the focal length in the y-direction.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.intrinsics[..., 1, 1]@@ -200,7 +200,7 @@ class PinholeCamera:r"""Return the x-coordinate of the principal point.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.intrinsics[..., 0, 2]@@ -210,7 +210,7 @@ class PinholeCamera:r"""Return the y-coordinate of the principal point.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.intrinsics[..., 1, 2]@@ -220,7 +220,7 @@ class PinholeCamera:r"""Return the x-coordinate of the translation vector.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.extrinsics[..., 0, -1]@@ -235,7 +235,7 @@ class PinholeCamera:r"""Return the y-coordinate of the translation vector.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.extrinsics[..., 1, -1]@@ -250,7 +250,7 @@ class PinholeCamera:r"""Returns the z-coordinate of the translation vector.Returns:- torch.Tensor of shape :math:`(B)`.+ torch.Tensor of shape ``(B)``."""return self.extrinsics[..., 2, -1]@@ -265,7 +265,7 @@ class PinholeCamera:r"""Return the 3x4 rotation-translation matrix.Returns:- torch.Tensor of shape :math:`(B, 3, 4)`.+ torch.Tensor of shape ``(B, 3, 4)``."""return self.extrinsics[..., :3, :4]@@ -275,7 +275,7 @@ class PinholeCamera:r"""Return the 3x3 camera matrix containing the intrinsics.Returns:- torch.Tensor of shape :math:`(B, 3, 3)`.+ torch.Tensor of shape ``(B, 3, 3)``."""return self.intrinsics[..., :3, :3]@@ -285,7 +285,7 @@ class PinholeCamera:r"""Return the 3x3 rotation matrix from the extrinsics.Returns:- torch.Tensor of shape :math:`(B, 3, 3)`.+ torch.Tensor of shape ``(B, 3, 3)``."""return self.extrinsics[..., :3, :3]@@ -295,7 +295,7 @@ class PinholeCamera:r"""Return the translation vector from the extrinsics.Returns:- torch.Tensor of shape :math:`(B, 3, 1)`.+ torch.Tensor of shape ``(B, 3, 1)``."""return self.extrinsics[..., :3, -1:]@@ -316,7 +316,7 @@ class PinholeCamera:which is one. See the Convention block on :class:`~kornia.geometry.camera.pinhole.PinholeCamera`.Returns:- torch.Tensor of shape :math:`(B, 4, 4)`.+ torch.Tensor of shape ``(B, 4, 4)``."""return _embed_intrinsics(_torch_inverse_cast(self.camera_matrix))@@ -336,7 +336,7 @@ class PinholeCamera:Args:scale_factor: a torch.Tensor with the scale factor. It hasto be broadcastable with class members. The expected shape is- :math:`(B)` or :math:`(1)`.+ ``(B)`` or ``(1)``.Returns:the camera model with scaled parameters.@@ -367,7 +367,7 @@ class PinholeCamera:Args:scale_factor: a torch.Tensor with the scale factor. It hasto be broadcastable with class members. The expected shape is- :math:`(B)` or :math:`(1)`.+ ``(B)`` or ``(1)``.Returns:the camera model with scaled parameters.@@ -389,7 +389,7 @@ class PinholeCamera:See the Convention block on :class:`~kornia.geometry.camera.pinhole.PinholeCamera`.Convention:- - ``point_3d`` must be at least rank 2. An unbatched :math:`(3,)` point raises :class:`ValueError`.+ - ``point_3d`` must be at least rank 2. An unbatched ``(3,)`` point raises :class:`ValueError`.An empty point set returns an empty result.- a point whose **camera-frame** ``z`` is 0 does not raise: ``K`` is applied first and theperspective divide is then skipped, so the result is the undivided ``K (R X + t)``.@@ -400,11 +400,11 @@ class PinholeCamera:Args:point_3d: torch.Tensor containing the 3d points to be projected- to the camera plane. The shape of the torch.Tensor can be :math:`(*, 3)` with at least two+ to the camera plane. The shape of the torch.Tensor can be ``(*, 3)`` with at least twodimensions.Returns:- torch.Tensor of (u, v) cam coordinates with shape :math:`(*, 2)`.+ torch.Tensor of (u, v) cam coordinates with shape ``(*, 2)``.Example:>>> _ = torch.manual_seed(0)@@ -432,13 +432,13 @@ class PinholeCamera:Args:point_2d: torch.Tensor containing the 2d to be projected to- world coordinates. The shape of the torch.Tensor can be :math:`(*, 2)` with at least two+ world coordinates. The shape of the torch.Tensor can be ``(*, 2)`` with at least twodimensions.depth: torch.Tensor containing the depth value of each 2d- points. The torch.Tensor shape must be equal to point2d :math:`(*, 1)`.+ points. The torch.Tensor shape must be equal to point2d ``(*, 1)``.Returns:- torch.Tensor of (x, y, z) world coordinates with shape :math:`(*, 3)`.+ torch.Tensor of (x, y, z) world coordinates with shape ``(*, 3)``.Example:>>> _ = torch.manual_seed(0)@@ -549,7 +549,7 @@ class PinholeCamerasList(PinholeCamera):.. note::The underlying data torch.Tensor will be stacked in the first dimension.That's it, given a list of two camera instances, the intrinsics torch.Tensor- will have a shape :math:`(B, N, 4, 4)` where :math:`B` is the batch+ will have a shape ``(B, N, 4, 4)`` where :math:`B` is the batchsize and :math:`N` is the numbers of cameras (in this case two).Args:@@ -633,10 +633,10 @@ def pixel2cam(depth: torch.Tensor, intrinsics_inv: torch.Tensor, pixel_coords: tSee the Convention block on :class:`~kornia.geometry.camera.pinhole.PinholeCamera`.Convention:- - ``intrinsics_inv`` is a :math:`(B, 4, 4)` inverse calibration matrix (the+ - ``intrinsics_inv`` is a ``(B, 4, 4)`` inverse calibration matrix (the:class:`~kornia.geometry.camera.pinhole.PinholeCamera` layout, not a ``3x3`` ``K``), and ``depth`` isthe camera-frame ``z`` at each pixel of the ``(u, v, 1)`` grid.- - a ``depth`` that is not ``Bx1xHxW``, an ``intrinsics_inv`` that is not :math:`(B, 4, 4)` or a+ - a ``depth`` that is not ``Bx1xHxW``, an ``intrinsics_inv`` that is not ``(B, 4, 4)`` or a``pixel_coords`` that is not ``BxHxWx3`` raises :class:`ValueError`; that ``pixel_coords`` matchesthe ``H`` and ``W`` of ``depth`` is not checked.@@ -669,7 +669,7 @@ def cam2pixel(cam_coords_src: torch.Tensor, dst_proj_src: torch.Tensor, eps: floSee the Convention block on :class:`~kornia.geometry.camera.pinhole.PinholeCamera`.Convention:- - ``dst_proj_src`` is a :math:`(B, 4, 4)` projection matrix (the+ - ``dst_proj_src`` is a ``(B, 4, 4)`` projection matrix (the:class:`~kornia.geometry.camera.pinhole.PinholeCamera` layout, not a ``3x3`` ``K``), and the result is``(u, v)`` pixel coordinates in the destination frame.diff --git a/kornia/geometry/camera/stereo.py b/kornia/geometry/camera/stereo.pyindex 541e954f6..24d927226 100644--- a/kornia/geometry/camera/stereo.py+++ b/kornia/geometry/camera/stereo.py@@ -55,7 +55,7 @@ class StereoCamera:Convention:- the two arguments are the **rectified projection matrices** of the left and the right camera, each of- shape :math:`(B, 3, 4)`: ``[[fx, 0, cx, 0], [0, fy, cy, 0], [0, 0, 1, 0]]`` for the left camera, and+ shape ``(B, 3, 4)``: ``[[fx, 0, cx, 0], [0, fy, cy, 0], [0, 0, 1, 0]]`` for the left camera, andthe same matrix with ``-tx * fx`` in the last column for the right one. The constructor requires thetwo to be equal outside that last column.- the baseline is read back as the attribute :attr:`tx` ``= -P_right[0, 3] / fx``, which must be@@ -67,8 +67,8 @@ class StereoCamera:- ``Q[0, 0]`` carries ``fy`` and ``Q[1, 1]`` carries ``fx``; with the divide by ``W = -fy * disparity``the result is ``X = (u - cx) Z / fx``, ``Y = (v - cy) Z / fy``, ``Z = fx * tx / disparity``.- ``u`` is the **column** index and ``v`` the **row** index, as in ``cv2.reprojectImageTo3D``.- - a disparity map is channels-**last**, :math:`(B, H, W, 1)` (a :math:`(B, 1, H, W)` map is rejected),- and the point cloud is :math:`(B, H, W, 3)`.+ - a disparity map is channels-**last**, ``(B, H, W, 1)`` (a ``(B, 1, H, W)`` map is rejected),+ and the point cloud is ``(B, H, W, 3)``.- pixel centres are integers; see the Convention block on:class:`~kornia.geometry.camera.pinhole.PinholeCamera`.@@ -81,8 +81,8 @@ class StereoCamera:reconstruction failures without changing those coordinates or their gradients.Args:- rectified_left_camera: The rectified left camera projection matrix of shape :math:`(B, 3, 4)`.- rectified_right_camera: The rectified right camera projection matrix of shape :math:`(B, 3, 4)`.+ rectified_left_camera: The rectified left camera projection matrix of shape ``(B, 3, 4)``.+ rectified_right_camera: The rectified right camera projection matrix of shape ``(B, 3, 4)``."""def __init__(self, rectified_left_camera: torch.Tensor, rectified_right_camera: torch.Tensor) -> None:@@ -90,9 +90,9 @@ class StereoCamera:Args:rectified_left_camera: The rectified left camera projection matrix- of shape :math:`(B, 3, 4)`+ of shape ``(B, 3, 4)``rectified_right_camera: The rectified right camera projection matrix- of shape :math:`(B, 3, 4)`+ of shape ``(B, 3, 4)``"""self._check_stereo_camera(rectified_left_camera, rectified_right_camera)@@ -110,9 +110,9 @@ class StereoCamera:Args:rectified_left_camera: The rectified left camera projection matrix- of shape :math:`(B, 3, 4)`+ of shape ``(B, 3, 4)``rectified_right_camera: The rectified right camera projection matrix- of shape :math:`(B, 3, 4)`+ of shape ``(B, 3, 4)``"""# Ensure correct shapes@@ -201,7 +201,7 @@ class StereoCamera:camera are assumed to be equal.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return self.rectified_left_camera[..., 0, 0]@@ -214,7 +214,7 @@ class StereoCamera:camera are assumed to be equal.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return self.rectified_left_camera[..., 1, 1]@@ -224,7 +224,7 @@ class StereoCamera:r"""Return the x-coordinate of the principal point for the left camera.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return self.rectified_left_camera[..., 0, 2]@@ -234,7 +234,7 @@ class StereoCamera:r"""Return the x-coordinate of the principal point for the right camera.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return self.rectified_right_camera[..., 0, 2]@@ -247,7 +247,7 @@ class StereoCamera:is assumed to be equal for the left and right camera.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return self.rectified_left_camera[..., 1, 2]@@ -257,7 +257,7 @@ class StereoCamera:r"""The horizontal baseline between the two cameras.Returns:- torch.Tensor of shape :math:`(B)`+ torch.Tensor of shape ``(B)``"""return -self.rectified_right_camera[..., 0, 3] / self.fx@@ -271,7 +271,7 @@ class StereoCamera:lengths in the x and y direction.Return:- The Q matrix of shape :math:`(B, 4, 4)`.+ The Q matrix of shape ``(B, 4, 4)``."""return self._Q_matrix@@ -280,7 +280,7 @@ class StereoCamera:r"""Initialize the Q matrix of the horizontal stereo setup. See the Q property.Returns:- The Q matrix of shape :math:`(B, 4, 4)`.+ The Q matrix of shape ``(B, 4, 4)``."""Q = torch.zeros((self.batch_size, 4, 4), device=self.device, dtype=self.dtype)@@ -317,14 +317,14 @@ class StereoCamera:See the Convention block on :class:`~kornia.geometry.camera.stereo.StereoCamera`.Args:- disparity_tensor: Disparity torch.Tensor of shape :math:`(B, H, W, 1)`.+ disparity_tensor: Disparity torch.Tensor of shape ``(B, H, W, 1)``.return_mask: If True, also return numerical reconstruction validity with- shape :math:`(B, H, W, 1)`. This only adds diagnostics; it does not fill+ shape ``(B, H, W, 1)``. This only adds diagnostics; it does not fillinvalid points or change their gradients. See the module-level:func:`reproject_disparity_to_3D` for the mask's complete contract.Returns:- The 3D point cloud of shape :math:`(B, H, W, 3)`, in the left rectified+ The 3D point cloud of shape ``(B, H, W, 3)``, in the left rectifiedcamera frame, or ``(points, valid)`` when ``return_mask=True``."""@@ -335,7 +335,7 @@ def _check_disparity_tensor(disparity_tensor: torch.Tensor) -> None:r"""Ensure correct user provided correct disparity torch.Tensor.Args:- disparity_tensor: The disparity torch.Tensor of shape :math:`(B, H, W, 1)`.+ disparity_tensor: The disparity torch.Tensor of shape ``(B, H, W, 1)``."""if not isinstance(disparity_tensor, torch.Tensor):@@ -364,7 +364,7 @@ def _check_Q_matrix(Q_matrix: torch.Tensor) -> None:r"""Ensure Q matrix is of correct form.Args:- Q_matrix: The Q matrix for reprojecting disparity to a point cloud of shape :math:`(B, 4, 4)`+ Q_matrix: The Q matrix for reprojecting disparity to a point cloud of shape ``(B, 4, 4)``"""if not isinstance(Q_matrix, torch.Tensor):@@ -409,13 +409,13 @@ def reproject_disparity_to_3D(See the Convention block on :class:`~kornia.geometry.camera.stereo.StereoCamera`.Args:- disparity_tensor: Disparity torch.Tensor of shape :math:`(B, H, W, 1)`.- Q_matrix: torch.Tensor of Q matrices of shape :math:`(B, 4, 4)` or :math:`(1, 4, 4)`.+ disparity_tensor: Disparity torch.Tensor of shape ``(B, H, W, 1)``.+ Q_matrix: torch.Tensor of Q matrices of shape ``(B, 4, 4)`` or ``(1, 4, 4)``.return_mask: If True, also return a boolean numerical reconstruction mask of- shape :math:`(B, H, W, 1)`, on the input device. Defaults to False.+ shape ``(B, H, W, 1)``, on the input device. Defaults to False.Returns:- The 3D point cloud of shape :math:`(B, H, W, 3)`, or ``(points, valid)`` when+ The 3D point cloud of shape ``(B, H, W, 3)``, or ``(points, valid)`` when``return_mask=True``. Points retain the disparity dtype in either mode.Raises:diff --git a/kornia/geometry/conversions.py b/kornia/geometry/conversions.pyindex 869c8b387..57f588ee3 100644--- a/kornia/geometry/conversions.py+++ b/kornia/geometry/conversions.py@@ -227,7 +227,7 @@ def convert_points_from_homogeneous(points: torch.Tensor, eps: float = 1e-8) ->Convention:- the **last** component of the last dimension is the homogeneouscoordinate ``w`` and is dropped from the output- - requires rank :math:`\geq 2`: a bare :math:`(D,)` point raises+ - requires rank :math:`\geq 2`: a bare ``(D,)`` point raises``ValueError``- when ``abs(w) > eps`` the remaining components are divided by exactly``w``, with its sign kept (``[[2., 4., -2.]]`` gives ``[[-1., -2.]]``)@@ -239,12 +239,12 @@ def convert_points_from_homogeneous(points: torch.Tensor, eps: float = 1e-8) ->working dtypeArgs:- points: the points to be transformed of shape :math:`(*, N, D)`.+ points: the points to be transformed of shape ``(*, N, D)``.eps: threshold on ``abs(w)`` below which the point is returnedunchanged instead of divided, to avoid division by zero.Returns:- the points in Euclidean space :math:`(*, N, D-1)`.+ the points in Euclidean space ``(*, N, D-1)``.Examples:>>> input = torch.tensor([[0., 0., 1.]])@@ -279,15 +279,15 @@ def convert_points_to_homogeneous(points: torch.Tensor) -> torch.Tensor:dimension, which is where:func:`~kornia.geometry.conversions.convert_points_from_homogeneous`expects it- - requires rank :math:`\geq 2`: a bare :math:`(D,)` point raises+ - requires rank :math:`\geq 2`: a bare ``(D,)`` point raises``ValueError``- the input dtype is preserved, integer dtypes includedArgs:- points: the points to be transformed with shape :math:`(*, N, D)`.+ points: the points to be transformed with shape ``(*, N, D)``.Returns:- the points in homogeneous coordinates :math:`(*, N, D+1)`.+ the points in homogeneous coordinates ``(*, N, D+1)``.Examples:>>> input = torch.tensor([[0., 0.]])@@ -318,13 +318,13 @@ def convert_affinematrix_to_homography(A: torch.Tensor) -> torch.Tensor:- appends the row ``[0, 0, 1]`` at the bottom and copies the:math:`2 \times 3` block verbatim; the input tensor is not modified- the rank is enforced to be exactly 3, so batching is **mandatory**: an- unbatched :math:`(2, 3)` matrix raises ``ValueError``+ unbatched ``(2, 3)`` matrix raises ``ValueError``Args:- A: the affine matrix with shape :math:`(B,2,3)`.+ A: the affine matrix with shape ``(B,2,3)``.Returns:- the homography matrix with shape of :math:`(B,3,3)`.+ the homography matrix with shape of ``(B,3,3)``.Examples:>>> A = torch.tensor([[[1., 0., 0.],@@ -350,14 +350,14 @@ def convert_affinematrix_to_homography3d(A: torch.Tensor) -> torch.Tensor:Convention:- same as:func:`~kornia.geometry.conversions.convert_affinematrix_to_homography`,- except that ``A`` is :math:`(B, 3, 4)` and the appended bottom row is+ except that ``A`` is ``(B, 3, 4)`` and the appended bottom row is``[0, 0, 0, 1]``Args:- A: the affine matrix with shape :math:`(B,3,4)`.+ A: the affine matrix with shape ``(B,3,4)``.Returns:- the homography matrix with shape of :math:`(B,4,4)`.+ the homography matrix with shape of ``(B,4,4)``.Examples:>>> A = torch.tensor([[[1., 0., 0., 0.],@@ -383,8 +383,8 @@ def axis_angle_to_rotation_matrix(axis_angle: torch.Tensor) -> torch.Tensor:r"""Convert 3d vector of axis-angle rotation to 3x3 rotation matrix.Convention:- - any number of leading batch dimensions is accepted: :math:`(3,)`- gives :math:`(3, 3)` and :math:`(2, 5, 3)` gives :math:`(2, 5, 3, 3)`+ - any number of leading batch dimensions is accepted: ``(3,)``+ gives ``(3, 3)`` and ``(2, 5, 3)`` gives ``(2, 5, 3, 3)``- the input is the rotation axis scaled by the angle, in **radians**:``[[0., 0., pi/2]]`` is a quarter turn about ``+z``,while ``[[0., 0., 90.]]`` is 90 *radians* about ``+z`` and returns a@@ -406,10 +406,10 @@ def axis_angle_to_rotation_matrix(axis_angle: torch.Tensor) -> torch.Tensor:moves no forward bitArgs:- axis_angle: tensor of 3d vector of axis-angle rotations in radians with shape :math:`(*, 3)`.+ axis_angle: tensor of 3d vector of axis-angle rotations in radians with shape ``(*, 3)``.Returns:- tensor of rotation matrices of shape :math:`(*, 3, 3)`.+ tensor of rotation matrices of shape ``(*, 3, 3)``.Example:>>> input = torch.tensor([[0., 0., 0.]])@@ -517,12 +517,12 @@ def rotation_matrix_to_axis_angle(rotation_matrix: torch.Tensor, check_rotation:r"""Convert 3x3 rotation matrix to Rodrigues vector in radians.Convention:- - any number of leading batch dimensions is accepted: :math:`(3, 3)`- gives :math:`(3,)` and :math:`(2, 5, 3, 3)` gives :math:`(2, 5, 3)`+ - any number of leading batch dimensions is accepted: ``(3, 3)``+ gives ``(3,)`` and ``(2, 5, 3, 3)`` gives ``(2, 5, 3)``- the output is the rotation axis scaled by the angle in **radians**,the parametrization:func:`~kornia.geometry.conversions.axis_angle_to_rotation_matrix`- consumes, at every rank: the :math:`(3,)` and :math:`(2, 5, 3)`+ consumes, at every rank: the ``(3,)`` and ``(2, 5, 3)``results above can be fed straight back- the round trip through:func:`~kornia.geometry.conversions.axis_angle_to_rotation_matrix`@@ -542,14 +542,14 @@ def rotation_matrix_to_axis_angle(rotation_matrix: torch.Tensor, check_rotation:``check_rotation=True`` to raise a ``ValueError`` instead.Args:- rotation_matrix: rotation matrix of shape :math:`(*, 3, 3)`.+ rotation_matrix: rotation matrix of shape ``(*, 3, 3)``.check_rotation: if ``True``, raise ``ValueError`` unless every inputis a rotation: ``max|R @ R^T - I|`` within 100 eps of the dtype of``rotation_matrix`` (16 eps for float16 and bfloat16) and``det(R) > 0``. Defaults to ``False`` (unchecked).Returns:- Rodrigues vector transformation of shape :math:`(*, 3)`.+ Rodrigues vector transformation of shape ``(*, 3)``.Example:>>> input = torch.tensor([[1., 0., 0.],@@ -606,7 +606,7 @@ def rotation_matrix_to_quaternion(Pass ``check_rotation=True`` to reject such an input insteadArgs:- rotation_matrix: the rotation matrix to convert with shape :math:`(*, 3, 3)`.+ rotation_matrix: the rotation matrix to convert with shape ``(*, 3, 3)``.eps: floor on each square-root radicand. It is never added to theradicand: a radicand above ``eps`` is used as is, and one at orbelow it (for example the negative radicand of a discarded branch@@ -620,7 +620,7 @@ def rotation_matrix_to_quaternion(``det(R) > 0``. Defaults to ``False`` (unchecked).Return:- the rotation in quaternion with shape :math:`(*, 4)`.+ the rotation in quaternion with shape ``(*, 4)``.Example:>>> input = torch.tensor([[1., 0., 0.],@@ -725,11 +725,11 @@ def normalize_quaternion(quaternion: torch.Tensor, eps: float = 1.0e-12) -> torcArgs:quaternion: a tensor containing a quaternion to be normalized.- The tensor can be of shape :math:`(*, 4)`.+ The tensor can be of shape ``(*, 4)``.eps: floor on the norm used as the divisor; see the Convention above.Return:- the normalized quaternion of shape :math:`(*, 4)`.+ the normalized quaternion of shape ``(*, 4)``.Example:>>> quaternion = torch.tensor((1., 0., 1., 0.))@@ -786,7 +786,7 @@ def quaternion_to_rotation_matrix(quaternion: torch.Tensor) -> torch.Tensor:Convention:- the quaternion is ``(w, x, y, z)``, **real part first**, shape- :math:`(*, 4)` in and :math:`(*, 3, 3)` out. ``[1., 0., 0., 0.]``+ ``(*, 4)`` in and ``(*, 3, 3)`` out. ``[1., 0., 0., 0.]``gives the identity and ``[0., 0., 0., 1.]`` gives``[[-1., 0., 0.], [0., -1., 0.], [0., 0., 1.]]``, a half turn about``+z`` β so a caller passing ``(x, y, z, w)`` gets a valid-looking@@ -813,10 +813,10 @@ def quaternion_to_rotation_matrix(quaternion: torch.Tensor) -> torch.Tensor:Args:quaternion: a tensor containing a quaternion to be converted.- The tensor can be of shape :math:`(*, 4)`.+ The tensor can be of shape ``(*, 4)``.Return:- the rotation matrix of shape :math:`(*, 3, 3)`.+ the rotation matrix of shape ``(*, 3, 3)``.Example:>>> quaternion = torch.tensor((0., 0., 0., 1.))@@ -914,8 +914,8 @@ def quaternion_to_axis_angle(quaternion: torch.Tensor) -> torch.Tensor:tensor with axis angle of rotation.Shape:- - Input: :math:`(*, 4)` where `*` means, any number of dimensions- - Output: :math:`(*, 3)`+ - Input: ``(*, 4)`` where `*` means, any number of dimensions+ - Output: ``(*, 3)``Example:>>> quaternion = torch.tensor((1., 0., 0., 0.))@@ -1005,8 +1005,8 @@ def quaternion_log_to_exp(quaternion: torch.Tensor, eps: float = 1.0e-8) -> torcr"""Apply exponential map to log quaternion.Convention:- - the **input** is a 3-vector of shape :math:`(*, 3)`, not a- quaternion; the **output** is the quaternion of shape :math:`(*, 4)`+ - the **input** is a 3-vector of shape ``(*, 3)``, not a+ quaternion; the **output** is the quaternion of shape ``(*, 4)``in ``(w, x, y, z)`` order (see:func:`~kornia.geometry.conversions.quaternion_to_rotation_matrix`)- the map is ``w = cos(||v||)`` with vector part@@ -1030,11 +1030,11 @@ def quaternion_log_to_exp(quaternion: torch.Tensor, eps: float = 1.0e-8) -> torchalf of the same rotationArgs:- quaternion: the log quaternion, a tensor of shape :math:`(*, 3)`.+ quaternion: the log quaternion, a tensor of shape ``(*, 3)``.eps: a small number for clamping.Return:- the quaternion exponential map of shape :math:`(*, 4)`.+ the quaternion exponential map of shape ``(*, 4)``.Example:>>> quaternion = torch.tensor((0., 0., 0.))@@ -1077,9 +1077,9 @@ def quaternion_exp_to_log(quaternion: torch.Tensor, eps: float = 1.0e-8) -> torcThe quaternion should be in (w, x, y, z) format.Convention:- - the input is the quaternion of shape :math:`(*, 4)` in+ - the input is the quaternion of shape ``(*, 4)`` in``(w, x, y, z)`` order and the output is a 3-vector of shape- :math:`(*, 3)`, the argument+ ``(*, 3)``, the argument:func:`~kornia.geometry.conversions.quaternion_log_to_exp` takes- for a **unit** ``q`` on the ``w >= 0`` half of the double cover theresult is ``quaternion_to_axis_angle(q) / 2``. On the ``w < 0`` half the two@@ -1102,11 +1102,11 @@ def quaternion_exp_to_log(quaternion: torch.Tensor, eps: float = 1.0e-8) -> torcArgs:quaternion: a tensor containing a quaternion to be converted.- The tensor can be of shape :math:`(*, 4)`.+ The tensor can be of shape ``(*, 4)``.eps: a small number for clamping.Return:- the quaternion log map of shape :math:`(*, 3)`.+ the quaternion log map of shape ``(*, 3)``.Example:>>> quaternion = torch.tensor((1., 0., 0., 0.))@@ -1156,8 +1156,8 @@ def axis_angle_to_quaternion(axis_angle: torch.Tensor) -> torch.Tensor:Convention:- the input is the rotation axis scaled by the angle in **radians**,- shape :math:`(*, 3)`; the output is ``(w, x, y, z)`` with- ``w = cos(theta / 2)``, shape :math:`(*, 4)` (see+ shape ``(*, 3)``; the output is ``(w, x, y, z)`` with+ ``w = cos(theta / 2)``, shape ``(*, 4)`` (see:func:`~kornia.geometry.conversions.quaternion_to_rotation_matrix`for the layout)- nothing is canonicalised, so ``theta > pi`` returns the ``w < 0`` half@@ -1183,8 +1183,8 @@ def axis_angle_to_quaternion(axis_angle: torch.Tensor) -> torch.Tensor:tensor with quaternion.Shape:- - Input: :math:`(*, 3)` where `*` means, any number of dimensions- - Output: :math:`(*, 4)`+ - Input: ``(*, 3)`` where `*` means, any number of dimensions+ - Output: ``(*, 4)``Example:>>> axis_angle = torch.tensor((0., 1., 0.))@@ -1245,7 +1245,7 @@ def euler_from_quaternion(Convention:- the four quaternion coefficients are passed as **separate** tensors in- ``(w, x, y, z)`` order, not as one :math:`(*, 4)` tensor, and their+ ``(w, x, y, z)`` order, not as one ``(*, 4)`` tensor, and theirshapes must be exactly equal: broadcastable shapes such as ``(2,)``and ``(1,)`` raise ``BaseError``- the return is a tuple of three tensors ``(roll, pitch, yaw)`` in@@ -1383,7 +1383,7 @@ def quaternion_from_euler(- the three arguments must have exactly equal shapes; broadcastableshapes such as ``(2,)`` and ``(1,)`` raise ``BaseError``- the return is a tuple of **four separate tensors** ``(w, x, y, z)``,- not a :math:`(*, 4)` tensor: ``(0.3, 0.7, 1.1)`` gives+ not a ``(*, 4)`` tensor: ``(0.3, 0.7, 1.1)`` gives``[0.8186, -0.0575, 0.3624, 0.4418]``Args:@@ -1430,7 +1430,7 @@ def normalize_pixel_coordinates(See :doc:`Conventions & Pitfalls </get-started/conventions>` for the library-wide pixel-centre,normalized-coordinate and ``align_corners`` conventions.- - ``pixel_coordinates`` is :math:`(*, 2)` in ``(x, y)`` order: ``x``+ - ``pixel_coordinates`` is ``(*, 2)`` in ``(x, y)`` order: ``x``indexes columns and is scaled by ``width``, ``y`` indexes rows and isscaled by ``height``. The positional argument order is the other wayround β ``(pixel_coordinates, height, width)``@@ -1463,13 +1463,13 @@ def normalize_pixel_coordinates(will be removed in a future breaking release.Args:- pixel_coordinates: the grid with pixel coordinates. Shape can be :math:`(*, 2)`.+ pixel_coordinates: the grid with pixel coordinates. Shape can be ``(*, 2)``.height: the maximum height in the y-axis.width: the maximum width in the x-axis.eps: deprecated compatibility parameter. It is ignored.Return:- the normalized pixel coordinates with shape :math:`(*, 2)`.+ the normalized pixel coordinates with shape ``(*, 2)``.Examples:>>> coords = torch.tensor([[50., 100.]])@@ -1541,13 +1541,13 @@ def denormalize_pixel_coordinates(the deprecated ``eps`` parameter follow the normalization functionArgs:- pixel_coordinates: the normalized grid coordinates. Shape can be :math:`(*, 2)`.+ pixel_coordinates: the normalized grid coordinates. Shape can be ``(*, 2)``.height: the maximum height in the y-axis.width: the maximum width in the x-axis.eps: deprecated compatibility parameter. It is ignored.Return:- the denormalized pixel coordinates with shape :math:`(*, 2)`.+ the denormalized pixel coordinates with shape ``(*, 2)``.Examples:>>> coords = torch.tensor([[-1., -1.]])@@ -1605,7 +1605,7 @@ def normalize_pixel_coordinates3d(r"""Map 3d pixel coordinates so that the first and last sample of each axis become -1 and 1.Convention:- - ``pixel_coordinates`` is :math:`(*, 3)` in ``(d, x, y)`` order β+ - ``pixel_coordinates`` is ``(*, 3)`` in ``(d, x, y)`` order β**depth first, then x, then y**, *not* ``(x, y, z)``. This is theorder :func:`~kornia.geometry.grid.create_meshgrid3d` produces. Thethree components are scaled by ``depth - 1``, ``width - 1`` and@@ -1619,7 +1619,7 @@ def normalize_pixel_coordinates3d(the deprecated ``eps`` parameter likewise follow that functionArgs:- pixel_coordinates: the grid with pixel coordinates. Shape can be :math:`(*, 3)`.+ pixel_coordinates: the grid with pixel coordinates. Shape can be ``(*, 3)``.depth: the maximum depth in the z-axis.height: the maximum height in the y-axis.width: the maximum width in the x-axis.@@ -1703,7 +1703,7 @@ def denormalize_pixel_coordinates3d(the deprecated ``eps`` parameter follow the 2-D counterpartArgs:- pixel_coordinates: the normalized grid coordinates. Shape can be :math:`(*, 3)`.+ pixel_coordinates: the normalized grid coordinates. Shape can be ``(*, 3)``.depth: the maximum depth in the z-axis.height: the maximum height in the y-axis.width: the maximum width in the x-axis.@@ -1771,8 +1771,8 @@ def angle_to_rotation_matrix(angle: torch.Tensor) -> torch.Tensor:r"""Create a rotation matrix out of angles in degrees.Convention:- - ``angle`` is in **degrees**, shape :math:`(*)` in and- :math:`(*, 2, 2)` out+ - ``angle`` is in **degrees**, shape ``(*)`` in and+ ``(*, 2, 2)`` out- the matrix is ``[[cos, sin], [-sin, cos]]`` with ``det = +1``; for``angle = 30`` it is ``[[0.8660, 0.5000], [-0.5000, 0.8660]]``- applied on the left to a column vector ``(x, y)``, ``angle = 30`` maps@@ -1783,10 +1783,10 @@ def angle_to_rotation_matrix(angle: torch.Tensor) -> torch.Tensor:spells out the modulo-:math:`2\pi` relation between the two opsArgs:- angle: tensor of angles in degrees, any shape :math:`(*)`.+ angle: tensor of angles in degrees, any shape ``(*)``.Returns:- tensor of rotation matrices with shape :math:`(*, 2, 2)`.+ tensor of rotation matrices with shape ``(*, 2, 2)``.Example:>>> input = torch.rand(1, 3) # Nx3@@ -1818,7 +1818,7 @@ def normalize_homography(the reverse ``inv(N_dst) @ H @ N_src``- both ``dsize`` arguments are ``(height, width)``, while the matrix actson ``(x, y, 1)`` column vectors- - a :math:`(3, 3)` or :math:`(B, 3, 3)` matrix is accepted and batching is+ - a ``(3, 3)`` or ``(B, 3, 3)`` matrix is accepted and batching isper sample; an unbatched input is returned as ``(1, 3, 3)``, and anyother shape raises ``ValueError``- in eager mode ``inv(N_src)`` is a closed-form adjugate built from@@ -1854,8 +1854,8 @@ def normalize_homography(Args:dst_pix_trans_src_pix: homography/ies from source to destination to be- normalized. :math:`(B, 3, 3)`, or an unbatched :math:`(3, 3)`, which- is promoted to :math:`(1, 3, 3)`+ normalized. ``(B, 3, 3)``, or an unbatched ``(3, 3)``, which+ is promoted to ``(1, 3, 3)``dsize_src: size of the source image (height, width).dsize_dst: size of the destination image (height, width).align_corners: which :py:func:`torch.nn.functional.grid_sample` convention the@@ -1865,7 +1865,7 @@ def normalize_homography(picks up a spurious sub-pixel scale and shift.Returns:- the normalized homography of shape :math:`(B, 3, 3)`.+ the normalized homography of shape ``(B, 3, 3)``."""if not isinstance(dst_pix_trans_src_pix, torch.Tensor):@@ -1919,7 +1919,7 @@ def normal_transform_pixel(r"""Compute the (1, 3, 3) matrix that maps 2D pixel coordinates (x, y) to [-1, 1], corner-aligned by default.Convention:- - the result is a **single** matrix of shape :math:`(1, 3, 3)` β never+ - the result is a **single** matrix of shape ``(1, 3, 3)`` β neverbatched β acting on homogeneous ``(x, y, 1)`` column vectors, with``x`` indexing columns and scaled by ``width`` and ``y`` indexing rowsand scaled by ``height``. The positional argument order is the other@@ -1979,7 +1979,7 @@ def normal_transform_pixel(*edges*.Returns:- normalized transform with shape :math:`(1, 3, 3)`.+ normalized transform with shape ``(1, 3, 3)``.Example:>>> normal_transform_pixel(4, 5)@@ -2116,7 +2116,7 @@ def normal_transform_pixel3d(parameter, so it applies that scaling unconditionally.Singleton axes use the same invertible centre mapping, and zero ornegative sizes raise ``ValueError``. Only the lines below differ- - the result has shape :math:`(1, 4, 4)` and acts on homogeneous+ - the result has shape ``(1, 4, 4)`` and acts on homogeneous``(x, y, z, 1)`` column vectors with ``x`` scaled by ``width``, ``y``by ``height`` and ``z`` by ``depth``, while the positional argumentorder is ``(depth, height, width)``: ``normal_transform_pixel3d(9, 5, 3)``@@ -2149,7 +2149,7 @@ def normal_transform_pixel3d(dtype: dtype of the result. ``None`` means ``torch.get_default_dtype()``.Returns:- normalized transform with shape :math:`(1, 4, 4)`.+ normalized transform with shape ``(1, 4, 4)``.Example:>>> normal_transform_pixel3d(2, 4, 5)@@ -2277,8 +2277,8 @@ def denormalize_homography(Args:dst_pix_trans_src_pix: homography/ies from source to destination to be- denormalized. :math:`(B, 3, 3)`, or an unbatched :math:`(3, 3)`,- which is promoted to :math:`(1, 3, 3)`+ denormalized. ``(B, 3, 3)``, or an unbatched ``(3, 3)``,+ which is promoted to ``(1, 3, 3)``dsize_src: size of the source image (height, width).dsize_dst: size of the destination image (height, width).align_corners: which :py:func:`torch.nn.functional.grid_sample` convention the@@ -2286,7 +2286,7 @@ def denormalize_homography(them, so that this function inverts :func:`normalize_homography`.Returns:- the denormalized homography of shape :math:`(B, 3, 3)`.+ the denormalized homography of shape ``(B, 3, 3)``."""if not isinstance(dst_pix_trans_src_pix, torch.Tensor):@@ -2352,19 +2352,19 @@ def normalize_homography3d(``cuda``, and a ``float32`` upcast for ``float16``/``bfloat16``),where the 2-D function uses a closed-form adjugate, with the same``float32`` upcast; the 2-D and 3-D routes therefore need not agree bitwise- - the matrices are :math:`(B, 4, 4)` and act on ``(x, y, z, 1)`` column+ - the matrices are ``(B, 4, 4)`` and act on ``(x, y, z, 1)`` columnvectors, while both ``dsize`` arguments are``(depth, height, width)`` triples- :func:`~kornia.geometry.conversions.denormalize_homography3d`computes the reverse ``inv(N_dst) @ H @ N_src``- - the shape guard is the 2-D function's for 4x4 matrices: :math:`(4, 4)`- (returned as ``(1, 4, 4)``) or :math:`(B, 4, 4)`, anything else raises+ - the shape guard is the 2-D function's for 4x4 matrices: ``(4, 4)``+ (returned as ``(1, 4, 4)``) or ``(B, 4, 4)``, anything else raises``ValueError``Args:dst_pix_trans_src_pix: homography/ies from source to destination to be- normalized. :math:`(B, 4, 4)`, or an unbatched :math:`(4, 4)`, which- is promoted to :math:`(1, 4, 4)`+ normalized. ``(B, 4, 4)``, or an unbatched ``(4, 4)``, which+ is promoted to ``(1, 4, 4)``dsize_src: size of the source image (depth, height, width).dsize_dst: size of the destination image (depth, height, width).@@ -2372,7 +2372,7 @@ def normalize_homography3d(the normalized homography.Shape:- Output: :math:`(B, 4, 4)`+ Output: ``(B, 4, 4)``"""if not isinstance(dst_pix_trans_src_pix, torch.Tensor):@@ -2439,8 +2439,8 @@ def denormalize_homography3d(Args:dst_pix_trans_src_pix: homography/ies from source to destination to be- denormalized. :math:`(B, 4, 4)`, or an unbatched :math:`(4, 4)`, which- is promoted to :math:`(1, 4, 4)`+ denormalized. ``(B, 4, 4)``, or an unbatched ``(4, 4)``, which+ is promoted to ``(1, 4, 4)``dsize_src: size of the source image (depth, height, width).dsize_dst: size of the destination image (depth, height, width).@@ -2448,7 +2448,7 @@ def denormalize_homography3d(the denormalized homography.Shape:- Output: :math:`(B, 4, 4)`+ Output: ``(B, 4, 4)``"""if not isinstance(dst_pix_trans_src_pix, torch.Tensor):@@ -2497,8 +2497,8 @@ def normalize_points_with_intrinsics(point_2d: torch.Tensor, camera_matrix: torcSee :doc:`camera and world conventions </get-started/camera-conventions>` for the camera intrinsics andpixel-centre conventions used by these coordinates.- - ``point_2d`` is :math:`(*, 2)` in pixel ``(u, v)`` order and- ``camera_matrix`` is a row-major pinhole :math:`(*, 3, 3)` with+ - ``point_2d`` is ``(*, 2)`` in pixel ``(u, v)`` order and+ ``camera_matrix`` is a row-major pinhole ``(*, 3, 3)`` with``fx = K[0, 0]``, ``fy = K[1, 1]``, ``cx = K[0, 2]``, ``cy = K[1, 2]``- the output is the calibrated camera coordinate``x = (u - cx) / fx``, ``y = (v - cy) / fy``: with@@ -2512,11 +2512,11 @@ def normalize_points_with_intrinsics(point_2d: torch.Tensor, camera_matrix: torcArgs:point_2d: tensor containing the 2d points in the image pixel coordinates. The shape of the tensor can be- :math:`(*, 2)`.- camera_matrix: tensor containing the intrinsics camera matrix. The tensor shape must be :math:`(*, 3, 3)`.+ ``(*, 2)``.+ camera_matrix: tensor containing the intrinsics camera matrix. The tensor shape must be ``(*, 3, 3)``.Returns:- tensor of normalized camera coordinates :math:`(x, y)` with shape :math:`(*, 2)`.+ tensor of normalized camera coordinates :math:`(x, y)` with shape ``(*, 2)``.Example:>>> _ = torch.manual_seed(0)@@ -2555,11 +2555,11 @@ def denormalize_points_with_intrinsics(point_2d_norm: torch.Tensor, camera_matriArgs:point_2d_norm: tensor containing the 2d points in normalized camera coordinates. The shape of the tensor can- be :math:`(*, 2)`.- camera_matrix: tensor containing the intrinsics camera matrix. The tensor shape must be :math:`(*, 3, 3)`.+ be ``(*, 2)``.+ camera_matrix: tensor containing the intrinsics camera matrix. The tensor shape must be ``(*, 3, 3)``.Returns:- tensor of :math:`(u, v)` pixel coordinates with shape :math:`(*, 2)`.+ tensor of :math:`(u, v)` pixel coordinates with shape ``(*, 2)``.Example:>>> _ = torch.manual_seed(0)@@ -2599,7 +2599,7 @@ def Rt_to_matrix4x4(R: torch.Tensor, t: torch.Tensor) -> torch.Tensor:world-to-camera form's ``-R^T t`` is a translation and not a centre.Which of the two you are packing is your bookkeeping, not thisfunction's- - shapes are strict: exactly :math:`(B, 3, 3)` and :math:`(B, 3, 1)`.+ - shapes are strict: exactly ``(B, 3, 3)`` and ``(B, 3, 1)``.An unbatched ``(3, 3)``, a ``(B, 3)`` translation, a ``(B, 1, 3)``translation and extra leading dimensions each raise ``ShapeError``;``R`` and ``t`` must also carry the same batch size: a mismatched@@ -2617,11 +2617,11 @@ def Rt_to_matrix4x4(R: torch.Tensor, t: torch.Tensor) -> torch.Tensor:negate and multiply, so they accept integer input as well.Args:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Returns:- the extrinsics :math:`(B, 4, 4)`.+ the extrinsics ``(B, 4, 4)``.Example:>>> R, t = torch.eye(3)[None], torch.ones(3).reshape(1, 3, 1)@@ -2650,7 +2650,7 @@ def matrix4x4_to_Rt(extrinsics: torch.Tensor) -> tuple[torch.Tensor, torch.Tensolayout β ``R`` is the top-left 3x3 block and ``t`` the first threerows of the last column β and the same frame-agnosticism. Only thelines below differ- - the input shape is strictly :math:`(B, 4, 4)`; an unbatched ``(4, 4)``,+ - the input shape is strictly ``(B, 4, 4)``; an unbatched ``(4, 4)``,a ``(B, 3, 3)`` and extra leading dimensions each raise ``ShapeError``- the **bottom row is ignored**: a projective 4x4 is silently truncatedto its rigid part, so replacing the bottom row with ``[9, 9, 9, 9]``@@ -2662,11 +2662,11 @@ def matrix4x4_to_Rt(extrinsics: torch.Tensor) -> tuple[torch.Tensor, torch.TensoClone before mutating either outputArgs:- extrinsics: pose matrix :math:`(B, 4, 4)`.+ extrinsics: pose matrix ``(B, 4, 4)``.Returns:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Example:>>> ext = torch.eye(4)[None]@@ -2712,7 +2712,7 @@ def camtoworld_graphics_to_vision_4x4(extrinsics_graphics: torch.Tensor) -> torcSee :doc:`camera and world conventions </get-started/camera-conventions>` for the graphics/vision cameraframes and camera-to-world extrinsics convention.- - the input is a **camera-to-world** pose :math:`(B, 4, 4)`: its 3x3+ - the input is a **camera-to-world** pose ``(B, 4, 4)``: its 3x3block maps camera axes into the world and its last column is thecamera centre in world coordinates- the operation is exactly ``extrinsics @ diag(1, -1, -1, 1)`` β a@@ -2737,8 +2737,8 @@ def camtoworld_graphics_to_vision_4x4(extrinsics_graphics: torch.Tensor) -> torcreturns the same matrix as this one on the same input, and applyingeither twice returns the input. The two names document the caller'sintent, not different arithmetic- - the shape is strictly :math:`(B, 4, 4)`; the ``_Rt`` variants take and- return :math:`(B, 3, 3)` and :math:`(B, 3, 1)` and agree with this+ - the shape is strictly ``(B, 4, 4)``; the ``_Rt`` variants take and+ return ``(B, 3, 3)`` and ``(B, 3, 1)`` and agree with thispath bitwise.. warning::@@ -2750,10 +2750,10 @@ def camtoworld_graphics_to_vision_4x4(extrinsics_graphics: torch.Tensor) -> torc:func:`~kornia.geometry.conversions.Rt_to_matrix4x4`.Args:- extrinsics_graphics: pose matrix :math:`(B, 4, 4)`.+ extrinsics_graphics: pose matrix ``(B, 4, 4)``.Returns:- extrinsics: pose matrix :math:`(B, 4, 4)`.+ extrinsics: pose matrix ``(B, 4, 4)``.Example:>>> ext = torch.eye(4)[None]@@ -2790,19 +2790,19 @@ def camtoworld_graphics_to_vision_Rt(R: torch.Tensor, t: torch.Tensor) -> tuple[:func:`~kornia.geometry.conversions.Rt_to_matrix4x4`, applies thatfunction and splits the result again, so the two paths agree bitwise.Only the lines below differ- - the shapes are strictly :math:`(B, 3, 3)` and :math:`(B, 3, 1)` in and+ - the shapes are strictly ``(B, 3, 3)`` and ``(B, 3, 1)`` in andout, with the same-batch-size rule and the integer-input ``ValueError`` of:func:`~kornia.geometry.conversions.Rt_to_matrix4x4`- ``t`` is returned unchanged; only ``R`` has its second and thirdcolumns negatedArgs:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Returns:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Example:>>> R, t = torch.eye(3)[None], torch.ones(3).reshape(1, 3, 1)@@ -2839,14 +2839,14 @@ def camtoworld_vision_to_graphics_4x4(extrinsics_vision: torch.Tensor) -> torch.records which direction the caller means- everything else β the right multiplication, the untouched translationcolumn, the two frame definitions, the preserved determinant, the- strict :math:`(B, 4, 4)` shape and the integer-dtype warning β is as+ strict ``(B, 4, 4)`` shape and the integer-dtype warning β is asdocumented thereArgs:- extrinsics_vision: pose matrix :math:`(B, 4, 4)`.+ extrinsics_vision: pose matrix ``(B, 4, 4)``.Returns:- extrinsics: pose matrix :math:`(B, 4, 4)`.+ extrinsics: pose matrix ``(B, 4, 4)``.Example:>>> ext = torch.eye(4)[None]@@ -2887,12 +2887,12 @@ def camtoworld_vision_to_graphics_Rt(R: torch.Tensor, t: torch.Tensor) -> tuple[graphics-to-vision ``_Rt`` formArgs:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Returns:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.Example:>>> R, t = torch.eye(3)[None], torch.ones(3).reshape(1, 3, 1)@@ -2980,7 +2980,7 @@ def camtoworld_to_worldtocam_Rt(- :func:`~kornia.geometry.conversions.worldtocam_to_camtoworld_Rt` isthe **same function** under the other name: applying either one twicereturns ``R`` exactly and ``t`` to rounding- - the shapes are :math:`(B, 3, 3)` and :math:`(B, 3, 1)`, and ``R`` and ``t``+ - the shapes are ``(B, 3, 3)`` and ``(B, 3, 1)``, and ``R`` and ``t``must carry the same batch size: a mismatched pair raises ``ShapeError``- an ``R`` and ``t`` of one integer dtype (``uint8``, ``int8``, ``int16``,``int32`` or ``int64``) are accepted on every device, CUDA (which has@@ -2996,16 +2996,16 @@ def camtoworld_to_worldtocam_Rt((``det(R) < 0``).Args:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.check_rotation: if ``True``, raise ``ValueError`` unless every ``R``is a rotation: ``max|R @ R^T - I|`` within 100 eps of the dtype of``R`` (16 eps for float16 and bfloat16) and ``det(R) > 0``.Defaults to ``False`` (unchecked).Returns:- Rinv: Rotation matrix, :math:`(B, 3, 3).`- tinv: Translation matrix :math:`(B, 3, 1)`.+ Rinv: Rotation matrix, ``(B, 3, 3)``.+ tinv: Translation matrix ``(B, 3, 1)``.Example:>>> R, t = torch.eye(3)[None], torch.ones(3).reshape(1, 3, 1)@@ -3050,16 +3050,16 @@ def worldtocam_to_camtoworld_Rt(- the shapes and the rotation warning are as documented thereArgs:- R: Rotation matrix, :math:`(B, 3, 3).`- t: Translation matrix :math:`(B, 3, 1)`.+ R: Rotation matrix, ``(B, 3, 3)``.+ t: Translation matrix ``(B, 3, 1)``.check_rotation: if ``True``, raise ``ValueError`` unless every ``R``is a rotation: ``max|R @ R^T - I|`` within 100 eps of the dtype of``R`` (16 eps for float16 and bfloat16) and ``det(R) > 0``.Defaults to ``False`` (unchecked).Returns:- Rinv: Rotation matrix, :math:`(B, 3, 3).`- tinv: Translation matrix :math:`(B, 3, 1)`.+ Rinv: Rotation matrix, ``(B, 3, 3)``.+ tinv: Translation matrix ``(B, 3, 1)``.Example:>>> R, t = torch.eye(3)[None], torch.ones(3).reshape(1, 3, 1)@@ -3093,8 +3093,8 @@ def ARKitQTVecs_to_ColmapQTVecs(qvec: torch.Tensor, tvec: torch.Tensor) -> tupleSee :doc:`camera and world conventions </get-started/camera-conventions>` for the camera frames andextrinsics conventions composed by this conversion.- - **input**: ``qvec`` :math:`(B, 4)` in ``(w, x, y, z)`` order β- ``[1., 0., 0., 0.]`` is the identity β and ``tvec`` :math:`(B, 3, 1)`,+ - **input**: ``qvec`` ``(B, 4)`` in ``(w, x, y, z)`` order β+ ``[1., 0., 0., 0.]`` is the identity β and ``tvec`` ``(B, 3, 1)``,read as a **camera-to-world** pose in the **graphics** frame (``+y``up, ``-z`` forward), so ``tvec`` is the camera centre in worldcoordinates@@ -3130,12 +3130,12 @@ def ARKitQTVecs_to_ColmapQTVecs(qvec: torch.Tensor, tvec: torch.Tensor) -> tupleidentity inputArgs:- qvec: ARKit rotation quaternion :math:`(B, 4)`, [w, x, y, z] format.- tvec: translation vector :math:`(B, 3, 1)`, [x, y, z]+ qvec: ARKit rotation quaternion ``(B, 4)``, [w, x, y, z] format.+ tvec: translation vector ``(B, 3, 1)``, [x, y, z]Returns:- qvec: Colmap rotation quaternion :math:`(B, 4)`, [w, x, y, z] format.- tvec: translation vector :math:`(B, 3, 1)`, [x, y, z]+ qvec: Colmap rotation quaternion ``(B, 4)``, [w, x, y, z] format.+ tvec: translation vector ``(B, 3, 1)``, [x, y, z]Example:>>> q, t = torch.tensor([0, 1, 0, 1.])[None], torch.ones(3).reshape(1, 3, 1)@@ -3167,8 +3167,8 @@ def ColmapQTVecs_to_ARKitQTVecs(qvec: torch.Tensor, tvec: torch.Tensor) -> tuple- the reverse of:func:`~kornia.geometry.conversions.ARKitQTVecs_to_ColmapQTVecs`,with the same layouts and the frames exchanged- - **input**: ``qvec`` :math:`(B, 4)` in ``(w, x, y, z)`` order β- ``[1., 0., 0., 0.]`` is the identity β and ``tvec`` :math:`(B, 3, 1)`,+ - **input**: ``qvec`` ``(B, 4)`` in ``(w, x, y, z)`` order β+ ``[1., 0., 0., 0.]`` is the identity β and ``tvec`` ``(B, 3, 1)``,read as a **world-to-camera** pose in the **vision** frame (``+y``down, ``+z`` forward) β Colmap's ``images.txt````QW QX QY QZ TX TY TZ``@@ -3203,12 +3203,12 @@ def ColmapQTVecs_to_ARKitQTVecs(qvec: torch.Tensor, tvec: torch.Tensor) -> tupleidentity inputArgs:- qvec: Colmap rotation quaternion :math:`(B, 4)`, [w, x, y, z] format.- tvec: translation vector :math:`(B, 3, 1)`, [x, y, z]+ qvec: Colmap rotation quaternion ``(B, 4)``, [w, x, y, z] format.+ tvec: translation vector ``(B, 3, 1)``, [x, y, z]Returns:- qvec: ARKit rotation quaternion :math:`(B, 4)`, [w, x, y, z] format.- tvec: translation vector :math:`(B, 3, 1)`, [x, y, z]+ qvec: ARKit rotation quaternion ``(B, 4)``, [w, x, y, z] format.+ tvec: translation vector ``(B, 3, 1)``, [x, y, z]Example:>>> q, t = torch.tensor([0, 1, 0, 1.])[None], torch.ones(3).reshape(1, 3, 1)@@ -3246,14 +3246,14 @@ def vector_to_skew_symmetric_matrix(vec: torch.Tensor) -> torch.Tensor:``vector_to_skew_symmetric_matrix(v) @ x`` equals ``cross(v, x)``, notits negation β for ``v = (1., 2., 3.)`` and ``x = (4., 5., 6.)`` bothare ``(-3., 6., -3.)``- - accepts :math:`(3,)` or :math:`(B, 3)` only; any higher rank raises+ - accepts ``(3,)`` or ``(B, 3)`` only; any higher rank raises``ValueError``Args:- vec: tensor of shape :math:`(3,)` or :math:`(B, 3)`.+ vec: tensor of shape ``(3,)`` or ``(B, 3)``.Returns:- tensor of shape :math:`(3, 3)` or :math:`(B, 3, 3)` respectively.+ tensor of shape ``(3, 3)`` or ``(B, 3, 3)`` respectively.Example:>>> vec = torch.tensor([1.0, 2.0, 3.0])diff --git a/kornia/geometry/epipolar/_metrics.py b/kornia/geometry/epipolar/_metrics.pyindex c8b9a5cc2..8035219ef 100644--- a/kornia/geometry/epipolar/_metrics.py+++ b/kornia/geometry/epipolar/_metrics.py@@ -36,11 +36,11 @@ def _sampson_epipolar_distance_manual_impl_(pts1: Tensor, pts2: Tensor, Fm: Tensconverted automatically.pts2: correspondences from the right images with shape :math:`(*, N, (2|3))`. If they are not homogeneous,converted automatically.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to avoid ambiguity with torch.nn.functional.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm to avoid ambiguity with torch.nn.functional.squared: if True (default), the squared distance is returned.Returns:- the computed Sampson distance with shape :math:`(*, N)`.+ the computed Sampson distance with shape ``(*, N)``."""if not isinstance(Fm, Tensor):@@ -96,11 +96,11 @@ def _sampson_epipolar_distance_matmul_impl_(pts1: Tensor, pts2: Tensor, Fm: Tensconverted automatically.pts2: correspondences from the right images with shape :math:`(*, N, (2|3))`. If they are not homogeneous,converted automatically.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to avoid ambiguity with torch.nn.functional.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm to avoid ambiguity with torch.nn.functional.squared: if True (default), the squared distance is returned.Returns:- the computed Sampson distance with shape :math:`(*, N)`.+ the computed Sampson distance with shape ``(*, N)``."""if pts1.shape[-1] == 2:@@ -241,9 +241,9 @@ def sampson_epipolar_distance(degenerate ``Fm``, is at distance ``inf``.Args:- pts1: points in the first image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- pts2: points in the second image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to avoid ambiguity with torch.nn.functional.+ pts1: points in the first image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ pts2: points in the second image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm to avoid ambiguity with torch.nn.functional.squared: if True (default), the squared distance is returned, else its square root.eps: unused; it was added to the denominator and inside the square root, which made the value depend on thescale of ``Fm`` and an exact match score :math:`\sqrt{\epsilon}` (#4881). The singular case is guarded@@ -252,7 +252,7 @@ def sampson_epipolar_distance(use the matmul implementation.Returns:- the computed Sampson distance with shape :math:`(*, N)`.+ the computed Sampson distance with shape ``(*, N)``."""# Checked here because the CUDA matmul and shared-point implementations do not check Fm. A single (3, 3) Fm@@ -354,14 +354,14 @@ def symmetrical_epipolar_distance(either image is at distance ``inf``.Args:- pts1: points in the first image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- pts2: points in the second image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to avoid ambiguity with torch.nn.functional.+ pts1: points in the first image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ pts2: points in the second image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm to avoid ambiguity with torch.nn.functional.squared: if True (default), the squared distance is returned, else its square root.eps: unused, as in :func:`sampson_epipolar_distance` (#4881).Returns:- the computed Symmetrical distance with shape :math:`(*, N)`.+ the computed Symmetrical distance with shape ``(*, N)``."""# Checked here because the CUDA matmul implementation does not check Fm.@@ -384,13 +384,13 @@ def left_to_right_epipolar_distance(pts1: Tensor, pts2: Tensor, Fm: Tensor) -> Tdistance ``inf``, as in :func:`~kornia.geometry.linalg.point_line_distance`.Args:- pts1: points in the first image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- pts2: points in the second image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to+ pts1: points in the first image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ pts2: points in the second image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm toavoid ambiguity with torch.nn.functional.Returns:- the one-sided distance with shape :math:`(*, N)`.+ the one-sided distance with shape ``(*, N)``."""KORNIA_CHECK_IS_TENSOR(pts1)@@ -419,13 +419,13 @@ def right_to_left_epipolar_distance(pts1: Tensor, pts2: Tensor, Fm: Tensor) -> Tdistance ``inf``, as in :func:`~kornia.geometry.linalg.point_line_distance`.Args:- pts1: points in the first image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- pts2: points in the second image with shape :math:`(*, N, 2)` or :math:`(*, N, 3)`.- Fm: Fundamental matrices with shape :math:`(*, 3, 3)`. Called Fm to+ pts1: points in the first image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ pts2: points in the second image with shape ``(*, N, 2)`` or ``(*, N, 3)``.+ Fm: Fundamental matrices with shape ``(*, 3, 3)``. Called Fm toavoid ambiguity with torch.nn.functional.Returns:- the one-sided distance with shape :math:`(*, N)`.+ the one-sided distance with shape ``(*, N)``."""KORNIA_CHECK_IS_TENSOR(pts1)diff --git a/kornia/geometry/epipolar/essential.py b/kornia/geometry/epipolar/essential.pyindex aa8bb003d..e3bf537c4 100644--- a/kornia/geometry/epipolar/essential.py+++ b/kornia/geometry/epipolar/essential.py@@ -58,7 +58,7 @@ def run_5point(points1: torch.Tensor, points2: torch.Tensor, weights: Optional[tspace of an exact five-point sample unchanged; for larger sets they can affect the least-squares fit.Returns:- the computed essential matrix with shape :math:`(B, 10, 3, 3)`.+ the computed essential matrix with shape ``(B, 10, 3, 3)``."""KORNIA_CHECK_SHAPE(points1, ["B", "N", "2"])@@ -469,12 +469,12 @@ def essential_from_fundamental(F_mat: torch.Tensor, K1: torch.Tensor, K2: torch.:math:`x_2^\top E x_1 = 0` order of :func:`find_essential`; it keeps the scale of ``F_mat``.Args:- F_mat: The fundamental matrix with shape of :math:`(*, 3, 3)`.- K1: The camera matrix from first camera with shape :math:`(*, 3, 3)`.- K2: The camera matrix from second camera with shape :math:`(*, 3, 3)`.+ F_mat: The fundamental matrix with shape of ``(*, 3, 3)``.+ K1: The camera matrix from first camera with shape ``(*, 3, 3)``.+ K2: The camera matrix from second camera with shape ``(*, 3, 3)``.Returns:- The essential matrix with shape :math:`(*, 3, 3)`.+ The essential matrix with shape ``(*, 3, 3)``."""KORNIA_CHECK_SHAPE(F_mat, ["*", "3", "3"])@@ -497,11 +497,11 @@ def project_to_essential(E_mat: torch.Tensor) -> torch.Tensor:- A caller's autocast region does not change the result, outside TorchScript.Args:- E_mat: The matrices to project with shape :math:`(*, 3, 3)`.+ E_mat: The matrices to project with shape ``(*, 3, 3)``.Returns:The closest matrices (in Frobenius norm) satisfying the essential-matrix constraint,- with shape :math:`(*, 3, 3)`.+ with shape ``(*, 3, 3)``."""KORNIA_CHECK_SHAPE(E_mat, ["*", "3", "3"])@@ -539,7 +539,7 @@ def decompose_essential_matrix(E_mat: torch.Tensor) -> Tuple[torch.Tensor, torchfloat32 rotations.Args:- E_mat: The essential matrix in the form of :math:`(*, 3, 3)`.+ E_mat: The essential matrix in the form of ``(*, 3, 3)``.Returns:A tuple containing the first and second possible rotation matrices and the translation vector,@@ -595,7 +595,7 @@ def decompose_essential_matrix_no_svd(E_mat: torch.Tensor) -> Tuple[torch.Tensor- A caller's autocast region does not change the result, outside TorchScript.Args:- E_mat: The essential matrix in the form of :math:`(*, 3, 3)`.+ E_mat: The essential matrix in the form of ``(*, 3, 3)``.Returns:A tuple containing the first and second possible rotation matrices and the translation vector, with@@ -674,13 +674,13 @@ def essential_from_Rt(R1: torch.Tensor, t1: torch.Tensor, R2: torch.Tensor, t2::math:`\|E\|_F = \sqrt{2} \|t\|`.Args:- R1: The first camera rotation matrix with shape :math:`(*, 3, 3)`.- t1: The first camera translation vector with shape :math:`(*, 3, 1)`.- R2: The second camera rotation matrix with shape :math:`(*, 3, 3)`.- t2: The second camera translation vector with shape :math:`(*, 3, 1)`.+ R1: The first camera rotation matrix with shape ``(*, 3, 3)``.+ t1: The first camera translation vector with shape ``(*, 3, 1)``.+ R2: The second camera rotation matrix with shape ``(*, 3, 3)``.+ t2: The second camera translation vector with shape ``(*, 3, 1)``.Returns:- The Essential matrix with the shape :math:`(*, 3, 3)`.+ The Essential matrix with the shape ``(*, 3, 3)``."""KORNIA_CHECK_SHAPE(R1, ["*", "3", "3"])@@ -709,7 +709,7 @@ def motion_from_essential(E_mat: torch.Tensor) -> Tuple[torch.Tensor, torch.Tens- A caller's autocast region does not change the result, as for :func:`decompose_essential_matrix`.Args:- E_mat: The essential matrix in the form of :math:`(*, 3, 3)`.+ E_mat: The essential matrix in the form of ``(*, 3, 3)``.Returns:The rotation and translation containing the four possible combination for the retrieved motion.@@ -754,16 +754,16 @@ def motion_from_essential_choose_solution(``E_mat``.Args:- E_mat: The essential matrix in the form of :math:`(B, 3, 3)`, or :math:`(3, 3)` with every other input+ E_mat: The essential matrix in the form of ``(B, 3, 3)``, or ``(3, 3)`` with every other inputunbatched too.- K1: The camera matrix from first camera with shape :math:`(B, 3, 3)`.- K2: The camera matrix from second camera with shape :math:`(B, 3, 3)`.- x1: The set of points in the first image with shape :math:`(B, N, 2)`.- x2: The set of points in the second image with shape :math:`(B, N, 2)`.+ K1: The camera matrix from first camera with shape ``(B, 3, 3)``.+ K2: The camera matrix from second camera with shape ``(B, 3, 3)``.+ x1: The set of points in the first image with shape ``(B, N, 2)``.+ x2: The set of points in the second image with shape ``(B, N, 2)``.mask: A boolean mask which can be used to exclude some points from choosingthe best solution. This is useful for using this function with sets of points ofdifferent cardinality (for instance after filtering with RANSAC) while keeping batch- semantics. Mask is of shape :math:`(B, N)`.+ semantics. Mask is of shape ``(B, N)``.Returns:The rotation, translation, 3d triangulated points, and the number of points@@ -870,10 +870,10 @@ def relative_camera_motion(:math:`E_2` returns :math:`E_1^{-1} E_2`.Args:- R1: The first camera rotation matrix with shape :math:`(*, 3, 3)`.- t1: The first camera translation vector with shape :math:`(*, 3, 1)`.- R2: The second camera rotation matrix with shape :math:`(*, 3, 3)`.- t2: The second camera translation vector with shape :math:`(*, 3, 1)`.+ R1: The first camera rotation matrix with shape ``(*, 3, 3)``.+ t1: The first camera translation vector with shape ``(*, 3, 1)``.+ R2: The second camera rotation matrix with shape ``(*, 3, 3)``.+ t2: The second camera translation vector with shape ``(*, 3, 1)``.Returns:A tuple with the relative rotation matrix and@@ -914,12 +914,12 @@ def find_essential(Args:points1: A set of points in the first image with a tensor shape :math:`(B, N, 2), N>=5`.points2: A set of points in the second image with a tensor shape :math:`(B, N, 2), N>=5`.- weights: Accepted with a shape of :math:`(B, N)` and ignored for compatibility, including for :math:`N > 5`.+ weights: Accepted with a shape of ``(B, N)`` and ignored for compatibility, including for :math:`N > 5`.Positive weights leave the null space of an exact five-point sample unchanged; for larger sets they canaffect the least-squares fit.Returns:- the computed essential matrices with shape :math:`(B, 10, 3, 3)`.+ the computed essential matrices with shape ``(B, 10, 3, 3)``.To choose the best one out of 10, try to check the one with the lowest Sampson distance, ignoring the``NaN`` slots.diff --git a/kornia/geometry/epipolar/fundamental.py b/kornia/geometry/epipolar/fundamental.pyindex 18becc538..aaa6502d3 100644--- a/kornia/geometry/epipolar/fundamental.py+++ b/kornia/geometry/epipolar/fundamental.py@@ -41,14 +41,14 @@ def normalize_points(the result as optimal.Args:- points: Tensor containing the points to be normalized with shape :math:`(B, N, 2)`.+ points: Tensor containing the points to be normalized with shape ``(B, N, 2)``.eps: epsilon value to avoid numerical instabilities.- weights: Optional nonnegative weights with shape :math:`(B, N)` for the centroid and mean radius.+ weights: Optional nonnegative weights with shape ``(B, N)`` for the centroid and mean radius.Zero-weight points do not influence the transform. An all-zero batch element uses unweighted statistics.Returns:- tuple containing the normalized points in the shape :math:`(B, N, 2)` and the transformation matrix- in the shape :math:`(B, 3, 3)` that maps the input points to them.+ tuple containing the normalized points in the shape ``(B, N, 2)`` and the transformation matrix+ in the shape ``(B, 3, 3)`` that maps the input points to them."""if points.ndim != 3:@@ -485,11 +485,11 @@ def run_7point(points1: torch.Tensor, points2: torch.Tensor) -> torch.Tensor:Reference: Hartley/Zisserman 11.1.2 pag.281Args:- points1: A set of 7 points in the first image with shape :math:`(B, 7, 2)`.- points2: A set of 7 points in the second image with shape :math:`(B, 7, 2)`.+ points1: A set of 7 points in the first image with shape ``(B, 7, 2)``.+ points2: A set of 7 points in the second image with shape ``(B, 7, 2)``.Returns:- The computed fundamental matrices with shape :math:`(B, 3, 3, 3)`, always 3 candidates per batch+ The computed fundamental matrices with shape ``(B, 3, 3, 3)``, always 3 candidates per batchelement. A cubic with a single real root gives one candidate followed by two zero matrices."""@@ -610,15 +610,15 @@ def find_fundamental(- A caller's autocast region does not change the fit.Args:- points1: A set of points in the first image with a tensor shape :math:`(B, N, 2)`: :math:`N \ge 8` for+ points1: A set of points in the first image with a tensor shape ``(B, N, 2)``: :math:`N \ge 8` for``"8POINT"``, exactly 7 for ``"7POINT"``.points2: A set of points in the second image with the shape of ``points1``.- weights: Tensor containing the weights per point correspondence with a shape of :math:`(B, N)`.+ weights: Tensor containing the weights per point correspondence with a shape of ``(B, N)``.method: The method to use for computing the fundamental matrix. Supported methods are "7POINT" and "8POINT".Returns:- the computed fundamental matrix with shape :math:`(B, 3, 3)` for ``"8POINT"`` and- :math:`(B, 3, 3, 3)` for ``"7POINT"``.+ the computed fundamental matrix with shape ``(B, 3, 3)`` for ``"8POINT"`` and+ ``(B, 3, 3, 3)`` for ``"7POINT"``.Raises:ValueError: If an invalid method is provided.@@ -641,11 +641,11 @@ def compute_correspond_epilines(points: torch.Tensor, F_mat: torch.Tensor) -> tofor second-image points pass ``F.transpose(-2, -1)``. Lines are scaled to :math:`a^2 + b^2 = 1`.Args:- points: tensor containing the set of points to project in the shape of :math:`(*, N, 2)` or :math:`(*, N, 3)`.- F_mat: the fundamental to use for projection the points in the shape of :math:`(*, 3, 3)`.+ points: tensor containing the set of points to project in the shape of ``(*, N, 2)`` or ``(*, N, 3)``.+ F_mat: the fundamental to use for projection the points in the shape of ``(*, 3, 3)``.Returns:- a tensor with shape :math:`(*, N, 3)` containing the epipolar lines :math:`F x` of the points.+ a tensor with shape ``(*, N, 3)`` containing the epipolar lines :math:`F x` of the points.Each line is described as:math:`ax + by + c = 0` and encoding the vectors as :math:`(a, b, c)`.@@ -677,11 +677,11 @@ def get_perpendicular(lines: torch.Tensor, points: torch.Tensor) -> torch.Tensorr"""Compute the perpendicular to a line, through the point.Args:- lines: tensor containing the set of lines :math:`(B, N, 3)`.- points: tensor containing the set of points :math:`(B, N, 2)`.+ lines: tensor containing the set of lines ``(B, N, 3)``.+ points: tensor containing the set of points ``(B, N, 2)``.Returns:- a tensor with shape :math:`(B, N, 3)` containing a vector of the epipolar+ a tensor with shape ``(B, N, 3)`` containing a vector of the epipolarperpendicular lines. Each line is described as:math:`ax + by + c = 0` and encoding the vectors as :math:`(a, b, c)`; the normal :math:`(a, b)` has thenorm of the input line's and is not rescaled.@@ -710,14 +710,14 @@ def get_closest_point_on_epipolar_line(pts1: torch.Tensor, pts2: torch.Tensor, Foutside TorchScript.Args:- pts1: points in the first image with shape :math:`(B, N, 2)` or :math:`(B, N, 3)`. If they are not+ pts1: points in the first image with shape ``(B, N, 2)`` or ``(B, N, 3)``. If they are nothomogeneous, converted automatically.- pts2: points in the second image with shape :math:`(B, N, 2)` or :math:`(B, N, 3)`. If they are not+ pts2: points in the second image with shape ``(B, N, 2)`` or ``(B, N, 3)``. If they are nothomogeneous, converted automatically.- Fm: Fundamental matrices with shape :math:`(B, 3, 3)`. Called Fm to avoid ambiguity with torch.nn.functional.+ Fm: Fundamental matrices with shape ``(B, 3, 3)``. Called Fm to avoid ambiguity with torch.nn.functional.Returns:- point on epipolar line :math:`(B, N, 2)`.+ point on epipolar line ``(B, N, 2)``."""if not isinstance(Fm, torch.Tensor):@@ -758,12 +758,12 @@ def fundamental_from_essential(E_mat: torch.Tensor, K1: torch.Tensor, K2: torch.``F[2, 2] = 1`` normalisation.Args:- E_mat: The essential matrix with shape of :math:`(*, 3, 3)`.- K1: The camera matrix from first camera with shape :math:`(*, 3, 3)`.- K2: The camera matrix from second camera with shape :math:`(*, 3, 3)`.+ E_mat: The essential matrix with shape of ``(*, 3, 3)``.+ K1: The camera matrix from first camera with shape ``(*, 3, 3)``.+ K2: The camera matrix from second camera with shape ``(*, 3, 3)``.Returns:- The fundamental matrix with shape :math:`(*, 3, 3)`.+ The fundamental matrix with shape ``(*, 3, 3)``."""KORNIA_CHECK_SHAPE(E_mat, ["*", "3", "3"])@@ -799,11 +799,11 @@ def fundamental_from_projections(P1: torch.Tensor, P2: torch.Tensor) -> torch.Tefloat32's exponent range and is cast back unnormalised.Args:- P1: The projection matrix from first camera with shape :math:`(*, 3, 4)`.- P2: The projection matrix from second camera with shape :math:`(*, 3, 4)`.+ P1: The projection matrix from first camera with shape ``(*, 3, 4)``.+ P2: The projection matrix from second camera with shape ``(*, 3, 4)``.Returns:- The fundamental matrix with shape :math:`(*, 3, 3)`.+ The fundamental matrix with shape ``(*, 3, 3)``."""KORNIA_CHECK_SHAPE(P1, ["*", "3", "4"])KORNIA_CHECK_SHAPE(P2, ["*", "3", "4"])diff --git a/kornia/geometry/epipolar/numeric.py b/kornia/geometry/epipolar/numeric.pyindex 788ad435c..fa652b6b8 100644--- a/kornia/geometry/epipolar/numeric.py+++ b/kornia/geometry/epipolar/numeric.py@@ -28,10 +28,10 @@ def cross_product_matrix(x: torch.Tensor) -> torch.Tensor::math:`[x]_\times w = x \times w`, for any number of leading dims.Args:- x: The input vector to construct the matrix in the shape :math:`(*, 3)`.+ x: The input vector to construct the matrix in the shape ``(*, 3)``.Returns:- The skew-symmetric matrix with shape :math:`(*, 3, 3)`.+ The skew-symmetric matrix with shape ``(*, 3, 3)``."""if not x.shape[-1] == 3:@@ -52,7 +52,7 @@ def matrix_cofactor_tensor(matrix: torch.Tensor) -> torch.Tensor:"""Cofactor matrix, refer to the numpy doc.Args:- matrix: The input matrix in the shape :math:`(*, 3, 3)`.+ matrix: The input matrix in the shape ``(*, 3, 3)``."""# Closed form: the rows of the cofactor matrix are the cross products of the other two rows. Unlike thediff --git a/kornia/geometry/epipolar/projection.py b/kornia/geometry/epipolar/projection.pyindex 0220711ad..bb50f87f5 100644--- a/kornia/geometry/epipolar/projection.py+++ b/kornia/geometry/epipolar/projection.py@@ -33,7 +33,7 @@ def intrinsics_like(focal: float, input: torch.Tensor) -> torch.Tensor:r"""Return a 3x3 intrinsics matrix per batch element of the input.Convention:- - ``fx = fy = focal`` and the principal point is ``(W / 2, H / 2)`` of the :math:`(B, C, H, W)` input;+ - ``fx = fy = focal`` and the principal point is ``(W / 2, H / 2)`` of the ``(B, C, H, W)`` input;dtype and device follow the input. ``focal`` must be positive and the input 4-D.- The input must be floating point, like kornia's images: an integer input raises by design rather thanreturning an integer ``K``.@@ -44,10 +44,10 @@ def intrinsics_like(focal: float, input: torch.Tensor) -> torch.Tensor:Args:focal: the focal length for the camera matrix.input: image tensor that will determine the batch size and image height- and width. It is assumed to be a floating-point tensor in the shape of :math:`(B, C, H, W)`.+ and width. It is assumed to be a floating-point tensor in the shape of ``(B, C, H, W)``.Returns:- The camera matrix with the shape of :math:`(B, 3, 3)`.+ The camera matrix with the shape of ``(B, 3, 3)``."""if len(input.shape) != 4:@@ -78,7 +78,7 @@ def random_intrinsics(low: Union[float, torch.Tensor], high: Union[float, torch.high: upper range (exclusive).Returns:- the random camera matrix with the shape of :math:`(1, 3, 3)`.+ the random camera matrix with the shape of ``(1, 3, 3)``."""sampler = torch.distributions.Uniform(low, high)@@ -102,12 +102,12 @@ def scale_intrinsics(camera_matrix: torch.Tensor, scale_factor: Union[float, torArgs:camera_matrix: the camera calibration matrix containing the intrinsic- parameters. The expected shape for the tensor is :math:`(B, 3, 3)`.- scale_factor: the scaling factor to be applied: a float, or a tensor of shape :math:`(B,)` that+ parameters. The expected shape for the tensor is ``(B, 3, 3)``.+ scale_factor: the scaling factor to be applied: a float, or a tensor of shape ``(B,)`` thatscales each batch element by its own factor.Returns:- The scaled camera matrix with the same shape as the input :math:`(B, 3, 3)`.+ The scaled camera matrix with the same shape as the input ``(B, 3, 3)``."""K_scale = camera_matrix.clone()@@ -131,12 +131,12 @@ def projection_from_KRt(K: torch.Tensor, R: torch.Tensor, t: torch.Tensor) -> to:func:`KRt_from_projection`, and :func:`depth_from_point` gives the depth of a point in this camera.Args:- K: the camera matrix with the intrinsics with shape :math:`(*, 3, 3)`.- R: The rotation matrix with shape :math:`(*, 3, 3)`.- t: The translation vector with shape :math:`(*, 3, 1)`.+ K: the camera matrix with the intrinsics with shape ``(*, 3, 3)``.+ R: The rotation matrix with shape ``(*, 3, 3)``.+ t: The translation vector with shape ``(*, 3, 1)``.Returns:- The projection matrix P with shape :math:`(*, 3, 4)`.+ The projection matrix P with shape ``(*, 3, 4)``."""KORNIA_CHECK_SHAPE(K, ["*", "3", "3"])@@ -170,14 +170,14 @@ def KRt_from_projection(P: torch.Tensor, eps: float = 1e-6) -> Tuple[torch.Tenso- A caller's autocast region does not change the result, outside TorchScript.Args:- P: the projection matrix with shape :math:`(B, 3, 4)`.+ P: the projection matrix with shape ``(B, 3, 4)``.eps: unused; kept for backward compatibility. The sign of the triangular factor's diagonal is takenexactly.Returns:- - The Camera matrix with shape :math:`(B, 3, 3)`.- - The Rotation matrix with shape :math:`(B, 3, 3)`.- - The Translation vector with shape :math:`(B, 3, 1)`.+ - The Camera matrix with shape ``(B, 3, 3)``.+ - The Rotation matrix with shape ``(B, 3, 3)``.+ - The Translation vector with shape ``(B, 3, 1)``."""KORNIA_CHECK_SHAPE(P, ["*", "3", "4"])@@ -229,12 +229,12 @@ def depth_from_point(R: torch.Tensor, t: torch.Tensor, X: torch.Tensor) -> torch``R`` is read as ``B`` points seen by every camera and gives ``(B, B)``, not one point per camera.Args:- R: The rotation matrix with shape :math:`(*, 3, 3)`.- t: The translation vector with shape :math:`(*, 3, 1)`.- X: The 3d points with shape :math:`(*, N, 3)`.+ R: The rotation matrix with shape ``(*, 3, 3)``.+ t: The translation vector with shape ``(*, 3, 1)``.+ X: The 3d points with shape ``(*, N, 3)``.Returns:- The depth value per point with shape :math:`(*, N)`.+ The depth value per point with shape ``(*, N)``."""X_tmp = R @ X.transpose(-2, -1)@@ -264,10 +264,10 @@ def projections_from_fundamental(F_mat: torch.Tensor) -> torch.Tensor:- ``F_mat`` must have exactly one batch dimension.Args:- F_mat: the fundamental matrix with the shape :math:`(B, 3, 3)`.+ F_mat: the fundamental matrix with the shape ``(B, 3, 3)``.Returns:- The projection matrices with shape :math:`(B, 3, 4, 2)`.+ The projection matrices with shape ``(B, 3, 4, 2)``."""KORNIA_CHECK_SHAPE(F_mat, ["*", "3", "3"])diff --git a/kornia/geometry/epipolar/scene.py b/kornia/geometry/epipolar/scene.pyindex 63898781c..8a99a4cd4 100644--- a/kornia/geometry/epipolar/scene.py+++ b/kornia/geometry/epipolar/scene.py@@ -42,12 +42,12 @@ def generate_scene(num_views: int, num_points: int) -> Dict[str, torch.Tensor]:Returns:A dictionary of tensors on torch's default device and in the default dtype:- - ``"K"``: the camera matrix shared by all views, with shape :math:`(1, 3, 3)`.- - ``"R"``: the rotation of each view, with shape :math:`(V, 3, 3)`.- - ``"t"``: the translation of each view, with shape :math:`(V, 3, 1)`.- - ``"P"``: the projection matrix :math:`K [R|t]` of each view, with shape :math:`(V, 3, 4)`.- - ``"points3d"``: the 3d points, in :math:`[0, 1)` per coordinate, with shape :math:`(1, N, 3)`.- - ``"points2d"``: the projection of ``points3d`` by each ``P``, with shape :math:`(V, N, 2)`.+ - ``"K"``: the camera matrix shared by all views, with shape ``(1, 3, 3)``.+ - ``"R"``: the rotation of each view, with shape ``(V, 3, 3)``.+ - ``"t"``: the translation of each view, with shape ``(V, 3, 1)``.+ - ``"P"``: the projection matrix :math:`K [R|t]` of each view, with shape ``(V, 3, 4)``.+ - ``"points3d"``: the 3d points, in :math:`[0, 1)` per coordinate, with shape ``(1, N, 3)``.+ - ``"points2d"``: the projection of ``points3d`` by each ``P``, with shape ``(V, N, 2)``."""# Generate the 3d pointsdiff --git a/kornia/geometry/epipolar/triangulation.py b/kornia/geometry/epipolar/triangulation.pyindex 07a075e12..8e00f794d 100644--- a/kornia/geometry/epipolar/triangulation.py+++ b/kornia/geometry/epipolar/triangulation.py@@ -130,12 +130,12 @@ def triangulate_points(- A caller's autocast region does not change the result.Args:- P1: The projection matrix for the first camera with shape :math:`(*, 3, 4)`.- P2: The projection matrix for the second camera with shape :math:`(*, 3, 4)`.+ P1: The projection matrix for the first camera with shape ``(*, 3, 4)``.+ P2: The projection matrix for the second camera with shape ``(*, 3, 4)``.points1: The set of points seen from the first camera, in the image coordinates of ``P1`` (pixels- for ``P1 = K [R | t]``), with shape :math:`(*, N, 2)`.+ for ``P1 = K [R | t]``), with shape ``(*, N, 2)``.points2: The set of points seen from the second camera, in the image coordinates of ``P2`` (pixels- for ``P2 = K [R | t]``), with shape :math:`(*, N, 2)`.+ for ``P2 = K [R | t]``), with shape ``(*, N, 2)``.solver: Back-end used to find the null vector of the :math:`4 \times 4` DLTconstraint matrix. One of:@@ -160,7 +160,7 @@ def triangulate_points(rank-deficient (zero baseline). Fastest option for large batches.Returns:- The reconstructed 3d points in the world frame with shape :math:`(*, N, 3)`.+ The reconstructed 3d points in the world frame with shape ``(*, N, 3)``.Example:>>> P1 = torch.eye(3, 4)[None] # 1x3x4diff --git a/kornia/geometry/grid.py b/kornia/geometry/grid.pyindex 05a2f4fc5..52d4f390e 100644--- a/kornia/geometry/grid.py+++ b/kornia/geometry/grid.py@@ -58,7 +58,7 @@ def create_meshgrid(outer pixel *edges*. Ignored when ``normalized_coordinates`` is ``False``.Return:- grid tensor with shape :math:`(1, H, W, 2)`.+ grid tensor with shape ``(1, H, W, 2)``.Example:>>> create_meshgrid(2, 2)@@ -178,7 +178,7 @@ def create_meshgrid3d(dtype: the data type of the generated grid.Return:- grid tensor with shape :math:`(1, D, H, W, 3)`.+ grid tensor with shape ``(1, D, H, W, 3)``."""# See ``create_meshgrid``: ``arange`` keeps eager and captured pixel ramps identical atdiff --git a/kornia/geometry/homography.py b/kornia/geometry/homography.pyindex 537c7ca2b..bce7b4ded 100644--- a/kornia/geometry/homography.py+++ b/kornia/geometry/homography.py@@ -72,14 +72,14 @@ def oneway_transfer_error((B, N, 2 or 3). If they are homogeneous, converted automatically.pts2: correspondences from the right images with shape(B, N, 2 or 3). If they are homogeneous, converted automatically.- H: Homographies with shape :math:`(B, 3, 3)`.+ H: Homographies with shape ``(B, 3, 3)``.squared: if True (default), the squared distance is returned.eps: unused; it was added to the projective denominator and inside the square root, which made the errordepend on the scale of ``H`` and an exact match score ``sqrt(eps)`` (#4881). The singular case isguarded exactly instead. Accepted so that existing calls keep working.Returns:- the computed distance with shape :math:`(B, N)`.+ the computed distance with shape ``(B, N)``."""KORNIA_CHECK_SHAPE(H, ["B", "3", "3"])@@ -147,12 +147,12 @@ def symmetric_transfer_error((B, N, 2 or 3). If they are homogeneous, converted automatically.pts2: correspondences from the right images with shape(B, N, 2 or 3). If they are homogeneous, converted automatically.- H: Homographies with shape :math:`(B, 3, 3)`.+ H: Homographies with shape ``(B, 3, 3)``.squared: if True (default), the squared distance is returned.eps: unused, as in :func:`oneway_transfer_error` (#4881).Returns:- the computed distance with shape :math:`(B, N)`. Rows whose homography is not invertible+ the computed distance with shape ``(B, N)``. Rows whose homography is not invertiblescore ``max_num``, i.e. ``torch.finfo(pts1.dtype).max``, for both values of ``squared``."""@@ -209,14 +209,14 @@ def sampson_homography_distance(all integers.Args:- pts1: points in the first image with shape :math:`(B, N, 2)`, or homogeneous :math:`(B, N, 3)`.- pts2: points in the second image with shape :math:`(B, N, 2)`, or homogeneous :math:`(B, N, 3)`.- H: homographies with shape :math:`(B, 3, 3)`. Points with a leading dimension of 1 are scored against every+ pts1: points in the first image with shape ``(B, N, 2)``, or homogeneous ``(B, N, 3)``.+ pts2: points in the second image with shape ``(B, N, 2)``, or homogeneous ``(B, N, 3)``.+ H: homographies with shape ``(B, 3, 3)``. Points with a leading dimension of 1 are scored against everyhomography.squared: if True (default), the squared distance is returned, else the distance.Returns:- the computed distance with shape :math:`(B, N)`.+ the computed distance with shape ``(B, N)``."""KORNIA_CHECK_SHAPE(H, ["B", "3", "3"])@@ -282,11 +282,11 @@ def line_segment_transfer_error_one_way((B, N, 2, 2).ls2: line segment correspondences from the right images with shape(B, N, 2, 2).- H: Homographies with shape :math:`(B, 3, 3)`.+ H: Homographies with shape ``(B, 3, 3)``.squared: if True (default is False), the squared error is returned.Returns:- the computed error with shape :math:`(B, N)`.+ the computed error with shape ``(B, N)``."""KORNIA_CHECK_SHAPE(H, ["B", "3", "3"])@@ -518,15 +518,15 @@ def find_homography_dlt(- A caller's autocast region does not change the fit.Args:- points1: A set of points in the first image with a tensor shape :math:`(B, N, 2)`.- points2: A set of points in the second image with a tensor shape :math:`(B, N, 2)`.- weights: Tensor containing the weights per point correspondence with a shape of :math:`(B, N)`.+ points1: A set of points in the first image with a tensor shape ``(B, N, 2)``.+ points2: A set of points in the second image with a tensor shape ``(B, N, 2)``.+ weights: Tensor containing the weights per point correspondence with a shape of ``(B, N)``.Zero-weight points are excluded from the DLT equations and Hartley normalization.solver: variants: svd, lu.Returns:- the computed homography matrix with shape :math:`(B, 3, 3)`. A batch element whose weighted DLT system is+ the computed homography matrix with shape ``(B, 3, 3)``. A batch element whose weighted DLT system isnot finite, because a weight or a point is not finite (zero-weight points included) or an entry overflows,is NaN for both solvers and on every device; the other elements are unaffected. If the SVD of``solver="svd"`` fails to converge on a finite system, the whole batch is NaN and a ``RuntimeWarning`` is@@ -730,15 +730,15 @@ def find_homography_dlt_iterated(standard deviation in pixels: a correspondence with ``e = soft_inl_th`` keeps weight ``exp(-1/2)``.Args:- points1: A set of points in the first image with a tensor shape :math:`(B, N, 2)`.- points2: A set of points in the second image with a tensor shape :math:`(B, N, 2)`.- weights: Tensor containing the weights per point correspondence with a shape of :math:`(B, N)`.+ points1: A set of points in the first image with a tensor shape ``(B, N, 2)``.+ points2: A set of points in the second image with a tensor shape ``(B, N, 2)``.+ weights: Tensor containing the weights per point correspondence with a shape of ``(B, N)``.Used for the first iteration of the IRWLS.soft_inl_th: standard deviation, in pixels, of the Gaussian re-weighting kernel given above.n_iter: number of solves, including the initial one.Returns:- the computed homography matrix with shape :math:`(B, 3, 3)`, NaN for a batch element as in+ the computed homography matrix with shape ``(B, 3, 3)``, NaN for a batch element as in:func:`find_homography_dlt`."""@@ -773,13 +773,13 @@ def sample_is_valid_for_homography(points1: torch.Tensor, points2: torch.Tensor)through a repeated point, counts as kept, so collinearity alone does not reject a sample.Args:- points1: A set of points in the first image with a tensor shape :math:`(B, N, 2)`; only the first four+ points1: A set of points in the first image with a tensor shape ``(B, N, 2)``; only the first fourpoints are used.- points2: A set of points in the second image with a tensor shape :math:`(B, N, 2)`; only the first four+ points2: A set of points in the second image with a tensor shape ``(B, N, 2)``; only the first fourpoints are used.Returns:- Mask with the minimal sample is good for homography estimation :math:`(B)`.+ Mask with the minimal sample is good for homography estimation ``(B)``."""if points1.shape != points2.shape:@@ -825,15 +825,15 @@ def find_homography_lines_dlt(- A caller's autocast region does not change the fit.Args:- ls1: A set of line segments in the first image with a tensor shape :math:`(B, N, 2, 2)`, or- :math:`(N, 2, 2)`, which is treated as :math:`B = 1`. ``N`` must be at least 4.- ls2: A set of line segments in the second image with a tensor shape :math:`(B, N, 2, 2)`, or- :math:`(N, 2, 2)`, which is treated as :math:`B = 1`.- weights: Tensor containing the weights per segment with a shape of :math:`(B, N)`.+ ls1: A set of line segments in the first image with a tensor shape ``(B, N, 2, 2)``, or+ ``(N, 2, 2)``, which is treated as :math:`B = 1`. ``N`` must be at least 4.+ ls2: A set of line segments in the second image with a tensor shape ``(B, N, 2, 2)``, or+ ``(N, 2, 2)``, which is treated as :math:`B = 1`.+ weights: Tensor containing the weights per segment with a shape of ``(B, N)``.Zero-weight segments are excluded from Hartley normalization.Returns:- the computed homography matrix with shape :math:`(B, 3, 3)`. A batch element whose weighted DLT system is+ the computed homography matrix with shape ``(B, 3, 3)``. A batch element whose weighted DLT system isnot finite, because a weight or an endpoint is not finite (zero-weight segments included) or an entryoverflows, is NaN on every device; the other elements are unaffected. If the SVD fails to converge on afinite system, the whole batch is NaN and a ``RuntimeWarning`` is issued.@@ -920,18 +920,18 @@ def find_homography_lines_dlt_iterated(the image-2 line. A zero-length image-2 segment gets weight zero.Args:- ls1: A set of line segments in the first image with a tensor shape :math:`(B, N, 2, 2)`, or- :math:`(N, 2, 2)`, which is treated as :math:`B = 1`, as in :func:`find_homography_lines_dlt`.- ls2: A set of line segments in the second image with a tensor shape :math:`(B, N, 2, 2)`, or- :math:`(N, 2, 2)`, which is treated as :math:`B = 1`.- weights: Tensor containing the weights per segment with a shape of :math:`(B, N)`.+ ls1: A set of line segments in the first image with a tensor shape ``(B, N, 2, 2)``, or+ ``(N, 2, 2)``, which is treated as :math:`B = 1`, as in :func:`find_homography_lines_dlt`.+ ls2: A set of line segments in the second image with a tensor shape ``(B, N, 2, 2)``, or+ ``(N, 2, 2)``, which is treated as :math:`B = 1`.+ weights: Tensor containing the weights per segment with a shape of ``(B, N)``.Used for the first iteration of the IRWLS.soft_inl_th: standard deviation, in pixels, of the Gaussian re-weighting kernel of:func:`find_homography_dlt_iterated`.n_iter: number of solves, including the initial one.Returns:- the computed homography matrix with shape :math:`(B, 3, 3)`. A batch element is NaN when one of its+ the computed homography matrix with shape ``(B, 3, 3)``. A batch element is NaN when one of itssolves is, as in :func:`find_homography_lines_dlt`. In float16, segments with coordinates in the hundredsof pixels overflow the re-weighting distances of :func:`line_segment_transfer_error_one_way` and give NaNthis way.diff --git a/kornia/geometry/keypoints.py b/kornia/geometry/keypoints.pyindex bcaa1602a..f6e7b894e 100644--- a/kornia/geometry/keypoints.py+++ b/kornia/geometry/keypoints.py@@ -35,10 +35,10 @@ def _merge_keypoint_list(keypoints: List[torch.torch.Tensor]) -> torch.torch.Tenclass Keypoints:- r"""2D keypoints, stored as an :math:`(N, 2)` or :math:`(B, N, 2)` tensor of ``(x, y)`` points.+ r"""2D keypoints, stored as an ``(N, 2)`` or ``(B, N, 2)`` tensor of ``(x, y)`` points.Args:- keypoints: tensor of :math:`(N, 2)` or :math:`(B, N, 2)` coordinates. A list of tensors is not implemented+ keypoints: tensor of ``(N, 2)`` or ``(B, N, 2)`` coordinates. A list of tensors is not implemented(see Known defects).raise_if_not_floating_point: ``True`` raises ``ValueError`` for a non-floating-point tensor, ``False`` castsit to ``float32``, or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.@@ -97,8 +97,8 @@ class Keypoints:"""Return the tensor shape used to store 2D keypoints.Returns:- Shape of :attr:`data`. The common layouts are :math:`(N, 2)` for- unbatched keypoints and :math:`(B, N, 2)` for batched keypoints,+ Shape of :attr:`data`. The common layouts are ``(N, 2)`` for+ unbatched keypoints and ``(B, N, 2)`` for batched keypoints,where :math:`B` is the batch size, :math:`N` is the number ofkeypoints, and the final dimension stores ``(x, y)`` coordinates."""@@ -181,11 +181,11 @@ class Keypoints:See the Convention block on :class:`Keypoints`.``padding_size`` is ordered as ``(left, right, top, bottom)``. Only ``left`` and ``top`` shift the- coordinate origin. Both the batched :math:`(B, N, 2)` and the unbatched :math:`(N, 2)` container are+ coordinate origin. Both the batched ``(B, N, 2)`` and the unbatched ``(N, 2)`` container aresupported; the unbatched form carries a single image, so ``padding_size`` must have exactly one row.Args:- padding_size: per-image padding in pixels, shaped :math:`(B, 4)`. A single row broadcasts across the+ padding_size: per-image padding in pixels, shaped ``(B, 4)``. A single row broadcasts across thebatch."""@@ -204,7 +204,7 @@ class Keypoints:Accepts the same batched and unbatched containers and ``padding_size`` layout as :meth:`pad`.Args:- padding_size: per-image padding in pixels, shaped :math:`(B, 4)`. A single row broadcasts across the+ padding_size: per-image padding in pixels, shaped ``(B, 4)``. A single row broadcasts across thebatch."""@@ -221,7 +221,7 @@ class Keypoints:See the Convention block on :class:`Keypoints`.Args:- M: The transformation matrix to be applied, shape of :math:`(3, 3)` or :math:`(B, 3, 3)`.+ M: The transformation matrix to be applied, shape of ``(3, 3)`` or ``(B, 3, 3)``.inplace: ``True`` rebinds this object to the transformed tensor and returns it; ``False`` returns a new:class:`Keypoints`.@@ -248,7 +248,7 @@ class Keypoints:"""Validate and wrap a tensor of 2D keypoint coordinates.Args:- keypoints: Floating-point tensor in :math:`(N, 2)` or :math:`(B, N, 2)` format; an integer tensor+ keypoints: Floating-point tensor in ``(N, 2)`` or ``(B, N, 2)`` format; an integer tensorraises ``ValueError``. The last dimension stores ``(x, y)`` coordinates.Returns:@@ -264,7 +264,7 @@ class Keypoints:(`#5023 <https://github.com/kornia/kornia/issues/5023>`_).Returns:- The stored tensor itself, :math:`(N, 2)` or :math:`(B, N, 2)`.+ The stored tensor itself, ``(N, 2)`` or ``(B, N, 2)``."""if as_padded_sequence:@@ -337,12 +337,12 @@ class VideoKeypoints(Keypoints):class Keypoints3D:- """3D keypoints, stored as an :math:`(N, 3)` or :math:`(B, N, 3)` tensor of ``(x, y, z)`` points.+ """3D keypoints, stored as an ``(N, 3)`` or ``(B, N, 3)`` tensor of ``(x, y, z)`` points.The constructor validates the tensor as :class:`Keypoints` does and wraps a floating-point one without copying it.Args:- keypoints: tensor of :math:`(N, 3)` or :math:`(B, N, 3)` coordinates. A list of tensors is not implemented+ keypoints: tensor of ``(N, 3)`` or ``(B, N, 3)`` coordinates. A list of tensors is not implemented(see Known defects).raise_if_not_floating_point: ``True`` raises ``ValueError`` for a non-floating-point tensor, ``False`` castsit to ``float32``, or ``float64`` when that is the default dtype. Floating-point input keeps its dtype.@@ -393,8 +393,8 @@ class Keypoints3D:"""Return the tensor shape used to store 3D keypoints.Returns:- Shape of :attr:`data`. The common layouts are :math:`(N, 3)` and- :math:`(B, N, 3)`, where the final dimension stores ``(x, y, z)``+ Shape of :attr:`data`. The common layouts are ``(N, 3)`` and+ ``(B, N, 3)``, where the final dimension stores ``(x, y, z)``coordinates."""return self.data.shape@@ -436,7 +436,7 @@ class Keypoints3D::func:`~kornia.geometry.conversions.convert_points_from_homogeneous`.Args:- M: The transformation matrix to be applied, shape of :math:`(4, 4)` or :math:`(B, 4, 4)`.+ M: The transformation matrix to be applied, shape of ``(4, 4)`` or ``(B, 4, 4)``.inplace: ``True`` rebinds this object to the transformed tensor and returns it, without writing into thetensor it wrapped; ``False`` returns a new :class:`Keypoints3D`.@@ -463,7 +463,7 @@ class Keypoints3D:"""Validate and wrap a tensor of 3D keypoint coordinates.Args:- keypoints: Tensor in :math:`(N, 3)` or :math:`(B, N, 3)` format,+ keypoints: Tensor in ``(N, 3)`` or ``(B, N, 3)`` format,where the last dimension stores ``(x, y, z)``.Returns:@@ -479,7 +479,7 @@ class Keypoints3D:(`#5023 <https://github.com/kornia/kornia/issues/5023>`_).Returns:- The stored tensor itself, :math:`(N, 3)` or :math:`(B, N, 3)`.+ The stored tensor itself, ``(N, 3)`` or ``(B, N, 3)``."""if as_padded_sequence:diff --git a/kornia/geometry/liegroup/se2.py b/kornia/geometry/liegroup/se2.pyindex 2fc3dce43..b12d28e9a 100644--- a/kornia/geometry/liegroup/se2.py+++ b/kornia/geometry/liegroup/se2.py@@ -88,7 +88,7 @@ class Se2(nn.Module):Convention:- ``matrix()`` is the 3x3 :math:`[[R, t], [0, 1]]`. ``a * b`` is ``a.matrix() @ b.matrix()`` and ``g * p`` is:math:`R p + t`, as in :class:`~kornia.geometry.liegroup.Se3`, but an unbatched pose also transforms- :math:`(N, 2)` points and a batched one a single :math:`(2,)` point. The rotation is an+ ``(N, 2)`` points and a batched one a single ``(2,)`` point. The rotation is an:class:`~kornia.geometry.liegroup.So2`, whose storage and direction conventions apply.- The tangent vector is :math:`(v_x, v_y, \theta)`, angle last: ``exp`` rotates by :math:`\theta` andtranslates by :math:`V(\theta) (v_x, v_y)`, and ``log`` returns :math:`\theta` in :math:`[-\pi, \pi]`.@@ -126,7 +126,7 @@ class Se2(nn.Module):Args:rotation: So2 group encompassing a rotation.- translation: translation torch.Tensor with the shape of :math:`(B, 2)`, or a Vector2 wrapping one; the+ translation: translation torch.Tensor with the shape of ``(B, 2)``, or a Vector2 wrapping one; thetensor is what gets stored. It must have the rotation's dtype (``z``'s real dtype) and device;a bfloat16 translation is also accepted beside a complex32, complex64 or complex128 rotation, whichis what ``.bfloat16()`` leaves (PyTorch has no complex bfloat16). Every method then reads the@@ -185,7 +185,7 @@ class Se2(nn.Module):"""Compose two Se2 transformations, or transform points.Args:- right: the other Se2 transformation, or points of shape :math:`(B, 2)` or :math:`(2,)`.+ right: the other Se2 transformation, or points of shape ``(B, 2)`` or ``(2,)``.Return:The resulting Se2 transformation, or the transformed points.@@ -213,7 +213,7 @@ class Se2(nn.Module):@propertydef t(self) -> torch.Tensor:- """Return the underlying translation vector of shape :math:`(B,2)`."""+ """Return the underlying translation vector of shape ``(B,2)``."""return self._translation@property@@ -223,7 +223,7 @@ class Se2(nn.Module):@propertydef translation(self) -> torch.Tensor:- """Return the underlying translation vector of shape :math:`(B,2)`."""+ """Return the underlying translation vector of shape ``(B,2)``."""return self._translation@staticmethod@@ -231,7 +231,7 @@ class Se2(nn.Module):"""Convert elements of lie algebra to elements of lie group.Args:- v: vector of shape :math:`(B, 3)`.+ v: vector of shape ``(B, 3)``.Example:>>> v = torch.ones((1, 3))@@ -306,7 +306,7 @@ class Se2(nn.Module)::meth:`vee` inverts it, and its matrix exponential is the pose :meth:`exp` returns.Args:- v: vector of shape :math:`(B, 3)` or :math:`(3,)`.+ v: vector of shape ``(B, 3)`` or ``(3,)``.Example:>>> v = torch.tensor([1.0, 2.0, 0.5])@@ -333,10 +333,10 @@ class Se2(nn.Module):It reads the translation from the last column and the angle from the ``[1, 0]`` entry.Args:- omega: 3x3-matrix built by :meth:`hat`, of shape :math:`(B, 3, 3)` or :math:`(3, 3)`.+ omega: 3x3-matrix built by :meth:`hat`, of shape ``(B, 3, 3)`` or ``(3, 3)``.Returns:- vector of shape :math:`(B, 3)` or :math:`(3,)`.+ vector of shape ``(B, 3)`` or ``(3,)``.Example:>>> v = torch.ones(3)@@ -385,7 +385,7 @@ class Se2(nn.Module):return cls(So2.identity(batch_size, device, dtype), t)def matrix(self) -> torch.Tensor:- """Return the matrix representation of shape :math:`(B, 3, 3)`.+ """Return the matrix representation of shape ``(B, 3, 3)``.Example:>>> s = Se2(So2.identity(1), torch.ones(1, 2))@@ -406,7 +406,7 @@ class Se2(nn.Module):"""Create an Se2 group from a matrix.Args:- matrix: torch.Tensor of shape :math:`(B, 3, 3)`.+ matrix: torch.Tensor of shape ``(B, 3, 3)``.Example:>>> s = Se2.from_matrix(torch.eye(3).repeat(2, 1, 1))@@ -506,7 +506,7 @@ class Se2(nn.Module):return cls.trans(zs, y)def adjoint(self) -> torch.Tensor:- """Return the adjoint matrix of shape :math:`(B, 3, 3)`.+ """Return the adjoint matrix of shape ``(B, 3, 3)``.Example:>>> s = Se2.identity()diff --git a/kornia/geometry/liegroup/se3.py b/kornia/geometry/liegroup/se3.pyindex 35aa03756..ecdf60daf 100644--- a/kornia/geometry/liegroup/se3.py+++ b/kornia/geometry/liegroup/se3.py@@ -110,7 +110,7 @@ class Se3(nn.Module):Args:rotation: So3 group encompassing a rotation, or a Quaternion to wrap in one; it is stored as given, anda non-unit quaternion stands for the rotation of its direction.- translation: translation torch.Tensor with the shape of :math:`(B, 3)`, or a Vector3 wrapping one; the+ translation: translation torch.Tensor with the shape of ``(B, 3)``, or a Vector3 wrapping one; thetensor is what gets stored. It must have the rotation's dtype and device.Raises:@@ -211,7 +211,7 @@ class Se3(nn.Module):@propertydef t(self) -> torch.Tensor:- """Return the underlying translation vector of shape :math:`(B,3)`."""+ """Return the underlying translation vector of shape ``(B,3)``."""return self._translation@property@@ -221,7 +221,7 @@ class Se3(nn.Module):@propertydef translation(self) -> torch.Tensor:- """Return the underlying translation vector of shape :math:`(B,3)`."""+ """Return the underlying translation vector of shape ``(B,3)``."""return self._translation@staticmethod@@ -229,7 +229,7 @@ class Se3(nn.Module):"""Convert elements of lie algebra to elements of lie group.Args:- v: vector of shape :math:`(B, 6)`.+ v: vector of shape ``(B, 6)``.Example:>>> v = torch.zeros((1, 6))@@ -299,10 +299,10 @@ class Se3(nn.Module):"""Convert elements from vector space to lie algebra.Args:- v: vector of shape :math:`(B, 6)`.+ v: vector of shape ``(B, 6)``.Returns:- matrix of shape :math:`(B, 4, 4)`.+ matrix of shape ``(B, 4, 4)``.Example:>>> v = torch.ones((1, 6))@@ -324,10 +324,10 @@ class Se3(nn.Module):"""Convert elements from lie algebra to vector space.Args:- omega: 4x4-matrix representing lie algebra of shape :math:`(B,4,4)`.+ omega: 4x4-matrix representing lie algebra of shape ``(B,4,4)``.Returns:- vector of shape :math:`(B,6)`.+ vector of shape ``(B,6)``.Example:>>> v = torch.ones((1, 6))@@ -371,7 +371,7 @@ class Se3(nn.Module):return cls(So3.identity(batch_size, device, dtype), t)def matrix(self) -> torch.Tensor:- """Return the matrix representation of shape :math:`(B, 4, 4)`.+ """Return the matrix representation of shape ``(B, 4, 4)``.Example:>>> s = Se3(So3.identity(), torch.ones(3))@@ -392,7 +392,7 @@ class Se3(nn.Module):"""Create a Se3 group from a matrix.Args:- matrix: torch.Tensor of shape :math:`(B, 4, 4)`.+ matrix: torch.Tensor of shape ``(B, 4, 4)``.check_rotation: if ``True``, raise ``ValueError`` unless the rotationblock of every input is a rotation matrix. The default ``False``keeps the unchecked behaviour, under which a reflection block@@ -417,7 +417,7 @@ class Se3(nn.Module):"""Create a Se3 group from a quaternion and a translation vector.Args:- qxyz: torch.Tensor of shape :math:`(B, 7)` laid out as ``[qw, qx, qy, qz, x, y, z]``, scalar first; the+ qxyz: torch.Tensor of shape ``(B, 7)`` laid out as ``[qw, qx, qy, qz, x, y, z]``, scalar first; thequaternion is stored as given, and a non-unit one stands for the rotation of its direction.Example:@@ -562,7 +562,7 @@ class Se3(nn.Module):return cls.trans(zs, zs, z)def adjoint(self) -> torch.Tensor:- """Return the adjoint matrix of shape :math:`(B, 6, 6)`.+ """Return the adjoint matrix of shape ``(B, 6, 6)``.Example:>>> s = Se3.identity()diff --git a/kornia/geometry/liegroup/so2.py b/kornia/geometry/liegroup/so2.pyindex fc08ffc60..a36d886a6 100644--- a/kornia/geometry/liegroup/so2.py+++ b/kornia/geometry/liegroup/so2.py@@ -53,8 +53,8 @@ class So2(nn.Module):See more: https://en.wikipedia.org/wiki/Orthogonal_group#Special_orthogonal_groupConvention:- - Represents the rotation as a complex number ``z`` of shape :math:`()` or :math:`(B,)`; a :math:`(B, 1)`- ``z`` or angle is accepted and read as :math:`(B,)`. For unit :math:`z = \cos\theta + i \sin\theta`,+ - Represents the rotation as a complex number ``z`` of shape :math:`()` or ``(B,)``; a ``(B, 1)``+ ``z`` or angle is accepted and read as ``(B,)``. For unit :math:`z = \cos\theta + i \sin\theta`,``matrix()`` is :math:`[[\cos\theta, -\sin\theta], [\sin\theta, \cos\theta]]`. Non-unit ``z = a + i b``is accepted and produces :math:`[[a, -b], [b, a]]`, which rotates and scales by :math:`|z|`. The complexstorage has no bfloat16 counterpart in PyTorch, so ``exp``, ``identity``, ``random`` and ``from_matrix``@@ -87,7 +87,7 @@ class So2(nn.Module):Internally represented by torch.complex number `z`.Args:- z: Complex number with the shape of :math:`(B,)` or :math:`()`; :math:`(B, 1)` is read as :math:`(B,)`.+ z: Complex number with the shape of ``(B,)`` or :math:`()`; ``(B, 1)`` is read as ``(B,)``.Raises:TypeCheckError: if ``z`` is not a complex tensor (an integer, bool or real floating-point tensor).@@ -155,7 +155,7 @@ class So2(nn.Module):"""Perform a left-multiplication either rotation concatenation or point-transform.Args:- right: the other So2 transformation, or points of shape :math:`(B, 2)` or :math:`(2,)` as a tensor or+ right: the other So2 transformation, or points of shape ``(B, 2)`` or ``(2,)`` as a tensor ora ``Vector2``.Return:@@ -185,10 +185,10 @@ class So2(nn.Module):@propertydef z(self) -> torch.Tensor:- """Return the underlying complex number of shape :math:`()` or :math:`(B,)`.+ """Return the underlying complex number of shape :math:`()` or ``(B,)``.- A :math:`(B, 1)` ``z`` given to the constructor stays stored, and registered, as it was given, and is read- here as a :math:`(B,)` view.+ A ``(B, 1)`` ``z`` given to the constructor stays stored, and registered, as it was given, and is read+ here as a ``(B,)`` view."""return self._z.squeeze(-1) if self._z.dim() == 2 else self._z@@ -197,7 +197,7 @@ class So2(nn.Module):"""Convert elements of lie algebra to elements of lie group.Args:- theta: angle in radians of shape :math:`(B,)` or :math:`()`; :math:`(B, 1)` is squeezed to :math:`(B,)`.+ theta: angle in radians of shape ``(B,)`` or :math:`()`; ``(B, 1)`` is squeezed to ``(B,)``.Raises:TypeCheckError: if ``theta`` is bfloat16, which has no complex dtype in PyTorch.@@ -234,11 +234,11 @@ class So2(nn.Module):def hat(theta: torch.Tensor) -> torch.Tensor:r"""Convert an angle to the so(2) generator :math:`[[0, -\theta], [\theta, 0]]`, which :meth:`vee` inverts.- The output has shape :math:`(2, 2)` or :math:`(B, 2, 2)`; a :math:`(B, 1)` angle is squeezed to :math:`(B,)`.+ The output has shape ``(2, 2)`` or ``(B, 2, 2)``; a ``(B, 1)`` angle is squeezed to ``(B,)``.Its matrix exponential is the rotation :meth:`exp` returns.Args:- theta: angle in radians of shape :math:`(B,)` or :math:`()`; :math:`(B, 1)` is squeezed to :math:`(B,)`.+ theta: angle in radians of shape ``(B,)`` or :math:`()`; ``(B, 1)`` is squeezed to ``(B,)``.Example:>>> theta = torch.tensor(3.1415/2)@@ -262,9 +262,9 @@ class So2(nn.Module):@staticmethoddef vee(omega: torch.Tensor) -> torch.Tensor:- r"""Read the angle back from a :meth:`hat` matrix of shape :math:`(2, 2)` or :math:`(B, 2, 2)`.+ r"""Read the angle back from a :meth:`hat` matrix of shape ``(2, 2)`` or ``(B, 2, 2)``.- Returns a scalar or a :math:`(B,)` vector, respectively.+ Returns a scalar or a ``(B,)`` vector, respectively.It reads the ``[1, 0]`` entry, :math:`\theta` in the so(2) generator :math:`[[0, -\theta], [\theta, 0]]`.@@ -305,7 +305,7 @@ class So2(nn.Module):"""Create So2 from a rotation matrix.Args:- matrix: the rotation matrix to convert of shape :math:`(B, 2, 2)`.+ matrix: the rotation matrix to convert of shape ``(B, 2, 2)``.Raises:TypeCheckError: if ``matrix`` is bfloat16, which has no complex dtype in PyTorch.@@ -419,7 +419,7 @@ class So2(nn.Module):return cls.exp(theta)def adjoint(self) -> torch.Tensor:- """Return the adjoint matrix of shape :math:`(B, 2, 2)`.+ """Return the adjoint matrix of shape ``(B, 2, 2)``.Example:>>> s = So2.identity()diff --git a/kornia/geometry/liegroup/so3.py b/kornia/geometry/liegroup/so3.pyindex 43091b915..979ca466d 100644--- a/kornia/geometry/liegroup/so3.py+++ b/kornia/geometry/liegroup/so3.py@@ -77,7 +77,7 @@ def _computes_in_float32(dtype: torch.dtype) -> bool:def _so3_rotate(q: Quaternion, points: torch.Tensor) -> torch.Tensor:- """Rotate points of shape :math:`(*, 3)` by the unit direction of ``q`` as :math:`q p q^*`.+ """Rotate points of shape ``(*, 3)`` by the unit direction of ``q`` as :math:`q p q^*`.A float16/bfloat16 result is computed in float32 and returned in float32, for the caller to add to it or round itonce; any other dtype combination is evaluated as given.@@ -108,7 +108,7 @@ class So3(nn.Module)::class:`~kornia.geometry.quaternion.Quaternion`, and returns the principal vector, of norm at most:math:`\pi`, the same for ``q`` and ``-q`` below a half turn.- ``a * b`` composes like ``a.matrix() @ b.matrix()``, so ``b`` acts first; ``s * p`` rotates points ``p`` of- shape :math:`(B, 3)`, a tensor or a ``Vector3``, as :math:`R p`; and ``adjoint()`` is :math:`R` itself.+ shape ``(B, 3)``, a tensor or a ``Vector3``, as :math:`R p`; and ``adjoint()`` is :math:`R` itself.:ref:`Rotations and rigid motions <rotation-conventions>` compares these with scipy, Sophus and Eigen.- A non-unit quaternion stands for the rotation of its direction :math:`q / |q|`, as for:meth:`~kornia.geometry.quaternion.Quaternion.matrix`: ``matrix()`` and ``s * p`` normalise it where they@@ -139,7 +139,7 @@ class So3(nn.Module):"""Construct the base class.Args:- q: Quaternion with the shape of :math:`(B, 4)`.+ q: Quaternion with the shape of ``(B, 4)``.Example:>>> data = torch.tensor([[1., 0., 0., 0.], [0., 1., 0., 0.]])@@ -174,7 +174,7 @@ class So3(nn.Module):Both compute in float32 for float16/bfloat16 inputs and return the input dtype.Args:- right: the other So3 transformation, or points of shape :math:`(B, 3)` as a tensor or a ``Vector3``.+ right: the other So3 transformation, or points of shape ``(B, 3)`` as a tensor or a ``Vector3``.Return:The resulting So3 transformation, or the rotated points of the type of ``right``.@@ -195,7 +195,7 @@ class So3(nn.Module):@propertydef q(self) -> Quaternion:- """Return the underlying data with shape :math:`(B,4)`."""+ """Return the underlying data with shape ``(B,4)``."""return self._q@staticmethod@@ -205,7 +205,7 @@ class So3(nn.Module):See more: https://vision.in.tum.de/_media/members/demmeln/nurlanov2021so3log.pdfArgs:- v: vector of shape :math:`(B,3)`.+ v: vector of shape ``(B,3)``.Example:>>> v = torch.zeros((2, 3))@@ -258,10 +258,10 @@ class So3(nn.Module):@staticmethoddef hat(v: Vector3 | torch.Tensor) -> torch.Tensor:- """Convert elements from vector space to lie algebra. Returns matrix of shape :math:`(B,3,3)`.+ """Convert elements from vector space to lie algebra. Returns matrix of shape ``(B,3,3)``.Args:- v: Vector3 or torch.Tensor of shape :math:`(B,3)`.+ v: Vector3 or torch.Tensor of shape ``(B,3)``.Example:>>> v = torch.ones((1,3))@@ -286,7 +286,7 @@ class So3(nn.Module):@staticmethoddef vee(omega: torch.Tensor) -> torch.Tensor:- r"""Convert elements from lie algebra to vector space. Returns vector of shape :math:`(B,3)`.+ r"""Convert elements from lie algebra to vector space. Returns vector of shape ``(B,3)``... math::omega = \begin{bmatrix} 0 & -c & b \\@@ -308,7 +308,7 @@ class So3(nn.Module):return torch.stack((a, b, c), -1)def matrix(self) -> torch.Tensor:- r"""Convert the quaternion to a rotation matrix of shape :math:`(B,3,3)`.+ r"""Convert the quaternion to a rotation matrix of shape ``(B,3,3)``.The matrix is of the form:@@ -354,7 +354,7 @@ class So3(nn.Module):"""Create So3 from a rotation matrix.Args:- matrix: the rotation matrix to convert of shape :math:`(B,3,3)`.+ matrix: the rotation matrix to convert of shape ``(B,3,3)``.check_rotation: if ``True``, raise ``ValueError`` unless every inputis a rotation matrix. The default ``False`` keeps the uncheckedbehaviour, under which a reflection such as ``diag(-1, 1, 1)``@@ -376,7 +376,7 @@ class So3(nn.Module):"""Create So3 from a torch.Tensor representing a quaternion.Args:- wxyz: the quaternion to convert of shape :math:`(B,4)`.+ wxyz: the quaternion to convert of shape ``(B,4)``.Example:>>> q = torch.tensor([1., 0., 0., 0.])@@ -481,7 +481,7 @@ class So3(nn.Module):return cls.exp(torch.stack((zs, zs, z), -1))def adjoint(self) -> torch.Tensor:- """Return the adjoint matrix of shape :math:`(B, 3, 3)`.+ """Return the adjoint matrix of shape ``(B, 3, 3)``.Example:>>> s = So3.identity()@@ -498,7 +498,7 @@ class So3(nn.Module):"""Compute the right Jacobian of So3.Args:- vec: the tangent vector of shape :math:`(B, 3)`.+ vec: the tangent vector of shape ``(B, 3)``.Example:>>> vec = torch.tensor([1., 2., 3.])@@ -520,7 +520,7 @@ class So3(nn.Module):"""Alias for right jacobian.Args:- vec: the tangent vector of shape :math:`(B, 3)`.+ vec: the tangent vector of shape ``(B, 3)``."""return So3.right_jacobian(vec)@@ -530,7 +530,7 @@ class So3(nn.Module):"""Compute the left Jacobian of So3.Args:- vec: the tangent vector of shape :math:`(B, 3)`.+ vec: the tangent vector of shape ``(B, 3)``.Example:>>> vec = torch.tensor([1., 2., 3.])@@ -552,7 +552,7 @@ class So3(nn.Module):"""Alias for left jacobian.Args:- vec: the tangent vector of shape :math:`(B, 3)`.+ vec: the tangent vector of shape ``(B, 3)``."""return So3.left_jacobian(vec)diff --git a/kornia/geometry/linalg.py b/kornia/geometry/linalg.pyindex 193de84f2..44eec61d7 100644--- a/kornia/geometry/linalg.py+++ b/kornia/geometry/linalg.py@@ -51,14 +51,14 @@ def compose_transformations(trans_01: torch.Tensor, trans_12: torch.Tensor) -> tArgs:trans_01: tensor with the homogeneous transformation froma reference frame 1 respect to a frame 0. The tensor must have a- shape of :math:`(N, 4, 4)` or :math:`(4, 4)`.+ shape of ``(N, 4, 4)`` or ``(4, 4)``.trans_12: tensor with the homogeneous transformation froma reference frame 2 respect to a frame 1. The tensor must have a- shape of :math:`(N, 4, 4)` or :math:`(4, 4)`. A batch of one broadcasts against a batch of+ shape of ``(N, 4, 4)`` or ``(4, 4)``. A batch of one broadcasts against a batch of:math:`N` in either argument.Returns:- the transformation between the two frames with shape :math:`(N, 4, 4)` or :math:`(4, 4)`.+ the transformation between the two frames with shape ``(N, 4, 4)`` or ``(4, 4)``.Example::>>> trans_01 = torch.eye(4) # 4x4@@ -119,10 +119,10 @@ def inverse_transformation(trans_12: torch.Tensor) -> torch.Tensor:is on :func:`relative_transformation`.Args:- trans_12: transformation tensor of shape :math:`(N, 4, 4)` or :math:`(4, 4)`.+ trans_12: transformation tensor of shape ``(N, 4, 4)`` or ``(4, 4)``.Returns:- tensor with inverted transformations with shape :math:`(N, 4, 4)` or :math:`(4, 4)`.+ tensor with inverted transformations with shape ``(N, 4, 4)`` or ``(4, 4)``.Example:>>> trans_12 = torch.eye(4)[None] # Nx4x4: a rotation of 90 degrees about z and a translation@@ -178,12 +178,12 @@ def relative_transformation(trans_01: torch.Tensor, trans_02: torch.Tensor) -> t:math:`E_2`.Args:- trans_01: reference transformation tensor of shape :math:`(N, 4, 4)` or :math:`(4, 4)`.- trans_02: destination transformation tensor of shape :math:`(N, 4, 4)` or :math:`(4, 4)`. A batch+ trans_01: reference transformation tensor of shape ``(N, 4, 4)`` or ``(4, 4)``.+ trans_02: destination transformation tensor of shape ``(N, 4, 4)`` or ``(4, 4)``. A batchof one broadcasts against a batch of :math:`N` in either argument.Returns:- the relative transformation between the transformations with shape :math:`(N, 4, 4)` or :math:`(4, 4)`.+ the relative transformation between the transformations with shape ``(N, 4, 4)`` or ``(4, 4)``.Example::>>> trans_01 = torch.eye(4) # 4x4@@ -231,8 +231,8 @@ def transform_points(trans_01: torch.Tensor, points_1: torch.Tensor) -> torch.TeArgs:trans_01: tensor for transformations of shape- :math:`(D+1, D+1)` or :math:`(B, D+1, D+1)`.- points_1: tensor of points of shape :math:`(N, D)` or :math:`(B, N, D)`.+ ``(D+1, D+1)`` or ``(B, D+1, D+1)``.+ points_1: tensor of points of shape ``(N, D)`` or ``(B, N, D)``.Returns:transformed points with the same shape as ``points_1``.@@ -331,14 +331,14 @@ def point_line_distance(point: torch.Tensor, line: torch.Tensor, eps: float = 1efrom every point, as a point at infinity is from every line.Args:- point: points :math:`(*, N, 2)`, or homogeneous points :math:`(*, N, 3)` whose last coordinate is the+ point: points ``(*, N, 2)``, or homogeneous points ``(*, N, 3)`` whose last coordinate is theweight :math:`w`; a point at infinity (:math:`w = 0`) is at distance ``inf`` from every line.- line: lines coefficients :math:`(a, b, c)` with shape :math:`(*, N, 3)`, where :math:`ax + by + c = 0`.+ line: lines coefficients :math:`(a, b, c)` with shape ``(*, N, 3)``, where :math:`ax + by + c = 0`.eps: unused; it was added to :math:`\|(a, b)\|` and made the distance depend on the scale of the line(#4881). The singular line is guarded exactly instead. Accepted so that existing calls keep working.Returns:- the computed distance with shape :math:`(*, N)`.+ the computed distance with shape ``(*, N)``."""KORNIA_CHECK_IS_TENSOR(point)@@ -391,8 +391,8 @@ def euclidean_distance(x: torch.Tensor, y: torch.Tensor, keepdim: bool = False,More: https://en.wikipedia.org/wiki/Euclidean_distanceArgs:- x: first set of points of shape :math:`(*, N)`.- y: second set of points of shape :math:`(*, N)`.+ x: first set of points of shape ``(*, N)``.+ y: second set of points of shape ``(*, N)``.keepdim: whether to keep the dimension after reduction.eps: unused; kept for backward compatibility. The result is the exact Euclidean distance.diff --git a/kornia/geometry/line.py b/kornia/geometry/line.pyindex c02e7fb9b..1697eb8eb 100644--- a/kornia/geometry/line.py+++ b/kornia/geometry/line.py@@ -104,8 +104,8 @@ class ParametrizedLine(nn.Module):"""Construct a parametrized line going from a point :math:`p0` to :math:`p1`.Args:- p0: tensor with first point :math:`(B, D)` where `D` is the point dimension.- p1: tensor with second point :math:`(B, D)` where `D` is the point dimension.+ p0: tensor with first point ``(B, D)`` where `D` is the point dimension.+ p1: tensor with second point ``(B, D)`` where `D` is the point dimension.Raises:ValueCheckError: if ``p0`` and ``p1`` coincide, so the line has no direction.@@ -131,7 +131,7 @@ class ParametrizedLine(nn.Module):Args:t: step along the line: a number or a 0-d tensor for every row, or one step per row of shape- :math:`(B,)` or :math:`(B, 1)` for a line of shape :math:`(B, D)`.+ ``(B,)`` or ``(B, 1)`` for a line of shape ``(B, D)``.Return:tensor with the point.@@ -358,12 +358,12 @@ def fit_line(points: torch.Tensor, weights: Optional[torch.Tensor] = None) -> PaArgs:points: tensor containing a batch of sets of n-dimensional points. The expected- shape of the tensor is :math:`(B, N, D)`.+ shape of the tensor is ``(B, N, D)``.weights: per-point weights, used in the centroid and in the fit. The expected- shape of the tensor is :math:`(B, N)`.+ shape of the tensor is ``(B, N)``.Return:- The fitted line, with origin and direction of shape :math:`(B, D)`.+ The fitted line, with origin and direction of shape ``(B, D)``.Raises:ValueCheckError: if the points do not determine a line β fewer than two points,diff --git a/kornia/geometry/plane.py b/kornia/geometry/plane.pyindex 8c49ebdfb..f983d149d 100644--- a/kornia/geometry/plane.py+++ b/kornia/geometry/plane.py@@ -289,8 +289,8 @@ def fit_plane(points: Vector3) -> Hyperplane:of unspecified sign. Each batch row is fitted on its own.Args:- points: a tensor or a :class:`~kornia.geometry.vector.Vector3` of 3D points, of shape :math:`(N, 3)` or- :math:`(B, N, 3)`. Another number of coordinates raises ``TypeError``.+ points: a tensor or a :class:`~kornia.geometry.vector.Vector3` of 3D points, of shape ``(N, 3)`` or+ ``(B, N, 3)``. Another number of coordinates raises ``TypeError``.Return:The computed hyperplane object.diff --git a/kornia/geometry/pointcloud.py b/kornia/geometry/pointcloud.pyindex e06427a35..7deef7c29 100644--- a/kornia/geometry/pointcloud.py+++ b/kornia/geometry/pointcloud.py@@ -49,7 +49,7 @@ def save_pointcloud_ply(filename: str | os.PathLike[str], pointcloud: torch.TensArgs:filename: path of the ``.ply`` file to write, a ``str`` or ``os.PathLike[str]``.- pointcloud: tensor of shape :math:`(*, 3)` with at least two dimensions, where the last dimension is the+ pointcloud: tensor of shape ``(*, 3)`` with at least two dimensions, where the last dimension is thepoint :math:`(X, Y, Z)`."""filename = os.fspath(filename)@@ -99,7 +99,7 @@ def save_pointcloud_ply_binary(filename: str | os.PathLike[str], pointcloud: torArgs:filename: path of the ``.ply`` file to write, a ``str`` or ``os.PathLike[str]``.- pointcloud: tensor of shape :math:`(*, 3)` with at least two dimensions, where the last dimension is the+ pointcloud: tensor of shape ``(*, 3)`` with at least two dimensions, where the last dimension is thepoint :math:`(X, Y, Z)`."""filename = os.fspath(filename)@@ -294,7 +294,7 @@ def load_pointcloud_ply(filename: str | os.PathLike[str], header_size: Optional[header_size: deprecated and ignored; the header is parsed instead of skipped.Return:- tensor containing the loaded points with shape :math:`(N, 3)` in ``float32``, where+ tensor containing the loaded points with shape ``(N, 3)`` in ``float32``, where:math:`N` is the declared vertex count."""filename = os.fspath(filename)@@ -356,7 +356,7 @@ def load_pointcloud_ply_binary(filename: str | os.PathLike[str], header_size: Opheader_size: deprecated and ignored; the header is parsed instead of skipped.Return:- tensor containing the loaded points with shape :math:`(N, 3)` in ``float32``, where+ tensor containing the loaded points with shape ``(N, 3)`` in ``float32``, where:math:`N` is the declared vertex count."""filename = os.fspath(filename)diff --git a/kornia/geometry/quaternion.py b/kornia/geometry/quaternion.pyindex fac7c0d92..d6c215d83 100644--- a/kornia/geometry/quaternion.py+++ b/kornia/geometry/quaternion.py@@ -58,7 +58,7 @@ class Quaternion(nn.Module):Q = \begin{bmatrix} q_w & q_x & q_y & q_z \end{bmatrix}Convention:- - ``data`` is ``(w, x, y, z)``, real part first, with shape :math:`(*, 4)`; only the last axis is checked.+ - ``data`` is ``(w, x, y, z)``, real part first, with shape ``(*, 4)``; only the last axis is checked.Other libraries' orders, such as scipy's default ``(x, y, z, w)``, are mapped on:ref:`Rotations and rigid motions <rotation-conventions>`.- ``*`` between quaternions is the Hamilton product, so ``(q1 * q2).matrix()`` is@@ -101,7 +101,7 @@ class Quaternion(nn.Module):"""Construct a quaternion from torch.Tensor or parameter data.Args:- data: torch.Tensor or parameter containing the quaternion data with the shape of :math:`(*, 4)`.+ data: torch.Tensor or parameter containing the quaternion data with the shape of ``(*, 4)``.Stored without copying as a persistent buffer, or as a parameter if already an ``nn.Parameter``.Example:@@ -358,7 +358,7 @@ class Quaternion(nn.Module):@propertydef data(self) -> torch.Tensor:- """Return the underlying data with shape :math:`(B, 4)`."""+ """Return the underlying data with shape ``(B, 4)``."""return self._data@property@@ -368,7 +368,7 @@ class Quaternion(nn.Module):@propertydef real(self) -> torch.Tensor:- """Return the real part with shape :math:`(B,)`.+ """Return the real part with shape ``(B,)``.Alias for :attr:`~kornia.geometry.quaternion.Quaternion.w`."""@@ -376,12 +376,12 @@ class Quaternion(nn.Module):@propertydef vec(self) -> torch.Tensor:- """Return the vector with the imaginary part with shape :math:`(B, 3)`."""+ """Return the vector with the imaginary part with shape ``(B, 3)``."""return self.data[..., 1:]@propertydef q(self) -> torch.Tensor:- """Return the underlying data with shape :math:`(B, 4)`.+ """Return the underlying data with shape ``(B, 4)``.Alias for :func:`~kornia.geometry.quaternion.Quaternion.data`"""@@ -389,7 +389,7 @@ class Quaternion(nn.Module):@propertydef scalar(self) -> torch.Tensor:- """Return a scalar with the real with shape :math:`(B,)`.+ """Return a scalar with the real with shape ``(B,)``.Alias for :attr:`~kornia.geometry.quaternion.Quaternion.w`."""@@ -397,32 +397,32 @@ class Quaternion(nn.Module):@propertydef w(self) -> torch.Tensor:- """Return the :math:`q_w` with shape :math:`(B,)`."""+ """Return the :math:`q_w` with shape ``(B,)``."""return self.data[..., 0]@propertydef x(self) -> torch.Tensor:- """Return the :math:`q_x` with shape :math:`(B,)`."""+ """Return the :math:`q_x` with shape ``(B,)``."""return self.data[..., 1]@propertydef y(self) -> torch.Tensor:- """Return the :math:`q_y` with shape :math:`(B,)`."""+ """Return the :math:`q_y` with shape ``(B,)``."""return self.data[..., 2]@propertydef z(self) -> torch.Tensor:- """Return the :math:`q_z` with shape :math:`(B,)`."""+ """Return the :math:`q_z` with shape ``(B,)``."""return self.data[..., 3]@propertydef shape(self) -> Tuple[int, ...]:- """Return the shape of the underlying data with shape :math:`(B, 4)`."""+ """Return the shape of the underlying data with shape ``(B, 4)``."""return tuple(self.data.shape)@propertydef polar_angle(self) -> torch.Tensor:- r"""Return the polar angle :math:`\arccos(w / |q|)` in :math:`[0, \pi]`, with shape :math:`(B,)`.+ r"""Return the polar angle :math:`\arccos(w / |q|)` in :math:`[0, \pi]`, with shape ``(B,)``.``q`` rotates by twice this angle about the axis ``vec``.@@ -437,7 +437,7 @@ class Quaternion(nn.Module):return torch.atan2(self.vec.norm(dim=-1), self.scalar)def matrix(self) -> torch.Tensor:- """Convert the quaternion to a rotation matrix of shape :math:`(B, 3, 3)`.+ """Convert the quaternion to a rotation matrix of shape ``(B, 3, 3)``.Example:>>> q = Quaternion.identity()@@ -455,7 +455,7 @@ class Quaternion(nn.Module):"""Create a quaternion from a rotation matrix.Args:- matrix: the rotation matrix to convert of shape :math:`(B, 3, 3)`.+ matrix: the rotation matrix to convert of shape ``(B, 3, 3)``.check_rotation: if ``True``, raise ``ValueError`` unless every inputis a rotation matrix. The default ``False`` keeps the uncheckedbehaviour, under which a reflection such as@@ -512,7 +512,7 @@ class Quaternion(nn.Module):"""Create a quaternion from axis-angle representation.Args:- axis_angle: rotation vector of shape :math:`(B, 3)`.+ axis_angle: rotation vector of shape ``(B, 3)``.Example:>>> axis_angle = torch.tensor([[1., 0., 0.]])@@ -587,7 +587,7 @@ class Quaternion(nn.Module):device: Union[str, torch.device, None] = None,dtype: Union[torch.dtype, None] = None,) -> "Quaternion":- """Create a random unit quaternion of shape :math:`(B, 4)`.+ """Create a random unit quaternion of shape ``(B, 4)``.Uniformly distributed across the rotation space as per: http://planning.cs.uiuc.edu/node198.html@@ -625,8 +625,8 @@ class Quaternion(nn.Module):Args:q1: second quaternion to be interpolated between.t: interpolation ratio, ``0`` at ``self`` and ``1`` at ``q1``. It is not validated: values outside- ``[0, 1]`` extrapolate along the same arc. A per-batch ratio has shape :math:`(B,)`, like- ``self.w``, or :math:`(B, 1)`.+ ``[0, 1]`` extrapolate along the same arc. A per-batch ratio has shape ``(B,)``, like+ ``self.w``, or ``(B, 1)``.Example:>>> q0 = Quaternion.identity()diff --git a/kornia/geometry/ransac.py b/kornia/geometry/ransac.pyindex 13e252563..379790037 100644--- a/kornia/geometry/ransac.py+++ b/kornia/geometry/ransac.py@@ -939,16 +939,16 @@ class RANSAC(nn.Module):r"""Call main forward method to execute the RANSAC algorithm.Args:- kp1: source image keypoints :math:`(N, 2)` (or line segments :math:`(N, 2, 2)`).+ kp1: source image keypoints ``(N, 2)`` (or line segments ``(N, 2, 2)``).kp2: target image keypoints with the same shape. For PROSAC, both inputs must be sortedbest-first using the same correspondence-quality ordering. Essential estimation usescamera-normalized coordinates and a threshold in those units.weights: optional correspondences weights. Not used now.Returns:- - Estimated model, shape of :math:`(3, 3)`, or zeros if no valid model is found. A model needs+ - Estimated model, shape of ``(3, 3)``, or zeros if no valid model is found. A model needsmore inliers than its minimal sample, since a model fitted to a sample fits that sample.- - Boolean inlier mask, shape of :math:`(N,)`, in the supplied correspondence order.+ - Boolean inlier mask, shape of ``(N,)``, in the supplied correspondence order."""self.validate_inputs(kp1, kp2, weights)diff --git a/kornia/geometry/solvers/affine.py b/kornia/geometry/solvers/affine.pyindex 63e636092..310376e73 100644--- a/kornia/geometry/solvers/affine.py+++ b/kornia/geometry/solvers/affine.py@@ -198,14 +198,14 @@ def find_affine(points1: torch.Tensor, points2: torch.Tensor, weights: Optional[Ambient autocast is disabled during fitting to preserve this arithmetic precision.Args:- points1: Source points with shape :math:`(B, N, 2)`, where :math:`N \geq 3`.- points2: Destination points with shape :math:`(B, N, 2)`.- weights: Optional correspondence weights with shape :math:`(B, N)`. They must be+ points1: Source points with shape ``(B, N, 2)``, where :math:`N \geq 3`.+ points2: Destination points with shape ``(B, N, 2)``.+ weights: Optional correspondence weights with shape ``(B, N)``. They must befinite and non-negative; other values are not detected and give undefinedresults. Only relative weights matter.Returns:- Homogeneous affine transformations with shape :math:`(B, 3, 3)`. Degenerate+ Homogeneous affine transformations with shape ``(B, 3, 3)``. Degeneratebatches without three non-collinear, positive-weight source points containNaNs, allowing robust estimators to reject singular fits as invalid models."""diff --git a/kornia/geometry/solvers/homogeneous.py b/kornia/geometry/solvers/homogeneous.pyindex 791383605..d0f0072bc 100644--- a/kornia/geometry/solvers/homogeneous.py+++ b/kornia/geometry/solvers/homogeneous.py@@ -63,7 +63,7 @@ def _det3(def null_vector_3x4(A: torch.Tensor) -> torch.Tensor:- r"""Return the null vector of a rank-3 matrix of shape :math:`(*, 3, 4)`.+ r"""Return the null vector of a rank-3 matrix of shape ``(*, 3, 4)``.The null vector :math:`\mathbf{v} \in \mathbb{R}^4` satisfies:math:`A\,\mathbf{v} = \mathbf{0}`. For a matrix of rank 3 this solution@@ -96,10 +96,10 @@ def null_vector_3x4(A: torch.Tensor) -> torch.Tensor:rank-deficient inputs (rank < 3) the result is the zero vector.Args:- A: matrix of shape :math:`(*, 3, 4)`.+ A: matrix of shape ``(*, 3, 4)``.Returns:- Null vector of shape :math:`(*, 4)`.+ Null vector of shape ``(*, 4)``.Raises:TypeCheckError: if ``A`` is not a :class:`torch.Tensor`.diff --git a/kornia/geometry/solvers/polynomial_solver.py b/kornia/geometry/solvers/polynomial_solver.pyindex b99e2e06d..8ea280cce 100644--- a/kornia/geometry/solvers/polynomial_solver.py+++ b/kornia/geometry/solvers/polynomial_solver.py@@ -2908,10 +2908,10 @@ def determinant_to_polynomial(``z**i``), the reverse of the :func:`solve_quadratic` layout.Args:- A: torch.Tensor :math:`(B, 3, 13)`.+ A: torch.Tensor ``(B, 3, 13)``.Returns:- a degree 10 poly of shape :math:`(B, 11)`, representing determinant (Eqn. 14 in the paper).+ a degree 10 poly of shape ``(B, 11)``, representing determinant (Eqn. 14 in the paper)."""B, device, dtype = A.shape[0], A.device, A.dtypediff --git a/kornia/geometry/subpix/dsnt.py b/kornia/geometry/subpix/dsnt.pyindex d464e51f2..1368c8588 100644--- a/kornia/geometry/subpix/dsnt.py+++ b/kornia/geometry/subpix/dsnt.py@@ -58,12 +58,12 @@ def spatial_softmax2d(input: torch.Tensor, temperature: Optional[torch.Tensor |instead applies Softmax over features at each spatial location.Args:- input: the input torch.Tensor with shape :math:`(B, N, H, W)`.+ input: the input torch.Tensor with shape ``(B, N, H, W)``.temperature: softmax temperature: the input is divided by it; smaller is sharper. Must be positive.``None`` means ``1.0``. A tensor temperature is not checked under ``torch.compile`` or export.Returns:- a 2D probability distribution per image channel with shape :math:`(B, N, H, W)`.+ a 2D probability distribution per image channel with shape ``(B, N, H, W)``.Examples:>>> heatmaps = torch.tensor([[[@@ -110,12 +110,12 @@ def spatial_expectation2d(input: torch.Tensor, normalized_coordinates: bool = Tr:func:`~kornia.geometry.subpix.spatial_softmax2d` does: a map summing to ``s`` scales the result by ``s``.Args:- input: the input torch.Tensor representing dense spatial probabilities with shape :math:`(B, N, H, W)`.+ input: the input torch.Tensor representing dense spatial probabilities with shape ``(B, N, H, W)``.normalized_coordinates: whether to return the coordinates normalized in the rangeof :math:`[-1, 1]`. Otherwise, it will return the coordinates in the range of the input shape.Returns:- expected value of the 2D coordinates with shape :math:`(B, N, 2)`. Output order of the coordinates is (x, y).+ expected value of the 2D coordinates with shape ``(B, N, 2)``. Output order of the coordinates is (x, y).Examples:>>> heatmaps = torch.tensor([[[@@ -164,15 +164,15 @@ def render_gaussian2d(- Float16 parameters are evaluated in float32; the heatmap retains the input dtype.Args:- mean: the mean location of the Gaussian to render, :math:`(\mu_x, \mu_y)`. Shape: :math:`(*, 2)`.+ mean: the mean location of the Gaussian to render, :math:`(\mu_x, \mu_y)`. Shape: ``(*, 2)``.std: the standard deviation of the Gaussian to render, :math:`(\sigma_x, \sigma_y)`.- Shape :math:`(*, 2)`. Should be able to be broadcast with `mean`.+ Shape ``(*, 2)``. Should be able to be broadcast with `mean`.size: the (height, width) of the output image.normalized_coordinates: whether ``mean`` and ``std`` are assumed to use coordinates normalizedin the range of :math:`[-1, 1]`. Otherwise, coordinates are assumed to be in the range of the output shape.Returns:- torch.Tensor including rendered points with shape :math:`(*, H, W)`.+ torch.Tensor including rendered points with shape ``(*, H, W)``."""if not (std.dtype == mean.dtype and std.device == mean.device):diff --git a/kornia/geometry/subpix/nms.py b/kornia/geometry/subpix/nms.pyindex b47e37b94..6f5d45921 100644--- a/kornia/geometry/subpix/nms.py+++ b/kornia/geometry/subpix/nms.py@@ -142,7 +142,7 @@ class NonMaximaSuppression2d(nn.Module):keypoint response maps into sparse candidate locations.Args:- x: Response tensor with shape :math:`(B, C, H, W)`, where+ x: Response tensor with shape ``(B, C, H, W)``, where:math:`B` is the batch size, :math:`C` is the number ofresponse channels, :math:`H` is height, and :math:`W` is width.mask_only: If ``True``, return the boolean maxima mask. If@@ -150,7 +150,7 @@ class NonMaximaSuppression2d(nn.Module):Returns:If ``mask_only`` is ``True``, a boolean tensor with shape- :math:`(B, C, H, W)`. Otherwise, a tensor with the same shape and+ ``(B, C, H, W)``. Otherwise, a tensor with the same shape anddtype as ``x`` where non-maxima have been set to zero."""if len(x.shape) != 4:@@ -313,7 +313,7 @@ class NonMaximaSuppression3d(nn.Module):locally maximal both in image position and in scale/depth.Args:- x: Response tensor with shape :math:`(B, C, D, H, W)`, where+ x: Response tensor with shape ``(B, C, D, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`D` is depth or scale level, :math:`H` is height, and:math:`W` is width.@@ -321,7 +321,7 @@ class NonMaximaSuppression3d(nn.Module):return suppressed responses.Returns:- Boolean maxima mask with shape :math:`(B, C, D, H, W)` when+ Boolean maxima mask with shape ``(B, C, D, H, W)`` when``mask_only`` is ``True``. Otherwise, an NMS-filtered tensor withthe same shape and dtype as ``x``."""@@ -428,7 +428,7 @@ def nms3d_minmax(input: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:minima alike.Args:- input: 5-D tensor of shape :math:`(B, C, D, H, W)`.+ input: 5-D tensor of shape ``(B, C, D, H, W)``.Returns:A pair ``(max_mask, min_mask)`` of bool tensors with the same shape asdiff --git a/kornia/geometry/subpix/spatial_soft_argmax.py b/kornia/geometry/subpix/spatial_soft_argmax.pyindex bf9352df0..73941acfc 100644--- a/kornia/geometry/subpix/spatial_soft_argmax.py+++ b/kornia/geometry/subpix/spatial_soft_argmax.py@@ -222,7 +222,7 @@ class ConvSoftArgmax2d(nn.Module):window coordinates, which gives differentiable subpixel coordinates.Args:- x: Heatmap tensor with shape :math:`(B, C, H, W)`, where+ x: Heatmap tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is the number of heatmapchannels, :math:`H` is height, and :math:`W` is width.@@ -288,7 +288,7 @@ class ConvSoftArgmax3d(nn.Module):"""Estimate local 3D coordinates from response-volume windows.Args:- x: Response tensor with shape :math:`(B, C, D, H, W)`, where+ x: Response tensor with shape ``(B, C, D, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`D` is depth or scale level, :math:`H` is height, and:math:`W` is width.@@ -611,14 +611,14 @@ def spatial_soft_argmax2d(not either peak.Args:- input: the given heatmap with shape :math:`(B, N, H, W)`.+ input: the given heatmap with shape ``(B, N, H, W)``.temperature: softmax temperature: the input is divided by it; smaller is sharper. Must be positive.``None`` means ``1.0``. A tensor temperature is not checked under ``torch.compile`` or export.normalized_coordinates: whether to return the coordinates normalized in the range of :math:`[-1, 1]`.Otherwise, it will return the coordinates in the range of the input shape.Returns:- the expected coordinates of each map with shape :math:`(B, N, 2)`.+ the expected coordinates of each map with shape ``(B, N, 2)``.Examples:>>> input = torch.tensor([[[@@ -663,7 +663,7 @@ class SpatialSoftArgmax2d(nn.Module):taking the hard argmax of each heatmap.Args:- input: Heatmap tensor with shape :math:`(B, C, H, W)`, where+ input: Heatmap tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`H` is height, and :math:`W` is width.@@ -899,7 +899,7 @@ def conv_quad_interp3d(than 3 is returned unrefined.Args:- input: response pyramid with shape :math:`(B, C, D, H, W)`.+ input: response pyramid with shape ``(B, C, D, H, W)``.n_iters: maximum number of localization iterations per keypoint. A keypoint that still moves on thelast iteration has not converged and is rejected: it keeps its grid coordinates and input value.strict_maxima_bonus: deprecated since kornia 0.9.0 and ignored; passing it emits a@@ -908,7 +908,7 @@ def conv_quad_interp3d(max_subpixel_shift: threshold above which the integer centre ismoved one step and another iteration is run.precomputed_nms_mask: optional bool tensor of shape- :math:`(B, C, D, H, W)` β pass the result of+ ``(B, C, D, H, W)`` β pass the result of:func:`~kornia.geometry.subpix.nms3d` to skip the internal NMS call.dilation_radius: L\ :math:`\infty` radius (in voxels) of the neighbourhoodaround each NMS maximum where the Hessian solve is precomputed.@@ -920,10 +920,10 @@ def conv_quad_interp3d(Returns:Tuple ``(coords_max, y_max)``:- * ``coords_max`` β shape :math:`(B, C, 3, D, H, W)`, refined+ * ``coords_max`` β shape ``(B, C, 3, D, H, W)``, refined``[scale, x(width), y(height)]`` coordinates for each NMS maximum;non-maximum positions keep their grid coordinates.- * ``y_max`` β shape :math:`(B, C, D, H, W)`, quadratically corrected+ * ``y_max`` β shape ``(B, C, D, H, W)``, quadratically correctedresponse at each NMS maximum; other positions keep the input value.Example:@@ -1194,7 +1194,7 @@ class ConvQuadInterp3d(nn.Module):offset gives a subpixel position in scale, x, and y coordinates.Args:- x: Response tensor with shape :math:`(B, C, D, H, W)`, where+ x: Response tensor with shape ``(B, C, D, H, W)``, where:math:`D` is the scale/depth dimension.precomputed_nms_mask: Optional boolean NMS mask with the same shapeas ``x``. Passing it avoids recomputing local maxima.@@ -1237,7 +1237,7 @@ def iterative_quad_interp3d(``dilation_radius`` neighbourhood.Args:- input: response pyramid with shape :math:`(B, C, D, H, W)`.+ input: response pyramid with shape ``(B, C, D, H, W)``.n_iters: maximum number of localization iterations per keypoint. A keypoint that still moves on thelast iteration has not converged and is rejected: it keeps its grid coordinates and input value.strict_maxima_bonus: deprecated since kornia 0.9.0 and ignored; passing it emits a@@ -1249,7 +1249,7 @@ def iterative_quad_interp3d(applied along the scale (depth) axis; set to ``False`` to keep thekeypoint on its original scale level.precomputed_nms_mask: optional bool tensor of shape- :math:`(B, C, D, H, W)` β pass the result of+ ``(B, C, D, H, W)`` β pass the result of:func:`~kornia.geometry.subpix.nms3d` to skip the internal NMS call.max_candidates: if given, only the top-``max_candidates`` NMS maxima (ranked bypre-refinement response) are processed. The rest keep their grid-coordinate@@ -1263,10 +1263,10 @@ def iterative_quad_interp3d(Returns:A tuple ``(coords_max, y_max)`` where- * ``coords_max`` has shape :math:`(B, C, 3, D, H, W)` and stores the refined+ * ``coords_max`` has shape ``(B, C, 3, D, H, W)`` and stores the refinedcoordinates ``[scale, x, y]`` for every position in the input.Non-NMS positions keep their original grid coordinates.- * ``y_max`` has shape :math:`(B, C, D, H, W)` and stores the quadratically+ * ``y_max`` has shape ``(B, C, D, H, W)`` and stores the quadraticallycorrected response values.Example:@@ -1499,7 +1499,7 @@ class IterativeQuadInterp3d(nn.Module):"""Refine 3D extrema by iteratively fitting local quadratic patches.Args:- x: Response tensor with shape :math:`(B, C, D, H, W)`.+ x: Response tensor with shape ``(B, C, D, H, W)``.precomputed_nms_mask: Optional boolean local-maxima mask with thesame shape as ``x``.@@ -1612,7 +1612,7 @@ class AdaptiveQuadInterp3d(nn.Module)::func:`conv_quad_interp3d` or :func:`iterative_quad_interp3d`.Args:- x: Response tensor with shape :math:`(B, C, D, H, W)`.+ x: Response tensor with shape ``(B, C, D, H, W)``.precomputed_nms_mask: Optional boolean local-maxima mask with thesame shape as ``x``.diff --git a/kornia/geometry/transform/affwarp.py b/kornia/geometry/transform/affwarp.pyindex d38fa6f6c..508122536 100644--- a/kornia/geometry/transform/affwarp.py+++ b/kornia/geometry/transform/affwarp.py@@ -164,11 +164,11 @@ def affine(See :doc:`Conventions & Pitfalls </get-started/conventions>` for the ``align_corners``defaults and sampling rules.- - ``matrix`` is the sourceβdestination **pixel** affine matrix :math:`(B, 2, 3)`+ - ``matrix`` is the sourceβdestination **pixel** affine matrix ``(B, 2, 3)``Args:tensor: The image tensor to be warped in shapes of- :math:`(C, H, W)` or :math:`(B, C, H, W)`.+ ``(C, H, W)`` or ``(B, C, H, W)``.matrix: The 2x3 affine transformation matrix.mode: interpolation mode to calculate output values ``'bilinear'`` | ``'nearest'``.padding_mode: padding mode for outside grid values@@ -223,13 +223,13 @@ def affine3d(r"""Apply an affine transformation to the 3d volume.Convention:- - ``matrix`` is the sourceβdestination **pixel** affine matrix :math:`(B, 3, 4)`+ - ``matrix`` is the sourceβdestination **pixel** affine matrix ``(B, 3, 4)``- align_corners: ``False`` by default (the 2D :func:`affine` defaults to ``True``)Args:tensor: The image tensor to be warped in shapes of- :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`.- matrix: The affine transformation matrix with shape :math:`(B, 3, 4)`.+ ``(C, D, H, W)`` or ``(B, C, D, H, W)``.+ matrix: The affine transformation matrix with shape ``(B, 3, 4)``.mode: interpolation mode to calculate output values``'bilinear'`` | ``'nearest'``.padding_mode: padding mode for outside grid values@@ -290,7 +290,7 @@ def rotate(- positive ``angle`` rotates counter-clockwise as displayed (y-down image axes)Args:- tensor: The image tensor to be warped in shapes of :math:`(C, H, W)` or :math:`(B, C, H, W)`.+ tensor: The image tensor to be warped in shapes of ``(C, H, W)`` or ``(B, C, H, W)``.angle: The angle through which to rotate. The tensormust have a shape of (B), where B is batch size.center: The center through which to rotate. The tensor@@ -383,7 +383,7 @@ def rotate3d(- align_corners: ``False`` by default (the 2D :func:`rotate` defaults to ``True``)Args:- tensor: The image tensor to be warped in shapes of :math:`(C, D, H, W)` or :math:`(B, C, D, H, W)`.+ tensor: The image tensor to be warped in shapes of ``(C, D, H, W)`` or ``(B, C, D, H, W)``.yaw: The ``rx`` component of the axis-angle vector. The tensormust have a shape of (B), where B is batch size.pitch: The ``ry`` component of the axis-angle vector. The tensor@@ -453,7 +453,7 @@ def translate(- ``translation`` is ``(dx, dy)`` in pixelsArgs:- tensor: The image tensor to be warped in shapes of :math:`(B, C, H, W)`.+ tensor: The image tensor to be warped in shapes of ``(B, C, H, W)``.translation: tensor containing the amount of pixels totranslate in the x and y direction. The tensor must have a shape of(B, 2), where B is batch size, last dimension contains dx dy.@@ -506,7 +506,7 @@ def scale(- ``center`` is ``(x, y)`` in pixels, origin at top-left; defaults to the tensor centerArgs:- tensor: The image tensor to be warped in shapes of :math:`(C, H, W)` or :math:`(B, C, H, W)`.+ tensor: The image tensor to be warped in shapes of ``(C, H, W)`` or ``(B, C, H, W)``.scale_factor: The scale factor apply. The tensormust have a shape of (B) or (B, 2), where B is batch size.If (B), isotropic scaling will perform.@@ -577,7 +577,7 @@ def shear(:class:`Shear`, which default to ``True``)Args:- tensor: The image tensor to be skewed with shape of :math:`(B, C, H, W)`.+ tensor: The image tensor to be skewed with shape of ``(B, C, H, W)``.shear: tensor containing raw shear factorsin the x and y direction about pixel (0, 0). The tensor must have a shape of(B, 2), where B is batch size, last dimension contains shx shy.@@ -643,13 +643,13 @@ def resize(conventions. When resizing camera images, see:doc:`camera and world conventions </get-started/camera-conventions>` for matching intrinsics scaling.- - input: :math:`(*, H, W)`; ``size`` is ``(h, w)``+ - input: ``(*, H, W)``; ``size`` is ``(h, w)``- align_corners: ``None`` by default (follows ``torch.nn.functional.interpolate``;note :func:`warp_perspective`/:func:`rotate` default ``True``)- ``side`` resizing preserves aspect ratio using the named sideArgs:- input: The image tensor to be skewed with shape of :math:`(..., H, W)`.+ input: The image tensor to be skewed with shape of ``(..., H, W)``.`...` means there can be any number of dimensions.size: Desired output size. If size is a sequence like (h, w),output size will be matched to this. If size is an int, smaller edge of the image will@@ -822,7 +822,7 @@ def rescale(when ``factor`` is not a power of two (``0.7`` at a side of 90 gives 63, eager 62)Args:- input: The image tensor to be scale with shape of :math:`(B, C, H, W)`.+ input: The image tensor to be scale with shape of ``(B, C, H, W)``.factor: Desired scaling factor as ``(factor_h, factor_w)`` β height first. If a singlefloat, the value is used for both height and width (an ``int`` raises ``TypeError``).interpolation: algorithm used for upsampling: ``'nearest'`` | ``'nearest-exact'`` | ``'bilinear'`` |@@ -923,7 +923,7 @@ class Resize(nn.Module):"""Resize the spatial dimensions of an image or feature tensor.Args:- input: Tensor with image-like layout :math:`(*, C, H, W)`, where+ input: Tensor with image-like layout ``(*, C, H, W)``, where``*`` represents optional leading batch dimensions,:math:`C` is channels, :math:`H` is height, and :math:`W` iswidth.@@ -1045,12 +1045,12 @@ class Affine(nn.Module):passed to :func:`affine` for sampling.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`H` is height, and :math:`W` is width.Returns:- Affine-warped tensor with shape :math:`(B, C, H, W)`. Values+ Affine-warped tensor with shape ``(B, C, H, W)``. Valuessampled outside the input image are handled by ``self.padding_mode``."""if self.shear is None:@@ -1113,7 +1113,7 @@ class Rescale(nn.Module):"""Resize spatial dimensions by the stored scale factor.Args:- input: Tensor with shape :math:`(*, C, H, W)`, where ``*`` is any+ input: Tensor with shape ``(*, C, H, W)``, where ``*`` is anyleading batch shape, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -1178,12 +1178,12 @@ class Rotate(nn.Module):"""Rotate an image batch around the configured center.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.Returns:- Rotated tensor with shape :math:`(B, C, H, W)`. The image extent is+ Rotated tensor with shape ``(B, C, H, W)``. The image extent iskept fixed; newly exposed pixels are filled according to``self.padding_mode``."""@@ -1235,12 +1235,12 @@ class Translate(nn.Module):"""Shift an image batch by the stored pixel translation.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.Returns:- Translated tensor with shape :math:`(B, C, H, W)`. Translation is+ Translated tensor with shape ``(B, C, H, W)``. Translation ismeasured in pixels along the x and y image axes."""return translate(input, self.translation, self.mode, self.padding_mode, self.align_corners)@@ -1297,7 +1297,7 @@ class Scale(nn.Module):"""Scale an image batch around the configured center point.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -1351,12 +1351,12 @@ class Shear(nn.Module):"""Skew an image batch with the configured x/y shear factors.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.Returns:- Sheared tensor with shape :math:`(B, C, H, W)`. The output image+ Sheared tensor with shape ``(B, C, H, W)``. The output imagesize is unchanged; pixels outside the sampled area use theconfigured padding mode."""diff --git a/kornia/geometry/transform/crop2d.py b/kornia/geometry/transform/crop2d.pyindex cb1e0087d..cbf60e0bf 100644--- a/kornia/geometry/transform/crop2d.py+++ b/kornia/geometry/transform/crop2d.py@@ -54,8 +54,8 @@ def crop_and_resize(See :doc:`Conventions & Pitfalls </get-started/conventions>` for the ``align_corners``defaults and sampling rules.- - input: :math:`(B, C, H, W)`; ``size`` is ``(h, w)``- - ``boxes``: :math:`(B, 4, 2)` corner points in ``(x, y)`` order+ - input: ``(B, C, H, W)``; ``size`` is ``(h, w)``+ - ``boxes``: ``(B, 4, 2)`` corner points in ``(x, y)`` ordertop-left, top-right, bottom-right, bottom-left; coordinates are**inclusive** pixel positions (box ``(1, 1)``..``(2, 2)`` selects a:math:`2 \times 2` pixel block), origin at top-left@@ -165,7 +165,7 @@ def center_crop(r"""Crop the 2D images (4D torch.Tensor) from the center.Convention:- - input: :math:`(B, C, H, W)` (strictly 4D β no unbatched ``(C, H, W)``/+ - input: ``(B, C, H, W)`` (strictly 4D β no unbatched ``(C, H, W)``/``(H, W)`` input is accepted); ``size`` is ``(h, w)``- offset: the crop starts at the integer pixel ``int(H / 2 - h / 2)`` (likewise for the width), as in:class:`CenterCrop2D`, so the output is a sub-image of the input. With an odd margin the extra pixel is@@ -262,8 +262,8 @@ def crop_by_boxes(the bounding boxes in a batch must be rectangles with same width and height.Convention:- - input: :math:`(B, C, H, W)`- - ``src_box``/``dst_box``: :math:`(B, 4, 2)` corner points in ``(x, y)`` order+ - input: ``(B, C, H, W)``+ - ``src_box``/``dst_box``: ``(B, 4, 2)`` corner points in ``(x, y)`` ordertop-left, top-right, bottom-right, bottom-left β same convention as:func:`crop_and_resize`; ``dst_box`` determines the output resolution- a single box (batch size 1) broadcasts over a batch of images, but a single@@ -368,11 +368,11 @@ def crop_by_transform_mat("""Perform crop transform on 2D images (4D torch.Tensor) given a perspective transformation matrix.Convention:- - input: :math:`(B, C, H, W)`; ``out_size`` is ``(h, w)``+ - input: ``(B, C, H, W)``; ``out_size`` is ``(h, w)``- ``transform`` is the sourceβdestination **pixel** transform, accepted as- either :math:`(B, 2, 3)` affine or :math:`(B, 3, 3)` homogeneous; dispatch is- by shape β :math:`(B, 2, 3)` takes the cheaper :func:`warp_affine` path,- while :math:`(B, 3, 3)` takes :func:`warp_perspective` and uses the **full**+ either ``(B, 2, 3)`` affine or ``(B, 3, 3)`` homogeneous; dispatch is+ by shape β ``(B, 2, 3)`` takes the cheaper :func:`warp_affine` path,+ while ``(B, 3, 3)`` takes :func:`warp_perspective` and uses the **full**matrix, so a non-trivial third (projective) row changes the output; an``out_size`` dimension of ``1`` is handled like any other size@@ -435,7 +435,7 @@ def _crop_inverse_by_transform_mat(only pixel, so the whole canvas axis gets its value, and with ``False`` it blends it into the next pixel. Onepixel of padding on each side of such an axis, in the warp's own padding (a reflected one-pixel axis repeatsits pixel), gives the sampler a neighbour to interpolate towards, and ``transform`` is shifted to match.- ``transform`` is the :math:`(B, 3, 3)` crop-to-canvas pixel matrix.+ ``transform`` is the ``(B, 3, 3)`` crop-to-canvas pixel matrix."""pad_h = int(input_tensor.shape[-2] == 1)pad_w = int(input_tensor.shape[-1] == 1)@@ -461,9 +461,9 @@ def crop_by_indices("""Crop tensors with naive indices.Convention:- - input: :math:`(B, C, H, W)`; ``size`` is ``(h, w)`` if given, else inferred+ - input: ``(B, C, H, W)``; ``size`` is ``(h, w)`` if given, else inferredfrom ``src_box``- - ``src_box``: :math:`(B, 4, 2)` corner points in ``(x, y)`` order top-left,+ - ``src_box``: ``(B, 4, 2)`` corner points in ``(x, y)`` order top-left,top-right, bottom-right, bottom-left β same convention as :func:`crop_and_resize`- unlike the other crop operators in this module: ``interpolation=`` (not``mode=``), ``align_corners=None`` by default (not ``True``), and an@@ -727,7 +727,7 @@ class CenterCrop2D(nn.Module):perspective-resampling (subpixel/interpolated) or by direct slicing.Args:- input: Image batch with shape :math:`(B, C, H, W)`, where+ input: Image batch with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` issource height, and :math:`W` is source width.diff --git a/kornia/geometry/transform/crop3d.py b/kornia/geometry/transform/crop3d.pyindex 5283c85b5..3a0a865dd 100644--- a/kornia/geometry/transform/crop3d.py+++ b/kornia/geometry/transform/crop3d.py@@ -36,8 +36,8 @@ def crop_and_resize3d(r"""Extract crops from 3D volumes (5D tensor) and resize them.Convention:- - input: :math:`(B, C, D, H, W)`; ``size`` is ``(d, h, w)``- - ``boxes``: :math:`(B, 8, 3)` corner points in ``(x, y, z)`` order, front face+ - input: ``(B, C, D, H, W)``; ``size`` is ``(d, h, w)``+ - ``boxes``: ``(B, 8, 3)`` corner points in ``(x, y, z)`` order, front facethen back face, each face top-left, top-right, bottom-right, bottom-left βsame ``(x, y)``/inclusive-pixel convention as :func:`crop_and_resize`, with``z`` anchored at the top-left of the first depth slice (``z = 0``);@@ -144,7 +144,7 @@ def center_crop3d(r"""Crop the 3D volumes (5D tensor) at the center.Convention:- - input: :math:`(B, C, D, H, W)`; ``size`` is ``(d, h, w)``+ - input: ``(B, C, D, H, W)``; ``size`` is ``(d, h, w)``- align_corners: ``True`` by default- offset: the crop starts at the integer voxel ``int(D / 2 - d / 2)`` (likewise for the height and width),as in :class:`~kornia.augmentation.CenterCrop3D`, so with the default ``align_corners=True`` the output is a@@ -284,8 +284,8 @@ def crop_by_boxes3d(in a batch must be rectangles with same width, height and depth.Convention:- - input: :math:`(B, C, D, H, W)`- - ``src_box``/``dst_box``: :math:`(B, 8, 3)` corner points in ``(x, y, z)``+ - input: ``(B, C, D, H, W)``+ - ``src_box``/``dst_box``: ``(B, 8, 3)`` corner points in ``(x, y, z)``order, front face then back face, each face top-left, top-right,bottom-right, bottom-left β same convention as :func:`crop_and_resize3d`;``dst_box`` determines the output resolution@@ -405,9 +405,9 @@ def crop_by_transform_mat3d("""Perform crop transform on 3D volumes (5D tensor) given a perspective transformation matrix.Convention:- - input: :math:`(B, C, D, H, W)`; ``out_size`` is ``(d, h, w)``+ - input: ``(B, C, D, H, W)``; ``out_size`` is ``(d, h, w)``- ``transform`` is the sourceβdestination **pixel** transform, accepted as- either :math:`(B, 3, 4)` affine or :math:`(B, 4, 4)` homogeneous; only the top+ either ``(B, 3, 4)`` affine or ``(B, 4, 4)`` homogeneous; only the topthree rows are used, so a projective last row is ignored (unlike the 2D:func:`crop_by_transform_mat`)- align_corners: ``True`` by defaultdiff --git a/kornia/geometry/transform/elastic_transform.py b/kornia/geometry/transform/elastic_transform.pyindex 89ad44fa0..3b5d35a2d 100644--- a/kornia/geometry/transform/elastic_transform.py+++ b/kornia/geometry/transform/elastic_transform.py@@ -44,7 +44,7 @@ def elastic_transform2d(.. image:: _static/img/elastic_transform2d.pngConvention:- - image: :math:`(B, C, H, W)`; ``noise``: :math:`(B, 2, H, W)` with+ - image: ``(B, C, H, W)``; ``noise``: ``(B, 2, H, W)`` withchannel 0 the x- and channel 1 the y-displacement of the samplinggrid (positive x-noise shifts image content left)- displacements are smoothed with a Gaussian (``kernel_size``,@@ -55,9 +55,9 @@ def elastic_transform2d(zeros, the edge value, or the reflected imageArgs:- image: Input image to be transformed with shape :math:`(B, C, H, W)`.+ image: Input image to be transformed with shape ``(B, C, H, W)``.noise: Noise image used to spatially transform the input image. Same- resolution as the input image with shape :math:`(B, 2, H, W)`. The coordinates order+ resolution as the input image with shape ``(B, 2, H, W)``. The coordinates orderit is expected to be in x-y.kernel_size: the size of the Gaussian kernel, in the y and x directions, respectively.sigma: The standard deviation of the Gaussian in the y and x directions,@@ -69,7 +69,7 @@ def elastic_transform2d(padding_mode: The padding used by ``grid_sample``. Either ``'zeros'``, ``'border'`` or ``'reflection'``.Returns:- the elastically transformed input image with shape :math:`(B,C,H,W)`.+ the elastically transformed input image with shape ``(B,C,H,W)``.Example:>>> image = torch.rand(1, 3, 5, 5)diff --git a/kornia/geometry/transform/flips.py b/kornia/geometry/transform/flips.pyindex 660dccbce..c74bef934 100644--- a/kornia/geometry/transform/flips.py+++ b/kornia/geometry/transform/flips.py@@ -52,7 +52,7 @@ class Vflip(nn.Module):Args:input: Tensor containing one image or a batch of images, typically- shaped :math:`(*, C, H, W)`, where :math:`H` is height and+ shaped ``(*, C, H, W)``, where :math:`H` is height and:math:`W` is width.Returns:@@ -96,7 +96,7 @@ class Hflip(nn.Module):Args:input: Tensor containing one image or a batch of images, typically- shaped :math:`(*, C, H, W)`, where :math:`H` is height and+ shaped ``(*, C, H, W)``, where :math:`H` is height and:math:`W` is width.Returns:@@ -137,7 +137,7 @@ class Rot180(nn.Module):Args:input: Tensor containing one image or a batch of images, typically- shaped :math:`(*, C, H, W)`, where :math:`H` is height and+ shaped ``(*, C, H, W)``, where :math:`H` is height and:math:`W` is width.Returns:@@ -158,8 +158,8 @@ def rot180(input: torch.Tensor) -> torch.Tensor:Convention:- flips both the height and width axes (equivalent to :func:`vflip` followed by:func:`hflip`)- - requires rank β₯ 2: unbatched :math:`(H, W)`/:math:`(C, H, W)` or batched- :math:`(*, C, H, W)` all work+ - requires rank β₯ 2: unbatched ``(H, W)``/``(C, H, W)`` or batched+ ``(*, C, H, W)`` all workArgs:input: input torch.Tensor.@@ -197,8 +197,8 @@ def vflip(input: torch.Tensor) -> torch.Tensor:Convention:- flips along the height axis (the second-to-last dimension)- - requires rank β₯ 2 (operates on dim ``-2``): unbatched :math:`(H, W)`/- :math:`(C, H, W)` or batched :math:`(*, C, H, W)` all work+ - requires rank β₯ 2 (operates on dim ``-2``): unbatched ``(H, W)``/+ ``(C, H, W)`` or batched ``(*, C, H, W)`` all workArgs:input: input torch.Tensor.diff --git a/kornia/geometry/transform/homography_warper.py b/kornia/geometry/transform/homography_warper.pyindex 67b6f97f8..88c601e5c 100644--- a/kornia/geometry/transform/homography_warper.py+++ b/kornia/geometry/transform/homography_warper.py@@ -50,10 +50,10 @@ class BaseWarper(nn.Module):Args:patch_src: Source image or patch tensor with shape- :math:`(B, C, H, W)`, where :math:`B` is batch size,+ ``(B, C, H, W)``, where :math:`B` is batch size,:math:`C` is channels, :math:`H` is source height, and:math:`W` is source width.- src_homo_dst: Optional homography with shape :math:`(B, 3, 3)`+ src_homo_dst: Optional homography with shape ``(B, 3, 3)``mapping destination coordinates into the source image. Concreteimplementations may also use a grid precomputed from thismatrix.@@ -68,7 +68,7 @@ class BaseWarper(nn.Module):"""Precompute a sampling grid for repeated homography warps.Args:- src_homo_dst: Homography tensor with shape :math:`(B, 3, 3)` used+ src_homo_dst: Homography tensor with shape ``(B, 3, 3)`` usedto transform destination grid points into source coordinates."""...@@ -142,7 +142,7 @@ class HomographyWarper(BaseWarper):Args:src_homo_dst: Homography or homographies (stacked) totransform all points in the grid. Shape of the homography- has to be :math:`(1, 3, 3)`, :math:`(N, 3, 3)` or :math:`(N, 1, 3, 3)`.+ has to be ``(1, 3, 3)``, ``(N, 3, 3)`` or ``(N, 1, 3, 3)``.The homography assumes normalized coordinates [-1, 1] ifnormalized_coordinates is True, and pixel coordinates otherwise.@@ -170,8 +170,8 @@ class HomographyWarper(BaseWarper):Patch sampled at locations from source to destination.Shape:- - Input: :math:`(N, C, H, W)` and :math:`(N, 3, 3)`- - Output: :math:`(N, C, H, W)`+ - Input: ``(N, C, H, W)`` and ``(N, 3, 3)``+ - Output: ``(N, C, H, W)``Example:>>> input = torch.rand(1, 3, 32, 32)diff --git a/kornia/geometry/transform/image_registrator.py b/kornia/geometry/transform/image_registrator.pyindex ce04078a6..627fe53e8 100644--- a/kornia/geometry/transform/image_registrator.py+++ b/kornia/geometry/transform/image_registrator.py@@ -81,7 +81,7 @@ class Homography(BaseModel):r"""Single-batch homography, scaled so that its ``[2, 2]`` entry is 1.Returns:- Homography matrix with shape :math:`(1, 3, 3)`.+ Homography matrix with shape ``(1, 3, 3)``."""return torch.unsqueeze(self.model / self.model[2, 2], dim=0) # 1x3x3@@ -90,7 +90,7 @@ class Homography(BaseModel):r"""Inverted single-batch homography.Returns:- Homography matrix with shape :math:`(1, 3, 3)`.+ Homography matrix with shape ``(1, 3, 3)``."""return torch.unsqueeze(_torch_inverse_cast(self.model), dim=0)@@ -163,7 +163,7 @@ class Similarity(BaseModel):r"""Single-batch similarity transform.Returns:- Similarity with shape :math:`(1, 3, 3)`+ Similarity with shape ``(1, 3, 3)``"""rot = self.scale * angle_to_rotation_matrix(self.rot)@@ -178,7 +178,7 @@ class Similarity(BaseModel):r"""Single-batch inverse similarity transform.Returns:- Similarity with shape :math:`(1, 3, 3)`+ Similarity with shape ``(1, 3, 3)``"""return _torch_inverse_cast(self.forward())diff --git a/kornia/geometry/transform/imgwarp.py b/kornia/geometry/transform/imgwarp.pyindex 7672c1ecd..839984d46 100644--- a/kornia/geometry/transform/imgwarp.py+++ b/kornia/geometry/transform/imgwarp.py@@ -275,8 +275,8 @@ def warp_perspective(See :doc:`Conventions & Pitfalls </get-started/conventions>` for transform direction, pixel centres,normalized coordinates and ``align_corners`` sampling rules.- - input: :math:`(B, C, H, W)`; ``dsize`` is ``(h, w)``- - ``M`` is the sourceβdestination **pixel** homography :math:`(B, 3, 3)`+ - input: ``(B, C, H, W)``; ``dsize`` is ``(h, w)``+ - ``M`` is the sourceβdestination **pixel** homography ``(B, 3, 3)``(contrast :func:`homography_warp`, which by default consumes destinationβsource normalized)- a nonzero scalar multiple of ``M`` describes the same warp; uniformly small or largenonzero entries are rescaled toward unit magnitude before the coordinate change and inversion@@ -284,15 +284,15 @@ def warp_perspective(negative output dimensions raise ``ValueError``Args:- src: input image with shape :math:`(B, C, H, W)`.- M: transformation matrix with shape :math:`(B, 3, 3)`.+ src: input image with shape ``(B, C, H, W)``.+ M: transformation matrix with shape ``(B, 3, 3)``.dsize: size of the output image (height, width).mode: interpolation mode to calculate output values ``'bilinear'`` | ``'nearest'``.padding_mode: padding mode for outside grid values ``'zeros'`` | ``'border'`` | ``'reflection'``| ``'fill'``.align_corners: interpolation flag.- fill_value: torch.Tensor of shape :math:`(C)` or :math:`(1)` that fills the padding area, or any shape that- broadcasts to the output :math:`(B, C, h, w)` without changing it, such as a per-sample :math:`(B, C, 1, 1)`+ fill_value: torch.Tensor of shape ``(C)`` or ``(1)`` that fills the padding area, or any shape that+ broadcasts to the output :math:`(B, C, h, w)` without changing it, such as a per-sample ``(B, C, 1, 1)``fill. Defaults to zeros.Returns:@@ -408,21 +408,21 @@ def warp_affine(See :doc:`Conventions & Pitfalls </get-started/conventions>` for transform direction, pixel centres,normalized coordinates and ``align_corners`` sampling rules.- - input: :math:`(B, C, H, W)`; ``dsize`` is ``(h, w)``- - ``M`` is the sourceβdestination **pixel** affine matrix :math:`(B, 2, 3)`+ - input: ``(B, C, H, W)``; ``dsize`` is ``(h, w)``+ - ``M`` is the sourceβdestination **pixel** affine matrix ``(B, 2, 3)``- a zero output dimension returns an autograd-connected empty tensor;negative output dimensions raise ``ValueError``Args:- src: input torch.Tensor of shape :math:`(B, C, H, W)`.- M: affine transformation of shape :math:`(B, 2, 3)`.+ src: input torch.Tensor of shape ``(B, C, H, W)``.+ M: affine transformation of shape ``(B, 2, 3)``.dsize: size of the output image (height, width).mode: interpolation mode to calculate output values ``'bilinear'`` | ``'nearest'``.padding_mode: padding mode for outside grid values ``'zeros'`` | ``'border'`` | ``'reflection'``| ``'fill'``.align_corners : mode for grid_generation.- fill_value: torch.Tensor of shape :math:`(C)` or :math:`(1)` that fills the padding area, or any shape that- broadcasts to the output :math:`(B, C, h, w)` without changing it, such as a per-sample :math:`(B, C, 1, 1)`+ fill_value: torch.Tensor of shape ``(C)`` or ``(1)`` that fills the padding area, or any shape that+ broadcasts to the output :math:`(B, C, h, w)` without changing it, such as a per-sample ``(B, C, 1, 1)``fill.Returns:@@ -545,18 +545,18 @@ def _fill_and_warp(r"""Warp a mask of torch.ones, then multiply with fill_value and add to default warp.Args:- src: input torch.Tensor of shape :math:`(B, C, H, W)`.+ src: input torch.Tensor of shape ``(B, C, H, W)``.grid: grid torch.Tensor from `transform_points`.mode: interpolation mode to calculate output values ``'bilinear'`` | ``'nearest'``.align_corners: interpolation flag.- fill_value: torch.Tensor of shape :math:`(C)` or :math:`(1)` that fills the padding area, or any shape that- broadcasts to the output :math:`(B, C, H, W)` without changing it, such as :math:`(B, C, 1, 1)`.+ fill_value: torch.Tensor of shape ``(C)`` or ``(1)`` that fills the padding area, or any shape that+ broadcasts to the output ``(B, C, H, W)`` without changing it, such as ``(B, C, 1, 1)``.out_shape: the output shape ``fill_value`` is checked against, when ``src`` and ``grid`` stand in for anempty destination; the fill is then reduced to one value. Defaults to the shape sampled from ``src``and ``grid``.Returns:- the warped and filled torch.Tensor with shape :math:`(B, C, H, W)`.+ the warped and filled torch.Tensor with shape ``(B, C, H, W)``."""stand_in = out_shape is not Noneif out_shape is None:@@ -601,10 +601,10 @@ def warp_grid(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:r"""Transform a 2D (x, y) coordinate grid by destinationβsource (N, 3, 3) homographies.Convention:- - ``grid`` coordinates: ``(x, y)`` (last dim), shape :math:`(1, H, W, 2)` or :math:`(N, H, W, 2)`- - ``src_homo_dst`` is the destinationβsource homography :math:`(1, 3, 3)`,- :math:`(N, 3, 3)` or :math:`(N, 1, 3, 3)`- - only the :math:`(1, H, W, 2)` grid broadcasts over homography batches; a batched grid+ - ``grid`` coordinates: ``(x, y)`` (last dim), shape ``(1, H, W, 2)`` or ``(N, H, W, 2)``+ - ``src_homo_dst`` is the destinationβsource homography ``(1, 3, 3)``,+ ``(N, 3, 3)`` or ``(N, 1, 3, 3)``+ - only the ``(1, H, W, 2)`` grid broadcasts over homography batches; a batched gridrequires a matching batch of :math:`N` homographies- ``src_homo_dst`` is divided by a detached scale toward unit magnitude before thehomogeneous division, as in :func:`warp_perspective`, so a nonzero scalar multiple of it@@ -614,14 +614,14 @@ def warp_grid(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:infinityArgs:- grid: Unwrapped grid of the shape :math:`(1, H, W, 2)`, or :math:`(N, H, W, 2)` with a+ grid: Unwrapped grid of the shape ``(1, H, W, 2)``, or ``(N, H, W, 2)`` with amatching batch of :math:`N` homographies.src_homo_dst: Homography or homographies (stacked) totransform all points in the grid. Shape of the homography- has to be :math:`(1, 3, 3)`, :math:`(N, 3, 3)` or :math:`(N, 1, 3, 3)`.+ has to be ``(1, 3, 3)``, ``(N, 3, 3)`` or ``(N, 1, 3, 3)``.Returns:- the transformed grid of shape :math:`(N, H, W, 2)`.+ the transformed grid of shape ``(N, H, W, 2)``."""batch_size: int = src_homo_dst.size(0)@@ -687,11 +687,11 @@ def warp_grid3d(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:r"""Transform a 3D (x, y, z) coordinate grid by destinationβsource (N, 4, 4) homographies.Convention:- - ``grid`` coordinates: ``(x, y, z)`` (last dim), shape :math:`(1, D, H, W, 3)` or- :math:`(N, D, H, W, 3)`- - ``src_homo_dst`` is the destinationβsource homography :math:`(1, 4, 4)`,- :math:`(N, 4, 4)` or :math:`(N, 1, 4, 4)`- - only the :math:`(1, D, H, W, 3)` grid broadcasts over homography batches; a batched+ - ``grid`` coordinates: ``(x, y, z)`` (last dim), shape ``(1, D, H, W, 3)`` or+ ``(N, D, H, W, 3)``+ - ``src_homo_dst`` is the destinationβsource homography ``(1, 4, 4)``,+ ``(N, 4, 4)`` or ``(N, 1, 4, 4)``+ - only the ``(1, D, H, W, 3)`` grid broadcasts over homography batches; a batchedgrid requires a matching batch of :math:`N` homographies- ``src_homo_dst`` is divided by a detached scale toward unit magnitude before thehomogeneous division, as in :func:`warp_perspective`, so a nonzero scalar multiple of it@@ -701,14 +701,14 @@ def warp_grid3d(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:infinityArgs:- grid: Unwrapped grid of the shape :math:`(1, D, H, W, 3)`, or :math:`(N, D, H, W, 3)`+ grid: Unwrapped grid of the shape ``(1, D, H, W, 3)``, or ``(N, D, H, W, 3)``with a matching batch of :math:`N` homographies.src_homo_dst: Homography or homographies (stacked) totransform all points in the grid. Shape of the homography- has to be :math:`(1, 4, 4)`, :math:`(N, 4, 4)` or :math:`(N, 1, 4, 4)`.+ has to be ``(1, 4, 4)``, ``(N, 4, 4)`` or ``(N, 1, 4, 4)``.Returns:- the transformed grid of shape :math:`(N, D, H, W, 3)`.+ the transformed grid of shape ``(N, D, H, W, 3)``."""batch_size: int = src_homo_dst.size(0)@@ -732,7 +732,7 @@ def _warp_pixel_grid3d(src_homo_dst: torch.Tensor, depth: int, height: int, widtThe 3-D counterpart of :func:`_warp_pixel_grid`: the grid is built and warped in :func:`_pixel_grid_work_dtype`,whatever the default dtype, with the projective gauge and homogeneous division of :func:`warp_grid3d`, as a sum ofelementwise column products that a caller's autocast region leaves alone, scripted or not. The result is- :math:`(N, D, H, W, 3)` in the ``(x, y, z)`` order the homography and ``grid_sample`` read.+ ``(N, D, H, W, 3)`` in the ``(x, y, z)`` order the homography and ``grid_sample`` read."""work_dtype = _pixel_grid_work_dtype(src_homo_dst)grid = create_meshgrid3d(@@ -875,18 +875,18 @@ def get_perspective_transform(points_src: torch.Tensor, points_dst: torch.Tensor\end{bmatrix}Convention:- - points: ``(x, y)``, pixel centers, origin at top-left; shape :math:`(B, 4, 2)`- - returns the sourceβdestination **pixel** homography :math:`(B, 3, 3)` that+ - points: ``(x, y)``, pixel centers, origin at top-left; shape ``(B, 4, 2)``+ - returns the sourceβdestination **pixel** homography ``(B, 3, 3)`` that:func:`warp_perspective` takes- a caller's autocast region does not change the result, outside TorchScriptArgs:- points_src: coordinates of quadrangle vertices in the source image with shape :math:`(B, 4, 2)`.+ points_src: coordinates of quadrangle vertices in the source image with shape ``(B, 4, 2)``.points_dst: coordinates of the corresponding quadrangle vertices in- the destination image with shape :math:`(B, 4, 2)`.+ the destination image with shape ``(B, 4, 2)``.Returns:- the perspective transformation with shape :math:`(B, 3, 3)`.+ the perspective transformation with shape ``(B, 3, 3)``... note::This function is often used in conjunction with :func:`warp_perspective`.@@ -940,17 +940,17 @@ def get_rotation_matrix2d(center: torch.Tensor, angle: torch.Tensor, scale: torcConvention:- ``center`` is ``(x, y)`` in pixels, origin at top-left- positive ``angle`` rotates counter-clockwise as displayed (y-down image axes)- - returns :math:`(B, 2, 3)` affine matrix in pixel coordinates+ - returns ``(B, 2, 3)`` affine matrix in pixel coordinatesArgs:- center: center of the rotation in the source image with shape :math:`(B, 2)`.+ center: center of the rotation in the source image with shape ``(B, 2)``.angle: rotation angle in degrees. Positive values meancounter-clockwise rotation (the coordinate origin is assumed to- be the top-left corner) with shape :math:`(B)`.- scale: scale factor for x, y scaling with shape :math:`(B, 2)`.+ be the top-left corner) with shape ``(B)``.+ scale: scale factor for x, y scaling with shape ``(B, 2)``.Returns:- the affine matrix of 2D rotation with shape :math:`(B, 2, 3)`.+ the affine matrix of 2D rotation with shape ``(B, 2, 3)``.Raises:TypeError: If any input is not a tensor.@@ -1038,7 +1038,7 @@ def remap(\text{dst}(x, y) = \text{src}(map_x(x, y), map_y(x, y))Convention:- - input: :math:`(B, C, H, W)`; ``map_x``/``map_y`` are :math:`(B, H, W)` pixel coordinates+ - input: ``(B, C, H, W)``; ``map_x``/``map_y`` are ``(B, H, W)`` pixel coordinatesunless ``normalized_coordinates=True``- align_corners: ``None`` by default, resolved to ``False`` internally- pixel maps are normalized with the ``align_corners=True`` convention whatever flag@@ -1137,15 +1137,15 @@ def invert_affine_transform(matrix: torch.Tensor) -> torch.Tensor:The result is also a 2x3 matrix of the same type as M.Convention:- - ``matrix`` is a :math:`(B, 2, 3)` affine transform in any coordinate convention+ - ``matrix`` is a ``(B, 2, 3)`` affine transform in any coordinate convention(pixel or normalized) β pure matrix inversion; the result stays in the input's conventionArgs:matrix: original affine transform. The torch.Tensor must be- in the shape of :math:`(B, 2, 3)`.+ in the shape of ``(B, 2, 3)``.Return:- the reverse affine transform with shape :math:`(B, 2, 3)`.+ the reverse affine transform with shape ``(B, 2, 3)``... note::This function is often used in conjunction with :func:`warp_affine`.@@ -1179,18 +1179,18 @@ def get_affine_matrix2d(before delegating to :func:`get_rotation_matrix2d`, whose convention is CCW-positive- ``sx`` and ``sy`` are angles in radians, using :func:`get_shear_matrix2d`'snegative-tangent, x-then-y shear about ``center``, applied before rotation, scale and translation- - returns :math:`(B, 3, 3)` affine matrix in pixel coordinates+ - returns ``(B, 3, 3)`` affine matrix in pixel coordinatesArgs:- translations: torch.Tensor containing the translation vector with shape :math:`(B, 2)`.- center: torch.Tensor containing the center vector with shape :math:`(B, 2)`.- scale: torch.Tensor containing the scale factor with shape :math:`(B, 2)`.- angle: torch.Tensor of angles in degrees :math:`(B)`.- sx: torch.Tensor containing the shear angle in radians in the x-direction with shape :math:`(B)`.- sy: torch.Tensor containing the shear angle in radians in the y-direction with shape :math:`(B)`.+ translations: torch.Tensor containing the translation vector with shape ``(B, 2)``.+ center: torch.Tensor containing the center vector with shape ``(B, 2)``.+ scale: torch.Tensor containing the scale factor with shape ``(B, 2)``.+ angle: torch.Tensor of angles in degrees ``(B)``.+ sx: torch.Tensor containing the shear angle in radians in the x-direction with shape ``(B)``.+ sy: torch.Tensor containing the shear angle in radians in the y-direction with shape ``(B)``.Returns:- the affine transformation matrix :math:`(B, 3, 3)`.+ the affine transformation matrix ``(B, 3, 3)``... note::This function is often used in conjunction with :func:`warp_affine`, :func:`warp_perspective`.@@ -1213,13 +1213,13 @@ def get_translation_matrix2d(translations: torch.Tensor) -> torch.Tensor:r"""Compose translation matrix from the components.Convention:- - ``translations`` is ``(dx, dy)`` in pixels; returns :math:`(B, 3, 3)` affine matrix in pixel coordinates+ - ``translations`` is ``(dx, dy)`` in pixels; returns ``(B, 3, 3)`` affine matrix in pixel coordinatesArgs:- translations: torch.Tensor containing the translation vector with shape :math:`(B, 2)`.+ translations: torch.Tensor containing the translation vector with shape ``(B, 2)``.Returns:- the affine transformation matrix :math:`(B, 3, 3)`.+ the affine transformation matrix ``(B, 3, 3)``... note::This function is often used in conjunction with :func:`warp_affine`, :func:`warp_perspective`.@@ -1252,7 +1252,7 @@ def get_shear_matrix2d(- ``sx`` and ``sy`` are angles in radians; about ``center = (cx, cy)``, the forward mapping is``x_out = x - tan(sx) * (y - cy)``, then ``y_out = y - tan(sy) * (x_out - cx)``.Pixel x increases rightward and y downward. This differs from :func:`shear`'s raw factors.- - returns :math:`(B, 3, 3)` affine matrix in pixel coordinates+ - returns ``(B, 3, 3)`` affine matrix in pixel coordinatesArgs:center: shearing center coordinates of (x, y).@@ -1260,7 +1260,7 @@ def get_shear_matrix2d(sy: shearing angle along y axis in radiansReturns:- params to be passed to the affine transformation with shape :math:`(B, 3, 3)`.+ params to be passed to the affine transformation with shape ``(B, 3, 3)``.Examples:>>> rng = torch.manual_seed(0)@@ -1313,24 +1313,24 @@ def get_affine_matrix3d(- ``angles`` are negated before delegating to :func:`get_projective_transform`, whose ownrotation convention follows the right-hand rule (see:func:`kornia.geometry.conversions.axis_angle_to_rotation_matrix`)- - returns :math:`(B, 4, 4)` affine matrix in pixel coordinates+ - returns ``(B, 4, 4)`` affine matrix in pixel coordinatesArgs:- translations: torch.Tensor containing the translation vector (dx,dy,dz) with shape :math:`(B, 3)`.- center: torch.Tensor containing the center vector (x,y,z) with shape :math:`(B, 3)`.- scale: torch.Tensor containing the scale factor with shape :math:`(B)`.+ translations: torch.Tensor containing the translation vector (dx,dy,dz) with shape ``(B, 3)``.+ center: torch.Tensor containing the center vector (x,y,z) with shape ``(B, 3)``.+ scale: torch.Tensor containing the scale factor with shape ``(B)``.angles: axis angle vector containing the rotation angles in degrees in the form- of (rx, ry, rz) with shape :math:`(B, 3)`. Internally it calls Rodrigues to compute+ of (rx, ry, rz) with shape ``(B, 3)``. Internally it calls Rodrigues to computethe rotation matrix from axis-angle.- sxy: torch.Tensor containing the shear factor in the xy-direction with shape :math:`(B)`.- sxz: torch.Tensor containing the shear factor in the xz-direction with shape :math:`(B)`.- syx: torch.Tensor containing the shear factor in the yx-direction with shape :math:`(B)`.- syz: torch.Tensor containing the shear factor in the yz-direction with shape :math:`(B)`.- szx: torch.Tensor containing the shear factor in the zx-direction with shape :math:`(B)`.- szy: torch.Tensor containing the shear factor in the zy-direction with shape :math:`(B)`.+ sxy: torch.Tensor containing the shear factor in the xy-direction with shape ``(B)``.+ sxz: torch.Tensor containing the shear factor in the xz-direction with shape ``(B)``.+ syx: torch.Tensor containing the shear factor in the yx-direction with shape ``(B)``.+ syz: torch.Tensor containing the shear factor in the yz-direction with shape ``(B)``.+ szx: torch.Tensor containing the shear factor in the zx-direction with shape ``(B)``.+ szy: torch.Tensor containing the shear factor in the zy-direction with shape ``(B)``.Returns:- the 3d affine transformation matrix :math:`(B, 4, 4)`.+ the 3d affine transformation matrix ``(B, 4, 4)``... note::This function is often used in conjunction with :func:`warp_perspective3d`.@@ -1383,7 +1383,7 @@ def get_shear_matrix3d(Convention:- ``center`` is ``(x, y, z)`` in pixels, origin at the top-left of the first depthslice (``z = 0``); it is a fixed point of the returned matrix for every combination of shears- - returns :math:`(B, 4, 4)` affine matrix in pixel coordinates+ - returns ``(B, 4, 4)`` affine matrix in pixel coordinatesArgs:center: shearing center coordinates of (x, y, z).@@ -1477,8 +1477,8 @@ def warp_affine3d(This API signature it is experimental and might suffer some changes in the future.Convention:- - input: :math:`(B, C, D, H, W)`; ``dsize`` is ``(d, h, w)``- - ``M`` is the sourceβdestination **pixel** affine matrix :math:`(B, 3, 4)`+ - input: ``(B, C, D, H, W)``; ``dsize`` is ``(d, h, w)``+ - ``M`` is the sourceβdestination **pixel** affine matrix ``(B, 3, 4)``- align_corners: ``True`` by default- padding_mode: ``'zeros'`` by default- an empty batch returns shape :math:`(0, C, d, h, w)` with gradients connected to both inputs@@ -1488,8 +1488,8 @@ def warp_affine3d(- a nonempty batch requires positive source spatial dimensions for a nonempty outputArgs:- src : input torch.Tensor of shape :math:`(B, C, D, H, W)`.- M: projective transformation matrix of shape :math:`(B, 3, 4)`.+ src : input torch.Tensor of shape ``(B, C, D, H, W)``.+ M: projective transformation matrix of shape ``(B, 3, 4)``.dsize: size of the output image (depth, height, width).flags: interpolation mode to calculate output values``'bilinear'`` | ``'nearest'``.@@ -1550,14 +1550,14 @@ def projection_from_Rt(rmat: torch.Tensor, tvec: torch.Tensor) -> torch.Tensor:Concatenates the batch of rotations and translations such that :math:`P = [R | t]`.Convention:- - returns the concatenation :math:`[R | t]` with shape :math:`(*, 3, 4)`+ - returns the concatenation :math:`[R | t]` with shape ``(*, 3, 4)``Args:- rmat: the rotation matrix with shape :math:`(*, 3, 3)`.- tvec: the translation vector with shape :math:`(*, 3, 1)`.+ rmat: the rotation matrix with shape ``(*, 3, 3)``.+ tvec: the translation vector with shape ``(*, 3, 1)``.Returns:- the projection matrix with shape :math:`(*, 3, 4)`.+ the projection matrix with shape ``(*, 3, 4)``."""if not (len(rmat.shape) >= 2 and rmat.shape[-2:] == (3, 3)):@@ -1582,17 +1582,17 @@ def get_projective_transform(center: torch.Tensor, angles: torch.Tensor, scales:- rotation follows the right-hand rule (see:func:`kornia.geometry.conversions.axis_angle_to_rotation_matrix`); a positive rotationabout +z is **clockwise on screen** (y-down image axes) β opposite of :func:`get_rotation_matrix2d`- - returns the projection matrix :math:`(B, 3, 4)` in pixel coordinates+ - returns the projection matrix ``(B, 3, 4)`` in pixel coordinatesArgs:- center: center of the rotation (x,y,z) in the source with shape :math:`(B, 3)`.+ center: center of the rotation (x,y,z) in the source with shape ``(B, 3)``.angles: axis angle vector containing the rotation angles in degrees in the form- of (rx, ry, rz) with shape :math:`(B, 3)`. Internally it calls Rodrigues to compute+ of (rx, ry, rz) with shape ``(B, 3)``. Internally it calls Rodrigues to computethe rotation matrix from axis-angle.- scales: scale factor for x-y-z-directions with shape :math:`(B, 3)`.+ scales: scale factor for x-y-z-directions with shape ``(B, 3)``.Returns:- the projection matrix of 3D rotation with shape :math:`(B, 3, 4)`.+ the projection matrix of 3D rotation with shape ``(B, 3, 4)``... note::This function is often used in conjunction with :func:`warp_affine3d`.@@ -1691,19 +1691,19 @@ def get_perspective_transform3d(src: torch.Tensor, dst: torch.Tensor) -> torch.T\end{pmatrix}Convention:- - points: ``(x, y, z)``, pixel centers, origin at the top-left of the first depth slice; shape :math:`(B, 8, 3)`+ - points: ``(x, y, z)``, pixel centers, origin at the top-left of the first depth slice; shape ``(B, 8, 3)``- the 15 unknowns are solved exactly from points 0, 1, 2, 5 and 7, the corners ``000``, ``100``, ``110``,``101`` and ``011`` in :func:`~kornia.geometry.bbox.bbox_generator3d` order; points 3, 4 and 6 are notused, so they map onto their ``dst`` only when all eight pairs are related by one homography- - returns the sourceβdestination **pixel** homography :math:`(B, 4, 4)`+ - returns the sourceβdestination **pixel** homography ``(B, 4, 4)``Args:- src: coordinates of the box corners in the source volume with shape :math:`(B, 8, 3)`.+ src: coordinates of the box corners in the source volume with shape ``(B, 8, 3)``.dst: coordinates of the corresponding box corners in- the destination volume with shape :math:`(B, 8, 3)`.+ the destination volume with shape ``(B, 8, 3)``.Returns:- the perspective transformation with shape :math:`(B, 4, 4)`.+ the perspective transformation with shape ``(B, 4, 4)``... note::This function is often used in conjunction with :func:`warp_perspective3d`.@@ -1871,8 +1871,8 @@ def warp_perspective3d(where :math:`\pi` divides by the fourth (homogeneous) coordinate.Convention:- - input: :math:`(B, C, D, H, W)`; ``dsize`` is ``(d, h, w)``- - ``M`` is the sourceβdestination **pixel** homography :math:`(B, 4, 4)`+ - input: ``(B, C, D, H, W)``; ``dsize`` is ``(d, h, w)``+ - ``M`` is the sourceβdestination **pixel** homography ``(B, 4, 4)``- align_corners: ``False`` by default (differs from the 2D :func:`warp_perspective`,whose default is ``True``)- border_mode: ``'zeros'`` by default@@ -1880,8 +1880,8 @@ def warp_perspective3d(negative output dimensions raise ``ValueError``Args:- src: input image with shape :math:`(B, C, D, H, W)`.- M: transformation matrix with shape :math:`(B, 4, 4)`.+ src: input image with shape ``(B, C, D, H, W)``.+ M: transformation matrix with shape ``(B, 4, 4)``.dsize: size of the output image (depth, height, width).flags: interpolation mode to calculate output values``'bilinear'`` | ``'nearest'``.@@ -1953,8 +1953,8 @@ def homography_warp(See :doc:`Conventions & Pitfalls </get-started/conventions>` for homography direction, normalizedcoordinates and ``align_corners`` sampling rules.- - input: :math:`(N, C, H, W)`- - ``src_homo_dst`` is the destinationβsource homography :math:`(N, 3, 3)` when+ - input: ``(N, C, H, W)``+ - ``src_homo_dst`` is the destinationβsource homography ``(N, 3, 3)`` when``normalized_homography=True`` (default), in normalized :math:`[-1, 1]` coordinates by default(``normalized_coordinates=True``). With ``normalized_coordinates=False`` it is in **pixel**coordinates, pixel centres at integers: it maps the pixel ``(x, y)`` of the ``dsize`` output to the@@ -1970,8 +1970,8 @@ def homography_warp(- negative output dimensions raise ``ValueError``Args:- patch_src: The image or torch.Tensor to warp. Should be from source of shape :math:`(N, C, H, W)`.- src_homo_dst: The homography or torch.stack of homographies of shape :math:`(N, 3, 3)` β+ patch_src: The image or torch.Tensor to warp. Should be from source of shape ``(N, C, H, W)``.+ src_homo_dst: The homography or torch.stack of homographies of shape ``(N, 3, 3)`` βdestination to source when ``normalized_homography=True`` (default), source todestination (pixel) when ``normalized_homography=False``.dsize: output size ``(h, w)``.@@ -2068,8 +2068,8 @@ def homography_warp3d(here with ``normalized_coordinates=False``. This function has no ``normalized_homography`` switch.Convention:- - input: :math:`(N, C, D, H, W)`; ``dsize`` is the output size ``(d, h, w)``- - ``src_homo_dst`` is the destinationβsource homography :math:`(N, 4, 4)`, in normalized+ - input: ``(N, C, D, H, W)``; ``dsize`` is the output size ``(d, h, w)``+ - ``src_homo_dst`` is the destinationβsource homography ``(N, 4, 4)``, in normalized:math:`[-1, 1]` coordinates by default (``normalized_coordinates=True``), and acts on``(x, y, z, 1)`` column vectors: ``x`` indexes ``W``, ``y`` indexes ``H``, ``z`` indexes``D``. That is the order :func:`torch.nn.functional.grid_sample` reads a 5-D grid in, and@@ -2092,9 +2092,9 @@ def homography_warp3d(- negative output dimensions raise ``ValueError``Args:- patch_src: The image or torch.Tensor to warp. Should be from source of shape :math:`(N, C, D, H, W)`.+ patch_src: The image or torch.Tensor to warp. Should be from source of shape ``(N, C, D, H, W)``.src_homo_dst: The homography or torch.stack of homographies from destination to source of shape- :math:`(N, 4, 4)`.+ ``(N, 4, 4)``.dsize: output size ``(d, h, w)``.mode: interpolation mode to calculate output values ``'bilinear'`` | ``'nearest'``.padding_mode: padding mode for outside grid values ``'zeros'`` | ``'border'`` | ``'reflection'``.diff --git a/kornia/geometry/transform/pyramid.py b/kornia/geometry/transform/pyramid.pyindex 4b501d1b4..8647e7c57 100644--- a/kornia/geometry/transform/pyramid.py+++ b/kornia/geometry/transform/pyramid.py@@ -75,8 +75,8 @@ class PyrDown(nn.Module):the downsampled torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H / 2, W / 2)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H / 2, W / 2)``Examples:>>> input = torch.rand(1, 2, 4, 4)@@ -98,7 +98,7 @@ class PyrDown(nn.Module):many multi-scale image algorithms.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -126,8 +126,8 @@ class PyrUp(nn.Module):the upsampled torch.Tensor.Shape:- - Input: :math:`(B, C, H, W)`- - Output: :math:`(B, C, H * 2, W * 2)`+ - Input: ``(B, C, H, W)``+ - Output: ``(B, C, H * 2, W * 2)``Examples:>>> input = torch.rand(1, 2, 4, 4)@@ -148,7 +148,7 @@ class PyrUp(nn.Module):reconstruction.Args:- input: Image tensor with shape :math:`(B, C, H, W)`, where+ input: Image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -165,10 +165,10 @@ class ScalePyramid(nn.Module):Images are consequently smoothed with Gaussian blur and downscaled.Convention:- - input: :math:`(B, C, H, W)`+ - input: ``(B, C, H, W)``- ``forward`` returns ``(pyr, sigmas, pixel_dists)``, one entry per octave: ``pyr[o]`` is- :math:`(B, C, L, H_o, W_o)` with ``L = n_levels + extra_levels``, and ``sigmas[o]`` and- ``pixel_dists[o]`` are :math:`(B, L)` nominal values (the targeted blur, not a measurement)+ ``(B, C, L, H_o, W_o)`` with ``L = n_levels + extra_levels``, and ``sigmas[o]`` and+ ``pixel_dists[o]`` are ``(B, L)`` nominal values (the targeted blur, not a measurement)- ``sigmas`` is octave-relative: the blur in input pixels is ``sigmas[o] * pixel_dists[o]``- an ``init_sigma`` below the assumed input blur (``0.5``, or ``1.0`` with``double_image=True``) leaves the first level at that blur, and the octave is built and@@ -190,7 +190,7 @@ class ScalePyramid(nn.Module):3rd output: pixelDists (nominal pixel spacing of each level relative to the input)Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output 1st: :math:`[(B, C, NL, H, W), (B, C, NL, H/2, W/2), ...]`- Output 2nd: :math:`[(B, NL), (B, NL), (B, NL), ...]`- Output 3rd: :math:`[(B, NL), (B, NL), (B, NL), ...]`@@ -308,7 +308,7 @@ class ScalePyramid(nn.Module):``init_sigma`` below the assumed input blur leaves the level unblurred.Args:- input: Image tensor with shape :math:`(B, C, H, W)`.+ input: Image tensor with shape ``(B, C, H, W)``.Returns:Tuple ``(cur_level, cur_sigma, pixel_distance)``. ``cur_level`` is@@ -349,7 +349,7 @@ class ScalePyramid(nn.Module):feature detectors can search both spatial location and scale.Args:- x: Input image tensor with shape :math:`(B, C, H, W)`, where+ x: Input image tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -420,7 +420,7 @@ def pyrdown(.. image:: _static/img/pyrdown.pngConvention:- - input: :math:`(B, C, H, W)`+ - input: ``(B, C, H, W)``- output spatial size is ``floor(side / factor)`` per dimension(:math:`5 \times 5 \to 2 \times 2` at the default ``factor=2.0`` βnote OpenCV's ``pyrDown`` rounds up instead)@@ -476,7 +476,7 @@ def pyrup(input: torch.Tensor, border_type: str = "reflect", align_corners: bool.. image:: _static/img/pyrup.pngConvention:- - input: :math:`(B, C, H, W)`+ - input: ``(B, C, H, W)``- output spatial size is exactly doubled per dimension (no ``factor``parameter, unlike :func:`pyrdown`; :math:`3 \times 3 \to 6 \times 6`)- border_type: ``'reflect'`` by default (blur after upsample)@@ -526,7 +526,7 @@ def build_pyramid(by recursively applying pyrDown to the previously built pyramid layers.Convention:- - input: :math:`(B, C, H, W)`+ - input: ``(B, C, H, W)``- ``max_level`` is the total number of levels returned (including theunchanged original as level 0), not a 0-based index of the last level- each subsequent level is produced by :func:`pyrdown` (``floor(side / 2)``@@ -542,7 +542,7 @@ def build_pyramid(align_corners: interpolation flag.Shape:- - Input: :math:`(B, C, H, W)`+ - Input: ``(B, C, H, W)``- Output :math:`[(B, C, H, W), (B, C, H/2, W/2), ...]`"""@@ -615,7 +615,7 @@ def build_laplacian_pyramid(See :cite:`burt1987laplacian` for more details.Convention:- - input: :math:`(B, C, H, W)`+ - input: ``(B, C, H, W)``- ``max_level`` is the total number of levels returned, not a 0-basedindex of the last level- levels ``0`` through ``max_level - 2`` are band-pass residuals: level@@ -633,7 +633,7 @@ def build_laplacian_pyramid(- align_corners: ``False`` by defaultArgs:- input : the torch.Tensor to be used to construct the pyramid with shape :math:`(B, C, H, W)`.+ input : the torch.Tensor to be used to construct the pyramid with shape ``(B, C, H, W)``.max_level: a positive integer giving the number of pyramid levels to return (see Conventionabove for what each level contains).border_type: the padding mode to be applied before convolving.@@ -643,7 +643,7 @@ def build_laplacian_pyramid(Return:Output: :math:`[(B, C, H', W'), (B, C, H'/2, W'/2), ...]`, where- :math:`(H', W')` equals the input :math:`(H, W)` unless padding was+ :math:`(H', W')` equals the input ``(H, W)`` unless padding wasapplied (see Convention above), in which case it is the padded size."""diff --git a/kornia/geometry/transform/thin_plate_spline.py b/kornia/geometry/transform/thin_plate_spline.pyindex 9165aaf80..8122597a4 100644--- a/kornia/geometry/transform/thin_plate_spline.py+++ b/kornia/geometry/transform/thin_plate_spline.py@@ -28,7 +28,7 @@ __all__ = ["get_tps_transform", "warp_image_tps", "warp_points_tps"]def _pair_square_euclidean(tensor1: torch.Tensor, tensor2: torch.Tensor) -> torch.Tensor:- r"""Compute the pairwise squared euclidean distance matrices :math:`(B, N, M)` between two tensors.+ r"""Compute the pairwise squared euclidean distance matrices ``(B, N, M)`` between two tensors.Tensors with shapes (B, N, C) and (B, M, C)."""@@ -58,13 +58,13 @@ def _kernel_distance(squared_distances: torch.Tensor) -> torch.Tensor:def get_tps_transform(points_src: torch.Tensor, points_dst: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:r"""Compute the TPS transform parameters that warp source points to target points.- The input to this function is a torch.Tensor of :math:`(x, y)` source points :math:`(B, N, 2)` and a corresponding- torch.Tensor of target :math:`(x, y)` points :math:`(B, N, 2)`.+ The input to this function is a torch.Tensor of :math:`(x, y)` source points ``(B, N, 2)`` and a corresponding+ torch.Tensor of target :math:`(x, y)` points ``(B, N, 2)``.Convention:- - ``points_src``/``points_dst``: :math:`(B, N, 2)` in ``(x, y)`` order, in whatever+ - ``points_src``/``points_dst``: ``(B, N, 2)`` in ``(x, y)`` order, in whatevercoordinate frame the caller supplies; no normalization is applied- - returns kernel weights :math:`(B, N, 2)` and affine weights :math:`(B, 3, 2)`; the+ - returns kernel weights ``(B, N, 2)`` and affine weights ``(B, 3, 2)``; theidentity mapping gives zero kernel weights and an identity affine up to solver round-off- the tensor passed as the **second** argument is the ``kernel_centers`` that the warpfunction must receive with these weights. :func:`warp_points_tps` is composed in the@@ -77,11 +77,11 @@ def get_tps_transform(points_src: torch.Tensor, points_dst: torch.Tensor) -> tupkernel_weights=kernel_weights, affine_weights=affine_weights)Args:- points_src: batch of source points :math:`(B, N, 2)` as :math:`(x, y)` coordinate vectors.- points_dst: batch of target points :math:`(B, N, 2)` as :math:`(x, y)` coordinate vectors.+ points_src: batch of source points ``(B, N, 2)`` as :math:`(x, y)` coordinate vectors.+ points_dst: batch of target points ``(B, N, 2)`` as :math:`(x, y)` coordinate vectors.Returns:- :math:`(B, N, 2)` torch.Tensor of kernel weights and :math:`(B, 3, 2)`+ ``(B, N, 2)`` torch.Tensor of kernel weights and ``(B, 3, 2)``torch.Tensor of affine weights. The last dimension contains the x-transform and y-transform weightsas separate columns.@@ -135,26 +135,26 @@ def warp_points_tps() -> torch.Tensor:r"""Warp a torch.Tensor of coordinate points using the thin plate spline defined by arguments.- The source points should be a :math:`(B, N, 2)` torch.Tensor of :math:`(x, y)` coordinates. The kernel centers are- a :math:`(B, K, 2)` torch.Tensor of :math:`(x, y)` coordinates. The kernel weights are a :math:`(B, K, 2)`- torch.Tensor, and the affine weights are a :math:`(B, 3, 2)` torch.Tensor. For the weight tensors,+ The source points should be a ``(B, N, 2)`` torch.Tensor of :math:`(x, y)` coordinates. The kernel centers are+ a ``(B, K, 2)`` torch.Tensor of :math:`(x, y)` coordinates. The kernel weights are a ``(B, K, 2)``+ torch.Tensor, and the affine weights are a ``(B, 3, 2)`` torch.Tensor. For the weight tensors,torch.Tensor[..., 0] contains the weights for the x-transform and torch.Tensor[..., 1] the weightsfor the y-transform.Convention:- - points: :math:`(B, N, 2)` (or :math:`(B, K, 2)` for kernel centers) in ``(x, y)``+ - points: ``(B, N, 2)`` (or ``(B, K, 2)`` for kernel centers) in ``(x, y)``order; no normalization is applied, and the output is in the same frame, not clamped- ``kernel_centers`` must be the second argument passed to :func:`get_tps_transform`(see its Convention block)Args:- points_src: torch.Tensor of source points :math:`(B, N, 2)`.- kernel_centers: torch.Tensor of kernel center points :math:`(B, K, 2)`.- kernel_weights: torch.Tensor of kernel weights :math:`(B, K, 2)`.- affine_weights: torch.Tensor of affine weights :math:`(B, 3, 2)`.+ points_src: torch.Tensor of source points ``(B, N, 2)``.+ kernel_centers: torch.Tensor of kernel center points ``(B, K, 2)``.+ kernel_weights: torch.Tensor of kernel weights ``(B, K, 2)``.+ affine_weights: torch.Tensor of affine weights ``(B, 3, 2)``.Returns:- The :math:`(B, N, 2)` torch.Tensor of warped source points, from applying the TPS transform.+ The ``(B, N, 2)`` torch.Tensor of warped source points, from applying the TPS transform.Example:>>> points_src = torch.rand(1, 5, 2)@@ -220,11 +220,11 @@ def warp_image_tps(image for interpolation of the output pixel. So the TPS parameters should correspond to a warp fromoutput space to input space.- The input `image` is a :math:`(B, C, H, W)` torch.Tensor. The kernel centers, kernel weight and affine weights+ The input `image` is a ``(B, C, H, W)`` torch.Tensor. The kernel centers, kernel weight and affine weightsare the same as in `warp_points_tps`.Convention:- - image: :math:`(B, C, H, W)`; the weights come from :func:`get_tps_transform` called+ - image: ``(B, C, H, W)``; the weights come from :func:`get_tps_transform` called**reversed**, ``get_tps_transform(points_dst, points_src)``, and ``kernel_centers`` is``points_src`` (see its Convention block)- all control points live in the normalized ``grid_sample`` frame selected by@@ -235,15 +235,15 @@ def warp_image_tps(- align_corners: ``False`` by default (the matrix warps default to ``True``)Args:- image: input image torch.Tensor :math:`(B, C, H, W)`.- kernel_centers: kernel center points :math:`(B, K, 2)`.- kernel_weights: torch.Tensor of kernel weights :math:`(B, K, 2)`.- affine_weights: torch.Tensor of affine weights :math:`(B, 3, 2)`.+ image: input image torch.Tensor ``(B, C, H, W)``.+ kernel_centers: kernel center points ``(B, K, 2)``.+ kernel_weights: torch.Tensor of kernel weights ``(B, K, 2)``.+ affine_weights: torch.Tensor of affine weights ``(B, 3, 2)``.align_corners: interpolation flag used by `grid_sample`.padding_mode: padding flag used by `grid_sample`.Returns:- warped image torch.Tensor :math:`(B, C, H, W)`.+ warped image torch.Tensor ``(B, C, H, W)``.Example:>>> points_src = torch.rand(1, 5, 2)diff --git a/kornia/geometry/vector.py b/kornia/geometry/vector.pyindex 72d95ba70..8cf37f0a0 100644--- a/kornia/geometry/vector.py+++ b/kornia/geometry/vector.py@@ -40,11 +40,11 @@ class Scalar(TensorWrapper):class Vector3(TensorWrapper):- r"""Wrap a tensor of 3D vectors, shape :math:`(*, 3)`.+ r"""Wrap a tensor of 3D vectors, shape ``(*, 3)``.Convention:- The tensor is wrapped without a copy; any leading shape and dtype are accepted. :attr:`x`, :attr:`y` and- :attr:`z` are plain tensors of the leading shape :math:`(*)`, and :meth:`dot` and :meth:`squared_norm`+ :attr:`z` are plain tensors of the leading shape ``(*)``, and :meth:`dot` and :meth:`squared_norm`return a :class:`Scalar` of that shape (for :meth:`dot`, the two operands' broadcast leading shape).- :meth:`random` draws vectors uniformly in the unit cube from torch's global generator, so every vectorlies in the first octant: it is not a random direction.@@ -131,7 +131,7 @@ class Vector3(TensorWrapper):Args:shape: Optional leading dimensions before the final coordinatedimension. For example, ``shape=(B, N)`` creates- :math:`(B, N, 3)` vectors.+ ``(B, N, 3)`` vectors.device: Target device for the generated tensor.dtype: Target dtype for the generated tensor.@@ -198,7 +198,7 @@ class Vector3(TensorWrapper):class Vector2(TensorWrapper):- r"""Wrap a tensor of 2D vectors, shape :math:`(*, 2)`.+ r"""Wrap a tensor of 2D vectors, shape ``(*, 2)``.See the Convention block on :class:`Vector3`, which applies to ``(x, y)`` vectors; :meth:`random` fills theunit square.@@ -266,7 +266,7 @@ class Vector2(TensorWrapper):Args:shape: Optional leading dimensions before the final coordinatedimension. For example, ``shape=(B, N)`` creates- :math:`(B, N, 2)` vectors.+ ``(B, N, 2)`` vectors.device: Target device for the generated tensor.dtype: Target dtype for the generated tensor.diff --git a/kornia/image/base.py b/kornia/image/base.pyindex c030090e5..bbe917b8d 100644--- a/kornia/image/base.py+++ b/kornia/image/base.py@@ -94,8 +94,8 @@ class ChannelsOrder(Enum):r"""Enum that represents the channels order of an image.Convention:- See the Convention block of :class:`~kornia.image.Image`. ``CHANNELS_FIRST`` stores :math:`(C, H, W)` and- ``CHANNELS_LAST`` stores :math:`(H, W, C)`.+ See the Convention block of :class:`~kornia.image.Image`. ``CHANNELS_FIRST`` stores ``(C, H, W)`` and+ ``CHANNELS_LAST`` stores ``(H, W, C)``."""CHANNELS_FIRST = 0diff --git a/kornia/image/draw.py b/kornia/image/draw.pyindex fc87bcc1c..3cf6dfa6a 100644--- a/kornia/image/draw.py+++ b/kornia/image/draw.py@@ -76,14 +76,14 @@ def draw_point2d(image: Tensor, points: Tensor, color: Tensor) -> Tensor:Convention:See the Convention block of :func:`~kornia.image.draw_line` for the coordinates, the rounding, the colour- and the in-place drawing. The image is :math:`(C, H, W)` or :math:`(H, W)`.+ and the in-place drawing. The image is ``(C, H, W)`` or ``(H, W)``.Args:- image: the input image on which to draw the points with shape :math:`(C,H,W)` or :math:`(H,W)`.- points: the [x, y] points to be drawn on the image with shape :math:`(N, 2)`, a single- point with shape :math:`(2,)`, or an empty tensor with shape :math:`(0, 2)`.- color: the color of the pixel with :math:`(C)` where :math:`C` is the number of channels of the image,- or a single value with shape :math:`(1)` or 0-d.+ image: the input image on which to draw the points with shape ``(C,H,W)`` or ``(H,W)``.+ points: the [x, y] points to be drawn on the image with shape ``(N, 2)``, a single+ point with shape ``(2,)``, or an empty tensor with shape ``(0, 2)``.+ color: the color of the pixel with ``(C)`` where :math:`C` is the number of channels of the image,+ or a single value with shape ``(1)`` or 0-d.Return:The image with points set to the color. This operation modifies image inplace but also@@ -135,10 +135,10 @@ def _draw_pixel(image: torch.Tensor, x: int, y: int, color: torch.Tensor) -> Nonr"""Draw a pixel into an image.Args:- image: the input image to where to draw the lines with shape :math:`(C,H,W)`.+ image: the input image to where to draw the lines with shape ``(C,H,W)``.x: the x coordinate of the pixel.y: the y coordinate of the pixel.- color: the color of the pixel with :math:`(C)` where :math:`C` is the number of channels of the image.+ color: the color of the pixel with ``(C)`` where :math:`C` is the number of channels of the image.Return:Nothing is returned.@@ -157,7 +157,7 @@ def draw_line(image: torch.Tensor, p1: torch.Tensor, p2: torch.Tensor, color: to- A line has one pixel per step along its longer axis: the pixel whose centre is nearest to the segmentbetween the two endpoint pixels, a tie going to the larger coordinate. The line is therefore the same from``p1`` to ``p2`` as from ``p2`` to ``p1``, and both endpoints are drawn.- - The image is one :math:`(C, H, W)` tensor, and ``(B, 2)`` endpoints draw ``B`` lines into it. An endpoint+ - The image is one ``(C, H, W)`` tensor, and ``(B, 2)`` endpoints draw ``B`` lines into it. An endpointoutside the image raises ``ValueError``; nothing is clipped.- The colour is cast to the image's dtype without rescaling or a range check, and a single value is writtento every channel.@@ -165,11 +165,11 @@ def draw_line(image: torch.Tensor, p1: torch.Tensor, p2: torch.Tensor, color: to- :ref:`Drawing <drawing-conventions>` compares these rules with OpenCV, Pillow and torchvision.Args:- image: the input image to where to draw the lines with shape :math:`(C,H,W)`.+ image: the input image to where to draw the lines with shape ``(C,H,W)``.p1: the start point [x y] of the line with shape (2, ) or (B, 2).p2: the end point [x y] of the line, with the same shape as ``p1``.- color: the color of the line with shape :math:`(C)` where :math:`C` is the number of channels- of the image, or a single value with shape :math:`(1)` or 0-d.+ color: the color of the line with shape ``(C)`` where :math:`C` is the number of channels+ of the image, or a single value with shape ``(1)`` or 0-d.Return:The image containing the line.@@ -277,10 +277,10 @@ def draw_rectangle(- The colour and the in-place drawing follow :func:`~kornia.image.draw_line`.Args:- image: the images, :math:`(B, C, H, W)`.- rectangle: the rectangles, :math:`(B, N, 4)`: ``N`` per image, each ``[x1, y1, x2, y2]``.- color: the colour, :math:`(C)` or :math:`(B, N, C)`, or a single value (0-d, :math:`(1)` or- :math:`(B, N, 1)`). Black by default.+ image: the images, ``(B, C, H, W)``.+ rectangle: the rectangles, ``(B, N, 4)``: ``N`` per image, each ``[x1, y1, x2, y2]``.+ color: the colour, ``(C)`` or ``(B, N, C)``, or a single value (0-d, ``(1)`` or+ ``(B, N, 1)``). Black by default.fill: whether to fill the rectangles instead of drawing their outlines.line_width: the thickness of each side of the outline in pixels, a positive integer. Ignored when``fill=True``.@@ -292,7 +292,7 @@ def draw_rectangle(Returns:This operation modifies image inplace but also returns the drawn tensor for- convenience, with the shape of the input :math:`(B, C, H, W)`.+ convenience, with the shape of the input ``(B, C, H, W)``.Note:The rectangle coordinates are read back to the host once, and ``torch.compile`` breaks the graph there: a@@ -448,12 +448,12 @@ def draw_convex_polygon(images: Tensor, polygons: Union[Tensor, List[Tensor]], cpolygons: represents polygons as points, either BxNx2 or List of variable length polygons.N is the number of points.2 is (x, y).- colors: the fill colours, :math:`(B, C)` or :math:`(C)`, or a single value (0-d, :math:`(1)` or- :math:`(B, 1)`).+ colors: the fill colours, ``(B, C)`` or ``(C)``, or a single value (0-d, ``(1)`` or+ ``(B, 1)``).Returns:This operation modifies image inplace but also returns the drawn tensor for- convenience, with the shape of the input :math:`(B, C, H, W)`.+ convenience, with the shape of the input ``(B, C, H, W)``.Raises:ShapeError: if the images are not ``(B, C, H, W)``. It is also a ``ValueError``.diff --git a/kornia/image/image.py b/kornia/image/image.pyindex 53f7856d4..0ee4f3325 100644--- a/kornia/image/image.py+++ b/kornia/image/image.py@@ -59,15 +59,15 @@ class Image:This API is experimental and might suffer changes in the future.Convention:- - An ``Image`` holds one image, :math:`(C, H, W)` or :math:`(H, W, C)` as ``layout.channels_order`` says,+ - An ``Image`` holds one image, ``(C, H, W)`` or ``(H, W, C)`` as ``layout.channels_order`` says,never a batch: a 4-D tensor raises ``ShapeError``. The layout and the pixel format are checked against thedata: ``bit_depth`` is the storage size, ``8 * data.element_size()``, and the color space must fit thechannel count, 1 for ``GRAY``, 3 for ``RGB`` and ``BGR``, any for ``UNKNOWN``.- :meth:`from_numpy`, :meth:`to_numpy`, :meth:`from_dlpack` and :meth:`to_dlpack` share memory with thearray or capsule of a CPU image. :meth:`to_numpy` and :meth:`to_dlpack` return the stored layout, so an- image from :meth:`from_file` gives :math:`(C, H, W)`. Neither the array nor the capsule carries the layout- or the color space: :meth:`from_numpy` reads :math:`(H, W, C)` and :meth:`from_dlpack` reads- :math:`(C, H, W)` unless ``channels_order`` says otherwise, and both label the color space by channel count+ image from :meth:`from_file` gives ``(C, H, W)``. Neither the array nor the capsule carries the layout+ or the color space: :meth:`from_numpy` reads ``(H, W, C)`` and :meth:`from_dlpack` reads+ ``(C, H, W)`` unless ``channels_order`` says otherwise, and both label the color space by channel countunless ``color_space`` is given. Pass ``img.pixel_format.color_space`` and ``img.channels_order`` to read anexported image back.- :meth:`to_gray`, :meth:`to_rgb` and :meth:`to_bgr` return the image itself when it is already in that color@@ -451,7 +451,7 @@ class Image:"""Construct an ``Image`` from a file.The file is loaded with :func:`~kornia.io.load_image` as ``ImageLoadType.RGB8``: the image is- :math:`(3, H, W)` ``uint8``, ``RGB`` and ``CHANNELS_FIRST``, on the CPU.+ ``(3, H, W)`` ``uint8``, ``RGB`` and ``CHANNELS_FIRST``, on the CPU.Args:file_path: the path to the file to read the image from.diff --git a/kornia/image/image_print.py b/kornia/image/image_print.pyindex 7d3373d6b..52565a86e 100644--- a/kornia/image/image_print.py+++ b/kornia/image/image_print.py@@ -380,7 +380,7 @@ def image_to_string(image: torch.Tensor, max_width: int = 256) -> str:used.Convention:- - The image is :math:`(C, H, W)` with 1 or 3 channels. A float image is read in [0, 1] and an integer one in+ - The image is ``(C, H, W)`` with 1 or 3 channels. A float image is read in [0, 1] and an integer one in[0, 255], so integer 255 and float 1.0 print alike; a value outside the range raises.- Each pixel prints as two spaces on its background colour, one text line per image row. An image wider than``max_width`` pixels is first resized to ``max_width`` pixels wide, keeping its aspect ratio, so a line is atdiff --git a/kornia/image/utils.py b/kornia/image/utils.pyindex e8f83d4a9..d641d1b35 100644--- a/kornia/image/utils.py+++ b/kornia/image/utils.py@@ -29,9 +29,9 @@ def image_to_tensor(image: Any, keepdim: bool = True) -> torch.Tensor:"""Convert a NumPy image to a PyTorch tensor image.Convention:- - The last axis of a 3-D or 4-D array is always the channels: :math:`(H, W, C)` becomes :math:`(C, H, W)` and- :math:`(B, H, W, C)` becomes :math:`(B, C, H, W)`. A channels-first :math:`(C, H, W)` array is not detected:- it is read as :math:`(H, W, C)`.+ - The last axis of a 3-D or 4-D array is always the channels: ``(H, W, C)`` becomes ``(C, H, W)`` and+ ``(B, H, W, C)`` becomes ``(B, C, H, W)``. A channels-first ``(C, H, W)`` array is not detected:+ it is read as ``(H, W, C)``.- The dtype and the values are kept, so ``uint8`` stays in [0, 255], and the tensor is a view of the arraythat shares its memory. An array with a negative stride, such as OpenCV's ``img[..., ::-1]``, raises``ValueError``; pass ``img[..., ::-1].copy()``.@@ -39,14 +39,14 @@ def image_to_tensor(image: Any, keepdim: bool = True) -> torch.Tensor:- :ref:`Files and arrays <image-io-conventions>` relates it to torchvision's ``ToTensor``.Args:- image: image of the form :math:`(H, W, C)`, :math:`(H, W)` or- :math:`(B, H, W, C)`.- keepdim: If ``False``, a 2-D or 3-D input gets a leading batch axis, :math:`(1, C, H, W)`. A 4-D input is- always :math:`(B, C, H, W)`.+ image: image of the form ``(H, W, C)``, ``(H, W)`` or+ ``(B, H, W, C)``.+ keepdim: If ``False``, a 2-D or 3-D input gets a leading batch axis, ``(1, C, H, W)``. A 4-D input is+ always ``(B, C, H, W)``.Returns:- tensor of the form :math:`(C, H, W)` for a 2-D or 3-D input with ``keepdim=True`` (a 2-D input has- :math:`C = 1`), and :math:`(B, C, H, W)` otherwise.+ tensor of the form ``(C, H, W)`` for a 2-D or 3-D input with ``keepdim=True`` (a 2-D input has+ :math:`C = 1`), and ``(B, C, H, W)`` otherwise.Raises:TypeError: if ``image`` is not a ``numpy.ndarray``.@@ -96,13 +96,13 @@ def image_list_to_tensor(images: List[Any]) -> torch.Tensor:Convention:See the Convention block of :func:`~kornia.image.image_to_tensor`. Unlike it, this function copies the images- into a new tensor and takes :math:`(H, W, C)` images only.+ into a new tensor and takes ``(H, W, C)`` images only.Args:- images: list of images, each of the form :math:`(H, W, C)`, all of the same shape.+ images: list of images, each of the form ``(H, W, C)``, all of the same shape.Returns:- tensor of the form :math:`(B, C, H, W)`.+ tensor of the form ``(B, C, H, W)``.Example:>>> imgs = [np.ones((4, 4, 1)), np.zeros((4, 4, 1))]@@ -133,10 +133,10 @@ def _to_bchw(tensor: torch.Tensor) -> torch.Tensor:"""Convert a PyTorch tensor image to BCHW format.Args:- tensor (torch.Tensor): image of the form :math:`(*, H, W)`.+ tensor (torch.Tensor): image of the form ``(*, H, W)``.Returns:- input tensor of the form :math:`(B, C, H, W)`.+ input tensor of the form ``(B, C, H, W)``."""if not isinstance(tensor, torch.Tensor):@@ -161,10 +161,10 @@ def _to_bcdhw(tensor: torch.Tensor) -> torch.Tensor:"""Convert a PyTorch tensor image to BCDHW format.Args:- tensor (torch.Tensor): image of the form :math:`(*, D, H, W)`.+ tensor (torch.Tensor): image of the form ``(*, D, H, W)``.Returns:- input tensor of the form :math:`(B, C, D, H, W)`.+ input tensor of the form ``(B, C, D, H, W)``."""if not isinstance(tensor, torch.Tensor):@@ -189,9 +189,9 @@ def tensor_to_image(tensor: torch.Tensor, keepdim: bool = False, force_contiguou"""Convert a PyTorch tensor image to a numpy image.Convention:- - The channels move last, and a single channel is always dropped: :math:`(1, H, W)` gives :math:`(H, W)` and- :math:`(B, 1, H, W)` gives :math:`(B, H, W)`. ``keepdim`` keeps only the batch axis of a- :math:`(1, C, H, W)` input.+ - The channels move last, and a single channel is always dropped: ``(1, H, W)`` gives ``(H, W)`` and+ ``(B, 1, H, W)`` gives ``(B, H, W)``. ``keepdim`` keeps only the batch axis of a+ ``(1, C, H, W)`` input.- The array shares memory with a CPU tensor whose dtype NumPy supports. A ``bfloat16`` tensor is returned as a``float32`` copy, a dtype NumPy cannot represent, such as ``float8_e4m3fn``, raises ``TypeError``, a tensoron another device is copied, and ``force_contiguous=True`` copies a result that is not contiguous, such as@@ -199,13 +199,13 @@ def tensor_to_image(tensor: torch.Tensor, keepdim: bool = False, force_contiguou- The dtype is kept, except ``bfloat16``, which NumPy lacks: it becomes ``float32``.Args:- tensor: image of the form :math:`(H, W)`, :math:`(C, H, W)` or- :math:`(B, C, H, W)`.- keepdim: If ``True``, keep the batch axis of a :math:`(1, C, H, W)` input.+ tensor: image of the form ``(H, W)``, ``(C, H, W)`` or+ ``(B, C, H, W)``.+ keepdim: If ``True``, keep the batch axis of a ``(1, C, H, W)`` input.force_contiguous: If ``True``, call ``contiguous`` on the result before converting it to NumPy.Returns:- image of the form :math:`(H, W)`, :math:`(H, W, C)`, :math:`(B, H, W)` or :math:`(B, H, W, C)`.+ image of the form ``(H, W)``, ``(H, W, C)``, ``(B, H, W)`` or ``(B, H, W, C)``.Raises:TypeError: if ``tensor`` is not a ``torch.Tensor``.@@ -262,11 +262,11 @@ class ImageToTensor(nn.Module):Convention:See the Convention block of :func:`~kornia.image.image_to_tensor`. Unlike it, ``keepdim`` defaults to- ``False``, so an :math:`(H, W, C)` array becomes :math:`(1, C, H, W)`.+ ``False``, so an ``(H, W, C)`` array becomes ``(1, C, H, W)``.Args:- keepdim: If ``False``, a 2-D or 3-D input gets a leading batch axis, :math:`(1, C, H, W)`. A 4-D input is- always :math:`(B, C, H, W)`.+ keepdim: If ``False``, a 2-D or 3-D input gets a leading batch axis, ``(1, C, H, W)``. A 4-D input is+ always ``(B, C, H, W)``."""diff --git a/kornia/io/io.py b/kornia/io/io.pyindex 64170007d..c95a4ef4c 100644--- a/kornia/io/io.py+++ b/kornia/io/io.py@@ -209,7 +209,7 @@ def _load_image_to_tensor(path_file: Path, device: Union[str, torch.device, Nonedevice: the device where you want to get your image placed.Return:- Image torch.Tensor with shape :math:`(C, H, W)`, as decoded.+ Image torch.Tensor with shape ``(C, H, W)``, as decoded."""# read image and return as `np.ndarray` with shape HxWxC@@ -347,7 +347,7 @@ def load_image(device: the device where you want to get your image placed.Return:- Image torch.Tensor with shape :math:`(C, H, W)`.+ Image torch.Tensor with shape ``(C, H, W)``.Raises:TypeCheckError: if ``desired_type`` is not an :class:`ImageLoadType` (also a ``TypeError``).@@ -416,7 +416,7 @@ def write_image(path_file: str | Path, image: torch.Tensor, quality: int = 80) -and PNG also 4. Any other dtype or channel count raises.- The tensor is written as it is, in RGB order with alpha last, without conversion, scaling or clamping: a``float32`` TIFF keeps values outside [0, 1].- - ``image`` is channels first. A channels-last :math:`(H, W, C)` tensor is not detected: its first axis is+ - ``image`` is channels first. A channels-last ``(H, W, C)`` tensor is not detected: its first axis isread as the channels.- :ref:`Files and arrays <image-io-conventions>` maps ``cv2.imwrite`` onto these arguments.- An image with zero height or width raises ``ShapeError`` before anything is written, so no empty or@@ -424,7 +424,7 @@ def write_image(path_file: str | Path, image: torch.Tensor, quality: int = 80) -Args:path_file: Path with a .jpg, .jpeg, .png, .tif or .tiff extension, in any letter case.- image: Image torch.Tensor with shape :math:`(C, H, W)` or :math:`(H, W)`.+ image: Image torch.Tensor with shape ``(C, H, W)`` or ``(H, W)``.quality: The quality of the JPEG encoding, an integer in [0, 100] and not a ``bool``. It is validated forevery format and used only for JPEG.diff --git a/kornia/io/sample.py b/kornia/io/sample.pyindex cf9a6be7b..830ac802e 100644--- a/kornia/io/sample.py+++ b/kornia/io/sample.py@@ -124,7 +124,7 @@ def get_sample_images(Optionally download them, resize them if specified, and return them as a batch of tensors or a list of tensors.Convention:- - Each image loads with :func:`~kornia.io.load_image`'s default type, ``RGB32``: :math:`(3, H, W)`+ - Each image loads with :func:`~kornia.io.load_image`'s default type, ``RGB32``: ``(3, H, W)````float32`` in [0, 1].- A path is a URL only when its scheme is ``http`` or ``https``. A URL is cached under ``cache_dir`` with thefile name of its path, byte for byte as downloaded, and a cached file is loaded without downloading it@@ -134,8 +134,8 @@ def get_sample_images(- ``resize`` is ``(height, width)`` and goes to :func:`~kornia.geometry.transform.resize`; ``divisible_factor``is applied after it by :func:`~kornia.geometry.transform.resize_to_be_divisible`, so the final size candiffer from ``resize``. ``**kwargs`` reach both.- - The result is one :math:`(B, 3, H, W)` tensor when ``resize`` is given and ``as_list`` is not ``True``, and a- list of :math:`(3, H, W)` tensors otherwise; ``as_list=False`` without ``resize`` still gives a list.+ - The result is one ``(B, 3, H, W)`` tensor when ``resize`` is given and ``as_list`` is not ``True``, and a+ list of ``(3, H, W)`` tensors otherwise; ``as_list=False`` without ``resize`` still gives a list.Args:paths: A list of path or URL from which to load or download images.diff --git a/kornia/losses/cauchy.py b/kornia/losses/cauchy.pyindex 58c2f8cb0..09e9b862d 100644--- a/kornia/losses/cauchy.py+++ b/kornia/losses/cauchy.py@@ -45,7 +45,7 @@ def cauchy_loss(img1: torch.Tensor, img2: torch.Tensor, reduction: str = "none"):math:`\alpha = 0`.Args:- img1: the predicted torch.Tensor with shape :math:`(*)`.+ img1: the predicted torch.Tensor with shape ``(*)``.img2: the target torch.Tensor with the same shape as img1.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction@@ -121,7 +121,7 @@ class CauchyLoss(nn.Module):summed.Shape:- - img1: the predicted torch.Tensor with shape :math:`(*)`.+ - img1: the predicted torch.Tensor with shape ``(*)``.- img2: the target torch.Tensor with the same shape as img1.Example:diff --git a/kornia/losses/charbonnier.py b/kornia/losses/charbonnier.pyindex 9b6b966c0..50da16c25 100644--- a/kornia/losses/charbonnier.py+++ b/kornia/losses/charbonnier.py@@ -63,7 +63,7 @@ def charbonnier_loss(img1: torch.Tensor, img2: torch.Tensor, reduction: str = "nreturn the input dtype.Args:- img1: the predicted torch.Tensor with shape :math:`(*)`.+ img1: the predicted torch.Tensor with shape ``(*)``.img2: the target torch.Tensor with the same shape as img1.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction@@ -154,7 +154,7 @@ class CharbonnierLoss(nn.Module):summed.Shape:- - img1: the predicted torch.Tensor with shape :math:`(*)`.+ - img1: the predicted torch.Tensor with shape ``(*)``.- img2: the target torch.Tensor with the same shape as img1.Example:diff --git a/kornia/losses/depth_smooth.py b/kornia/losses/depth_smooth.pyindex c601fb4d7..d6657523e 100644--- a/kornia/losses/depth_smooth.py+++ b/kornia/losses/depth_smooth.py@@ -55,12 +55,12 @@ def inverse_depth_smoothness_loss(idepth: torch.Tensor, image: torch.Tensor) ->a few levels already drives its weight to about 0.- ``idepth`` is not normalised, so the loss is linear in its scale;:ref:`Losses and metrics <losses-metrics-conventions>` shows how to port a normalised smoothness term.- - Only the rank, :math:`(H, W)`, device and dtype are validated: the channel counts are not, a batch of one+ - Only the rank, ``(H, W)``, device and dtype are validated: the channel counts are not, a batch of onebroadcasts against the other argument, and swapped arguments return a value.Args:- idepth: tensor with the inverse depth with shape :math:`(N, 1, H, W)`.- image: tensor with the input image with shape :math:`(N, 3, H, W)`.+ idepth: tensor with the inverse depth with shape ``(N, 1, H, W)``.+ image: tensor with the input image with shape ``(N, 3, H, W)``.Return:a scalar with the computed loss.@@ -125,8 +125,8 @@ class InverseDepthSmoothnessLoss(nn.Module):See the Convention block of :func:`~kornia.losses.inverse_depth_smoothness_loss`.Shape:- - Inverse Depth: :math:`(N, 1, H, W)`- - Image: :math:`(N, 3, H, W)`+ - Inverse Depth: ``(N, 1, H, W)``+ - Image: ``(N, 3, H, W)``- Output: scalarExamples:@@ -141,8 +141,8 @@ class InverseDepthSmoothnessLoss(nn.Module):"""Compute image-aware smoothness regularization for inverse depth.Args:- idepth: Inverse-depth tensor with shape :math:`(B, 1, H, W)`.- image: RGB image tensor with shape :math:`(B, 3, H, W)` used to+ idepth: Inverse-depth tensor with shape ``(B, 1, H, W)``.+ image: RGB image tensor with shape ``(B, 3, H, W)`` used toreduce the smoothness penalty across visible image edges.Returns:diff --git a/kornia/losses/dice.py b/kornia/losses/dice.pyindex 6cc4e8855..a850d0d02 100644--- a/kornia/losses/dice.py+++ b/kornia/losses/dice.py@@ -223,8 +223,8 @@ def dice_loss(the one-hot target there, and its compiled ``one_hot`` does not check the labels.Args:- pred: logits torch.Tensor with shape :math:`(N, C, H, W)` where C = number of classes.- target: labels torch.Tensor with shape :math:`(N, H, W)` where each value+ pred: logits torch.Tensor with shape ``(N, C, H, W)`` where C = number of classes.+ target: labels torch.Tensor with shape ``(N, H, W)`` where each valueis in range :math:`0 β€ targets[i] β€ C-1`.average:Reduction applied in multi-class scenario:@@ -361,12 +361,12 @@ class DiceLoss(nn.Module):average: Reduction strategy for multi-class computation. Use "micro" to pool the classes of eachsample, or "macro" to average over classes present in each sample's non-ignored target.eps: Small constant added to the denominator for numerical stability.- weight: Optional class-weight tensor of shape :math:`(C,)`.+ weight: Optional class-weight tensor of shape ``(C,)``.ignore_index: Label value to exclude from loss computation.Shapes:- - pred: :math:`(N, C, H, W)` where C is the number of classes.- - target: :math:`(N, H, W)` where each value is in the range :math:`[0, C-1]`.+ - pred: ``(N, C, H, W)`` where C is the number of classes.+ - target: ``(N, H, W)`` where each value is in the range :math:`[0, C-1]`.- Output: scalar."""@@ -382,7 +382,7 @@ class DiceLoss(nn.Module):Args:average: Reduction strategy for multi-class computation.eps: Small constant added for numerical stability.- weight: Optional class-weight tensor of shape :math:`(C,)`.+ weight: Optional class-weight tensor of shape ``(C,)``.ignore_index: Label value to exclude from loss computation."""if isinstance(eps, (int, float)) and eps < 0.0:@@ -403,10 +403,10 @@ class DiceLoss(nn.Module):"""Compute SΓΈrensen-Dice loss for segmentation logits and labels.Args:- pred: Logit tensor with shape :math:`(B, C, H, W)`, where+ pred: Logit tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is number of classes,:math:`H` is height, and :math:`W` is width.- target: Integer target labels with shape :math:`(B, H, W)`.+ target: Integer target labels with shape ``(B, H, W)``.Returns:Scalar tensor containing ``1 - Dice`` after applying the configureddiff --git a/kornia/losses/divergence.py b/kornia/losses/divergence.pyindex 50ccadaa9..c99db9278 100644--- a/kornia/losses/divergence.py+++ b/kornia/losses/divergence.py@@ -84,8 +84,8 @@ def js_div_loss_2d(pred: torch.Tensor, target: torch.Tensor, reduction: str = "mThe returned loss retains the promoted input dtype.Args:- pred: the input torch.Tensor with shape :math:`(B, N, H, W)`.- target: the target torch.Tensor with shape :math:`(B, N, H, W)`.+ pred: the input torch.Tensor with shape ``(B, N, H, W)``.+ target: the target torch.Tensor with shape ``(B, N, H, W)``.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reductionwill be applied, ``'mean'``: the sum of the output will be divided by@@ -114,15 +114,15 @@ def kl_div_loss_2d(pred: torch.Tensor, target: torch.Tensor, reduction: str = "m- The inputs are probabilities, each :math:`(b, n)` slice a distribution over :math:`H \times W`. The log istaken inside, so log-probabilities give NaN, and nothing is normalised. A zero in ``pred`` where ``target``is positive gives ``inf``.- - ``reduction='none'`` returns :math:`(B, N)`; the default ``'mean'`` averages over the :math:`B N`+ - ``reduction='none'`` returns ``(B, N)``; the default ``'mean'`` averages over the :math:`B N`distributions and ``'sum'`` adds them.- Both inputs must have the same shape. Unsupported reductions, including torch's ``'batchmean'``, raise``NotImplementedError``. A zero in ``target`` with a finite nonnegative ``pred`` contributes zero to thevalue and gradients, including when both entries are zero.Args:- pred: the input torch.Tensor with shape :math:`(B, N, H, W)`.- target: the target torch.Tensor with shape :math:`(B, N, H, W)`.+ pred: the input torch.Tensor with shape ``(B, N, H, W)``.+ target: the target torch.Tensor with shape ``(B, N, H, W)``.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reductionwill be applied, ``'mean'``: the sum of the output will be divided bydiff --git a/kornia/losses/focal.py b/kornia/losses/focal.pyindex 76dd480a8..cf72d9eef 100644--- a/kornia/losses/focal.py+++ b/kornia/losses/focal.py@@ -213,8 +213,8 @@ def focal_loss(same NaN and infinity positions and a zero gradient at ignored pixels, and supports double backward.Args:- pred: logits torch.Tensor with shape :math:`(N, C, *)` where C = number of classes.- target: labels torch.Tensor with shape :math:`(N, *)` where each value is an integer+ pred: logits torch.Tensor with shape ``(N, C, *)`` where C = number of classes.+ target: labels torch.Tensor with shape ``(N, *)`` where each value is an integerrepresenting correct classification :math:`target[i] \in [0, C)`.alpha: Weighting factor :math:`\alpha \in [0, 1]` of classes :math:`1, \dots, C - 1`; class 0 is weighted by:math:`1 - \alpha`. ``None`` weights every class by 1.@@ -367,8 +367,8 @@ class FocalLoss(nn.Module):ignore_index: labels with this value contribute 0 to the loss but stay in the ``'mean'`` denominator.Shape:- - Pred: :math:`(N, C, *)` where C = number of classes.- - Target: :math:`(N, *)` where each value is an integer+ - Pred: ``(N, C, *)`` where C = number of classes.+ - Target: ``(N, *)`` where each value is an integerrepresenting correct classification :math:`target[i] \in [0, C)`.Example:@@ -404,10 +404,10 @@ class FocalLoss(nn.Module):"""Compute multi-class focal loss from class logits.Args:- pred: Logit tensor with shape :math:`(B, C, *)`, where :math:`B`+ pred: Logit tensor with shape ``(B, C, *)``, where :math:`B`is batch size, :math:`C` is number of classes, and ``*`` isany number of spatial dimensions.- target: Integer class-label tensor with shape :math:`(B, *)`.+ target: Integer class-label tensor with shape ``(B, *)``.Returns:Focal-loss tensor reduced according to ``self.reduction``. See :func:`~kornia.losses.focal_loss` for@@ -454,8 +454,8 @@ def binary_focal_loss_with_logits(``sigmoid_focal_loss`` and torch's ``pos_weight``.Args:- pred: logits torch.Tensor with shape :math:`(N, C, *)` where C = number of classes.- target: labels torch.Tensor with the same shape as pred :math:`(N, C, *)`+ pred: logits torch.Tensor with shape ``(N, C, *)`` where C = number of classes.+ target: labels torch.Tensor with the same shape as pred ``(N, C, *)``where each value is between 0 and 1.alpha: Weighting factor :math:`\alpha \in [0, 1]` of the positive term; the negative term is weighted by:math:`1 - \alpha`.@@ -581,8 +581,8 @@ class BinaryFocalLossWithLogits(nn.Module):denominator.Shape:- - Pred: :math:`(N, C, *)` where C = number of classes.- - Target: the same shape as Pred :math:`(N, C, *)`+ - Pred: ``(N, C, *)`` where C = number of classes.+ - Target: the same shape as Pred ``(N, C, *)``where each value is between 0 and 1.Examples:@@ -623,7 +623,7 @@ class BinaryFocalLossWithLogits(nn.Module):"""Compute binary focal loss from logits.Args:- pred: Logit tensor with shape :math:`(B, C, *)`, at least two dimensions.+ pred: Logit tensor with shape ``(B, C, *)``, at least two dimensions.target: Binary target tensor with the same shape as ``pred``.Returns:diff --git a/kornia/losses/geman_mcclure.py b/kornia/losses/geman_mcclure.pyindex e1af1f47b..24c257f95 100644--- a/kornia/losses/geman_mcclure.py+++ b/kornia/losses/geman_mcclure.py@@ -45,7 +45,7 @@ def geman_mcclure_loss(img1: torch.Tensor, img2: torch.Tensor, reduction: str =:math:`\alpha = -2`.Args:- img1: the predicted torch.Tensor with shape :math:`(*)`.+ img1: the predicted torch.Tensor with shape ``(*)``.img2: the target torch.Tensor with the same shape as img1.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction@@ -122,7 +122,7 @@ class GemanMcclureLoss(nn.Module):summed.Shape:- - img1: the predicted torch.Tensor with shape :math:`(*)`.+ - img1: the predicted torch.Tensor with shape ``(*)``.- img2: the target torch.Tensor with the same shape as img1.Example:diff --git a/kornia/losses/hausdorff.py b/kornia/losses/hausdorff.pyindex d24f00fd5..0ba977d08 100644--- a/kornia/losses/hausdorff.py+++ b/kornia/losses/hausdorff.py@@ -119,9 +119,9 @@ class _HausdorffERLossBase(nn.Module):"""Compute Hausdorff loss.Args:- pred: predicted torch.Tensor with a shape of :math:`(B, C, H, W)` or :math:`(B, C, D, H, W)`.+ pred: predicted torch.Tensor with a shape of ``(B, C, H, W)`` or ``(B, C, D, H, W)``.Each channel is as binary as: 1 -> fg, 0 -> bg.- target: target torch.Tensor with a shape of :math:`(B, 1, H, W)` or :math:`(B, 1, D, H, W)`.+ target: target torch.Tensor with a shape of ``(B, 1, H, W)`` or ``(B, 1, D, H, W)``.Returns:Estimated Hausdorff Loss.@@ -238,9 +238,9 @@ class HausdorffERLoss(_HausdorffERLossBase):"""Compute Hausdorff loss.Args:- pred: predicted torch.Tensor with a shape of :math:`(B, C, H, W)`.+ pred: predicted torch.Tensor with a shape of ``(B, C, H, W)``.Each channel is as binary as: 1 -> fg, 0 -> bg.- target: target torch.Tensor with a shape of :math:`(B, 1, H, W)`.+ target: target torch.Tensor with a shape of ``(B, 1, H, W)``.Returns:Estimated Hausdorff Loss.@@ -321,9 +321,9 @@ class HausdorffERLoss3D(_HausdorffERLossBase):"""Compute 3D Hausdorff loss.Args:- pred: predicted torch.Tensor with a shape of :math:`(B, C, D, H, W)`.+ pred: predicted torch.Tensor with a shape of ``(B, C, D, H, W)``.Each channel is as binary as: 1 -> fg, 0 -> bg.- target: target torch.Tensor with a shape of :math:`(B, 1, D, H, W)`.+ target: target torch.Tensor with a shape of ``(B, 1, D, H, W)``.Returns:Estimated Hausdorff Loss.diff --git a/kornia/losses/lovasz_hinge.py b/kornia/losses/lovasz_hinge.pyindex d210ad91c..2f5cc915e 100644--- a/kornia/losses/lovasz_hinge.py+++ b/kornia/losses/lovasz_hinge.py@@ -70,8 +70,8 @@ def lovasz_hinge_loss(pred: Tensor, target: Tensor) -> Tensor:loss negative.Args:- pred: logits tensor with shape :math:`(N, 1, H, W)`.- target: labels tensor with shape :math:`(N, H, W)` with binary values.+ pred: logits tensor with shape ``(N, 1, H, W)``.+ target: labels tensor with shape ``(N, H, W)`` with binary values.Return:a scalar with the computed loss, in the dtype of a floating-point ``pred`` and in float32 for an@@ -159,8 +159,8 @@ class LovaszHingeLoss(nn.Module):See the Convention block of :func:`~kornia.losses.lovasz_hinge_loss`.Args:- pred: logits tensor with shape :math:`(N, 1, H, W)`.- target: labels tensor with shape :math:`(N, H, W)` with binary values.+ pred: logits tensor with shape ``(N, 1, H, W)``.+ target: labels tensor with shape ``(N, H, W)`` with binary values.Return:a scalar with the computed loss, in the dtype of a floating-point ``pred`` and in float32 for an@@ -184,8 +184,8 @@ class LovaszHingeLoss(nn.Module):"""Compute binary Lovasz hinge loss for segmentation logits.Args:- pred: Binary logit tensor with shape :math:`(B, 1, H, W)`.- target: Binary label tensor with shape :math:`(B, H, W)`.+ pred: Binary logit tensor with shape ``(B, 1, H, W)``.+ target: Binary label tensor with shape ``(B, H, W)``.Returns:Scalar tensor containing the Lovasz hinge surrogate for thediff --git a/kornia/losses/lovasz_softmax.py b/kornia/losses/lovasz_softmax.pyindex 044fa7281..0e0a4d1e3 100644--- a/kornia/losses/lovasz_softmax.py+++ b/kornia/losses/lovasz_softmax.py@@ -72,8 +72,8 @@ def lovasz_softmax_loss(pred: Tensor, target: Tensor, weight: Optional[Tensor] =averages.Args:- pred: logits tensor with shape :math:`(N, C, H, W)` where C = number of classes > 1.- target: labels tensor with shape :math:`(N, H, W)` where each value+ pred: logits tensor with shape ``(N, C, H, W)`` where C = number of classes > 1.+ target: labels tensor with shape ``(N, H, W)`` where each valueis in range :math:`0 β€ targets[i] β€ C-1`.weight: weights for classes with shape :math:`(num\_of\_classes,)`.@@ -189,8 +189,8 @@ class LovaszSoftmaxLoss(nn.Module):See the Convention block of :func:`~kornia.losses.lovasz_softmax_loss`.Args:- pred: logits tensor with shape :math:`(N, C, H, W)` where C = number of classes > 1.- target: labels tensor with shape :math:`(N, H, W)` where each value+ pred: logits tensor with shape ``(N, C, H, W)`` where C = number of classes > 1.+ target: labels tensor with shape ``(N, H, W)`` where each valueis in range :math:`0 β€ targets[i] β€ C-1`.weight: weights for classes with shape :math:`(num\_of\_classes,)`.@@ -219,9 +219,9 @@ class LovaszSoftmaxLoss(nn.Module):"""Compute multi-class Lovasz-Softmax loss.Args:- pred: Class logit tensor with shape :math:`(B, C, H, W)`, where+ pred: Class logit tensor with shape ``(B, C, H, W)``, where:math:`C` is the number of classes.- target: Integer class-label tensor with shape :math:`(B, H, W)`.+ target: Integer class-label tensor with shape ``(B, H, W)``.Returns:Scalar tensor containing the Lovasz-Softmax surrogate for thediff --git a/kornia/losses/ms_ssim.py b/kornia/losses/ms_ssim.pyindex 2546fea7e..82b2dca6a 100644--- a/kornia/losses/ms_ssim.py+++ b/kornia/losses/ms_ssim.py@@ -64,9 +64,9 @@ class MS_SSIMLoss(nn.Module):- ``data_range`` is the ``max_val`` of :func:`~kornia.metrics.ssim`: it sets :math:`C_1` and :math:`C_2` anddivides the L1 term; pixel values are not rescaled.- The defaults follow [3]: ``alpha=0.025``, as in [2], and ``compensation=200``, which neither [1] nor [2]- applies; [1] sets :math:`\alpha = 0.84`. The default ``reduction='mean'`` averages the :math:`(B, H, W)`+ applies; [1] sets :math:`\alpha = 0.84`. The default ``reduction='mean'`` averages the ``(B, H, W)``map, whose channels are already averaged.- - The two images must have the same :math:`(C, H, W)` shape. Their batch sizes must match, or one of them+ - The two images must have the same ``(C, H, W)`` shape. Their batch sizes must match, or one of themmust be 1, and that image is then compared with every image of the other batch.Reference:@@ -89,9 +89,9 @@ class MS_SSIMLoss(nn.Module):The computed loss.Shape:- - Input1: :math:`(N, C, H, W)`.- - Input2: :math:`(N, C, H, W)`.- - Output: :math:`(N, H, W)` or scalar if reduction is set to ``'mean'`` or ``'sum'``.+ - Input1: ``(N, C, H, W)``.+ - Input2: ``(N, C, H, W)``.+ - Output: ``(N, H, W)`` or scalar if reduction is set to ``'mean'`` or ``'sum'``.Note:Integer and bool images count as the dtype of the Gaussian masks: float32, unless the module was moved to@@ -198,8 +198,8 @@ class MS_SSIMLoss(nn.Module):"""Compute MS_SSIM loss.Args:- img1: the predicted image with shape :math:`(B, C, H, W)`.- img2: the target image with a shape of :math:`(B, C, H, W)`.+ img1: the predicted image with shape ``(B, C, H, W)``.+ img2: the target image with a shape of ``(B, C, H, W)``.Returns:Estimated MS-SSIM_L1 loss.diff --git a/kornia/losses/mutual_information.py b/kornia/losses/mutual_information.pyindex dcb36e403..128b7efce 100644--- a/kornia/losses/mutual_information.py+++ b/kornia/losses/mutual_information.py@@ -504,11 +504,11 @@ class MILossFromRef2D(MILossFromRef):"""Flatten the spatial dimensions of a 2D signal batch.Args:- tensor: Signal tensor with shape :math:`(*, H, W)`, where ``*`` is+ tensor: Signal tensor with shape ``(*, H, W)``, where ``*`` isany leading batch shape.Returns:- Tensor with shape :math:`(*, H * W)` suitable for histogram-based+ Tensor with shape ``(*, H * W)`` suitable for histogram-basedmutual-information computation."""return tensor.flatten(max(tensor.dim() - 2, 0))@@ -592,7 +592,7 @@ class MILossFromRef3D(MILossFromRef):"""Flatten the spatial dimensions of a 3D signal batch.Args:- tensor: Signal tensor with shape :math:`(*, D, H, W)`, where+ tensor: Signal tensor with shape ``(*, D, H, W)``, where:math:`D` is depth, :math:`H` is height, and :math:`W` iswidth.@@ -680,10 +680,10 @@ class NMILossFromRef2D(NMILossFromRef):"""Flatten the spatial dimensions of a 2D signal batch.Args:- tensor: Signal tensor with shape :math:`(*, H, W)`.+ tensor: Signal tensor with shape ``(*, H, W)``.Returns:- Tensor with shape :math:`(*, H * W)` used by the normalized+ Tensor with shape ``(*, H * W)`` used by the normalizedmutual-information base implementation."""return tensor.flatten(max(tensor.dim() - 2, 0))@@ -767,7 +767,7 @@ class NMILossFromRef3D(NMILossFromRef):"""Flatten the spatial dimensions of a 3D signal batch.Args:- tensor: Signal tensor with shape :math:`(*, D, H, W)`.+ tensor: Signal tensor with shape ``(*, D, H, W)``.Returns:Tensor with shape :math:`(*, D * H * W)` used by the normalizeddiff --git a/kornia/losses/one_hot.py b/kornia/losses/one_hot.pyindex ae0ad7400..60eff8582 100644--- a/kornia/losses/one_hot.py+++ b/kornia/losses/one_hot.py@@ -38,7 +38,7 @@ def one_hot(are not validated by kornia; the result for them is undefined.Args:- labels: torch.Tensor with labels of shape :math:`(N, *)`, where N is batch size.+ labels: torch.Tensor with labels of shape ``(N, *)``, where N is batch size.Each value is an integer representing correct classification.num_classes: number of classes in labels.device: the desired device of returned torch.Tensor.@@ -47,7 +47,7 @@ def one_hot(zeros with ``eps`` and keeps the ones, which needs a floating point ``dtype``.Returns:- the labels in one hot torch.Tensor of shape :math:`(N, C, *)`,+ the labels in one hot torch.Tensor of shape ``(N, C, *)``,Examples:>>> labels = torch.LongTensor([[[0, 1], [2, 0]]])diff --git a/kornia/losses/psnr.py b/kornia/losses/psnr.pyindex 8a6793695..0a99b2f05 100644--- a/kornia/losses/psnr.py+++ b/kornia/losses/psnr.py@@ -38,8 +38,8 @@ def psnr_loss(image: torch.Tensor, target: torch.Tensor, max_val: _PSNRMaxVal) -inputs give ``-inf``.Args:- image: the input image with shape :math:`(*)`.- target : the labels image with shape :math:`(*)`.+ image: the input image with shape ``(*)``.+ target : the labels image with shape ``(*)``.max_val: the data range of the images, :math:`\text{MAX}_I`, as a float, integer or tensor.Return:@@ -71,8 +71,8 @@ class PSNRLoss(nn.Module):max_val: the data range of the images, :math:`\text{MAX}_I`, as a float, integer or tensor.Shape:- - Image: arbitrary dimensional tensor :math:`(*)`.- - Target: arbitrary dimensional tensor :math:`(*)` same shape as image.+ - Image: arbitrary dimensional tensor ``(*)``.+ - Target: arbitrary dimensional tensor ``(*)`` same shape as image.- Output: a scalar for a scalar range, or with the shape of a tensor range.Examples:diff --git a/kornia/losses/ssim.py b/kornia/losses/ssim.pyindex ca8e8de09..35717af33 100644--- a/kornia/losses/ssim.py+++ b/kornia/losses/ssim.py@@ -49,8 +49,8 @@ def ssim_loss(- The default ``reduction='mean'`` averages every element; ``'none'`` keeps the shape of the SSIM map.Args:- img1: the first input image with shape :math:`(B, C, H, W)`.- img2: the second input image with shape :math:`(B, C, H, W)`.+ img1: the first input image with shape ``(B, C, H, W)``.+ img2: the second input image with shape ``(B, C, H, W)``.window_size: the size of the gaussian kernel to smooth the images.max_val: the dynamic range of the images.eps: Small value for numerically stability when dividing.@@ -136,7 +136,7 @@ class SSIMLoss(nn.Module):"""Compute SSIM loss between two 2D image tensors.Args:- img1: First image batch with shape :math:`(B, C, H, W)`, where+ img1: First image batch with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`H` is height, and :math:`W` is width.img2: Second image batch with the same shape as ``img1``.diff --git a/kornia/losses/ssim3d.py b/kornia/losses/ssim3d.pyindex 5f3126a15..c76028ecd 100644--- a/kornia/losses/ssim3d.py+++ b/kornia/losses/ssim3d.py@@ -46,8 +46,8 @@ def ssim3d_loss(- The per-voxel loss is ``clamp((1 - SSIM) / 2, 0, 1)``, as in :func:`~kornia.losses.ssim_loss`.Args:- img1: the first input image with shape :math:`(B, C, D, H, W)`.- img2: the second input image with shape :math:`(B, C, D, H, W)`.+ img1: the first input image with shape ``(B, C, D, H, W)``.+ img2: the second input image with shape ``(B, C, D, H, W)``.window_size: the size of the gaussian kernel to smooth the images.max_val: the dynamic range of the images.eps: Small value for numerically stability when dividing.@@ -133,7 +133,7 @@ class SSIM3DLoss(nn.Module):"""Compute SSIM loss between two 3D image or volume tensors.Args:- img1: First volume batch with shape :math:`(B, C, D, H, W)`, where+ img1: First volume batch with shape ``(B, C, D, H, W)``, where:math:`B` is batch size, :math:`C` is channel count,:math:`D` is depth, :math:`H` is height, and :math:`W` iswidth.diff --git a/kornia/losses/total_variation.py b/kornia/losses/total_variation.pyindex 0ad533cb3..cb46e4a44 100644--- a/kornia/losses/total_variation.py+++ b/kornia/losses/total_variation.py@@ -28,7 +28,7 @@ def total_variation(img: torch.Tensor, reduction: str = "sum") -> torch.Tensor:Convention:- The anisotropic L1 variation, :math:`\sum |\partial_y I| + \sum |\partial_x I|`, over the last two axes- only: the output keeps every leading axis, :math:`(B, C)` for an image batch, and the channels are not+ only: the output keeps every leading axis, ``(B, C)`` for an image batch, and the channels are notsummed.- The default ``reduction='sum'`` adds the differences. ``'mean'`` averages each term over its own count,:math:`(H - 1) W` vertical and :math:`H (W - 1)` horizontal differences, and adds the two means; it is not@@ -36,13 +36,13 @@ def total_variation(img: torch.Tensor, reduction: str = "sum") -> torch.Tensor::ref:`Losses and metrics <losses-metrics-conventions>` compares both with torchmetrics.Args:- img: the input image with shape :math:`(*, H, W)`.+ img: the input image with shape ``(*, H, W)``.reduction : Specifies the reduction to apply to the output: ``'mean'`` | ``'sum'``.``'mean'``: each of the vertical and horizontal terms is averaged over its own number of differences,``'sum'``: the differences are summed.Return:- a torch.Tensor with shape :math:`(*,)`.+ a torch.Tensor with shape ``(*,)``.Examples:>>> total_variation(torch.ones(4, 4))@@ -107,8 +107,8 @@ class TotalVariation(nn.Module):always sums.Shape:- - Input: :math:`(*, H, W)`.- - Output: :math:`(*,)`.+ - Input: ``(*, H, W)``.+ - Output: ``(*,)``.Examples:>>> tv = TotalVariation()@@ -127,7 +127,7 @@ class TotalVariation(nn.Module):"""Compute total variation for an image or image batch.Args:- img: Tensor with shape :math:`(*, H, W)`, where ``*`` represents+ img: Tensor with shape ``(*, H, W)``, where ``*`` representsoptional leading dimensions such as batch and channels,:math:`H` is height, and :math:`W` is width.diff --git a/kornia/losses/tversky.py b/kornia/losses/tversky.pyindex b9e7d2588..af549cec7 100644--- a/kornia/losses/tversky.py+++ b/kornia/losses/tversky.py@@ -82,8 +82,8 @@ def tversky_loss(enters the batch mean as loss 1. There is no ``weight``, ``average`` or ``reduction``.Args:- pred: logits tensor with shape :math:`(N, C, H, W)` where C = number of classes.- target: labels tensor with shape :math:`(N, H, W)` where each value+ pred: logits tensor with shape ``(N, C, H, W)`` where C = number of classes.+ target: labels tensor with shape ``(N, H, W)`` where each valueis in range :math:`0 β€ targets[i] β€ C-1`.alpha: the first coefficient in the denominator.beta: the second coefficient in the denominator.@@ -184,8 +184,8 @@ class TverskyLoss(nn.Module):ignore_index: labels with this value are ignored in the loss computation.Shape:- - Pred: :math:`(N, C, H, W)` where C = number of classes.- - Target: :math:`(N, H, W)` where each value is+ - Pred: ``(N, C, H, W)`` where C = number of classes.+ - Target: ``(N, H, W)`` where each value is:math:`0 β€ targets[i] β€ C-1`.Examples:@@ -210,10 +210,10 @@ class TverskyLoss(nn.Module):"""Compute the Tversky segmentation loss for class logits and labels.Args:- pred: Logit tensor with shape :math:`(B, C, H, W)`, where+ pred: Logit tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is number of classes,:math:`H` is height, and :math:`W` is width.- target: Integer class-label tensor with shape :math:`(B, H, W)`.+ target: Integer class-label tensor with shape ``(B, H, W)``.Labels matching ``self.ignore_index`` are excluded from theloss when an ignore index is configured.diff --git a/kornia/losses/welsch.py b/kornia/losses/welsch.pyindex 7ad91c66a..598b58e3c 100644--- a/kornia/losses/welsch.py+++ b/kornia/losses/welsch.py@@ -47,7 +47,7 @@ def welsch_loss(img1: torch.Tensor, img2: torch.Tensor, reduction: str = "none"):math:`\alpha = -\infty`.Args:- img1: the predicted torch.Tensor with shape :math:`(*)`.+ img1: the predicted torch.Tensor with shape ``(*)``.img2: the target torch.Tensor with the same shape as img1.reduction: Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction@@ -126,7 +126,7 @@ class WelschLoss(nn.Module):summed.Shape:- - img1: the predicted torch.Tensor with shape :math:`(*)`.+ - img1: the predicted torch.Tensor with shape ``(*)``.- img2: the target torch.Tensor with the same shape as img1.Example:diff --git a/kornia/metrics/accuracy.py b/kornia/metrics/accuracy.pyindex 6a3ddc205..bfa781b6f 100644--- a/kornia/metrics/accuracy.py+++ b/kornia/metrics/accuracy.py@@ -45,8 +45,8 @@ def accuracy(pred: torch.Tensor, target: torch.Tensor, topk: Tuple[int, ...] = ("""Compute the accuracy over the k top predictions for the specified values of k.Convention:- - ``pred`` holds one score per class, :math:`(B, C)`; only the order of the scores in a row matters.- ``target`` holds class indices, :math:`(B,)` or :math:`(B, 1)`. The batch sizes of ``pred`` and+ - ``pred`` holds one score per class, ``(B, C)``; only the order of the scores in a row matters.+ ``target`` holds class indices, ``(B,)`` or ``(B, 1)``. The batch sizes of ``pred`` and``target`` must match.- The result is a list with one 0-d float32 tensor per entry of ``topk``, in that order. Each is a**percentage** in :math:`[0, 100]`, not a fraction, taken over the whole batch: a sample counts for ``k``@@ -54,8 +54,8 @@ def accuracy(pred: torch.Tensor, target: torch.Tensor, topk: Tuple[int, ...] = (:ref:`Losses and metrics <losses-metrics-conventions>` lists the scale of every task metric.Args:- pred: the class scores, with shape :math:`(B, C)`.- target: the ground-truth class indices, with shape :math:`(B,)` or :math:`(B, 1)`.+ pred: the class scores, with shape ``(B, C)``.+ target: the ground-truth class indices, with shape ``(B,)`` or ``(B, 1)``.topk: the expected topk ranking.Example:diff --git a/kornia/metrics/confusion_matrix.py b/kornia/metrics/confusion_matrix.pyindex f0d1ecc9b..ccab1c3e7 100644--- a/kornia/metrics/confusion_matrix.py+++ b/kornia/metrics/confusion_matrix.py@@ -52,8 +52,8 @@ def confusion_matrix(a label outside :math:`[0, K)`, unless graph capture traces the range check (``torch.export``,``torch.compile(fullgraph=True)``), which skips it: an out-of-range label is then counted in another cellor makes the call fail.- - The first axis is always the batch: the result holds one :math:`(K, K)` float32 count matrix per sample,- :math:`(B, K, K)`, and is never pooled over the batch, so a flat :math:`(N,)` label vector gives :math:`N`+ - The first axis is always the batch: the result holds one ``(K, K)`` float32 count matrix per sample,+ ``(B, K, K)``, and is never pooled over the batch, so a flat ``(N,)`` label vector gives :math:`N`matrices that count one label each. Sum over the first axis for the matrix of a whole batch or dataset.- Rows are the target and columns the prediction, ``cm[b, target, pred]``; swapping the two argumentstransposes every count matrix. :ref:`Losses and metrics <losses-metrics-conventions>` maps the matrix and@@ -61,7 +61,7 @@ def confusion_matrix(Args:pred: tensor with estimated targets returned by a- classifier. The shape can be :math:`(B, *)` and must contain integer+ classifier. The shape can be ``(B, *)`` and must contain integervalues between 0 and K-1.target: tensor with ground truth (correct) targetvalues. The shape must be that of ``pred``, and it must contain integer@@ -72,7 +72,7 @@ def confusion_matrix(Returns:a tensor containing the confusion matrix with shape- :math:`(B, K, K)` where K is the number of classes.+ ``(B, K, K)`` where K is the number of classes.Example:>>> logits = torch.tensor([[0, 1, 0]])diff --git a/kornia/metrics/disparity.py b/kornia/metrics/disparity.pyindex 15edd44a7..a670d3d17 100644--- a/kornia/metrics/disparity.py+++ b/kornia/metrics/disparity.py@@ -112,12 +112,12 @@ def mean_absolute_disparity_error(\text{MAE}(D, D^{gt}) = \frac{1}{|\mathcal{V}|}\sum_{p \in \mathcal{V}} |D_{p} - D^{gt}_{p}|Convention:- - The maps hold disparities in pixels, have any shape :math:`(*)` and must have a floating dtype. ``'mean'``+ - The maps hold disparities in pixels, have any shape ``(*)`` and must have a floating dtype. ``'mean'``and ``'sum'`` pool every valid pixel of every image into one 0-d value, in pixels here, so for images withdifferent numbers of valid pixels the result is not the mean of the per-image errors. The other disparitymetrics pool the same way.- - ``valid_mask`` is broadcast to the maps from the right: an :math:`(H, W)` mask applies to every image of a- :math:`(B, H, W)` batch and a :math:`(B, 1, 1)` mask selects whole images, while a :math:`(B,)` mask is+ - ``valid_mask`` is broadcast to the maps from the right: an ``(H, W)`` mask applies to every image of a+ ``(B, H, W)`` batch and a ``(B, 1, 1)`` mask selects whole images, while a ``(B,)`` mask ismatched against the last axis, not the batch. Nothing is masked automatically: a pixel with an invalidground truth, such as a zero disparity, counts unless ``valid_mask`` excludes it.- A ``nan`` at a valid pixel of either map propagates into this error and the RMSE, while@@ -125,7 +125,7 @@ def mean_absolute_disparity_error(good pixel.Args:- input: the predicted disparity map with arbitrary shape :math:`(*)`.+ input: the predicted disparity map with arbitrary shape ``(*)``.target: the ground truth disparity map with the same shape as ``input``.valid_mask: optional mask broadcastable to the shape of ``input``, where nonzero(``True``) values mark the pixels to evaluate. Non-boolean masks are converted@@ -189,7 +189,7 @@ def root_mean_squared_disparity_error(a sum of errors.Args:- input: the predicted disparity map with arbitrary shape :math:`(*)`.+ input: the predicted disparity map with arbitrary shape ``(*)``.target: the ground truth disparity map with the same shape as ``input``.valid_mask: optional mask broadcastable to the shape of ``input``, where nonzero(``True``) values mark the pixels to evaluate. Non-boolean masks are converted@@ -272,7 +272,7 @@ def mean_bad_pixel_error(number of bad pixels.Args:- input: the predicted disparity map with arbitrary shape :math:`(*)`.+ input: the predicted disparity map with arbitrary shape ``(*)``.target: the ground truth disparity map with the same shape as ``input``.threshold: the disparity error above which a pixel is considered bad.valid_mask: optional mask broadcastable to the shape of ``input``, where nonzero@@ -348,7 +348,7 @@ def kitti_d1_error(change the result.Args:- input: the predicted disparity map with arbitrary shape :math:`(*)`.+ input: the predicted disparity map with arbitrary shape ``(*)``.target: the ground truth disparity map with the same shape as ``input``.abs_threshold: the absolute disparity error above which a pixel may be an outlier.rel_threshold: the relative disparity error above which a pixel may be an outlier.diff --git a/kornia/metrics/endpoint_error.py b/kornia/metrics/endpoint_error.pyindex 7e9f22439..04b4c8204 100644--- a/kornia/metrics/endpoint_error.py+++ b/kornia/metrics/endpoint_error.py@@ -32,28 +32,28 @@ def aepe(input: torch.Tensor, target: torch.Tensor, reduction: str = "mean") ->\text{AEPE}=\frac{1}{hw}\sum_{i=1, j=1}^{h, w}\sqrt{(I_{i,j,1}-T_{i,j,1})^{2}+(I_{i,j,2}-T_{i,j,2})^{2}}Convention:- - Flow is channel-last, :math:`(*, 2)` such as :math:`(B, H, W, 2)`, in the units of the flow (pixels for- optical flow). Permute a channel-first :math:`(B, 2, H, W)` flow to :math:`(B, H, W, 2)` first: it raises+ - Flow is channel-last, ``(*, 2)`` such as ``(B, H, W, 2)``, in the units of the flow (pixels for+ optical flow). Permute a channel-first ``(B, 2, H, W)`` flow to ``(B, H, W, 2)`` first: it raisesunless :math:`W = 2`, where it is read wrongly. :ref:`Losses and metrics <losses-metrics-conventions>` portsRAFT's endpoint error.- The endpoint error is the Euclidean distance between the two vectors at every position, symmetric in``input`` and ``target`` and not normalized by the image size. ``reduction='mean'`` (the default) averagesit over every position of every sample at once and ``'sum'`` adds it up, both into a 0-d tensor;- ``'none'`` returns the :math:`(*)` map. There is no valid mask: mask sparse ground truth on the ``'none'``+ ``'none'`` returns the ``(*)`` map. There is no valid mask: mask sparse ground truth on the ``'none'``map. An unknown ``reduction`` raises ``NotImplementedError``.- :func:`~kornia.metrics.aepe` and :func:`~kornia.metrics.average_endpoint_error` are the same function.- Float16 and bfloat16 inputs are computed in float32 and the result is returned in their promoted dtype.Args:- input: the input flow map with shape :math:`(*, 2)`.- target: the target flow map with shape :math:`(*, 2)`.+ input: the input flow map with shape ``(*, 2)``.+ target: the target flow map with shape ``(*, 2)``.reduction : Specifies the reduction to apply to theoutput: ``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction will be applied,``'mean'``: the sum of the output will be divided by the number of elementsin the output, ``'sum'``: the output will be summed.Return:- the computed AEPE as a 0-d tensor, or the endpoint-error map of shape :math:`(*)` for ``reduction='none'``.+ the computed AEPE as a 0-d tensor, or the endpoint-error map of shape ``(*)`` for ``reduction='none'``.Examples:>>> ones = torch.ones(4, 4, 2)@@ -118,9 +118,9 @@ class AEPE(nn.Module):in the output, ``'sum'``: the output will be summed.Shape:- - input: :math:`(*, 2)`.- - target :math:`(*, 2)`.- - output: :math:`()` for ``'mean'`` and ``'sum'``, :math:`(*)` for ``'none'``.+ - input: ``(*, 2)``.+ - target ``(*, 2)``.+ - output: :math:`()` for ``'mean'`` and ``'sum'``, ``(*)`` for ``'none'``.Examples:>>> input1 = torch.rand(1, 4, 5, 2)@@ -138,7 +138,7 @@ class AEPE(nn.Module):"""Compute average endpoint error between vector fields.Args:- input: Predicted vector field with shape :math:`(B, H, W, 2)`.+ input: Predicted vector field with shape ``(B, H, W, 2)``.target: Target vector field with the same shape as ``input``.Returns:diff --git a/kornia/metrics/mean_iou.py b/kornia/metrics/mean_iou.pyindex bc898e588..1eb59c4c7 100644--- a/kornia/metrics/mean_iou.py+++ b/kornia/metrics/mean_iou.py@@ -30,7 +30,7 @@ def mean_iou(pred: torch.Tensor, target: torch.Tensor, num_classes: int, eps: flConvention:- See the Convention block of :func:`~kornia.metrics.confusion_matrix`, which counts the labels: the samelabel contract, one result per sample.- - The result is the IoU of every class in every sample, :math:`(B, K)` float32, each a fraction in+ - The result is the IoU of every class in every sample, ``(B, K)`` float32, each a fraction in:math:`[0, 1]`; despite the name, neither axis is averaged. Averaging it over :math:`B` gives the mean ofper-image IoUs; for the IoU of a whole dataset, sum :func:`~kornia.metrics.confusion_matrix` over allimages and take the IoU of the sum.@@ -42,7 +42,7 @@ def mean_iou(pred: torch.Tensor, target: torch.Tensor, num_classes: int, eps: flArgs:pred : tensor with estimated targets returned by a- classifier. The shape can be :math:`(B, *)` and must contain integer+ classifier. The shape can be ``(B, *)`` and must contain integervalues between 0 and K-1.target: tensor with ground truth (correct) targetvalues. The shape must be that of ``pred``, and it must contain integer@@ -51,7 +51,7 @@ def mean_iou(pred: torch.Tensor, target: torch.Tensor, num_classes: int, eps: fleps: the value added to the numerator and the denominator of every IoU.Returns:- a tensor with the IoU of every class, with shape :math:`(B, K)` where K is the number of classes.+ a tensor with the IoU of every class, with shape ``(B, K)`` where K is the number of classes.Example:>>> logits = torch.tensor([[0, 1, 0]])@@ -112,7 +112,7 @@ def mean_iou_bbox(boxes_1: torch.Tensor, boxes_2: torch.Tensor, box_format: str"""Compute the IoU of the cartesian product of two sets of boxes.Convention:- - The result is the IoU of every pair, :math:`(B1, B2)`, each a fraction in :math:`[0, 1]`; despite the name,+ - The result is the IoU of every pair, ``(B1, B2)``, each a fraction in :math:`[0, 1]`; despite the name,nothing is averaged, and swapping the two sets transposes it.- Boxes are exclusive in every ``box_format``: the area of ``(x1, y1, x2, y2)`` is:math:`(x_2 - x_1)(y_2 - y_1)`, with no ``+ 1``, as in :func:`~kornia.geometry.bbox.nms`. A box with a@@ -122,8 +122,8 @@ def mean_iou_bbox(boxes_1: torch.Tensor, boxes_2: torch.Tensor, box_format: strinclusive ``'xyxy_plus'`` export.Args:- boxes_1: a tensor of bounding boxes in :math:`(B1, 4)`.- boxes_2: a tensor of bounding boxes in :math:`(B2, 4)`.+ boxes_1: a tensor of bounding boxes in ``(B1, 4)``.+ boxes_2: a tensor of bounding boxes in ``(B2, 4)``.box_format: the bounding box format. Supported formats are:- 'xyxy': (x1, y1, x2, y2) where (x1, y1) is top-left and (x2, y2) is bottom-right- 'xywh': (x, y, w, h) where (x, y) is top-left, w is width, h is height@@ -131,7 +131,7 @@ def mean_iou_bbox(boxes_1: torch.Tensor, boxes_2: torch.Tensor, box_format: strDefault: 'xyxy'.Returns:- a tensor in dimensions :math:`(B1, B2)`, representing the+ a tensor in dimensions ``(B1, B2)``, representing theIoU of each of the boxes in set 1 with each of the boxes in set 2... note::diff --git a/kornia/metrics/pose.py b/kornia/metrics/pose.pyindex 59c8bf2b3..9966454b4 100644--- a/kornia/metrics/pose.py+++ b/kornia/metrics/pose.py@@ -64,11 +64,11 @@ def angle_error_mat(R1: Tensor, R2: Tensor) -> Tensor:checked to be rotations.Args:- R1: a rotation matrix of shape :math:`(*, 3, 3)`.- R2: a rotation matrix of shape :math:`(*, 3, 3)`.+ R1: a rotation matrix of shape ``(*, 3, 3)``.+ R2: a rotation matrix of shape ``(*, 3, 3)``.Return:- the per-matrix angle in degrees, with shape :math:`(*,)`.+ the per-matrix angle in degrees, with shape ``(*,)``... note::The angle has a kink at exactly :math:`0^\circ` and :math:`180^\circ` (identical or opposite@@ -110,11 +110,11 @@ def angle_error_vec(v1: Tensor, v2: Tensor) -> Tensor:folded: opposite vectors give 180.Args:- v1: a vector of shape :math:`(*, 3)`.- v2: a vector of shape :math:`(*, 3)`.+ v1: a vector of shape ``(*, 3)``.+ v2: a vector of shape ``(*, 3)``.Return:- the per-vector angle in degrees, with shape :math:`(*,)`.+ the per-vector angle in degrees, with shape ``(*,)``... note::The angle has a kink at exactly :math:`0^\circ` and :math:`180^\circ` (identical or opposite@@ -159,12 +159,12 @@ def translation_ate(t: Tensor, t_gt: Tensor) -> Tensor:the translations, with no alignment: a trajectory shifted by a constant keeps that offset at every pose.Args:- t: an estimated translation of shape :math:`(*, 3)`.+ t: an estimated translation of shape ``(*, 3)``.t_gt: a ground-truth translation of the same shape as ``t``.Return:- the per-sample translation error, with shape :math:`(*,)`. An unbatched :math:`(3,)` input is- treated as a single sample and returns shape :math:`(1,)`.+ the per-sample translation error, with shape ``(*,)``. An unbatched ``(3,)`` input is+ treated as a single sample and returns shape ``(1,)``... note::The gradient stays finite even at zero distance, where ``norm`` returns the subgradient ``0``.@@ -191,21 +191,21 @@ def pose_errors(P: Tensor, P_gt: Tensor, fold_translation: bool = True) -> dict[Convention:- Every error is an angle in **degrees**, one per pose and never averaged over the batch; an unbatched pose- gives shape :math:`(1,)`, where :func:`~kornia.metrics.angle_error_mat` gives a 0-d tensor.+ gives shape ``(1,)``, where :func:`~kornia.metrics.angle_error_mat` gives a 0-d tensor.- ``"R_err"`` is :func:`~kornia.metrics.angle_error_mat` of the two rotation blocks and is never folded.``"t_err"`` is :func:`~kornia.metrics.angle_error_vec` of the two translations, so it compares theirdirections only, folded as ``fold_translation`` says. ``"max_err"`` is the larger of the two per pose.- - Only the top three rows are read: the bottom row of a :math:`(4, 4)` pose is ignored.+ - Only the top three rows are read: the bottom row of a ``(4, 4)`` pose is ignored.Args:- P: an estimated relative pose ``[R | t]`` of shape :math:`(3, 4)`, :math:`(4, 4)`, or batched- :math:`(B, 3, 4)` / :math:`(B, 4, 4)`.+ P: an estimated relative pose ``[R | t]`` of shape ``(3, 4)``, ``(4, 4)``, or batched+ ``(B, 3, 4)`` / ``(B, 4, 4)``.P_gt: a ground-truth relative pose of the same shape.fold_translation: if ``True`` (default), fold the translation error into :math:`[0, 90]` via:math:`\min(e, 180 - e)` to absorb the sign ambiguity of an essential-matrix translation.Return:- a dict of per-pose errors of shape :math:`(B,)`: ``"R_err"`` (rotation), ``"t_err"``+ a dict of per-pose errors of shape ``(B,)``: ``"R_err"`` (rotation), ``"t_err"``(translation) and ``"max_err"`` (element-wise max of the two)... note::@@ -255,7 +255,7 @@ def auc_from_errors(errors: Tensor, thresholds: float | Sequence[float] = (1, 3,SuperGlue.Args:- errors: per-sample error values of shape :math:`(B,)`. Must be non-negative. Integer and+ errors: per-sample error values of shape ``(B,)``. Must be non-negative. Integer andhalf-precision inputs are promoted to the default floating dtype before accumulating.thresholds: a single threshold or a sequence of thresholds, in the same units as ``errors``.Must be strictly positive. Defaults to ``(1, 3, 5, 10)``.diff --git a/kornia/metrics/psnr.py b/kornia/metrics/psnr.pyindex 2e3c8b9f3..abd644994 100644--- a/kornia/metrics/psnr.py+++ b/kornia/metrics/psnr.py@@ -55,8 +55,8 @@ def psnr(image: torch.Tensor, target: torch.Tensor, max_val: _PSNRMaxVal) -> torgives a float32 result for half-precision images.Args:- image: the input image with arbitrary shape :math:`(*)`.- target: the labels image with arbitrary shape :math:`(*)`.+ image: the input image with arbitrary shape ``(*)``.+ target: the labels image with arbitrary shape ``(*)``.max_val: the data range of the images, :math:`\text{MAX}_I`, as a float, integer or tensor.Return:diff --git a/kornia/metrics/ssim.py b/kornia/metrics/ssim.pyindex d32ad6f24..1992e26e2 100644--- a/kornia/metrics/ssim.py+++ b/kornia/metrics/ssim.py@@ -131,7 +131,7 @@ def ssim(- The window is a sampled Gaussian with :math:`\sigma = 1.5` whatever ``window_size``, which sets only thenumber of taps and must be odd.- ``padding='same'`` pads with ``'reflect'``, the torch mode that :ref:`Filtering <filtering-conventions>` maps- onto OpenCV and scipy, and keeps :math:`(H, W)`; ``'valid'`` drops ``window_size // 2`` pixels on every side+ onto OpenCV and scipy, and keeps ``(H, W)``; ``'valid'`` drops ``window_size // 2`` pixels on every sideand equals the ``'same'`` map cropped. Sizes are not checked: ``'same'`` needs ``H`` and ``W`` larger than``window_size // 2``.- ``max_val`` is the data range :math:`L`, a Python ``float``: :math:`c_1 = (0.01 L)^2` and@@ -147,8 +147,8 @@ def ssim(- ``padding`` accepts ``'same'`` and ``'valid'`` case-insensitively; unsupported values raise ``BaseError``.Args:- img1: the first input image with shape :math:`(B, C, H, W)`.- img2: the second input image with shape :math:`(B, C, H, W)`.+ img1: the first input image with shape ``(B, C, H, W)``.+ img2: the second input image with shape ``(B, C, H, W)``.window_size: the size of the gaussian kernel to smooth the images.max_val: the dynamic range of the images.eps: Small value for numerically stability when dividing.@@ -156,7 +156,7 @@ def ssim(area to compute SSIM to match the MATLAB implementation of original SSIM paper.Returns:- The ssim index map with shape :math:`(B, C, H, W)`, or :math:`(B, C, H - 2p, W - 2p)` with+ The ssim index map with shape ``(B, C, H, W)``, or :math:`(B, C, H - 2p, W - 2p)` with``p = window_size // 2`` under ``padding='valid'``.Note:@@ -301,9 +301,9 @@ class SSIM(nn.Module):area to compute SSIM to match the MATLAB implementation of original SSIM paper.Shape:- - Input: :math:`(B, C, H, W)`.- - Target :math:`(B, C, H, W)`.- - Output: :math:`(B, C, H, W)`, or :math:`(B, C, H - 2p, W - 2p)` with ``p = window_size // 2`` under+ - Input: ``(B, C, H, W)``.+ - Target ``(B, C, H, W)``.+ - Output: ``(B, C, H, W)``, or :math:`(B, C, H - 2p, W - 2p)` with ``p = window_size // 2`` under``padding='valid'``.Examples:@@ -325,11 +325,11 @@ class SSIM(nn.Module):"""Compute a 2D SSIM map between two image batches.Args:- img1: First image tensor with shape :math:`(B, C, H, W)`.+ img1: First image tensor with shape ``(B, C, H, W)``.img2: Second image tensor with the same shape as ``img1``.Returns:- Tensor with shape :math:`(B, C, H, W)`, cropped under ``padding='valid'``, containing local structural+ Tensor with shape ``(B, C, H, W)``, cropped under ``padding='valid'``, containing local structuralsimilarity values for each channel and spatial location."""return ssim(img1, img2, self.window_size, self.max_val, self.eps, self.padding)diff --git a/kornia/metrics/ssim3d.py b/kornia/metrics/ssim3d.pyindex b7f94184e..23b0d9822 100644--- a/kornia/metrics/ssim3d.py+++ b/kornia/metrics/ssim3d.py@@ -68,14 +68,14 @@ def ssim3d(Convention:- See the Convention block of :func:`~kornia.metrics.ssim` for the window, reflected border, ``padding`` and- ``max_val``. ``ssim3d`` applies them to :math:`(D, H, W)` with an isotropic Gaussian window, and ``'valid'``+ ``max_val``. ``ssim3d`` applies them to ``(D, H, W)`` with an isotropic Gaussian window, and ``'valid'``crops every axis. A volume of identical slices reproduces the 2-D map up to floating-point roundoff.- The Gaussian window uses the computation dtype of the inputs; integer and half-precision inputs areevaluated in float32.Args:- img1: the first input image with shape :math:`(B, C, D, H, W)`.- img2: the second input image with shape :math:`(B, C, D, H, W)`.+ img1: the first input image with shape ``(B, C, D, H, W)``.+ img2: the second input image with shape ``(B, C, D, H, W)``.window_size: the size of the gaussian kernel to smooth the images.max_val: the dynamic range of the images.eps: Small value for numerically stability when dividing.@@ -83,7 +83,7 @@ def ssim3d(area to compute SSIM to match the MATLAB implementation of original SSIM paper.Returns:- The ssim index map with shape :math:`(B, C, D, H, W)`, or :math:`(B, C, D - 2p, H - 2p, W - 2p)` with+ The ssim index map with shape ``(B, C, D, H, W)``, or :math:`(B, C, D - 2p, H - 2p, W - 2p)` with``p = window_size // 2`` under ``padding='valid'``.Note:@@ -216,9 +216,9 @@ class SSIM3D(nn.Module):area to compute SSIM to match the MATLAB implementation of original SSIM paper.Shape:- - Input: :math:`(B, C, D, H, W)`.- - Target :math:`(B, C, D, H, W)`.- - Output: :math:`(B, C, D, H, W)`, or :math:`(B, C, D - 2p, H - 2p, W - 2p)` with ``p = window_size // 2``+ - Input: ``(B, C, D, H, W)``.+ - Target ``(B, C, D, H, W)``.+ - Output: ``(B, C, D, H, W)``, or :math:`(B, C, D - 2p, H - 2p, W - 2p)` with ``p = window_size // 2``under ``padding='valid'``.Examples:@@ -240,11 +240,11 @@ class SSIM3D(nn.Module):"""Compute a 3D SSIM map between two volume batches.Args:- img1: First volume tensor with shape :math:`(B, C, D, H, W)`.+ img1: First volume tensor with shape ``(B, C, D, H, W)``.img2: Second volume tensor with the same shape as ``img1``.Returns:- Tensor with shape :math:`(B, C, D, H, W)`, cropped under ``padding='valid'``, containing local+ Tensor with shape ``(B, C, D, H, W)``, cropped under ``padding='valid'``, containing localstructural similarity values across depth, height, and width."""return ssim3d(img1, img2, self.window_size, self.max_val, self.eps, self.padding)diff --git a/kornia/models/_hf_models/preprocessor.py b/kornia/models/_hf_models/preprocessor.pyindex 86bf51826..b2feeb09d 100644--- a/kornia/models/_hf_models/preprocessor.py+++ b/kornia/models/_hf_models/preprocessor.py@@ -89,7 +89,7 @@ class _DPTResize(nn.Module):self.interpolation = interpolationdef forward(self, image: torch.Tensor) -> torch.Tensor:- """Resize ``image`` of shape :math:`(*, C, H, W)` to the DPT output size of its ``H`` and ``W``."""+ """Resize ``image`` of shape ``(*, C, H, W)`` to the DPT output size of its ``H`` and ``W``."""height, width = image.shape[-2:]output_size = _dpt_output_size(height, width, self.size, self.keep_aspect_ratio, self.multiple)batch = image.reshape(-1, *image.shape[-3:])diff --git a/kornia/models/base.py b/kornia/models/base.pyindex 3dedfd2a2..a74fe68a5 100644--- a/kornia/models/base.py+++ b/kornia/models/base.py@@ -84,11 +84,11 @@ class ModelBaseMixin:is_batch: If True, the output is expected to be a batch of tensors.Returns:- The output unchanged for "torch". For "pil", a list of PIL images, one per :math:`(C, H, W)` or- :math:`(H, W)` image: a :math:`(B, C, H, W)` tensor gives B images, and a list gives the images of each+ The output unchanged for "torch". For "pil", a list of PIL images, one per ``(C, H, W)`` or+ ``(H, W)`` image: a ``(B, C, H, W)`` tensor gives B images, and a list gives the images of eachelement in turn. They are converted as :meth:`~kornia.core.mixin.image_module.ImageModuleMixIn.to_pil`does: a floating image is clamped to ``[0, 1]`` and rounded to 8 bits, and a one-channel or- :math:`(H, W)` image becomes a mode ``"L"`` image.+ ``(H, W)`` image becomes a mode ``"L"`` image.Raises:RuntimeError: If the output type is not supported.diff --git a/kornia/models/common.py b/kornia/models/common.pyindex ded17dc03..49e85f0ed 100644--- a/kornia/models/common.py+++ b/kornia/models/common.py@@ -167,7 +167,7 @@ class LayerNorm2d(nn.Module):"""Apply channel-wise layer normalization to an NCHW tensor.Args:- x: Tensor with shape :math:`(B, C, H, W)`, where :math:`B` is batch+ x: Tensor with shape ``(B, C, H, W)``, where :math:`B` is batchsize, :math:`C` is channel count, :math:`H` is height, and:math:`W` is width.diff --git a/kornia/models/depth_estimation/base.py b/kornia/models/depth_estimation/base.pyindex 087b9205f..b57f9072d 100644--- a/kornia/models/depth_estimation/base.py+++ b/kornia/models/depth_estimation/base.py@@ -44,12 +44,12 @@ class DepthEstimation(HFONNXComunnityModel):cast to the dtype of the image and moved to its device.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`. Any floating dtype.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``. Any floating dtype.Returns:- The depth maps at the size of the images: a tensor of shape :math:`(B, 1, H, W)` for a tensor, and a- list of tensors of shape :math:`(1, H, W)` for a list.+ The depth maps at the size of the images: a tensor of shape ``(B, 1, H, W)`` for a tensor, and a+ list of tensors of shape ``(1, H, W)`` for a list.Raises:BaseError: If an image is not of a floating dtype.@@ -60,7 +60,7 @@ class DepthEstimation(HFONNXComunnityModel):return self._estimate(images)def _estimate(self, images: torch.Tensor) -> torch.Tensor:- """Return the depth maps :math:`(B, 1, H, W)` of a batch of images :math:`(B, 3, H, W)`."""+ """Return the depth maps ``(B, 1, H, W)`` of a batch of images ``(B, 3, H, W)``."""KORNIA_CHECK(images.is_floating_point(), f"images must be of a floating dtype, got {images.dtype}")# float32 is the dtype the graph takes, and the resizes run in it as well, so that the depth does not depend on# the input dtype. They run on the CPU, where ONNX Runtime reads its input: torch 2.5.1 has no bicubic kernel@@ -87,15 +87,15 @@ class DepthEstimation(HFONNXComunnityModel):"""Draw the depth maps.Args:- images: a tensor of shape :math:`(B, 3, H, W)` or a list of tensors of shape :math:`(3, H, W)`.- depth_maps: estimated depths, as the model returns them: :math:`(B, 1, H, W)` or a list of- :math:`(1, H, W)`. Estimated from ``images`` if not given.+ images: a tensor of shape ``(B, 3, H, W)`` or a list of tensors of shape ``(3, H, W)``.+ depth_maps: estimated depths, as the model returns them: ``(B, 1, H, W)`` or a list of+ ``(1, H, W)``. Estimated from ``images`` if not given.output_type: type of the output.depth_type: 'metric' or 'relative' depth.max_depth: maximum depth value. Only valid for metric depth.Returns:- A list with one RGB image of shape :math:`(3, H, W)` per depth map, the depth divided by its maximum+ A list with one RGB image of shape ``(3, H, W)`` per depth map, the depth divided by its maximum(``"relative"``) or by ``max_depth`` (``"metric"``), converted according to ``output_type``."""@@ -125,9 +125,9 @@ class DepthEstimation(HFONNXComunnityModel):"""Save the images and their depth maps.Args:- images: a tensor of shape :math:`(B, 3, H, W)` or a list of tensors of shape :math:`(3, H, W)`.- depth_maps: estimated depths, as the model returns them: :math:`(B, 1, H, W)` or a list of- :math:`(1, H, W)`. Estimated from ``images`` if not given.+ images: a tensor of shape ``(B, 3, H, W)`` or a list of tensors of shape ``(3, H, W)``.+ depth_maps: estimated depths, as the model returns them: ``(B, 1, H, W)`` or a list of+ ``(1, H, W)``. Estimated from ``images`` if not given.output_type: type of the output.depth_type: 'metric' or 'relative' depth.max_depth: maximum depth value. Only valid for metric depth.diff --git a/kornia/models/dexined.py b/kornia/models/dexined.pyindex fe62e0a8c..51af5d6b3 100644--- a/kornia/models/dexined.py+++ b/kornia/models/dexined.py@@ -197,7 +197,7 @@ class DexiNed(ONNXExportMixin, nn.Module):converts an RGB image in :math:`[0, 1]` to this input and applies a sigmoid to the output.Return:- The fused edge logits, one tensor with shape :math:`(B,1,H,W)`.+ The fused edge logits, one tensor with shape ``(B,1,H,W)``.Example:>>> img = torch.rand(1, 3, 320, 320)@@ -275,7 +275,7 @@ class DexiNed(ONNXExportMixin, nn.Module):Args:x: Input BGR image tensor in :math:`[0, 255]` minus the BGR mean ``[103.939, 116.779, 123.68]``, with- shape :math:`(B, 3, H, W)`, where :math:`B` is batch size, :math:`H` is height, and :math:`W` is+ shape ``(B, 3, H, W)``, where :math:`B` is batch size, :math:`H` is height, and :math:`W` iswidth.Returns:@@ -331,10 +331,10 @@ class DexiNed(ONNXExportMixin, nn.Module):Args:x: Input BGR image tensor in :math:`[0, 255]` minus the BGR mean ``[103.939, 116.779, 123.68]``, with- shape :math:`(B, 3, H, W)`.+ shape ``(B, 3, H, W)``.Returns:- Tensor with shape :math:`(B, 1, H, W)` containing the fused DexiNed+ Tensor with shape ``(B, 1, H, W)`` containing the fused DexiNededge logits."""features = self.get_features(x)diff --git a/kornia/models/efficient_vit/backbone.py b/kornia/models/efficient_vit/backbone.pyindex 6b86e5f0a..d8d76e227 100644--- a/kornia/models/efficient_vit/backbone.py+++ b/kornia/models/efficient_vit/backbone.py@@ -180,7 +180,7 @@ class EfficientViTBackbone(nn.Module):"""Run the EfficientViT backbone and collect stage outputs.Args:- x: Image tensor with shape :math:`(B, C, H, W)`.+ x: Image tensor with shape ``(B, C, H, W)``.Returns:Dictionary containing the input, each stage output, and@@ -392,7 +392,7 @@ class EfficientViTLargeBackbone(nn.Module):"""Run the EfficientViT large backbone and collect stage outputs.Args:- x: Image tensor with shape :math:`(B, C, H, W)`.+ x: Image tensor with shape ``(B, C, H, W)``.Returns:Dictionary with entries for each stage and ``"stage_final"`` fordiff --git a/kornia/models/efficient_vit/model.py b/kornia/models/efficient_vit/model.pyindex ddc191e2b..cc7be940a 100644--- a/kornia/models/efficient_vit/model.py+++ b/kornia/models/efficient_vit/model.py@@ -118,7 +118,7 @@ class EfficientViT(ModelBase[EfficientViTConfig]):"""Extract features from the input images.Args:- images: input images tensor of shape :math:`(B, C, H, W)`.+ images: input images tensor of shape ``(B, C, H, W)``.Returns:a dictionary with the input under ``"input"``, the output of each stage under ``"stage0"``,diff --git a/kornia/models/efficient_vit/nn/norm.py b/kornia/models/efficient_vit/nn/norm.pyindex ec1b133fd..a295dce67 100644--- a/kornia/models/efficient_vit/nn/norm.py+++ b/kornia/models/efficient_vit/nn/norm.py@@ -35,7 +35,7 @@ class LayerNorm2d(nn.LayerNorm):"""Normalize an NCHW feature map across channels.Args:- x: Tensor with shape :math:`(B, C, H, W)`.+ x: Tensor with shape ``(B, C, H, W)``.Returns:Tensor with the same shape as ``x`` after channel-wise layerdiff --git a/kornia/models/efficient_vit/nn/ops.py b/kornia/models/efficient_vit/nn/ops.pyindex 10d10038b..6b70ab8a9 100644--- a/kornia/models/efficient_vit/nn/ops.py+++ b/kornia/models/efficient_vit/nn/ops.py@@ -97,7 +97,7 @@ class ConvLayer(nn.Module):"""Apply dropout, convolution, optional normalization, and activation.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after the configured convolutional layer stack.@@ -175,7 +175,7 @@ class DSConv(nn.Module):"""Apply depthwise then pointwise convolution.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map with ``out_channels`` produced by the pointwise@@ -248,7 +248,7 @@ class MBConv(nn.Module):"""Apply an inverted bottleneck convolution block.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after expansion, depthwise convolution, and projection.@@ -320,7 +320,7 @@ class FusedMBConv(nn.Module):"""Apply a fused mobile inverted bottleneck convolution.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after fused spatial convolution and pointwise@@ -382,7 +382,7 @@ class ResBlock(nn.Module):"""Apply the two-convolution residual-block main branch.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after the block's convolutional transformations.@@ -499,7 +499,7 @@ class LiteMLA(nn.Module):"""Apply lightweight multi-scale linear attention.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after multi-scale query/key/value aggregation, linear@@ -564,7 +564,7 @@ class EfficientViTBlock(nn.Module):"""Apply an EfficientViT attention-plus-local block.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map with the same shape after the context module and localdiff --git a/kornia/models/kimi_vl/moonvit.py b/kornia/models/kimi_vl/moonvit.pyindex 5148e2025..3f1073d95 100644--- a/kornia/models/kimi_vl/moonvit.py+++ b/kornia/models/kimi_vl/moonvit.py@@ -166,7 +166,7 @@ class MoonViTAttention(nn.Module):"""Apply rotary self-attention to a sequence of visual patch tokens.Args:- hidden_states: Input token tensor with shape :math:`(B, N, D)`, where+ hidden_states: Input token tensor with shape ``(B, N, D)``, where``B`` is the batch size, ``N`` is the number of flattened imagepatches, and ``D`` is the hidden size.cos: Cosine component of the rotary positional embedding with shape@@ -175,17 +175,17 @@ class MoonViTAttention(nn.Module)::math:`(N, d / 2)`.attention_mask: Optional boolean mask, ``True`` where a query may attend to a key. A 2-D or 3-D maskholds one mask per sample, shared by the heads, as- :class:`~kornia.models.siglip2.attention.SigLip2Attention` reads it: :math:`(B, N)` masks keys- (padding) and :math:`(B, N, N)` query-key pairs; a leading dimension of 1 shares the mask across the- batch, and any other raises. A 4-D mask, such as :math:`(B, 1, N, N)` or a per-head- :math:`(1, H, N, N)`, is passed as is and broadcasts against the :math:`(B, H, N, N)` attention scores+ :class:`~kornia.models.siglip2.attention.SigLip2Attention` reads it: ``(B, N)`` masks keys+ (padding) and ``(B, N, N)`` query-key pairs; a leading dimension of 1 shares the mask across the+ batch, and any other raises. A 4-D mask, such as ``(B, 1, N, N)`` or a per-head+ ``(1, H, N, N)``, is passed as is and broadcasts against the ``(B, H, N, N)`` attention scoresof :func:`~torch.nn.functional.scaled_dot_product_attention`. The last dimension of every form is the:math:`N` keys, and in a 3-D or 4-D mask the one before it is the :math:`N` queries or 1, whichshares the key mask across the queries; other sizes raise. An integer mask is read as boolean; afloat mask is added to the scores.Returns:- Tensor with shape :math:`(B, N, D)` containing the attended visual token+ Tensor with shape ``(B, N, D)`` containing the attended visual tokenfeatures after the output projection."""batch_size, seq_len, _ = hidden_states.shape@@ -243,12 +243,12 @@ class MoonViTMLP(nn.Module):"""Project token features through the MoonViT feed-forward network.Args:- x: Input token features with shape :math:`(B, N, D)`, where ``B`` is the+ x: Input token features with shape ``(B, N, D)``, where ``B`` is thebatch size, ``N`` is the number of patch tokens, and ``D`` is the modelhidden size.Returns:- Tensor with shape :math:`(B, N, D)` after expansion to the intermediate+ Tensor with shape ``(B, N, D)`` after expansion to the intermediatehidden size, GELU activation, projection back to ``D``, and dropout."""x = self.fc1(x)@@ -287,7 +287,7 @@ class MoonViTLayer(nn.Module):pre-normalization and residual pattern for the MLP sub-block.Args:- x: Token tensor with shape :math:`(B, N, D)`, where ``B`` is the batch+ x: Token tensor with shape ``(B, N, D)``, where ``B`` is the batchsize, ``N`` is the number of flattened image patches, and ``D`` is thehidden size.cos: Cosine rotary embedding table with shape :math:`(N, d / 2)`, where ``d``@@ -297,7 +297,7 @@ class MoonViTLayer(nn.Module):layer.Returns:- Tensor with shape :math:`(B, N, D)` after attention, MLP processing, and+ Tensor with shape ``(B, N, D)`` after attention, MLP processing, andresidual updates."""x = x + self.attn(self.norm1(x), cos, sin, attention_mask)@@ -323,7 +323,7 @@ class MoonViTEncoder(nn.Module):"""Encode visual patch tokens through the full MoonViT transformer stack.Args:- x: Input token tensor with shape :math:`(B, N, D)`, where ``B`` is batch+ x: Input token tensor with shape ``(B, N, D)``, where ``B`` is batchsize, ``N`` is the flattened patch count, and ``D`` is hidden size.cos: Cosine rotary embedding table shared by all encoder layers.sin: Sine rotary embedding table shared by all encoder layers.@@ -331,7 +331,7 @@ class MoonViTEncoder(nn.Module):layout once and shared by every transformer layer.Returns:- Tensor with shape :math:`(B, N, D)` containing the encoded patch sequence+ Tensor with shape ``(B, N, D)`` containing the encoded patch sequenceafter all MoonViT layers have been applied."""if attention_mask is not None:diff --git a/kornia/models/paligemma/modeling_paligemma.py b/kornia/models/paligemma/modeling_paligemma.pyindex 6f5ca6696..d2df3c7e6 100644--- a/kornia/models/paligemma/modeling_paligemma.py+++ b/kornia/models/paligemma/modeling_paligemma.py@@ -43,7 +43,7 @@ class GemmaRMSNorm(nn.Module):"""Apply Gemma RMS normalization to hidden states.Args:- x: Hidden-state tensor with shape :math:`(B, N, D)`, where+ x: Hidden-state tensor with shape ``(B, N, D)``, where:math:`B` is batch size, :math:`N` is sequence length, and:math:`D` is hidden dimension.@@ -80,7 +80,7 @@ class GemmaRotaryEmbedding(nn.Module):Args:x: Tensor whose dtype is used for the returned embeddings.- position_ids: Position tensor with shape :math:`(B, N)`.+ position_ids: Position tensor with shape ``(B, N)``.Returns:Tuple ``(cos, sin)`` containing rotary embedding factors with dtype@@ -132,10 +132,10 @@ class GemmaMLP(nn.Module):"""Apply the gated Gemma feed-forward projection.Args:- x: Hidden-state tensor with shape :math:`(B, N, D)`.+ x: Hidden-state tensor with shape ``(B, N, D)``.Returns:- Tensor with shape :math:`(B, N, D)` after gate projection,+ Tensor with shape ``(B, N, D)`` after gate projection,activation, up projection, elementwise gating, and down projection."""return self.down_proj(self.act_fn(self.gate_proj(x)) * self.up_proj(x))@@ -182,13 +182,13 @@ class GemmaAttention(nn.Module):"""Apply grouped-query self-attention with rotary position embeddings.Args:- hidden_states: Input token tensor with shape :math:`(B, N, D)`.+ hidden_states: Input token tensor with shape ``(B, N, D)``.attention_mask: Optional attention mask passed to scaled dot-productattention.- position_ids: Token position ids with shape :math:`(B, N)`.+ position_ids: Token position ids with shape ``(B, N)``.Returns:- Tensor with shape :math:`(B, N, D)` after attention and output+ Tensor with shape ``(B, N, D)`` after attention and outputprojection."""bsz, q_len, _ = hidden_states.size()@@ -246,12 +246,12 @@ class GemmaDecoderLayer(nn.Module):"""Run one Gemma decoder layer.Args:- hidden_states: Input token tensor with shape :math:`(B, N, D)`.+ hidden_states: Input token tensor with shape ``(B, N, D)``.attention_mask: Optional mask used by the attention block.position_ids: Token position ids used to build rotary embeddings.Returns:- Tensor with shape :math:`(B, N, D)` after self-attention, MLP, and+ Tensor with shape ``(B, N, D)`` after self-attention, MLP, andresidual connections."""residual = hidden_statesdiff --git a/kornia/models/processors/__init__.py b/kornia/models/processors/__init__.pyindex 1db6e034a..b3ee747fb 100644--- a/kornia/models/processors/__init__.py+++ b/kornia/models/processors/__init__.py@@ -62,13 +62,13 @@ class ResizePreProcessor(nn.Module):r"""Resize input images to the target size.Args:- imgs: Input images, either a tensor of shape :math:`(B, C, H, W)` or- a list of tensors of shape :math:`(C, H, W)`.+ imgs: Input images, either a tensor of shape ``(B, C, H, W)`` or+ a list of tensors of shape ``(C, H, W)``.Returns:Tuple containing:- resized_imgs: Resized images as a tensor of shape :math:`(B, C, H_{\text{new}}, W_{\text{new}})`.- - original_sizes: Original image sizes of shape :math:`(B, 2)` containing (height, width), as+ - original_sizes: Original image sizes of shape ``(B, 2)`` containing (height, width), as``int64`` on the images' device."""# int64: a half-precision image dtype cannot hold every size (bfloat16 rounds 667 to 668). Filled in rather@@ -119,13 +119,13 @@ class ResizePostProcessor(nn.Module):r"""Resize model outputs back to original dimensions.Args:- imgs: Input images, either a tensor of shape :math:`(B, C, H, W)` or- a list of tensors of shape :math:`(C, H, W)`.- original_sizes: Original image sizes of shape :math:`(B, 2)` containing+ imgs: Input images, either a tensor of shape ``(B, C, H, W)`` or+ a list of tensors of shape ``(C, H, W)``.+ original_sizes: Original image sizes of shape ``(B, 2)`` containing(height, width) pairs.Returns:- A list of :math:`(1, C, H, W)` tensors, one per image, each resized to its original size. If ONNX export+ A list of ``(1, C, H, W)`` tensors, one per image, each resized to its original size. If ONNX exportis active, returns inputs unchanged with a warning.Warning:diff --git a/kornia/models/processors/naflex.py b/kornia/models/processors/naflex.pyindex fed7d3920..c90bb1587 100644--- a/kornia/models/processors/naflex.py+++ b/kornia/models/processors/naflex.py@@ -44,8 +44,8 @@ class NaFlex(nn.Module):Args:patch_embedding_fcn: A callable (e.g., Conv2d) that takes images and returns- patch embeddings of shape :math:`(B, C, h, w)` or :math:`(B, N, C)`. A :math:`(B, C, h, w)` output gives- the patch grid. A :math:`(B, N, C)` output carries no grid: without ``patch_size`` its :math:`N` tokens+ patch embeddings of shape :math:`(B, C, h, w)` or ``(B, N, C)``. A :math:`(B, C, h, w)` output gives+ the patch grid. A ``(B, N, C)`` output carries no grid: without ``patch_size`` its :math:`N` tokensare read as a square :math:`\sqrt{N} \times \sqrt{N}` grid in raster order, and a :math:`N` that is nota square number raises. A non-square grid therefore needs ``patch_size`` or a :math:`(B, C, h, w)` output:the :math:`8 \times 32` grid of a :math:`128 \times 512` image at patch 16 is read right with@@ -59,7 +59,7 @@ class NaFlex(nn.Module):parameter of the module, so it is trained with it; any other tensor is registered as a buffer. A tablethat is not a square grid is added as is when it has one row per patch.patch_size: The patch size :math:`p` or :math:`(p_h, p_w)` of a patch embedding that returns- :math:`(B, N, C)`, which then has the grid :math:`(H // p_h, W // p_w)` of whole patches with the remainder+ ``(B, N, C)``, which then has the grid :math:`(H // p_h, W // p_w)` of whole patches with the remainderdropped (a ``Conv2d`` with that kernel and stride); the grid must have :math:`N` cells. Ignored for a:math:`(B, C, h, w)` output. Default: ``None``, the square reading above.@@ -112,15 +112,15 @@ class NaFlex(nn.Module):r"""Forward pass through NaFlex wrapper.Args:- pixel_values: Input tensor of shape :math:`(B, C, H, W)`.+ pixel_values: Input tensor of shape ``(B, C, H, W)``.Returns:- Embeddings with interpolated positional embeddings of shape :math:`(B, N, C)`.+ Embeddings with interpolated positional embeddings of shape ``(B, N, C)``.Raises:ValueError: If original positional embedding does not form a square grid and does not have one row perpatch.- BaseError: If a :math:`(B, N, C)` patch output's grid cannot be read: with ``patch_size``, when+ BaseError: If a ``(B, N, C)`` patch output's grid cannot be read: with ``patch_size``, when:math:`(H // p_h) (W // p_w) \neq N`; without it, when :math:`N` is not a square number."""embeddings = self.patch_embedding_fcn(pixel_values)diff --git a/kornia/models/qwen25/vision.py b/kornia/models/qwen25/vision.pyindex 5ca219c34..d3fa10f39 100644--- a/kornia/models/qwen25/vision.py+++ b/kornia/models/qwen25/vision.py@@ -78,7 +78,7 @@ class Qwen25RMSNorm(nn.Module):"""Normalize ``x`` over its last dimension.Args:- x: Tensor with shape :math:`(*, D)`.+ x: Tensor with shape ``(*, D)``.Returns:Tensor with the shape and dtype of ``x``.@@ -106,10 +106,10 @@ class Qwen25VisionPatchEmbed(nn.Module):"""Embed every patch of ``images``.Args:- images: Image tensor with shape :math:`(B, C, H, W)`.+ images: Image tensor with shape ``(B, C, H, W)``.Returns:- Patch tokens with shape :math:`(B, N, D)` in merge order, where :math:`N` is the number of patches.+ Patch tokens with shape ``(B, N, D)`` in merge order, where :math:`N` is the number of patches."""frames = images.unsqueeze(2).expand(-1, -1, self.temporal_patch_size, -1, -1)x = self.proj(frames).squeeze(2)@@ -140,13 +140,13 @@ class Qwen25VisionAttention(nn.Module):"""Attend over the tokens of each image.Args:- x: Tokens with shape :math:`(B, N, D)`.- cos: Rotary cosine table with shape :math:`(N, D / H)`.- sin: Rotary sine table with shape :math:`(N, D / H)`.- attn_mask: Optional boolean mask with shape :math:`(N, N)`, ``True`` where attention is allowed.+ x: Tokens with shape ``(B, N, D)``.+ cos: Rotary cosine table with shape ``(N, D / H)``.+ sin: Rotary sine table with shape ``(N, D / H)``.+ attn_mask: Optional boolean mask with shape ``(N, N)``, ``True`` where attention is allowed.Returns:- Tokens with shape :math:`(B, N, D)`.+ Tokens with shape ``(B, N, D)``."""b, n, d = x.shapeq, k, v = self.qkv(x).reshape(b, n, 3, self.num_heads, self.head_dim).permute(2, 0, 3, 1, 4).unbind(0)@@ -176,10 +176,10 @@ class Qwen25VisionMLP(nn.Module):"""Apply the gated MLP.Args:- x: Tokens with shape :math:`(B, N, D)`.+ x: Tokens with shape ``(B, N, D)``.Returns:- Tokens with shape :math:`(B, N, D)`.+ Tokens with shape ``(B, N, D)``."""return self.down_proj(F.silu(self.gate_proj(x)) * self.up_proj(x))@@ -204,13 +204,13 @@ class Qwen25VisionBlock(nn.Module):"""Run one block.Args:- x: Tokens with shape :math:`(B, N, D)`.- cos: Rotary cosine table with shape :math:`(N, D / H)`.- sin: Rotary sine table with shape :math:`(N, D / H)`.- attn_mask: Optional boolean attention mask with shape :math:`(N, N)`.+ x: Tokens with shape ``(B, N, D)``.+ cos: Rotary cosine table with shape ``(N, D / H)``.+ sin: Rotary sine table with shape ``(N, D / H)``.+ attn_mask: Optional boolean attention mask with shape ``(N, N)``.Returns:- Tokens with shape :math:`(B, N, D)`.+ Tokens with shape ``(B, N, D)``."""x = x + self.attn(self.norm1(x), cos, sin, attn_mask)return x + self.mlp(self.norm2(x))@@ -237,7 +237,7 @@ class Qwen25VisionPatchMerger(nn.Module):"""Merge tokens.Args:- x: Tokens with shape :math:`(B, N, D)` in merge order.+ x: Tokens with shape ``(B, N, D)`` in merge order.Returns:Merged tokens with shape :math:`(B, N / s^2, D_{out})`, where :math:`s` is the spatial merge size.@@ -308,7 +308,7 @@ class Qwen25VisionTransformer(nn.Module):"""Encode a batch of images into vision tokens.Args:- images: Normalized images with shape :math:`(B, C, H, W)`. ``H`` and ``W`` must be multiples of+ images: Normalized images with shape ``(B, C, H, W)``. ``H`` and ``W`` must be multiples of``patch_size * spatial_merge_size`` (28 for the released checkpoints).Returns:diff --git a/kornia/models/rrdbnet.py b/kornia/models/rrdbnet.pyindex fdd70bf0c..1488bd4bb 100644--- a/kornia/models/rrdbnet.py+++ b/kornia/models/rrdbnet.py@@ -93,7 +93,7 @@ class ResidualDenseBlock(nn.Module):_default_init_weights([self.conv1, self.conv2, self.conv3, self.conv4, self.conv5], 0.1)def forward(self, x: torch.Tensor) -> torch.Tensor:- """Run the dense block on ``x`` of shape :math:`(B, C, H, W)`."""+ """Run the dense block on ``x`` of shape ``(B, C, H, W)``."""x1 = self.lrelu(self.conv1(x))x2 = self.lrelu(self.conv2(torch.cat((x, x1), 1)))x3 = self.lrelu(self.conv3(torch.cat((x, x1, x2), 1)))@@ -119,7 +119,7 @@ class RRDB(nn.Module):self.rdb3 = ResidualDenseBlock(num_feat, num_grow_ch)def forward(self, x: torch.Tensor) -> torch.Tensor:- """Run the three stacked dense blocks on ``x`` of shape :math:`(B, C, H, W)`."""+ """Run the three stacked dense blocks on ``x`` of shape ``(B, C, H, W)``."""out = self.rdb1(x)out = self.rdb2(out)out = self.rdb3(out)diff --git a/kornia/models/rt_detr/architecture/hgnetv2.py b/kornia/models/rt_detr/architecture/hgnetv2.pyindex cde93c7ed..d2a0f5d61 100644--- a/kornia/models/rt_detr/architecture/hgnetv2.py+++ b/kornia/models/rt_detr/architecture/hgnetv2.py@@ -47,7 +47,7 @@ class StemBlock(nn.Module):"""Run the HGNetV2 stem and reduce the input spatial resolution.Args:- x: Image tensor with shape :math:`(B, C, H, W)`.+ x: Image tensor with shape ``(B, C, H, W)``.Returns:Stem feature map after strided convolutions, pooling, concatenation,@@ -114,7 +114,7 @@ class HGBlock(nn.Module):"""Apply one HGNetV2 aggregation block.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Aggregated feature map. If ``self.identity`` is enabled, the input@@ -168,7 +168,7 @@ class PPHGNetV2(nn.Module):"""Run the PPHGNetV2 backbone and return detection feature maps.Args:- x: Image tensor with shape :math:`(B, 3, H, W)`.+ x: Image tensor with shape ``(B, 3, H, W)``.Returns:List ``[s3, s4, s5]`` containing the final three backbone stagesdiff --git a/kornia/models/rt_detr/architecture/hybrid_encoder.py b/kornia/models/rt_detr/architecture/hybrid_encoder.pyindex 63686d983..054f85a90 100644--- a/kornia/models/rt_detr/architecture/hybrid_encoder.py+++ b/kornia/models/rt_detr/architecture/hybrid_encoder.py@@ -52,7 +52,7 @@ class RepVggBlock(nn.Module):"""Apply the RepVGG block in training or fused deployment form.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after either the fused convolution or the summed@@ -118,7 +118,7 @@ class CSPRepLayer(nn.Module):"""Fuse cross-stage partial RepVGG features.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map after one branch passes through RepVGG bottlenecks and@@ -157,10 +157,10 @@ class AIFI(nn.Module):"""Apply all-scale feature interaction to one feature map.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:- Tensor with shape :math:`(B, C, H, W)` after positional+ Tensor with shape ``(B, C, H, W)`` after positionalself-attention and feed-forward refinement."""# using post-norm@@ -212,7 +212,7 @@ class AIFI(nn.Module):dtype: data type of the positional embeddingsReturns:- positional embeddings, shape :math:`(H * W, 1, C)`+ positional embeddings, shape ``(H * W, 1, C)``"""xs = torch.arange(w, device=device, dtype=dtype)diff --git a/kornia/models/rt_detr/architecture/resnet_d.py b/kornia/models/rt_detr/architecture/resnet_d.pyindex b0c4fb81c..901aef0f0 100644--- a/kornia/models/rt_detr/architecture/resnet_d.py+++ b/kornia/models/rt_detr/architecture/resnet_d.py@@ -74,7 +74,7 @@ class BasicBlockD(nn.Module):"""Apply a basic ResNet-D residual block.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Tensor after two convolutions, shortcut projection if needed, and@@ -108,7 +108,7 @@ class BottleneckD(nn.Module):"""Apply a bottleneck ResNet-D residual block.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Tensor after ``1x1``, ``3x3``, and ``1x1`` convolutions, shortcut@@ -190,7 +190,7 @@ class ResNetD(nn.Module):"""Run the ResNet-D backbone and return detector feature maps.Args:- x: Image tensor with shape :math:`(B, 3, H, W)`.+ x: Image tensor with shape ``(B, 3, H, W)``.Returns:List ``[res3, res4, res5]`` containing the final three featurediff --git a/kornia/models/rt_detr/architecture/rtdetr_head.py b/kornia/models/rt_detr/architecture/rtdetr_head.pyindex 37c285962..a5f812e99 100644--- a/kornia/models/rt_detr/architecture/rtdetr_head.py+++ b/kornia/models/rt_detr/architecture/rtdetr_head.py@@ -205,7 +205,7 @@ class TransformerDecoderLayer(nn.Module):"""Run one RT-DETR transformer decoder layer.Args:- tgt: Query tensor with shape :math:`(B, N_q, D)`.+ tgt: Query tensor with shape ``(B, N_q, D)``.ref_points: Reference points for deformable cross-attention.memory: Flattened encoder memory tensor.memory_spatial_shapes: Spatial shape for each memory level.@@ -215,7 +215,7 @@ class TransformerDecoderLayer(nn.Module):query_pos_embed: Optional positional embedding for object queries.Returns:- Updated query tensor with shape :math:`(B, N_q, D)`.+ Updated query tensor with shape ``(B, N_q, D)``."""# TODO: rename variables because is confusing# self attention@@ -262,7 +262,7 @@ class TransformerDecoder(nn.Module):"""Decode object queries into bounding boxes and class logits.Args:- tgt: Initial query tensor with shape :math:`(B, N_q, D)`.+ tgt: Initial query tensor with shape ``(B, N_q, D)``.ref_points_unact: Unactivated reference boxes for the queries.memory: Flattened encoder feature memory.memory_spatial_shapes: Spatial shape for each feature level.diff --git a/kornia/models/rt_detr/model.py b/kornia/models/rt_detr/model.pyindex 23195ee83..4189c42bc 100644--- a/kornia/models/rt_detr/model.py+++ b/kornia/models/rt_detr/model.py@@ -377,12 +377,12 @@ class RTDETR(ONNXExportMixin, ModelBase[RTDETRConfig]):"""Detect objects in an image.Args:- images: images to be detected. Shape :math:`(N, C, H, W)`.+ images: images to be detected. Shape ``(N, C, H, W)``.Returns:- - **logits** - Tensor of shape :math:`(N, Q, K)`, where :math:`Q` is the number of queries,+ - **logits** - Tensor of shape ``(N, Q, K)``, where :math:`Q` is the number of queries,:math:`K` is the number of classes.- - **boxes** - Tensor of shape :math:`(N, Q, 4)`, where :math:`Q` is the number of queries.+ - **boxes** - Tensor of shape ``(N, Q, 4)``, where :math:`Q` is the number of queries."""feats = self.backbone(images)diff --git a/kornia/models/rt_detr/post_processor.py b/kornia/models/rt_detr/post_processor.pyindex c7160066a..f207307d4 100644--- a/kornia/models/rt_detr/post_processor.py+++ b/kornia/models/rt_detr/post_processor.py@@ -91,18 +91,18 @@ class DETRPostProcessor(nn.Module):"""Post-process outputs from DETR.Args:- logits: tensor with shape :math:`(N, Q, K)`, where :math:`N` is the batch size, :math:`Q` is the number of+ logits: tensor with shape ``(N, Q, K)``, where :math:`N` is the batch size, :math:`Q` is the number ofqueries, :math:`K` is the number of classes.- boxes: tensor with shape :math:`(N, Q, 4)`, where :math:`N` is the batch size, :math:`Q` is the number of+ boxes: tensor with shape ``(N, Q, 4)``, where :math:`N` is the batch size, :math:`Q` is the number ofqueries.- original_sizes: tensor with shape :math:`(N, 2)`, where :math:`N` is the batch size and each element+ original_sizes: tensor with shape ``(N, 2)``, where :math:`N` is the batch size and each elementrepresents the image size of (img_height, img_width).Returns:Processed detections, each a row (class_id, confidence_score, x, y, w, h). A tensor of shape- :math:`(N, T, 6)`, :math:`T` = ``num_top_queries``, when ``confidence_filtering`` is ``False`` or+ ``(N, T, 6)``, :math:`T` = ``num_top_queries``, when ``confidence_filtering`` is ``False`` or``confidence_threshold`` is 0; with ``filter_as_zero``, the same tensor with the detections at or below the- threshold set to zero. Otherwise a list of :math:`N` tensors of shape :math:`(D, 6)`, where :math:`D` is the+ threshold set to zero. Otherwise a list of :math:`N` tensors of shape ``(D, 6)``, where :math:`D` is thenumber of detections above the threshold in that image."""diff --git a/kornia/models/sam/architecture/image_encoder.py b/kornia/models/sam/architecture/image_encoder.pyindex 2d33370d4..46e0fd288 100644--- a/kornia/models/sam/architecture/image_encoder.py+++ b/kornia/models/sam/architecture/image_encoder.py@@ -139,7 +139,7 @@ class ImageEncoderViT(nn.Module):"""Encode an image batch into SAM image embeddings.Args:- x: Image tensor with shape :math:`(B, C, H, W)`, where :math:`B`+ x: Image tensor with shape ``(B, C, H, W)``, where :math:`B`is batch size, :math:`C` is channel count, and :math:`H`,:math:`W` are image height and width.@@ -208,7 +208,7 @@ class Block(nn.Module):"""Apply one SAM image-encoder transformer block.Args:- x: Feature tensor with shape :math:`(B, H, W, C)`.+ x: Feature tensor with shape ``(B, H, W, C)``.Returns:Tensor with the same shape as ``x`` after window or global@@ -271,10 +271,10 @@ class Attention(nn.Module):"""Apply multi-head attention over 2D image tokens.Args:- x: Token grid with shape :math:`(B, H, W, C)`.+ x: Token grid with shape ``(B, H, W, C)``.Returns:- Tensor with shape :math:`(B, H, W, C)` after attention, optional+ Tensor with shape ``(B, H, W, C)`` after attention, optionaldecomposed relative positional bias, and output projection."""_, H, W, C = x.shape@@ -395,10 +395,10 @@ class PatchEmbed(nn.Module):"""Project an image into patch embeddings.Args:- x: Image tensor with shape :math:`(B, C, H, W)`.+ x: Image tensor with shape ``(B, C, H, W)``.Returns:- Patch embedding tensor with shape :math:`(B, H_p, W_p, D)`, where+ Patch embedding tensor with shape ``(B, H_p, W_p, D)``, where:math:`H_p` and :math:`W_p` are patch-grid dimensions and:math:`D` is embedding dimension."""diff --git a/kornia/models/sam/architecture/transformer.py b/kornia/models/sam/architecture/transformer.pyindex 44f279913..fbe9e74d4 100644--- a/kornia/models/sam/architecture/transformer.py+++ b/kornia/models/sam/architecture/transformer.py@@ -191,8 +191,8 @@ class TwoWayAttentionBlock(nn.Module):"""Run one two-way transformer block for prompt and image tokens.Args:- queries: Prompt token tensor with shape :math:`(B, N_q, D)`.- keys: Image token tensor with shape :math:`(B, N_k, D)`.+ queries: Prompt token tensor with shape ``(B, N_q, D)``.+ keys: Image token tensor with shape ``(B, N_k, D)``.query_pe: Positional encoding for ``queries`` with the same shape.key_pe: Positional encoding for ``keys`` with the same shape.@@ -261,12 +261,12 @@ class Attention(nn.Module):"""Apply scaled dot-product attention to query, key, and value tokens.Args:- q: Query tensor with shape :math:`(B, N_q, D)`.- k: Key tensor with shape :math:`(B, N_k, D)`.- v: Value tensor with shape :math:`(B, N_k, D)`.+ q: Query tensor with shape ``(B, N_q, D)``.+ k: Key tensor with shape ``(B, N_k, D)``.+ v: Value tensor with shape ``(B, N_k, D)``.Returns:- Tensor with shape :math:`(B, N_q, D)` after multi-head attention+ Tensor with shape ``(B, N_q, D)`` after multi-head attentionand output projection."""# Input projectionsdiff --git a/kornia/models/sam/model.py b/kornia/models/sam/model.pyindex 1d8142c5b..3e68f541f 100644--- a/kornia/models/sam/model.py+++ b/kornia/models/sam/model.py@@ -338,14 +338,14 @@ class Sam(ONNXExportMixin, ModelBase[SamConfig]):This method expects that the images have already been pre-processed, at least been normalized, resized andpadded to be compatible with the `self.image_encoder`.- .. note:: For each image :math:`(3, H, W)`, it is possible to input a batch (:math:`K`) of :math:`N` prompts,+ .. note:: For each image ``(3, H, W)``, it is possible to input a batch (:math:`K`) of :math:`N` prompts,the results are batched by the number of prompts batch. So given a prompt with :math:`K=5`, and:math:`N=10`, the results will look like :math:`5xCxHxW` where :math:`C` is determined bymultimask_output. And within each of these masks :math:`(5xC)`, it should be possible to find:math:`N` instances if the model succeed.Args:- images: The image as a torch tensor in :math:`(B, 3, H, W)` format, already transformed for input to the+ images: The image as a torch tensor in ``(B, 3, H, W)`` format, already transformed for input to themodel.batched_prompts: A list over the batch of images (list length should be :math:`B`), each a dictionary withthe following keys. If it does not have the respective prompt, it should not be included@@ -353,25 +353,25 @@ class Sam(ONNXExportMixin, ModelBase[SamConfig]):- "points": tuple of (torch.Tensor, torch.Tensor) within the coordinate keypointsand their respective labels. The tuple should look like (keypoints, labels), where the keypoints- (a tensor) are a batched point prompts for this image, with shape :math:`(K, N, 2)`. Already+ (a tensor) are a batched point prompts for this image, with shape ``(K, N, 2)``. Alreadytransformed to the input frame of the model. The labels (a tensor) are a batched labels for point- prompts, with shape :math:`(K, N)`. Where 1 indicates a foreground point and 0 indicates a background+ prompts, with shape ``(K, N)``. Where 1 indicates a foreground point and 0 indicates a backgroundpoint.- - "boxes": (torch.Tensor) Batched box inputs, with shape :math:`(K, 4)`.+ - "boxes": (torch.Tensor) Batched box inputs, with shape ``(K, 4)``.Already transformed to the input frame of the model.- - "mask_inputs": (torch.Tensor) Batched mask inputs to the model, in the form :math:`(K, 1, H, W)`.+ - "mask_inputs": (torch.Tensor) Batched mask inputs to the model, in the form ``(K, 1, H, W)``.multimask_output: Whether the model should predict multiple disambiguating masks, or return a single mask.Returns:A list over input images, where each element is as SegmentationResults the following:- - logits: Low resolution logits with shape :math:`(K, C, H, W)`. Can be passed as mask input to+ - logits: Low resolution logits with shape ``(K, C, H, W)``. Can be passed as mask input tosubsequent iterations of prediction. Where :math:`K` is the number of input prompts,:math:`C` is determined by multimask_output, and :math:`H=W=256` are the model output size.- - scores: The predicted IoU of each mask, :math:`(K, C)`.+ - scores: The predicted IoU of each mask, ``(K, C)``."""KORNIA_CHECK_SHAPE(images, ["B", "3", "H", "W"])diff --git a/kornia/models/segmentation/base.py b/kornia/models/segmentation/base.pyindex 32d1bbfa6..9a45dc209 100644--- a/kornia/models/segmentation/base.py+++ b/kornia/models/segmentation/base.py@@ -97,8 +97,8 @@ class SemanticSegmentation(ModelBase):"""Forward pass of the semantic segmentation model.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``.Returns:output tensor.@@ -215,10 +215,10 @@ class SemanticSegmentation(ModelBase):"""Visualize the segmentation masks.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`.- semantic_masks: If list of segmentation masks. Each mask is a torch.Tensor with shape :math:`(C, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, C, H, W)`.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``.+ semantic_masks: If list of segmentation masks. Each mask is a torch.Tensor with shape ``(C, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, C, H, W)``.output_type: The type of output, can be "torch" or "pil".colormap: The colormap to use, can be "random" or a custom color map.manual_seed: The manual seed to use for the colormap.@@ -262,10 +262,10 @@ class SemanticSegmentation(ModelBase):"""Save the segmentation results.Args:- images: If list of RGB images. Each image is a torch.Tensor with shape :math:`(3, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, 3, H, W)`.- semantic_masks: If list of segmentation masks. Each mask is a torch.Tensor with shape :math:`(C, H, W)`.- If torch.Tensor, a torch.Tensor with shape :math:`(B, C, H, W)`.+ images: If list of RGB images. Each image is a torch.Tensor with shape ``(3, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, 3, H, W)``.+ semantic_masks: If list of segmentation masks. Each mask is a torch.Tensor with shape ``(C, H, W)``.+ If torch.Tensor, a torch.Tensor with shape ``(B, C, H, W)``.directory: The directory to save the results.output_type: "torch" or "pil", as in :meth:`visualize`; it does not change the files written.colormap: The colormap to use, can be "random" or a custom color map.diff --git a/kornia/models/siglip2/preprocessor.py b/kornia/models/siglip2/preprocessor.pyindex 78b89cfd5..4100beb1d 100644--- a/kornia/models/siglip2/preprocessor.py+++ b/kornia/models/siglip2/preprocessor.py@@ -91,8 +91,8 @@ class SigLip2ImagePreprocessor(nn.Module):"""Prepare images for SigLIP2 vision encoding.Args:- images: Image tensor with shape :math:`(C, H, W)` or- :math:`(B, C, H, W)`. Values are expected in the range used by+ images: Image tensor with shape ``(C, H, W)`` or+ ``(B, C, H, W)``. Values are expected in the range used bythe configured rescale factor.Returns:diff --git a/kornia/models/siglip2/vision_encoder.py b/kornia/models/siglip2/vision_encoder.pyindex 9ab75478b..d008238b4 100644--- a/kornia/models/siglip2/vision_encoder.py+++ b/kornia/models/siglip2/vision_encoder.py@@ -196,14 +196,14 @@ class SigLip2MultiheadAttentionPoolingHead(nn.Module):"""Pool vision tokens with a learned probe query.Args:- hidden_state: Vision token tensor with shape :math:`(B, N, D)`,+ hidden_state: Vision token tensor with shape ``(B, N, D)``,where :math:`B` is batch size, :math:`N` is token count, and:math:`D` is hidden size.attention_mask: Optional mask of the tokens, ``1``/``True`` for a token to pool and ``0``/``False`` for- padding, in any form :class:`SigLip2Attention` accepts: :math:`(B, N)`, :math:`(B, N, N)` or- :math:`(B, 1, N, N)`. The probe does not attend to the padding tokens. For a 3-D or 4-D mask, a token- that no query may attend to is padding, so a :math:`(B, N)` mask broadcast over the queries pools- exactly as the :math:`(B, N)` mask itself. As in transformers, a padding token's attention score gets+ padding, in any form :class:`SigLip2Attention` accepts: ``(B, N)``, ``(B, N, N)`` or+ ``(B, 1, N, N)``. The probe does not attend to the padding tokens. For a 3-D or 4-D mask, a token+ that no query may attend to is padding, so a ``(B, N)`` mask broadcast over the queries pools+ exactly as the ``(B, N)`` mask itself. As in transformers, a padding token's attention score gets``torch.finfo(dtype).min`` added rather than ``-inf``: a sample whose tokens are all padding poolsthem with exactly uniform weights in float32, float64 and bfloat16. In float16, as in transformers,``finfo(float16).min`` plus a score rounds to a multiple of 32, so those weights are only roughly@@ -214,7 +214,7 @@ class SigLip2MultiheadAttentionPoolingHead(nn.Module):input, which autocast leaves alone, keeps the float64 mask.Returns:- Tensor with shape :math:`(B, D)` containing the pooled visual+ Tensor with shape ``(B, D)`` containing the pooled visualrepresentation after attention, layer normalization, and MLPrefinement."""@@ -331,7 +331,7 @@ class SigLip2VisionModel(nn.Module):pixel_values: Input images of shape (batch_size, num_channels, height, width), with height and widthboth equal to ``config.image_size`` (see :class:`SigLip2VisionEmbeddings`).attention_mask: Optional mask of the patches, ``1``/``True`` for a patch to keep and ``0``/``False`` for- a padded one: :math:`(B, N)`, :math:`(B, N, N)` or :math:`(B, 1, N, N)` for :math:`N` patches (see+ a padded one: ``(B, N)``, ``(B, N, N)`` or ``(B, 1, N, N)`` for :math:`N` patches (see:class:`SigLip2Attention`). It excludes the padded patches from the encoder, where no patch attendsto them, and from the pooling.output_hidden_states: Whether to return hidden states from all layers.diff --git a/kornia/models/small_sr.py b/kornia/models/small_sr.pyindex 38cda27ee..effb58377 100644--- a/kornia/models/small_sr.py+++ b/kornia/models/small_sr.py@@ -83,7 +83,7 @@ class SmallSRNet(nn.Module):"""Super-resolve a single-channel image tensor.Args:- x: Luminance image tensor with shape :math:`(B, 1, H, W)`, where+ x: Luminance image tensor with shape ``(B, 1, H, W)``, where:math:`B` is batch size, :math:`H` is height, and :math:`W` iswidth.@@ -128,7 +128,7 @@ class SmallSRNetWrapper(nn.Module):"""Apply RGB super-resolution through a luminance-only SR model.Args:- input: RGB image tensor with shape :math:`(B, 3, H, W)`.+ input: RGB image tensor with shape ``(B, 3, H, W)``.Returns:RGB tensor upscaled by ``self.upscale_factor``. The Y channel isdiff --git a/kornia/models/structures.py b/kornia/models/structures.pyindex 5f642168f..c06128632 100644--- a/kornia/models/structures.py+++ b/kornia/models/structures.py@@ -31,10 +31,10 @@ class SegmentationResults:"""Encapsulate the results obtained by a Segmentation model.Args:- logits: Results logits with shape :math:`(K, C, H, W)` for one image: :math:`K` is the number of its prompts+ logits: Results logits with shape ``(K, C, H, W)`` for one image: :math:`K` is the number of its prompts(the leading size of its point, box or mask prompts; 1 when it has none), :math:`C` the number of maskspredicted per prompt (3 with ``multimask_output``, else 1), and :math:`H = W = 256` for SAM.- scores: The predicted IoU of each mask. Shape :math:`(K, C)`+ scores: The predicted IoU of each mask. Shape ``(K, C)``mask_threshold: The threshold value to generate the `binary_masks` from the `logits`"""@@ -48,7 +48,7 @@ class SegmentationResults:def binary_masks(self) -> torch.Tensor:"""Binary mask generated from logits considering the mask_threshold.- Shape will be the same of logits :math:`(K, C, H, W)` where :math:`C` is the number masks predicted per prompt.+ Shape will be the same of logits ``(K, C, H, W)`` where :math:`C` is the number masks predicted per prompt... note:: If you run `original_res_logits`, this will generate the masksbased on the original resolution logits.@@ -74,7 +74,7 @@ class SegmentationResults:logits back to encoder resolution before remove the padding.Returns:- Batched logits in :math:`(K, C, H, W)` format, where (H, W) is given by original_size.+ Batched logits in ``(K, C, H, W)`` format, where (H, W) is given by original_size."""x = self.logits@@ -103,10 +103,10 @@ class Prompts:"""Encapsulate the prompts inputs for a Model.Args:- points: A tuple with the keypoints (coordinates x, y) and their respective labels. Shape :math:`(K, N, 2)` for- the keypoints, and :math:`(K, N)`- boxes: Batched box inputs, with shape :math:`(K, 4)`. Expected to be into xyxy format.- masks: Batched mask prompts to the model with shape :math:`(K, 1, H, W)`+ points: A tuple with the keypoints (coordinates x, y) and their respective labels. Shape ``(K, N, 2)`` for+ the keypoints, and ``(K, N)``+ boxes: Batched box inputs, with shape ``(K, 4)``. Expected to be into xyxy format.+ masks: Batched mask prompts to the model with shape ``(K, 1, H, W)``"""diff --git a/kornia/models/tiny_vit.py b/kornia/models/tiny_vit.pyindex 610334af6..dcdd0d7d3 100644--- a/kornia/models/tiny_vit.py+++ b/kornia/models/tiny_vit.py@@ -116,7 +116,7 @@ class MBConv(nn.Module):"""Apply the MBConv residual block to a feature map.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`, where+ x: Feature map tensor with shape ``(B, C, H, W)``, where:math:`B` is batch size, :math:`C` is channels, :math:`H` isheight, and :math:`W` is width.@@ -159,8 +159,8 @@ class PatchMerging(nn.Module):"""Merge or project patch tokens for TinyViT downsampling.Args:- x: Either token tensor with shape :math:`(B, H * W, C)` or feature- map tensor with shape :math:`(B, C, H, W)`.+ x: Either token tensor with shape ``(B, H * W, C)`` or feature+ map tensor with shape ``(B, C, H, W)``.Returns:Token tensor with shape :math:`(B, H_{out} * W_{out}, C_{out})`.@@ -170,7 +170,7 @@ class PatchMerging(nn.Module):Raises:ValueError: if :math:`(H_{out}, W_{out})` is not the grid the next stage is built for: the input of a:class:`TinyViT` is not ``img_size`` (the first patch merging reads the image's own grid from a- :math:`(B, C, H, W)` map), or ``img_size`` is not a multiple of 32 (of 16 with ``mobile_sam=True``),+ ``(B, C, H, W)`` map), or ``img_size`` is not a multiple of 32 (of 16 with ``mobile_sam=True``),so the stride-2 convolution rounds an odd grid up where the stages were built for it rounded down."""if x.ndim == 3:@@ -337,12 +337,12 @@ class Attention(nn.Module):"""Apply relative-position self-attention to token features.Args:- x: Token tensor with shape :math:`(B, N, C)`, where :math:`B` is+ x: Token tensor with shape ``(B, N, C)``, where :math:`B` isbatch size, :math:`N` is number of tokens, and :math:`C` isembedding dimension.Returns:- Tensor with shape :math:`(B, N, C)` after attention and projection.+ Tensor with shape ``(B, N, C)`` after attention and projection."""B, N, _ = x.shapex = self.norm(x)@@ -403,7 +403,7 @@ class TinyViTBlock(nn.Module):"""Apply one TinyViT window-attention block.Args:- x: Token tensor with shape :math:`(B, H * W, C)`, where+ x: Token tensor with shape ``(B, H * W, C)``, where:math:`H` and :math:`W` match ``self.input_resolution``.Returns:@@ -492,7 +492,7 @@ class BasicLayer(nn.Module):"""Run a TinyViT stage made of several blocks.Args:- x: Token tensor with shape :math:`(B, H * W, C)`.+ x: Token tensor with shape ``(B, H * W, C)``.Returns:Tensor after all TinyViT blocks and optional patch merging. The@@ -626,7 +626,7 @@ class TinyViT(nn.Module):"""Classify images if ``mobile_sam=False``, produce feature maps if ``mobile_sam=True``.Args:- x: images :math:`(B, C, H, W)` with :math:`H = W =` ``img_size``. The strided convolutions before the+ x: images ``(B, C, H, W)`` with :math:`H = W =` ``img_size``. The strided convolutions before thefirst attention stage round up, so :math:`H` and :math:`W` from ``img_size - 7`` to ``img_size`` givethe same token grid and run too.diff --git a/kornia/models/vit.py b/kornia/models/vit.pyindex fc5068f0c..af36df4f6 100644--- a/kornia/models/vit.py+++ b/kornia/models/vit.py@@ -264,7 +264,7 @@ class VisionTransformer(nn.Module):Returns:List of tensors produced by the encoder blocks. Each tensor stores- token embeddings for a layer, typically shaped :math:`(B, N, D)`,+ token embeddings for a layer, typically shaped ``(B, N, D)``,where :math:`B` is batch size, :math:`N` is token count, and:math:`D` is embedding dimension."""@@ -274,7 +274,7 @@ class VisionTransformer(nn.Module):"""Encode an image batch into Vision Transformer token embeddings.Args:- x: Image tensor with shape :math:`(B, C, H, W)`. Without a+ x: Image tensor with shape ``(B, C, H, W)``. Without a``backbone``, :math:`C` must equal ``self.in_channels`` and:math:`H` and :math:`W` must both equal ``self.image_size``;with one, the backbone's token grid must be the one it gives@@ -284,10 +284,10 @@ class VisionTransformer(nn.Module):Returns:Normalized token embedding tensor produced by patch embedding andthe transformer encoder. The output shape follows the encoder- layout, usually :math:`(B, N, D)`.+ layout, usually ``(B, N, D)``.Raises:- ValueError: without a ``backbone``, if :math:`C` is not ``in_channels`` or :math:`(H, W)` is not+ ValueError: without a ``backbone``, if :math:`C` is not ``in_channels`` or ``(H, W)`` is not``(image_size, image_size)``; with one, if the backbone's token grid is not the one it gives for an``image_size`` input."""diff --git a/kornia/models/vit_mobile.py b/kornia/models/vit_mobile.pyindex 583176930..8c63c3e01 100644--- a/kornia/models/vit_mobile.py+++ b/kornia/models/vit_mobile.py@@ -112,7 +112,7 @@ class Attention(nn.Module):"""Apply multi-head self-attention to MobileViT tokens.Args:- x: Token tensor with shape :math:`(B, P, N, D)`, where+ x: Token tensor with shape ``(B, P, N, D)``, where:math:`B` is batch size, :math:`P` is patch area,:math:`N` is number of patches, and :math:`D` is embeddingdimension.@@ -166,7 +166,7 @@ class Transformer(nn.Module):"""Run stacked attention and feed-forward residual layers.Args:- x: Token tensor with shape :math:`(B, P, N, D)`.+ x: Token tensor with shape ``(B, P, N, D)``.Returns:Tensor with the same shape as ``x`` after all transformer layers.@@ -277,7 +277,7 @@ class MobileViTBlock(nn.Module):"""Fuse local convolutions with global transformer context.Args:- x: Feature map tensor with shape :math:`(B, C, H, W)`.+ x: Feature map tensor with shape ``(B, C, H, W)``.Returns:Feature map tensor with the same spatial size as ``x``. Local@@ -388,13 +388,13 @@ class MobileViT(nn.Module):r"""Run the MobileViT backbone and return final feature maps.Args:- x: Image tensor with shape :math:`(B, C, H, W)`, where :math:`C`+ x: Image tensor with shape ``(B, C, H, W)``, where :math:`C`matches the configured input channel count.Returns:Feature tensor from the final MobileViT stage. For the defaultconfiguration, a :math:`256 \times 256` input produces- :math:`(B, 320, 8, 8)`.+ ``(B, 320, 8, 8)``."""x = self.conv1(x)x = self.mv2[0](x)diff --git a/kornia/models/yunet/model.py b/kornia/models/yunet/model.pyindex 951457356..ff13b6ec3 100644--- a/kornia/models/yunet/model.py+++ b/kornia/models/yunet/model.py@@ -123,7 +123,7 @@ class YuNet(nn.Module):"""Run YuNet face detection heads over an input image batch.Args:- x: Image tensor with shape :math:`(B, C, H, W)`, where :math:`B` is+ x: Image tensor with shape ``(B, C, H, W)``, where :math:`B` isbatch size, :math:`C` is channel count, :math:`H` is height,and :math:`W` is width.diff --git a/kornia/models/yunet/processors.py b/kornia/models/yunet/processors.pyindex 237790be2..8514bb52a 100644--- a/kornia/models/yunet/processors.py+++ b/kornia/models/yunet/processors.py@@ -97,7 +97,7 @@ class PriorBox:"""Generate YuNet prior boxes for all configured feature maps.Returns:- Tensor with shape :math:`(N, 4)`, where :math:`N` is the total+ Tensor with shape ``(N, 4)``, where :math:`N` is the totalnumber of anchors and the four values are normalized center-x,center-y, width, and height."""diff --git a/kornia/morphology/morphology.py b/kornia/morphology/morphology.pyindex 9ca756a93..93451cfb8 100644--- a/kornia/morphology/morphology.py+++ b/kornia/morphology/morphology.py@@ -300,10 +300,10 @@ def dilation(window of a kernel with no non-zero cell. The composite operations inherit these infinities.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -338,7 +338,7 @@ def dilation(pass, which is more memory than ``"unfold"``, not less.Returns:- Dilated image with shape :math:`(B, C, H, W)`.+ Dilated image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -493,10 +493,10 @@ def erosion(OpenCV. ``structuring_element`` is subtracted before the minimum.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -531,7 +531,7 @@ def erosion(pass, which is more memory than ``"unfold"``, not less.Returns:- Eroded image with shape :math:`(B, C, H, W)`.+ Eroded image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -688,10 +688,10 @@ def opening(``replicate`` can break them.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -726,7 +726,7 @@ def opening(pass, which is more memory than ``"unfold"``, not less.Returns:- Opened image with shape :math:`(B, C, H, W)`.+ Opened image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -794,10 +794,10 @@ def closing(``replicate`` can break them.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -832,7 +832,7 @@ def closing(pass, which is more memory than ``"unfold"``, not less.Returns:- Closed image with shape :math:`(B, C, H, W)`.+ Closed image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -898,10 +898,10 @@ def gradient(``gradient`` is ``dilation(tensor) - erosion(tensor)`` with the same arguments; see :func:`dilation`.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -936,7 +936,7 @@ def gradient(pass, which is more memory than ``"unfold"``, not less.Returns:- Gradient image with shape :math:`(B, C, H, W)`.+ Gradient image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -991,10 +991,10 @@ def top_hat(``top_hat`` is ``tensor - opening(tensor)`` with the same arguments.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -1029,7 +1029,7 @@ def top_hat(pass, which is more memory than ``"unfold"``, not less.Returns:- Top hat transformed image with shape :math:`(B, C, H, W)`.+ Top hat transformed image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -1087,10 +1087,10 @@ def bottom_hat(``bottom_hat`` is ``closing(tensor) - tensor`` with the same arguments.Args:- tensor: Floating-point image with shape :math:`(B, C, H, W)`; any other dtype raises a ``TypeError``.+ tensor: Floating-point image with shape ``(B, C, H, W)``; any other dtype raises a ``TypeError``.kernel: Positions of non-infinite elements of a flat structuring element. Non-zero values givethe set of neighbors of the ``origin`` cell over which the operation is applied, and their- magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's :math:`(H, W)` axes.+ magnitude is ignored. Its shape is :math:`(k_h, k_w)`, laid over the image's ``(H, W)`` axes.For a full neighborhood pass a ``kernel`` of all ones.structuring_element: Non-flat structuring element, added to the neighbor values before the maximumin :func:`dilation` and subtracted before the minimum in :func:`erosion`. Its shape must equal@@ -1125,7 +1125,7 @@ def bottom_hat(pass, which is more memory than ``"unfold"``, not less.Returns:- Bottom hat transformed image with shape :math:`(B, C, H, W)`.+ Bottom hat transformed image with shape ``(B, C, H, W)``... note::See a working example `here <https://www.kornia.org/tutorials/nbs/morphology_101.html>`__.@@ -1214,7 +1214,7 @@ def reconstruction(``mask`` (below it for ``"erosion"``) is clipped to ``mask`` instead of raising.Args:- seed: Floating-point starting image with shape :math:`(B, C, H, W)`.+ seed: Floating-point starting image with shape ``(B, C, H, W)``.mask: Floating-point image bounding the reconstruction, with the same shape as ``seed``.kernel: Offsets from the center that a pixel's value spreads to in one step, with shape:math:`(k_h, k_w)` and odd sizes. Non-zero cells mark an offset; their magnitude and dtype are@@ -1232,7 +1232,7 @@ def reconstruction(is rejected: it is not exact on every backend, and an inexact step can keep the loop from converging.Returns:- Reconstructed image with shape :math:`(B, C, H, W)` and the promoted dtype of ``seed`` and ``mask``.+ Reconstructed image with shape ``(B, C, H, W)`` and the promoted dtype of ``seed`` and ``mask``.Raises:TypeCheckError: if ``seed``, ``mask`` or ``kernel`` is not a tensor.diff --git a/kornia/sensors/camera/camera_model.py b/kornia/sensors/camera/camera_model.pyindex def16af91..aeb602308 100644--- a/kornia/sensors/camera/camera_model.py+++ b/kornia/sensors/camera/camera_model.py@@ -85,7 +85,7 @@ def _validate_params(distortion: CameraDistortionType, params: torch.Tensor) ->was accepted and projected to a silently wrong ``(1, 1, 2)`` result.Raises:- ValueError: if ``params`` is not of shape :math:`(N,)` or :math:`(B, N)`,+ ValueError: if ``params`` is not of shape ``(N,)`` or ``(B, N)``,with ``N`` the length the distortion model reads."""@@ -115,10 +115,10 @@ class CameraModelBase::meth:`unproject` the reverse; a raw :class:`torch.Tensor` is not accepted. This type system is keptseparate from :doc:`kornia.geometry.camera </geometry.camera>` by design(`#4274 <https://github.com/kornia/kornia/issues/4274>`_).- - ``params`` is a flat ``(N,)`` or batched :math:`(B, N)` vector whose length is fixed by the model:+ - ``params`` is a flat ``(N,)`` or batched ``(B, N)`` vector whose length is fixed by the model:``[fx, fy, cx, cy]`` for ``PINHOLE`` and ``ORTHOGRAPHIC``, 12 for ``BROWN_CONRADY`` and 8 for``KANNALA_BRANDT_K3``; another length or a rank above 2 raises ``ValueError``.- - :meth:`matrix` and its alias :meth:`K` return the :math:`(*, 3, 3)` ``K``, not the :math:`(B, 4, 4)`+ - :meth:`matrix` and its alias :meth:`K` return the ``(*, 3, 3)`` ``K``, not the ``(B, 4, 4)````intrinsics`` that :class:`~kornia.geometry.camera.pinhole.PinholeCamera` stores.- :meth:`project` is ``distortion.distort(params, projection.project(points))`` and :meth:`unproject`the reverse; ``depth`` is the camera-frame ``z``, shaped ``(*,)`` where@@ -155,7 +155,7 @@ class CameraModelBase:distortion: Distortion typeprojection: Projection typeimage_size: Image size- params: Camera parameters of shape :math:`(B, N)` or :math:`(N,)`, with+ params: Camera parameters of shape ``(B, N)`` or ``(N,)``, with:math:`N` fixed by ``distortion``: 4 for:class:`AffineTransform` (pinhole and orthographic), 12 for:class:`BrownConradyTransform`, 8 for@@ -303,7 +303,7 @@ class PinholeModel(CameraModelBase):Args:image_size: Image size- params: Camera parameters of shape :math:`(B, 4)` of the form :math:`(fx, fy, cx, cy)`.+ params: Camera parameters of shape ``(B, 4)`` of the form :math:`(fx, fy, cx, cy)`."""if params.shape[-1] != 4 or len(params.shape) > 2:@@ -385,7 +385,7 @@ class BrownConradyModel(CameraModelBase):Args:image_size: Image size- params: Camera parameters of shape :math:`(12,)` or :math:`(B, 12)`, ordered as+ params: Camera parameters of shape ``(12,)`` or ``(B, 12)``, ordered as:math:`(fx, fy, cx, cy, k1, k2, p1, p2, k3, k4, k5, k6)`. The first four valuesare the camera intrinsics and the trailing eight values are the Brown-Conradydistortion coefficients.@@ -408,7 +408,7 @@ class KannalaBrandtK3(CameraModelBase):Args:image_size: Image size- params: Camera parameters of shape :math:`(B, 8)` of the form :math:`(fx, fy, cx, cy, kb0, kb1, kb2, kb3)`.+ params: Camera parameters of shape ``(B, 8)`` of the form :math:`(fx, fy, cx, cy, kb0, kb1, kb2, kb3)`."""if params.shape[-1] != 8 or len(params.shape) > 2:@@ -428,7 +428,7 @@ class Orthographic(CameraModelBase):Args:image_size: Image size- params: Camera parameters of shape :math:`(B, 4)` of the form :math:`(fx, fy, cx, cy)`.+ params: Camera parameters of shape ``(B, 4)`` of the form :math:`(fx, fy, cx, cy)`."""if params.shape[-1] != 4 or len(params.shape) > 2:@@ -468,7 +468,7 @@ class CameraModel:Args:image_size: Image sizemodel_type: Camera model type- params: Camera parameters of shape :math:`(B, N)`.+ params: Camera parameters of shape ``(B, N)``."""self._model = get_model_from_type(model_type, image_size, params)diff --git a/kornia/tracking/planar_tracker.py b/kornia/tracking/planar_tracker.pyindex 2700bca6d..cabdd268c 100644--- a/kornia/tracking/planar_tracker.py+++ b/kornia/tracking/planar_tracker.py@@ -31,9 +31,9 @@ class HomographyTracker(nn.Module):r"""Perform local-feature-based tracking of the target planar object in the sequence of the frames.Convention:- - The returned homography ``H`` is :math:`(3, 3)` and maps target pixel coordinates :math:`(x, y)` to frame+ - The returned homography ``H`` is ``(3, 3)`` and maps target pixel coordinates :math:`(x, y)` to framepixel coordinates, the direction of ``cv2.findHomography(target_points, frame_points)``.- - The target and every frame are one grayscale image, :math:`(1, 1, H, W)`; a frame can have another size than+ - The target and every frame are one grayscale image, ``(1, 1, H, W)``; a frame can have another size thanthe target. Call :meth:`set_target` before the first frame. The target is not a buffer, so:meth:`~torch.nn.Module.to` leaves it where it is: call :meth:`set_target` again after moving the tracker.- For a :class:`~kornia.feature.LoFTR`, a :class:`~kornia.feature.LocalFeatureMatcher` or a matcher with andiff --git a/testing/docstring_rollout.py b/testing/docstring_rollout.pyindex 926a19495..3af7ae63b 100644--- a/testing/docstring_rollout.py+++ b/testing/docstring_rollout.py@@ -52,9 +52,6 @@ EXCLUDED_PACKAGES: dict[str, str] = {}"""Top-level packages left out of the rollout, with the reason."""-SHAPE_CHECK_MODULES: tuple[str, ...] | None = ("kornia.geometry.depth",)-"""Module prefixes whose source may not write a shape as ``:math:``; ``None`` means all of ``kornia/``."""-CATALOG_NAMESPACES: tuple[str, ...] = ("kornia.geometry.depth",)"""Namespaces whose module docstring must name every export in ``__all__``."""@@ -63,3 +60,17 @@ DOCSTRING_MODULES: tuple[str, ...] = ("kornia.geometry.depth",)SEE_ALSO_EXCEPTIONS: dict[str, str] = {}"""Qualified name of a converted object that needs no ``See Also:`` section, with the reason."""++MATH_NON_SHAPES: dict[str, dict[str, str]] = {+ "docs/source/geometry.calibration.rst": {"(X, Y, Z)": "the coordinates of one 3D point"},+ "docs/source/geometry.camera.pinhole.rst": {"(X,Y,Z)": "the coordinates of one 3D point"},+ "docs/source/geometry.camera.stereo.rst": {"(X/W, Y/W, Z/W)": "the Euclidean coordinates of one 3D point"},+ "kornia/contrib/visual_prompter.py": {"(0, 0, W, H)": "a box, the whole image before the resize"},+ "kornia/feature/affine_shape.py": {"(1, 0, 1)": "the ellipse coefficients (a, b, c) of a circle"},+ "kornia/geometry/pointcloud.py": {"(X, Y, Z)": "the coordinates of one point"},+ "kornia/metrics/pose.py": {"(0, 0)": "the origin of the recall curve"},+}+"""``:math:`` tuples that read as a shape but are values, by repository path, each with what the value is.++The shape check covers every ``kornia/**/*.py`` file and every page under ``docs/source``; it skips these.+"""diff --git a/testing/docstring_style.py b/testing/docstring_style.pyindex e05fc7de2..d4088f407 100644--- a/testing/docstring_style.py+++ b/testing/docstring_style.py@@ -609,7 +609,7 @@ def _add_module_members(_NOT_PAGES = frozenset({"_build", ".ipynb_checkpoints", "_templates", "_static", "_extra"})-def _rst_pages(docs_source: Path) -> list[Path]:+def rst_pages(docs_source: Path) -> list[Path]:"""Every ``.rst`` page under ``docs_source``, subdirectories included, except those Sphinx does not build."""root = Path(docs_source)return sorted(page for page in root.rglob("*.rst") if _NOT_PAGES.isdisjoint(page.relative_to(root).parts[:-1]))@@ -630,7 +630,7 @@ def sphinx_registry(docs_source: Path) -> dict[str, object]:"""registry: dict[str, object] = {}- for page in _rst_pages(docs_source):+ for page in rst_pages(docs_source):lines = page.read_text(encoding="utf-8").splitlines()current = ""enclosing_class = ""diff --git a/tests/test_docstring_style.py b/tests/test_docstring_style.pyindex 48856148d..aa9721d64 100644--- a/tests/test_docstring_style.py+++ b/tests/test_docstring_style.py@@ -18,17 +18,19 @@"""Converted kornia modules keep the docstring style the rollout set out to give them.``testing/docstring_rollout.py`` lists the modules that are converted. For those, this file enforces what a reader,-an IDE or a coding agent relies on and what a refactor silently breaks:+an IDE or a coding agent relies on and what a refactor silently breaks; the shape rule applies everywhere:* every public function and class has a ``See Also:`` section whose entries name a sibling and say how it differs;* every Python-domain object role (``:func:``, ``:class:``, ``:meth:``, ``:attr:``, ``:data:``, ``:const:``,``:exc:``, ``:obj:``) resolves to a name that Sphinx registers from ``docs/source``, or to a torch, Python or NumPyobject of a type that role links in the cached intersphinx inventories, so it renders as a link and not as plaintext (a short import alias is importable but is not a target); See Also entries name kornia objects only;-* the source writes a tensor shape as a literal such as ``(B, 1, H, W)``, not as ``:math:``;+* every ``kornia/**/*.py`` file and every page Sphinx builds from ``docs/source`` writes a tensor shape as a literal+ such as ``(B, 1, H, W)``, not as ``:math:``, except for the values listed in ``MATH_NON_SHAPES``;* the module docstring of a namespace names every export of its ``__all__`` in a role or a double-backtick literal.-The test ids are qualified names, so a failure names the object to fix. Run with ``-s`` to see the progress table.+The test ids are qualified names, or repository paths for the shape check, so a failure names what to fix. Run with+``-s`` to see the progress table."""from __future__ import annotations@@ -46,8 +48,8 @@ from testing.docstring_rollout import (DOCSTRING_MODULES,EXCLUDED_PACKAGES,IN_SCOPE_PACKAGES,+ MATH_NON_SHAPES,SEE_ALSO_EXCEPTIONS,- SHAPE_CHECK_MODULES,)from testing.docstring_style import (catalog_missing,@@ -64,12 +66,14 @@ from testing.docstring_style import (public_objects,reference_resolves,resolve_reference,+ rst_pages,see_also_entries,sphinx_registry,)KORNIA_ROOT = Path(kornia.__file__).resolve().parent-DOCS = KORNIA_ROOT.parent / "docs" / "source"+REPO_ROOT = KORNIA_ROOT.parent+DOCS = REPO_ROOT / "docs" / "source"REGISTRY = sphinx_registry(DOCS)INTERSPHINX = intersphinx_names(DOCS)@@ -79,18 +83,7 @@ CONVERTED = sorted()-def _module_name(path: Path) -> str:- parts = list(path.relative_to(KORNIA_ROOT.parent).with_suffix("").parts)- if parts[-1] == "__init__":- parts.pop()- return ".".join(parts)---SHAPE_CHECK_FILES = sorted(- path- for path in KORNIA_ROOT.rglob("*.py")- if SHAPE_CHECK_MODULES is None or covered(_module_name(path), SHAPE_CHECK_MODULES)-)+SHAPE_CHECK_FILES = sorted([*KORNIA_ROOT.rglob("*.py"), *rst_pages(DOCS)])def _suggest(target: str) -> str:@@ -109,7 +102,7 @@ def _wrong_role(role: str, target: str) -> str:def test_rollout_selects_something() -> None:"""The parametrized checks below are not vacuous: the rollout lists select objects and files."""assert CONVERTED, f"DOCSTRING_MODULES {DOCSTRING_MODULES} select no public object"- assert SHAPE_CHECK_FILES, f"SHAPE_CHECK_MODULES {SHAPE_CHECK_MODULES} select no source file"+ assert SHAPE_CHECK_FILES, f"no source file or docs page found under {KORNIA_ROOT} and {DOCS}"assert CATALOG_NAMESPACES, "CATALOG_NAMESPACES is empty, so no module catalog is checked"assert REGISTRY, f"sphinx_registry({DOCS}) registered nothing"assert INTERSPHINX, f"intersphinx_names({DOCS}) found no inventory names"@@ -117,10 +110,6 @@ def test_rollout_selects_something() -> None:assert any(covered(obj.__module__, [prefix]) for _, obj in CONVERTED), (f"DOCSTRING_MODULES entry {prefix!r} selects no public object with a docstring")- for prefix in SHAPE_CHECK_MODULES or ():- assert any(covered(_module_name(path), [prefix]) for path in SHAPE_CHECK_FILES), (- f"SHAPE_CHECK_MODULES entry {prefix!r} selects no source file"- )def test_every_package_is_assigned() -> None:@@ -137,7 +126,6 @@ def test_rollout_lists_are_real() -> None:lists = {"DOCSTRING_MODULES": DOCSTRING_MODULES,"CATALOG_NAMESPACES": CATALOG_NAMESPACES,- "SHAPE_CHECK_MODULES": SHAPE_CHECK_MODULES or (),}for list_name, entries in lists.items():for entry in entries:@@ -198,15 +186,29 @@ def test_converted_object_references_resolve(qualified: str, obj: object) -> Non@pytest.mark.parametrize(- "path", SHAPE_CHECK_FILES, ids=[str(path.relative_to(KORNIA_ROOT.parent)) for path in SHAPE_CHECK_FILES]+ "path", SHAPE_CHECK_FILES, ids=[path.relative_to(REPO_ROOT).as_posix() for path in SHAPE_CHECK_FILES])def test_no_math_shape_roles(path: Path) -> None:- found = math_shape_roles(path.read_text(encoding="utf-8"))+ relative = path.relative_to(REPO_ROOT).as_posix()+ values = MATH_NON_SHAPES.get(relative, {})+ found = [content for content in math_shape_roles(path.read_text(encoding="utf-8")) if content not in values]assert found == [], (- f"{path.relative_to(KORNIA_ROOT.parent)} writes shapes as :math: {found}; use literals like ``(B, 1, H, W)``"+ f"{relative} writes shapes as :math: {found}; use literals like ``(B, 1, H, W)``, or list a tuple that is "+ "a value, not a shape, in MATH_NON_SHAPES with what it is")+def test_math_non_shapes_are_current() -> None:+ """Every ``MATH_NON_SHAPES`` entry names a checked file that still writes that tuple as ``:math:``."""+ checked = {path.relative_to(REPO_ROOT).as_posix(): path for path in SHAPE_CHECK_FILES}+ for relative, values in MATH_NON_SHAPES.items():+ assert relative in checked, f"MATH_NON_SHAPES key {relative!r} is not a checked source file or docs page"+ found = set(math_shape_roles(checked[relative].read_text(encoding="utf-8")))+ for content, reason in values.items():+ assert content in found, f"MATH_NON_SHAPES entry {content!r} no longer occurs in {relative}; remove it"+ assert reason.strip(), f"MATH_NON_SHAPES entry {content!r} in {relative} needs a reason"++@pytest.mark.parametrize("namespace", CATALOG_NAMESPACES)def test_catalog_names_every_export(namespace: str) -> None:module = importlib.import_module(namespace)