Skip to content

šŸ Geometric Computer Vision Library for Spatial AI

docs: give sibling symbols distinct first docstring lines and test it (#6356)

Dmytro Mishkin9b1faa671e49
diff --git a/kornia/augmentation/_2d/intensity/color_jiggle.py b/kornia/augmentation/_2d/intensity/color_jiggle.py
index 1fb5bc550..f18694827 100644
--- a/kornia/augmentation/_2d/intensity/color_jiggle.py
+++ b/kornia/augmentation/_2d/intensity/color_jiggle.py
@@ -120,7 +120,7 @@ def _apply_cond(order: Tuple[int, ...], input: torch.Tensor, factors: Tuple[torc
class ColorJiggle(IntensityAugmentationBase2D):
- r"""Apply a random transformation to the brightness, contrast, saturation and hue of a torch.Tensor image.
+ r"""Randomly shift brightness, scale contrast and HSV saturation, and rotate the hue of an image.
.. image:: _static/img/ColorJiggle.png
diff --git a/kornia/augmentation/_2d/intensity/color_jitter.py b/kornia/augmentation/_2d/intensity/color_jitter.py
index c4300f69a..0e9949eae 100644
--- a/kornia/augmentation/_2d/intensity/color_jitter.py
+++ b/kornia/augmentation/_2d/intensity/color_jitter.py
@@ -63,7 +63,7 @@ def _apply_cond(order: Tuple[int, ...], input: torch.Tensor, factors: Tuple[torc
class ColorJitter(_PicklableCompileMixin, IntensityAugmentationBase2D):
- r"""Apply a random transformation to the brightness, contrast, saturation and hue of a torch.Tensor image.
+ r"""Randomly adjust brightness, contrast, saturation and hue using torchvision-compatible formulas.
The four steps are torchvision's formulas -- brightness multiplies the image by the factor, contrast blends it
with its grayscale mean, saturation with its grayscale, and hue is torchvision's ``adjust_hue`` shift -- so this
diff --git a/kornia/augmentation/utils/helpers.py b/kornia/augmentation/utils/helpers.py
index 7d3b43406..994b4edfc 100644
--- a/kornia/augmentation/utils/helpers.py
+++ b/kornia/augmentation/utils/helpers.py
@@ -158,7 +158,7 @@ def _validate_input3d(f: Callable[..., Any]) -> Callable[..., Any]:
def _infer_batch_shape(input: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]) -> torch.Size:
- r"""Infer input shape.
+ r"""Return the (B, C, H, W) shape of a 2D augmentation input, or of the image of an (input, transform) tuple.
Input may be either (torch.Tensor,) or (torch.Tensor, transform_matrix)
"""
@@ -167,7 +167,7 @@ def _infer_batch_shape(input: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tens
def _infer_batch_shape3d(input: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]) -> torch.Size:
- r"""Infer input shape.
+ r"""Return the (B, C, D, H, W) shape of a 3D augmentation input, or of the volume of an (input, transform) tuple.
Input may be either (torch.Tensor,) or (torch.Tensor, transform_matrix)
"""
@@ -178,7 +178,7 @@ def _infer_batch_shape3d(input: Union[torch.Tensor, Tuple[torch.Tensor, torch.Te
def _transform_input_by_shape(
input: torch.Tensor, reference_shape: torch.Tensor, match_channel: bool = True
) -> torch.Tensor:
- """Reshape an input torch.Tensor to have the same dimensions as the reference_shape.
+ """Add the missing batch or channel dimension of an image tensor, e.g. a mask, to match a (B, C, H, W) reference.
Arguments:
input: torch.Tensor to be transformed
@@ -209,7 +209,12 @@ def _transform_input_by_shape(
def _transform_input3d_by_shape(
input: torch.Tensor, reference_shape: torch.Tensor, match_channel: bool = True
) -> torch.Tensor:
- """Reshape an input torch.Tensor to have the same dimensions as the reference_shape.
+ """Unsqueeze a 3-dim tensor at dim 0, then a 4-dim one at dim 2 if its first size equals the reference batch size.
+
+ A 3-dim ``(D, H, W)`` input first becomes ``(1, D, H, W)``. When the reference batch size is 1, the next branch
+ also inserts dimension 2, giving ``(1, D, 1, H, W)``; otherwise it stays 4-dim. A 4-dim ``(B, D, H, W)`` input
+ becomes ``(B, D, 1, H, W)``: the new axis lands after ``D`` rather than at ``C``. Tracked in
+ `#6354 <https://github.com/kornia/kornia/issues/6354>`_.
Arguments:
input: torch.Tensor to be transformed
@@ -238,7 +243,7 @@ def _transform_input3d_by_shape(
def _transform_input(input: torch.Tensor) -> torch.Tensor:
- r"""Reshape an input torch.Tensor to be (*, C, H, W). Accept either (H, W), (C, H, W) or (*, C, H, W).
+ r"""Unsqueeze an ``(H, W)`` or ``(C, H, W)`` image tensor to 4 dims, ``(B, C, H, W)``; a 4-dim input is kept.
Args:
input: torch.Tensor
@@ -263,7 +268,7 @@ def _transform_input(input: torch.Tensor) -> torch.Tensor:
def _transform_input3d(input: torch.Tensor) -> torch.Tensor:
- r"""Reshape an input torch.Tensor to be (*, C, D, H, W). Accept either (D, H, W), (C, D, H, W) or (*, C, D, H, W).
+ r"""Unsqueeze a ``(D, H, W)`` or ``(C, D, H, W)`` volume to 5 dims, ``(B, C, D, H, W)``; a 5-dim input is kept.
Args:
input: torch.Tensor
@@ -290,7 +295,7 @@ def _transform_input3d(input: torch.Tensor) -> torch.Tensor:
def _validate_input_dtype(input: torch.Tensor, accepted_dtypes: List[torch.dtype]) -> None:
- r"""Check if the dtype of the input torch.Tensor is in the range of accepted_dtypes.
+ r"""Raise TypeError unless the dtype of ``input`` is one of ``accepted_dtypes``.
Args:
input: torch.Tensor
@@ -328,7 +333,7 @@ def _transform_output_shape(
def _validate_shape(shape: Union[Tuple[int, ...], torch.Size], required_shapes: Tuple[str, ...] = ("BCHW",)) -> None:
- r"""Check if the dtype of the input torch.Tensor is in the range of accepted_dtypes.
+ r"""Raise TypeError unless ``shape`` has as many dimensions as one of ``required_shapes``, e.g. ``"BCHW"``.
Args:
shape: torch.Tensor shape
@@ -366,7 +371,7 @@ def _adapted_rsampling(
dist: torch.distributions.Distribution,
same_on_batch: Optional[bool] = False,
) -> torch.Tensor:
- r"""Sample from a uniform reparameterized sampling function that accepts 'same_on_batch'.
+ r"""Draw a reparameterized sample of ``shape`` from ``dist``, one draw repeated over the batch if same_on_batch.
If same_on_batch is True, all values generated will be exactly same given a batch_size (shape[0]). By default,
same_on_batch is set to False.
@@ -397,7 +402,7 @@ def _adapted_sampling(
dist: torch.distributions.Distribution,
same_on_batch: Optional[bool] = False,
) -> torch.Tensor:
- r"""Sample from a uniform sampling function that accepts 'same_on_batch'.
+ r"""Draw a sample of ``shape`` from ``dist`` without reparameterization, one draw for the batch if same_on_batch.
If same_on_batch is True, all values generated will be exactly same given a batch_size (shape[0]). By default,
same_on_batch is set to False.
@@ -416,7 +421,7 @@ def _adapted_uniform(
high: Union[float, torch.Tensor],
same_on_batch: bool = False,
) -> torch.Tensor:
- r"""Sample from a uniform sampling function that accepts 'same_on_batch'.
+ r"""Draw a reparameterized sample of ``shape`` from Uniform(low, high), one draw for the batch if same_on_batch.
If same_on_batch is True, all values generated will be exactly same given a batch_size (shape[0]). By default,
same_on_batch is set to False.
diff --git a/kornia/color/yuv.py b/kornia/color/yuv.py
index ca0b81de9..a57505989 100644
--- a/kornia/color/yuv.py
+++ b/kornia/color/yuv.py
@@ -168,7 +168,7 @@ def rgb_to_yuv422(image: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
def yuv_to_rgb(image: torch.Tensor) -> torch.Tensor:
- r"""Convert an YUV image to RGB.
+ 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.
@@ -223,7 +223,7 @@ def yuv_to_rgb(image: torch.Tensor) -> torch.Tensor:
def yuv420_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:
- r"""Convert an YUV420 image to RGB.
+ r"""Convert YUV 4:2:0 to RGB from separate luma and half-resolution chroma tensors.
Input need to be padded to be evenly divisible by 2 horizontal and vertical.
@@ -278,7 +278,7 @@ def yuv420_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:
def yuv422_to_rgb(imagey: torch.Tensor, imageuv: torch.Tensor) -> torch.Tensor:
- r"""Convert an YUV422 image to RGB.
+ r"""Convert YUV 4:2:2 to RGB from separate luma and half-width chroma tensors.
Input width must be evenly divisible by 2; height may be odd.
@@ -477,7 +477,7 @@ class RgbToYuv422(nn.Module):
class YuvToRgb(nn.Module):
- r"""Convert an image from YUV to RGB.
+ r"""Convert a full-resolution YUV (4:4:4) image of shape ``(*, 3, H, W)`` to RGB.
See the Convention block on :func:`yuv_to_rgb`.
@@ -524,7 +524,7 @@ class YuvToRgb(nn.Module):
class Yuv420ToRgb(nn.Module):
- r"""Convert an image from YUV to RGB.
+ r"""Convert YUV 4:2:0 to RGB from separate luma and half-resolution chroma tensors.
See the Convention block on :func:`yuv420_to_rgb`.
@@ -573,7 +573,7 @@ class Yuv420ToRgb(nn.Module):
class Yuv422ToRgb(nn.Module):
- r"""Convert an image from YUV to RGB.
+ r"""Convert YUV 4:2:2 to RGB from separate luma and half-width chroma tensors.
See the Convention block on :func:`yuv422_to_rgb`.
diff --git a/kornia/enhance/adjust.py b/kornia/enhance/adjust.py
index b67d91062..61d81c77a 100644
--- a/kornia/enhance/adjust.py
+++ b/kornia/enhance/adjust.py
@@ -111,7 +111,7 @@ def _make_factor_broadcastable(factor: torch.Tensor, image: torch.Tensor) -> tor
def adjust_saturation_raw(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust color saturation of an image.
+ r"""Scale the saturation channel of an HSV image by a factor and clamp it to [0, 1].
Convention:
Expects HSV, not RGB. The saturation channel is multiplied by factor
@@ -143,7 +143,7 @@ def adjust_saturation_raw(image: torch.Tensor, factor: Union[float, torch.Tensor
def adjust_saturation_with_gray_subtraction(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust color saturation of an image by blending the image with its grayscaled version.
+ r"""Adjust the saturation of an RGB image by blending it with its grayscale version, as PIL and torchvision do.
Convention:
factor=0 selects grayscale and factor=1 preserves RGB input; grayscale
@@ -203,7 +203,7 @@ def adjust_saturation_with_gray_subtraction(image: torch.Tensor, factor: Union[f
def adjust_saturation(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust color saturation of an image.
+ r"""Adjust the saturation of an RGB image by scaling its HSV saturation channel.
Convention:
Expects RGB in [0, 1] with channel dimension -3. factor=1 preserves the image;
@@ -275,7 +275,7 @@ def adjust_saturation(image: torch.Tensor, factor: Union[float, torch.Tensor]) -
def adjust_hue_raw(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust hue of an image.
+ r"""Shift the hue channel of an HSV image by an angle in radians, wrapping it into [0, 2Ļ€).
Convention:
Expects HSV. factor is an angle in radians added to the hue, and the sum is wrapped into
@@ -312,7 +312,7 @@ def adjust_hue_raw(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> t
def adjust_hue(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust hue of an image.
+ r"""Shift the hue of an RGB image by an angle in radians.
Convention:
Expects RGB in [0, 1] with channel dimension -3. factor is a hue angle
@@ -485,7 +485,7 @@ def adjust_gamma(
def adjust_contrast(image: torch.Tensor, factor: Union[float, torch.Tensor], clip_output: bool = True) -> torch.Tensor:
- r"""Adjust the contrast of an image torch.Tensor.
+ r"""Adjust the contrast of an image by multiplying its values by a factor.
Convention:
Contrast is a direct multiplicative scale of RGB values; factor=1
@@ -566,7 +566,7 @@ def adjust_contrast(image: torch.Tensor, factor: Union[float, torch.Tensor], cli
def adjust_contrast_with_mean_subtraction(image: torch.Tensor, factor: Union[float, torch.Tensor]) -> torch.Tensor:
- r"""Adjust the contrast of an image torch.Tensor by subtracting the mean over channels.
+ r"""Adjust the contrast of an image by blending it with its mean gray level, as PIL and torchvision do.
.. note::
this is just a convenience function to have compatibility with Pil. For exact
@@ -575,9 +575,8 @@ def adjust_contrast_with_mean_subtraction(image: torch.Tensor, factor: Union[flo
Args:
image: Image to be adjusted in the shape of :math:`(*, H, W)`.
factor: Contrast adjust factor per element
- in the batch. 0 generates a completely black image, 1 does not modify
- the input image while any other non-negative number modify the
- brightness by this factor.
+ in the batch. 0 gives a uniform image at the mean gray level, 1 does not modify
+ the input image and a larger factor increases the contrast.
Return:
Adjusted image in the shape of :math:`(*, H, W)`.
@@ -1323,7 +1322,7 @@ def invert(image: torch.Tensor, max_val: Optional[torch.Tensor] = None) -> torch
class AdjustSaturation(nn.Module):
- r"""Adjust color saturation of an image.
+ r"""Adjust the saturation of an RGB image by scaling its HSV saturation channel.
Convention:
See :func:`adjust_saturation` for the RGB input and factor policy.
@@ -1381,7 +1380,7 @@ class AdjustSaturation(nn.Module):
class AdjustSaturationWithGraySubtraction(nn.Module):
- r"""Adjust color saturation of an image.
+ r"""Adjust the saturation of an RGB image by blending it with its grayscale version, as PIL and torchvision do.
Convention:
See :func:`adjust_saturation_with_gray_subtraction` for blending.
@@ -1445,7 +1444,7 @@ class AdjustSaturationWithGraySubtraction(nn.Module):
class AdjustHue(nn.Module):
- r"""Adjust hue of an image.
+ r"""Shift the hue of an RGB image by an angle in radians.
Convention:
See :func:`adjust_hue` for RGB input and radians convention.
@@ -1559,7 +1558,7 @@ class AdjustGamma(nn.Module):
class AdjustContrast(nn.Module):
- r"""Adjust Contrast of an image.
+ r"""Adjust the contrast of an image by multiplying its values by a factor.
Convention:
See :func:`adjust_contrast` for the multiplicative scale; this module always clips to [0, 1].
@@ -1608,7 +1607,7 @@ class AdjustContrast(nn.Module):
class AdjustContrastWithMeanSubtraction(nn.Module):
- r"""Adjust Contrast of an image.
+ r"""Adjust the contrast of an image by blending it with its mean gray level, as PIL and torchvision do.
Convention:
See :func:`adjust_contrast_with_mean_subtraction` for its mean blend.
@@ -1620,9 +1619,8 @@ class AdjustContrastWithMeanSubtraction(nn.Module):
Args:
contrast_factor: Contrast adjust factor per element
in the batch by subtracting its mean grayscaled version.
- 0 generates a completely black image, 1 does not modify
- the input image while any other non-negative number modify the
- brightness by this factor.
+ 0 gives a uniform image at the mean gray level, 1 does not modify
+ the input image and a larger factor increases the contrast.
Shape:
- Input: Image/Input to be adjusted in the shape of :math:`(*, N)`.
diff --git a/kornia/feature/affine_shape.py b/kornia/feature/affine_shape.py
index a6d203e74..5323170ad 100644
--- a/kornia/feature/affine_shape.py
+++ b/kornia/feature/affine_shape.py
@@ -187,9 +187,10 @@ def _finalize_laf(
class LAFAffineShapeEstimator(nn.Module):
- r"""Module, which extracts patches using input images and local affine frames (LAFs).
+ r"""Adapt local affine frames using the second-moment matrices of their image-patch gradients.
- Then runs :class:`~kornia.feature.PatchAffineShapeEstimator` on patches to estimate LAFs shape.
+ It extracts a patch per LAF and runs :class:`~kornia.feature.PatchAffineShapeEstimator` on it to estimate the
+ shape.
Convention:
- Each patch is sampled through the upright form of its LAF (:func:`~kornia.feature.make_upright`), so the
@@ -267,10 +268,10 @@ class LAFAffineShapeEstimator(nn.Module):
class LAFAffNetShapeEstimator(nn.Module):
- """Module, which extracts patches using input images and local affine frames (LAFs).
+ """Adapt local affine frames using affine shapes estimated by the AffNet CNN.
- Then runs AffNet on patches to estimate LAFs shape. This is based on the original code from paper
- "Repeatability Is Not Enough: Learning Discriminative Affine Regions via Discriminability"".
+ It extracts a patch per LAF and runs AffNet on it to estimate the shape. This is based on the original code from
+ the paper "Repeatability Is Not Enough: Learning Discriminative Affine Regions via Discriminability".
See :cite:`AffNet2018` for more details.
Convention:
diff --git a/kornia/feature/laf.py b/kornia/feature/laf.py
index 798495136..9d4f41ff3 100644
--- a/kornia/feature/laf.py
+++ b/kornia/feature/laf.py
@@ -799,7 +799,7 @@ def _empty_patches(img: torch.Tensor, laf: torch.Tensor, B: int, N: int, PS: int
def extract_patches_simple(
img: torch.Tensor, laf: torch.Tensor, PS: int = 32, normalize_lafs_before_extraction: bool = True
) -> torch.Tensor:
- """Extract patches defined by LAFs from image torch.Tensor.
+ """Extract (B, N, CH, PS, PS) patches defined by LAFs from the full-resolution image only, without anti-aliasing.
Convention:
See the Convention block on :func:`~kornia.feature.extract_patches_from_pyramid`. This function samples the
@@ -853,7 +853,7 @@ def extract_patches_simple(
def extract_patches_from_pyramid(
img: torch.Tensor, laf: torch.Tensor, PS: int = 32, normalize_lafs_before_extraction: bool = True
) -> torch.Tensor:
- """Extract patches defined by LAFs from image torch.Tensor.
+ """Extract (B, N, CH, PS, PS) patches defined by LAFs, each sampled from the pyramid level that matches its scale.
Patches are extracted from the appropriate pyramid level.
diff --git a/kornia/feature/matching.py b/kornia/feature/matching.py
index 575d5cf6f..0374f7f27 100644
--- a/kornia/feature/matching.py
+++ b/kornia/feature/matching.py
@@ -100,7 +100,7 @@ def _no_match(dm: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
def match_nn(
desc1: torch.Tensor, desc2: torch.Tensor, dm: Optional[torch.Tensor] = None
) -> Tuple[torch.Tensor, torch.Tensor]:
- r"""Find nearest neighbors in desc2 for each vector in desc1.
+ r"""Match each descriptor in desc1 to its nearest neighbor in desc2, with no filtering.
Convention:
- Every ``match_*`` function returns ``(dists, idxs)``, one row per match. ``idxs`` is an int64
@@ -157,7 +157,7 @@ def match_nn(
def match_mnn(
desc1: torch.Tensor, desc2: torch.Tensor, dm: Optional[torch.Tensor] = None
) -> Tuple[torch.Tensor, torch.Tensor]:
- """Find mutual nearest neighbors in desc2 for each vector in desc1.
+ """Match the descriptors of desc1 and desc2 that are each other's nearest neighbors (mutual nearest neighbors).
Convention:
See the Convention block on :func:`match_nn`. A pair is kept only when each of the two descriptors is the
@@ -199,9 +199,9 @@ def match_mnn(
def match_snn(
desc1: torch.Tensor, desc2: torch.Tensor, th: float = 0.8, dm: Optional[torch.Tensor] = None
) -> Tuple[torch.Tensor, torch.Tensor]:
- """Find nearest neighbors in desc2 for each vector in desc1.
+ """Match each descriptor in desc1 to its nearest neighbor in desc2 if it passes Lowe's second-nearest ratio test.
- The method satisfies first to second nearest neighbor distance <= th.
+ The ratio of the first to the second nearest neighbor distance must be <= th.
Convention:
See the Convention block on :func:`match_nn`; ``dists`` is the ratio of the nearest to the second-nearest
@@ -241,9 +241,9 @@ def match_snn(
def match_smnn(
desc1: torch.Tensor, desc2: torch.Tensor, th: float = 0.95, dm: Optional[torch.Tensor] = None
) -> Tuple[torch.Tensor, torch.Tensor]:
- """Find mutual nearest neighbors in desc2 for each vector in desc1.
+ """Match mutual nearest neighbors of desc1 and desc2 that also pass the second-nearest ratio test both ways.
- the method satisfies first to second nearest neighbor distance <= th.
+ The ratio of the first to the second nearest neighbor distance must be <= th in both directions.
Convention:
- See the Convention block on :func:`match_nn`. A pair is kept when the two descriptors are mutual nearest
@@ -428,11 +428,10 @@ def match_fginn(
mutual: bool = False,
dm: Optional[torch.Tensor] = None,
) -> Tuple[torch.Tensor, torch.Tensor]:
- """Find nearest neighbors in desc2 for each vector in desc1.
+ """Match desc1 to desc2 by a ratio test against the first geometrically inconsistent nearest neighbor (FGINN).
- The method satisfies first to second nearest neighbor distance <= th,
- and assures 2nd nearest neighbor is geometrically inconsistent with the 1st one
- (see :cite:`MODS2015` for more details)
+ The ratio test compares the nearest distance with that of the nearest candidate whose ``lafs2`` centre lies at
+ least ``spatial_th`` from the first one's; closer candidates are skipped (see :cite:`MODS2015` for more details).
Convention:
- See the Convention block on :func:`match_nn`. ``dists`` is a ratio: the nearest distance over the distance
diff --git a/kornia/feature/orientation.py b/kornia/feature/orientation.py
index 03b6671f2..521e8a131 100644
--- a/kornia/feature/orientation.py
+++ b/kornia/feature/orientation.py
@@ -286,10 +286,10 @@ class OriNet(nn.Module):
class LAFOrienter(nn.Module):
- """Module, which extracts patches using input images and local affine frames (LAFs).
+ """Estimate the orientation of (B, N, 2, 3) LAFs from their image patches and rotate the LAFs by it.
- Then runs :class:`~kornia.feature.PatchDominantGradientOrientation` or
- :class:`~kornia.feature.OriNet` on patches and then rotates the LAFs by the estimated angles
+ It extracts a patch per LAF, runs :class:`~kornia.feature.PatchDominantGradientOrientation` or
+ :class:`~kornia.feature.OriNet` on it and rotates the LAF by the estimated angle.
Convention:
- Each LAF's patch (:func:`~kornia.feature.extract_patches_from_pyramid`) gives an angle, measured in the
diff --git a/kornia/feature/responses.py b/kornia/feature/responses.py
index a1bc3d6e8..756f1e00e 100644
--- a/kornia/feature/responses.py
+++ b/kornia/feature/responses.py
@@ -308,7 +308,7 @@ def hessian_response(
def dog_response(input: torch.Tensor) -> torch.Tensor:
- r"""Compute the Difference-of-Gaussian response.
+ r"""Compute the Difference-of-Gaussian response between adjacent levels of a (B, C, D, H, W) Gaussian scale stack.
Convention:
- Output level ``i`` is ``input[:, :, i + 1] - input[:, :, i]`` along the level axis ``D`` (dim 2), so ``D``
@@ -328,7 +328,7 @@ def dog_response(input: torch.Tensor) -> torch.Tensor:
def dog_response_single(input: torch.Tensor, sigma1: float = 1.0, sigma2: float = 1.6) -> torch.Tensor:
- r"""Compute the Difference-of-Gaussian response.
+ r"""Compute the Difference-of-Gaussian response of a (B, C, H, W) image, its sigma2 blur minus its sigma1 blur.
.. image:: _static/img/dog_response_single.png
@@ -356,7 +356,7 @@ def dog_response_single(input: torch.Tensor, sigma1: float = 1.0, sigma2: float
class BlobDoG(nn.Module):
- r"""nn.Module that calculates Difference-of-Gaussians blobs.
+ 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
@@ -383,7 +383,7 @@ class BlobDoG(nn.Module):
class BlobDoGSingle(nn.Module):
- r"""nn.Module that calculates Difference-of-Gaussians blobs.
+ r"""Compute the Difference-of-Gaussian response of a (B, C, H, W) image; the module form of dog_response_single.
.. image:: _static/img/dog_response_single.png
diff --git a/kornia/filters/kernels.py b/kornia/filters/kernels.py
index 91a07465a..84a8f2ca3 100644
--- a/kornia/filters/kernels.py
+++ b/kornia/filters/kernels.py
@@ -943,7 +943,7 @@ def get_gaussian_kernel2d(
device: Optional[torch.device] = None,
dtype: Optional[torch.dtype] = None,
) -> torch.Tensor:
- r"""Return Gaussian filter matrix coefficients.
+ r"""Return 2D Gaussian filter coefficients of shape (B, k_y, k_x), the outer product of two 1D kernels.
Convention:
See the Convention block on :func:`~kornia.filters.get_gaussian_kernel1d`. ``kernel_size`` is
@@ -1007,7 +1007,7 @@ def get_gaussian_kernel3d(
device: Optional[torch.device] = None,
dtype: Optional[torch.dtype] = None,
) -> torch.Tensor:
- r"""Return Gaussian filter matrix coefficients.
+ r"""Return 3D Gaussian filter coefficients of shape (B, k_z, k_y, k_x), the outer product of three 1D kernels.
Convention:
See the Convention block on :func:`~kornia.filters.get_gaussian_kernel1d`. ``kernel_size`` is
diff --git a/kornia/geometry/camera/projection_orthographic.py b/kornia/geometry/camera/projection_orthographic.py
index e1f22019f..eb7f5bf01 100644
--- a/kornia/geometry/camera/projection_orthographic.py
+++ b/kornia/geometry/camera/projection_orthographic.py
@@ -15,7 +15,7 @@
# limitations under the License.
#
-"""nn.Module containing functions for orthographic projection."""
+"""Functions for orthographic projection."""
# inspired by: https://github.com/farm-ng/sophus-rs/blob/main/src/sensor/ortho_camera.rs
import torch
@@ -24,11 +24,11 @@ from kornia.core.check import KORNIA_CHECK_SHAPE
def project_points_orthographic(points_in_camera: torch.Tensor) -> torch.Tensor:
- r"""Project points from the camera frame into the canonical z=1 plane through orthographic projection.
+ r"""Project camera-frame points orthographically onto the image plane by dropping z: (x, y, z) -> (x, y).
.. math::
\begin{bmatrix} u \\ v \end{bmatrix} =
- \begin{bmatrix} x \\ y \\ z \end{bmatrix}
+ \begin{bmatrix} x \\ y \end{bmatrix}
Args:
@@ -48,7 +48,7 @@ def project_points_orthographic(points_in_camera: torch.Tensor) -> torch.Tensor:
def unproject_points_orthographic(points_in_camera: torch.Tensor, extension: torch.Tensor) -> torch.Tensor:
- r"""Unproject one or more points from the canonical z=1 plane into the camera frame.
+ r"""Unproject orthographic image-plane points into the camera frame by appending a z value: (u, v) -> (u, v, z).
.. math::
\begin{bmatrix} x \\ y \\ z \end{bmatrix} =
@@ -81,7 +81,7 @@ def unproject_points_orthographic(points_in_camera: torch.Tensor, extension: tor
def dx_project_points_orthographic(points_in_camera: torch.Tensor) -> torch.Tensor:
- r"""Compute the derivative of the x projection with respect to the x coordinate.
+ r"""Compute the derivative of the orthographic x projection with respect to x, which is always 1.
.. math::
\frac{\partial u}{\partial x} = 1
diff --git a/kornia/geometry/camera/projection_z1.py b/kornia/geometry/camera/projection_z1.py
index 837df61bb..3c01d6305 100644
--- a/kornia/geometry/camera/projection_z1.py
+++ b/kornia/geometry/camera/projection_z1.py
@@ -15,7 +15,7 @@
# limitations under the License.
#
-"""nn.Module for the projection of points in the canonical z=1 plane."""
+"""Functions for the perspective projection of points onto the canonical z=1 plane."""
# inspired by: https://github.com/farm-ng/sophus-rs/blob/main/src/sensor/perspective_camera.rs
from __future__ import annotations
@@ -72,11 +72,11 @@ def project_points_z1(points_in_camera: torch.Tensor) -> torch.Tensor:
def unproject_points_z1(
points_in_cam_canonical: torch.Tensor, extension: Optional[torch.Tensor] = None
) -> torch.Tensor:
- r"""Unproject one or more points from the canonical z=1 plane into the camera frame.
+ r"""Unproject points on the canonical z=1 plane into the camera frame by scaling them by a depth (default 1).
.. math::
\begin{bmatrix} x \\ y \\ z \end{bmatrix} =
- \begin{bmatrix} u \\ v \end{bmatrix} \cdot w
+ \begin{bmatrix} u \\ v \\ 1 \end{bmatrix} \cdot w
Convention:
- ``extension`` is the camera-frame ``z`` of the unprojected point: the canonical point is multiplied
@@ -117,9 +117,7 @@ def unproject_points_z1(
def dx_project_points_z1(points_in_camera: torch.Tensor) -> torch.Tensor:
- r"""Compute the derivative of the x projection with respect to the x coordinate.
-
- Returns point derivative of inverse depth point projection with respect to the x coordinate.
+ r"""Compute the 2x3 Jacobian of the z=1 perspective projection with respect to the camera-frame point (x, y, z).
.. math::
\frac{\partial \pi}{\partial x} =
@@ -143,8 +141,8 @@ def dx_project_points_z1(points_in_camera: torch.Tensor) -> torch.Tensor:
points_in_camera: torch.Tensor representing the points to project with shape (..., 3).
Returns:
- torch.Tensor representing the derivative of the x projection with respect to the x coordinate
- with shape (..., 2, 3).
+ torch.Tensor representing the Jacobian of the projected point :math:`(u, v)` with respect to
+ :math:`(x, y, z)`, with shape (..., 2, 3).
Example:
>>> points = torch.tensor([1., 2., 3.])
diff --git a/kornia/geometry/conversions.py b/kornia/geometry/conversions.py
index a31e43426..869c8b387 100644
--- a/kornia/geometry/conversions.py
+++ b/kornia/geometry/conversions.py
@@ -1805,7 +1805,7 @@ def normalize_homography(
dsize_dst: tuple[int, int],
align_corners: bool = True,
) -> torch.Tensor:
- r"""Normalize a given homography in pixels to [-1, 1].
+ r"""Express a 2D source→destination pixel homography (B, 3, 3) in [-1, 1] coordinates, corner-aligned by default.
Convention:
- the input maps **source pixels to destination pixels** and the output
@@ -1916,7 +1916,7 @@ def normal_transform_pixel(
dtype: Optional[torch.dtype] = None,
align_corners: bool = True,
) -> torch.Tensor:
- r"""Compute the normalization matrix from image size in pixels to [-1, 1].
+ 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
@@ -2105,7 +2105,7 @@ def normal_transform_pixel3d(
device: Optional[torch.device] = None,
dtype: Optional[torch.dtype] = None,
) -> torch.Tensor:
- r"""Compute the normalization matrix from image size in pixels to [-1, 1].
+ r"""Compute the (1, 4, 4) matrix that maps 3D voxel coordinates (x, y, z) to [-1, 1], always corner-aligned.
Convention:
- the 3-D counterpart of
@@ -2334,7 +2334,7 @@ def denormalize_homography(
def normalize_homography3d(
dst_pix_trans_src_pix: torch.Tensor, dsize_src: tuple[int, int, int], dsize_dst: tuple[int, int, int]
) -> torch.Tensor:
- r"""Normalize a given homography in pixels to [-1, 1].
+ r"""Express a 3D source→destination voxel homography (B, 4, 4) in [-1, 1] coordinates, always corner-aligned.
Convention:
- the 3-D counterpart of
@@ -2350,8 +2350,8 @@ def normalize_homography3d(
record
- it inverts ``N_src`` with ``torch.linalg.inv`` (so ``cusolver`` on
``cuda``, and a ``float32`` upcast for ``float16``/``bfloat16``),
- where the 2-D function uses a closed-form adjugate in the working
- dtype; the 2-D and 3-D routes therefore need not agree bitwise
+ 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
vectors, while both ``dsize`` arguments are
``(depth, height, width)`` triples
@@ -2703,7 +2703,7 @@ def _integer_safe_matmul(a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
def camtoworld_graphics_to_vision_4x4(extrinsics_graphics: torch.Tensor) -> torch.Tensor:
- r"""Convert a camera-to-world pose from the graphics frame (e.g. OpenGL) to the vision frame (e.g. OpenCV).
+ r"""Convert a (B, 4, 4) camera-to-world matrix from the graphics (OpenGL) frame to the vision (OpenCV) frame.
I.e. flips y and z axis. Graphics convention: [+x, +y, +z] == [right, up, backwards].
Vision convention: [+x, +y, +z] == [right, down, forwards].
@@ -2774,7 +2774,7 @@ def camtoworld_graphics_to_vision_4x4(extrinsics_graphics: torch.Tensor) -> torc
def camtoworld_graphics_to_vision_Rt(R: torch.Tensor, t: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
- r"""Convert a camera-to-world pose from the graphics frame (e.g. OpenGL) to the vision frame (e.g. OpenCV).
+ r"""Convert a camera-to-world pose given as (R, t) from the graphics (OpenGL) frame to the vision (OpenCV) frame.
I.e. flips y and z axis. Graphics convention: [+x, +y, +z] == [right, up, backwards].
Vision convention: [+x, +y, +z] == [right, down, forwards].
@@ -2822,7 +2822,7 @@ def camtoworld_graphics_to_vision_Rt(R: torch.Tensor, t: torch.Tensor) -> tuple[
def camtoworld_vision_to_graphics_4x4(extrinsics_vision: torch.Tensor) -> torch.Tensor:
- r"""Convert a camera-to-world pose from the vision frame (e.g. OpenCV) to the graphics frame (e.g. OpenGL).
+ r"""Convert a (B, 4, 4) camera-to-world matrix from the vision (OpenCV) frame to the graphics (OpenGL) frame.
I.e. flips y and z axis. Graphics convention: [+x, +y, +z] == [right, up, backwards].
Vision convention: [+x, +y, +z] == [right, down, forwards].
@@ -2867,7 +2867,7 @@ def camtoworld_vision_to_graphics_4x4(extrinsics_vision: torch.Tensor) -> torch.
def camtoworld_vision_to_graphics_Rt(R: torch.Tensor, t: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
- r"""Convert a camera-to-world pose from the vision frame (e.g. OpenCV) to the graphics frame (e.g. OpenGL).
+ r"""Convert a camera-to-world pose given as (R, t) from the vision (OpenCV) frame to the graphics (OpenGL) frame.
I.e. flips y and z axis. Graphics convention: [+x, +y, +z] == [right, up, backwards].
Vision convention: [+x, +y, +z] == [right, down, forwards].
diff --git a/kornia/geometry/depth.py b/kornia/geometry/depth.py
index 7096a1f73..ed7eccf17 100644
--- a/kornia/geometry/depth.py
+++ b/kornia/geometry/depth.py
@@ -81,7 +81,7 @@ def unproject_meshgrid(
device: Optional[torch.device] = None,
dtype: Optional[torch.dtype] = None,
) -> torch.Tensor:
- """Compute a 3d point per pixel given its depth value and the camera intrinsics.
+ """Generate camera-frame rays through each pixel, with z = 1 by default, for caching in depth_to_3d_v2.
.. tip::
@@ -107,7 +107,8 @@ def unproject_meshgrid(
dtype: dtype of the pixel grid; the output dtype follows promotion with ``camera_matrix``.
Return:
- tensor with a 3d point per pixel, with shape :math:`(B, H, W, 3)`.
+ the ray through each pixel, with ``z`` equal to 1 (or unit length with ``normalize_points=True``), with
+ shape :math:`(B, H, W, 3)`.
"""
KORNIA_CHECK_SHAPE(camera_matrix, ["B", "3", "3"])
@@ -141,12 +142,13 @@ def depth_to_3d_v2(
) -> torch.Tensor:
# NOTE: when this replaces the `depth_to_3d` behaviour, a deprecated function should be added here, instead
# of just replace the other function.
- """Compute a 3d point per pixel given its depth value and the camera intrinsics.
+ """Unproject a ``(*, H, W)`` depth map to channels-last camera-frame 3D points, broadcast with the camera batch.
.. note::
- This is an alternative implementation of :py:func:`kornia.geometry.depth.depth_to_3d`
- that does not require the creation of a meshgrid.
+ This is an alternative implementation of :py:func:`kornia.geometry.depth.depth_to_3d` that can reuse a
+ grid from :py:func:`kornia.geometry.depth.unproject_meshgrid`, passed as ``xyz_grid``, instead of building
+ the meshgrid on every call.
Convention:
- ``depth`` is the camera-frame ``z`` of each pixel and the result the camera-frame point
@@ -203,12 +205,12 @@ def depth_to_3d_v2(
def depth_to_3d(depth: torch.Tensor, camera_matrix: torch.Tensor, normalize_points: bool = False) -> torch.Tensor:
- """Compute a 3d point per pixel given its depth value and the camera intrinsics.
+ """Unproject a (B, 1, H, W) depth map to camera-frame 3D points, returned channels-first as (B, 3, H, W).
.. note::
- :py:func:`kornia.geometry.depth.depth_to_3d_v2` computes the same points without building a meshgrid,
- in the :math:`(B, H, W, 3)` layout.
+ :py:func:`kornia.geometry.depth.depth_to_3d_v2` computes the same points in the :math:`(B, H, W, 3)`
+ layout and can reuse a grid cached with :py:func:`kornia.geometry.depth.unproject_meshgrid`.
Convention:
- ``depth`` is the camera-frame ``z`` of each pixel and the result the camera-frame point
diff --git a/kornia/geometry/epipolar/_metrics.py b/kornia/geometry/epipolar/_metrics.py
index f38cb64a2..c8b9a5cc2 100644
--- a/kornia/geometry/epipolar/_metrics.py
+++ b/kornia/geometry/epipolar/_metrics.py
@@ -375,7 +375,7 @@ def symmetrical_epipolar_distance(
def left_to_right_epipolar_distance(pts1: Tensor, pts2: Tensor, Fm: Tensor) -> Tensor:
- r"""Return one-sided epipolar distance for correspondences given the fundamental matrix.
+ r"""Return the one-sided distance from each point in ``pts2`` to the epipolar line of its match in ``pts1``.
Convention:
- Argument order as :func:`sampson_epipolar_distance`; returns the unsquared pixel distance of each
@@ -410,7 +410,7 @@ def left_to_right_epipolar_distance(pts1: Tensor, pts2: Tensor, Fm: Tensor) -> T
def right_to_left_epipolar_distance(pts1: Tensor, pts2: Tensor, Fm: Tensor) -> Tensor:
- r"""Return one-sided epipolar distance for correspondences given the fundamental matrix.
+ r"""Return the one-sided distance from each point in ``pts1`` to the epipolar line of its match in ``pts2``.
Convention:
- Argument order as :func:`sampson_epipolar_distance`; returns the unsquared pixel distance of each
diff --git a/kornia/geometry/grid.py b/kornia/geometry/grid.py
index 01e051d2b..05a2f4fc5 100644
--- a/kornia/geometry/grid.py
+++ b/kornia/geometry/grid.py
@@ -33,7 +33,7 @@ def create_meshgrid(
dtype: Optional[torch.dtype] = None,
align_corners: bool = True,
) -> torch.Tensor:
- r"""Generate a coordinate grid for an image.
+ r"""Generate a (1, H, W, 2) grid of (x, y) pixel coordinates, normalized to [-1, 1] by default.
Convention:
- Coordinates follow :ref:`Coordinates and sizes <coordinate-conventions>`. With
@@ -158,7 +158,7 @@ def create_meshgrid3d(
device: Optional[torch.device] = None,
dtype: Optional[torch.dtype] = None,
) -> torch.Tensor:
- """Generate a coordinate grid for an image.
+ """Generate a (1, D, H, W, 3) grid of (d, x, y) voxel coordinates, normalized to [-1, 1] by default.
Convention:
- Coordinates follow :ref:`Coordinates and sizes <coordinate-conventions>`. A normalized grid is always
diff --git a/kornia/geometry/subpix/nms.py b/kornia/geometry/subpix/nms.py
index 4baa82a89..b47e37b94 100644
--- a/kornia/geometry/subpix/nms.py
+++ b/kornia/geometry/subpix/nms.py
@@ -101,7 +101,7 @@ def _neighbourhood_max3d(x: torch.Tensor, kd: int, ky: int, kx: int) -> torch.Te
class NonMaximaSuppression2d(nn.Module):
- r"""Apply non maxima suppression to filter.
+ r"""Keep only the strict local maxima of a (B, C, H, W) map in a 2D window; the module form of nms2d.
Convention:
- See the convention block of :func:`~kornia.geometry.subpix.nms2d`.
@@ -291,7 +291,7 @@ class NonMaximaSuppression2d(nn.Module):
class NonMaximaSuppression3d(nn.Module):
- r"""Apply non maxima suppression to filter.
+ r"""Keep only the strict local maxima of a (B, C, D, H, W) volume in a 3D window; the module form of nms3d.
Convention:
- See the convention block of :func:`~kornia.geometry.subpix.nms2d`.
@@ -387,7 +387,7 @@ class NonMaximaSuppression3d(nn.Module):
def nms2d(input: torch.Tensor, kernel_size: tuple[int, int], mask_only: bool = False) -> torch.Tensor:
- r"""Apply non maxima suppression to filter.
+ r"""Keep only the strict local maxima of a (B, C, H, W) map in a 2D ``kernel_size`` window, zeroing the rest.
Convention:
- Only strict maxima survive: a position must be greater than every other value in its ``kernel_size``
@@ -404,7 +404,7 @@ def nms2d(input: torch.Tensor, kernel_size: tuple[int, int], mask_only: bool = F
def nms3d(input: torch.Tensor, kernel_size: tuple[int, int, int], mask_only: bool = False) -> torch.Tensor:
- r"""Apply non maxima suppression to filter.
+ r"""Keep only the strict local maxima of a (B, C, D, H, W) volume in a 3D ``kernel_size`` window, zeroing the rest.
Convention:
- See the convention block of :func:`nms2d`, applied over depth, height and width.
diff --git a/kornia/geometry/transform/imgwarp.py b/kornia/geometry/transform/imgwarp.py
index b2215cfcc..7672c1ecd 100644
--- a/kornia/geometry/transform/imgwarp.py
+++ b/kornia/geometry/transform/imgwarp.py
@@ -260,7 +260,7 @@ def warp_perspective(
align_corners: bool = True,
fill_value: Optional[torch.Tensor] = None, # needed for jit
) -> torch.Tensor:
- r"""Apply a perspective transformation to an image.
+ r"""Warp a 2D (B, C, H, W) image by a (B, 3, 3) source→destination homography in pixel coordinates.
The function warp_perspective transforms the source image using
the specified matrix:
@@ -598,7 +598,7 @@ def _fill_and_warp(
def warp_grid(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:
- r"""Compute the grid to warp the coordinates grid by the homography/ies.
+ 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)`
@@ -684,7 +684,7 @@ def _normalize_warped_pixel_grid(grid: torch.Tensor, height: int, width: int, al
def warp_grid3d(grid: torch.Tensor, src_homo_dst: torch.Tensor) -> torch.Tensor:
- r"""Compute the grid to warp the coordinates grid by the homography/ies.
+ 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
@@ -1860,9 +1860,9 @@ def warp_perspective3d(
border_mode: str = "zeros",
align_corners: bool = False,
) -> torch.Tensor:
- r"""Apply a perspective transformation to an image.
+ r"""Warp a 3D (B, C, D, H, W) volume by a (B, 4, 4) source→destination homography in voxel coordinates.
- The function warp_perspective transforms the source image using
+ The function warp_perspective3d transforms the source volume using
the specified matrix:
.. math::
diff --git a/kornia/losses/focal.py b/kornia/losses/focal.py
index 916a0183e..76dd480a8 100644
--- a/kornia/losses/focal.py
+++ b/kornia/losses/focal.py
@@ -174,7 +174,7 @@ def focal_loss(
weight: Optional[torch.Tensor] = None,
ignore_index: Optional[int] = -100,
) -> torch.Tensor:
- r"""Criterion that computes Focal loss.
+ r"""Compute the multi-class focal loss of ``(B, C, *)`` logits against ``(B, *)`` class indices, using softmax.
According to :cite:`lin2018focal`, the Focal loss is computed as follows:
@@ -339,7 +339,7 @@ def focal_loss(
class FocalLoss(nn.Module):
- r"""Criterion that computes Focal loss.
+ r"""Compute the multi-class focal loss of ``(B, C, *)`` logits against ``(B, *)`` class indices, using softmax.
According to :cite:`lin2018focal`, the Focal loss is computed as follows:
@@ -426,7 +426,7 @@ def binary_focal_loss_with_logits(
weight: Optional[torch.Tensor] = None,
ignore_index: Optional[int] = -100,
) -> torch.Tensor:
- r"""Criterion that computes Binary Focal loss.
+ r"""Compute the binary focal loss of ``(B, C, *)`` logits against same-shape targets in [0, 1], using sigmoid.
According to :cite:`lin2018focal`, the Focal loss is computed as follows:
@@ -550,7 +550,7 @@ def binary_focal_loss_with_logits(
class BinaryFocalLossWithLogits(nn.Module):
- r"""Criterion that computes Focal loss.
+ r"""Compute the binary focal loss of ``(B, C, *)`` logits against same-shape targets in [0, 1], using sigmoid.
According to :cite:`lin2018focal`, the Focal loss is computed as follows:
diff --git a/kornia/losses/ssim.py b/kornia/losses/ssim.py
index cc26721e7..ca8e8de09 100644
--- a/kornia/losses/ssim.py
+++ b/kornia/losses/ssim.py
@@ -32,7 +32,7 @@ def ssim_loss(
reduction: str = "mean",
padding: str = "same",
) -> torch.Tensor:
- r"""Compute a loss based on the SSIM measurement.
+ r"""Compute the DSSIM loss, clamp((1 - SSIM) / 2, 0, 1), between two (B, C, H, W) images.
The loss, or the Structural dissimilarity (DSSIM) is described as:
@@ -89,7 +89,7 @@ def ssim_loss(
class SSIMLoss(nn.Module):
- r"""Create a criterion that computes a loss based on the SSIM measurement.
+ r"""Compute the DSSIM loss, clamp((1 - SSIM) / 2, 0, 1), between two (B, C, H, W) images.
The loss, or the Structural dissimilarity (DSSIM) is described as:
diff --git a/kornia/losses/ssim3d.py b/kornia/losses/ssim3d.py
index c2730ef64..5f3126a15 100644
--- a/kornia/losses/ssim3d.py
+++ b/kornia/losses/ssim3d.py
@@ -32,7 +32,7 @@ def ssim3d_loss(
reduction: str = "mean",
padding: str = "same",
) -> torch.Tensor:
- r"""Compute a loss based on the SSIM measurement.
+ r"""Compute the DSSIM loss, clamp((1 - SSIM) / 2, 0, 1), between two (B, C, D, H, W) volumes.
The loss is the structural dissimilarity (DSSIM) of each voxel, clamped to :math:`[0, 1]`:
@@ -86,7 +86,7 @@ def ssim3d_loss(
class SSIM3DLoss(nn.Module):
- r"""Create a criterion that computes a loss based on the SSIM measurement.
+ r"""Compute the DSSIM loss, clamp((1 - SSIM) / 2, 0, 1), between two (B, C, D, H, W) volumes.
The loss is the structural dissimilarity (DSSIM) of each voxel, clamped to :math:`[0, 1]`:
diff --git a/kornia/metrics/ssim.py b/kornia/metrics/ssim.py
index eba9e1739..d32ad6f24 100644
--- a/kornia/metrics/ssim.py
+++ b/kornia/metrics/ssim.py
@@ -110,7 +110,7 @@ def ssim(
eps: float = 1e-12,
padding: str = "same",
) -> torch.Tensor:
- r"""Compute the Structural Similarity (SSIM) index map between two images.
+ r"""Compute the per-pixel Structural Similarity (SSIM) map between two (B, C, H, W) images.
Measures the (SSIM) index between each element in the input `x` and target `y`.
@@ -273,7 +273,7 @@ def ssim(
class SSIM(nn.Module):
- r"""Create a module that computes the Structural Similarity (SSIM) index between two images.
+ r"""Compute the per-pixel Structural Similarity (SSIM) map between two (B, C, H, W) images.
Measures the (SSIM) index between each element in the input `x` and target `y`.
diff --git a/kornia/metrics/ssim3d.py b/kornia/metrics/ssim3d.py
index 4ccb3bb33..b7f94184e 100644
--- a/kornia/metrics/ssim3d.py
+++ b/kornia/metrics/ssim3d.py
@@ -49,7 +49,7 @@ def ssim3d(
eps: float = 1e-12,
padding: str = "same",
) -> torch.Tensor:
- r"""Compute the Structural Similarity (SSIM) index map between two images.
+ r"""Compute the per-voxel Structural Similarity (SSIM) map between two (B, C, D, H, W) volumes.
Measures the (SSIM) index between each element in the input `x` and target `y`.
@@ -188,7 +188,7 @@ def ssim3d(
class SSIM3D(nn.Module):
- r"""Create a module that computes the Structural Similarity (SSIM) index between two 3D images.
+ r"""Compute the per-voxel Structural Similarity (SSIM) map between two (B, C, D, H, W) volumes.
Measures the (SSIM) index between each element in the input `x` and target `y`.
diff --git a/tests/test_docstring_first_lines.py b/tests/test_docstring_first_lines.py
new file mode 100644
index 000000000..c4cc61f33
--- /dev/null
+++ b/tests/test_docstring_first_lines.py
@@ -0,0 +1,184 @@
+# LICENSE HEADER MANAGED BY add-license-header
+#
+# Copyright 2018 Kornia Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""No two public kornia functions or classes share a first docstring line.
+
+``help()``, IDE hovers, the Sphinx autosummary tables and coding agents often read only the first docstring line.
+When two different symbols share it -- ``match_nn``, ``match_snn`` and ``match_fginn`` once all said "Find nearest
+neighbors in desc2 for each vector in desc1" -- that reader cannot tell which one it needs. Each first line therefore
+names what sets its symbol apart from its siblings: the dimension, variant, criterion, input form or direction.
+
+The one exception is a class and the function it wraps, whose names match once underscores are removed and case is
+ignored (``AdjustHue`` / ``adjust_hue``, ``PyrDown`` / ``pyrdown``) and which live in the same top-level subpackage
+(``kornia.enhance``): they do the same thing and may say so in the same words. A cross-package pair such as
+``kornia.augmentation.Resize`` and ``kornia.geometry.transform.resize`` is not exempt.
+
+The scan covers every name in the ``__all__`` of a non-private kornia module that is a function or a class defined
+in kornia, deduplicated by object identity. Names that start with an underscore are out of scope, and so is a class
+without a docstring of its own, which inherits one from its base. Lines are compared exactly after casefolding and
+collapsing whitespace, so this catches copies, not near-duplicates: two lines that differ by a single word pass.
+"""
+
+import ast
+import importlib
+import inspect
+import warnings
+from functools import cache
+from pathlib import Path
+
+import kornia
+
+_KORNIA_ROOT = Path(kornia.__file__).resolve().parent
+
+
+def _modules_declaring_all() -> list[str]:
+ """Name every non-private kornia module that assigns ``__all__``, found from source without importing it.
+
+ The same parse as ``_declared_inventory_modules`` in ``tests/test_api_surface.py``, over the whole package
+ rather than the inventory roots: the inventory leaves out ``kornia.feature``, whose matchers and LAF estimators
+ are among the symbols this test exists for.
+ """
+ found = []
+ for path in sorted(_KORNIA_ROOT.rglob("*.py")):
+ parts = list(path.relative_to(_KORNIA_ROOT).with_suffix("").parts)
+ if parts[-1] == "__init__":
+ parts.pop()
+ if any(part.startswith("_") for part in parts):
+ continue
+ tree = ast.parse(path.read_bytes(), filename=str(path))
+ if any(
+ (
+ isinstance(node, ast.Assign)
+ and any(isinstance(target, ast.Name) and target.id == "__all__" for target in node.targets)
+ )
+ or (isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == "__all__")
+ for node in tree.body
+ ):
+ found.append(".".join(["kornia", *parts]))
+ return found
+
+
+def _first_line(doc: str) -> str:
+ return next((line.strip() for line in inspect.cleandoc(doc).splitlines() if line.strip()), "")
+
+
+def _qualified_name(obj: object) -> str:
+ return f"{obj.__module__}.{obj.__qualname__}"
+
+
+def _squash(name: str) -> str:
+ return name.replace("_", "").casefold()
+
+
+def _subpackage(obj: object) -> str:
+ """Return the top-level kornia subpackage that defines ``obj``, such as ``kornia.enhance``."""
+ return ".".join(obj.__module__.split(".")[:2])
+
+
+def _is_wrapper_pair(objects: list) -> bool:
+ """Whether ``objects`` is one class and one function of one subpackage whose names match without underscores."""
+ if len(objects) != 2:
+ return False
+ classes = [obj for obj in objects if inspect.isclass(obj)]
+ functions = [obj for obj in objects if inspect.isfunction(obj)]
+ return (
+ len(classes) == 1
+ and len(functions) == 1
+ and _squash(classes[0].__name__) == _squash(functions[0].__name__)
+ and _subpackage(classes[0]) == _subpackage(functions[0])
+ )
+
+
+@cache
+def _public_first_lines() -> dict[int, tuple[object, str]]:
+ """Map ``id(obj)`` to ``(obj, first docstring line)`` for every public kornia function and class."""
+ collected: dict[int, tuple[object, str]] = {}
+ for module_name in _modules_declaring_all():
+ with warnings.catch_warnings():
+ # ``getattr`` runs module-level ``__getattr__`` shims, which warn about deprecated names.
+ warnings.simplefilter("ignore")
+ try:
+ module = importlib.import_module(module_name)
+ except ModuleNotFoundError as error:
+ # A module that needs an optional package which is not installed is out of scope here.
+ if (error.name or "").partition(".")[0] == "kornia":
+ raise
+ continue
+ exported = [(name, getattr(module, name, None)) for name in module.__all__ if not name.startswith("_")]
+ for _, obj in exported:
+ if not (inspect.isclass(obj) or inspect.isfunction(obj)):
+ continue
+ module_of_obj = obj.__module__ or ""
+ if not (module_of_obj == "kornia" or module_of_obj.startswith("kornia.")):
+ continue
+ # ``inspect.getdoc`` would hand a class without a docstring its base class's one.
+ doc = obj.__dict__.get("__doc__") if inspect.isclass(obj) else obj.__doc__
+ if doc:
+ collected[id(obj)] = (obj, _first_line(doc))
+ return collected
+
+
+def test_the_scan_covers_the_public_api():
+ # Guards against a vacuous pass: a discovery that silently stopped importing modules would find no duplicates.
+ collected = _public_first_lines()
+ assert len(collected) >= 800, len(collected)
+ # Looked up through public names and matched by identity, so moving a definition to another file keeps this.
+ for obj in (
+ kornia.augmentation.ColorJitter,
+ kornia.feature.match_snn,
+ kornia.geometry.subpix.nms2d,
+ kornia.losses.FocalLoss,
+ ):
+ assert id(obj) in collected, _qualified_name(obj)
+ # A known wrapper pair is scanned and recognised; its two lines may, but need not, be identical.
+ assert id(kornia.enhance.AdjustHue) in collected
+ assert id(kornia.enhance.adjust_hue) in collected
+ assert _is_wrapper_pair([kornia.enhance.AdjustHue, kornia.enhance.adjust_hue])
+
+
+def test_the_wrapper_pair_rule():
+ from kornia.enhance import adjust_hue, adjust_hue_raw
+ from kornia.geometry.subpix import NonMaximaSuppression2d, nms2d
+ from kornia.geometry.transform import PyrDown, pyrdown
+
+ assert _is_wrapper_pair([PyrDown, pyrdown])
+ assert not _is_wrapper_pair([NonMaximaSuppression2d, nms2d])
+ assert not _is_wrapper_pair([adjust_hue, adjust_hue_raw])
+ assert not _is_wrapper_pair([kornia.enhance.AdjustHue, adjust_hue, adjust_hue_raw])
+ # Same name after squashing, but different subpackages.
+ assert not _is_wrapper_pair([kornia.augmentation.Resize, kornia.geometry.transform.resize])
+
+
+def test_first_docstring_lines_are_distinct():
+ groups: dict[str, list] = {}
+ for obj, line in _public_first_lines().values():
+ # Case and spacing changes do not make two lines distinguishable to a reader.
+ groups.setdefault(" ".join(line.casefold().split()), []).append((obj, line))
+
+ offending = sorted(
+ (sorted(_qualified_name(obj) for obj, _ in members), members[0][1])
+ for members in groups.values()
+ if len(members) > 1 and not _is_wrapper_pair([obj for obj, _ in members])
+ )
+ report = "\n".join(f" {line!r}\n" + "\n".join(f" {name}" for name in names) for names, line in offending)
+ assert not offending, (
+ f"{len(offending)} first docstring line(s) are shared by different public symbols, so help(), IDE hovers and "
+ "the API tables cannot tell them apart. Give each symbol a first line that names what sets it apart from the "
+ "others: dimension, variant, criterion, input form or direction. Only a class and the function it wraps, "
+ "defined in the same subpackage with names that match without underscores (AdjustHue / adjust_hue), may "
+ "share one.\n" + report
+ )