š Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-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.pyindex 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[torcclass 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.pngdiff --git a/kornia/augmentation/_2d/intensity/color_jitter.py b/kornia/augmentation/_2d/intensity/color_jitter.pyindex 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[torcclass 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 itwith its grayscale mean, saturation with its grayscale, and hue is torchvision's ``adjust_hue`` shift -- so thisdiff --git a/kornia/augmentation/utils/helpers.py b/kornia/augmentation/utils/helpers.pyindex 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.Tensdef _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.Tedef _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.pyindex 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.pyindex 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) -> tordef 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.Tensordef 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[fdef 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]) -> tdef 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], clidef 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[floArgs: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) -> torchclass 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 elementin 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.pyindex 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.pyindex 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: intdef 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.pyindex 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 distancediff --git a/kornia/feature/orientation.py b/kornia/feature/orientation.pyindex 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 thediff --git a/kornia/feature/responses.py b/kornia/feature/responses.pyindex 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: floatclass 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.pngdiff --git a/kornia/filters/kernels.py b/kornia/filters/kernels.pyindex 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`` isdiff --git a/kornia/geometry/camera/projection_orthographic.py b/kornia/geometry/camera/projection_orthographic.pyindex 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.rsimport torch@@ -24,11 +24,11 @@ from kornia.core.check import KORNIA_CHECK_SHAPEdef 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: tordef 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} = 1diff --git a/kornia/geometry/camera/projection_z1.py b/kornia/geometry/camera/projection_z1.pyindex 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.rsfrom __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 wConvention:- ``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.pyindex 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)`` columnvectors, 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) -> torcdef 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.pyindex 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 pointdiff --git a/kornia/geometry/epipolar/_metrics.py b/kornia/geometry/epipolar/_metrics.pyindex 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) -> Tdef 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 eachdiff --git a/kornia/geometry/grid.py b/kornia/geometry/grid.pyindex 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 alwaysdiff --git a/kornia/geometry/subpix/nms.py b/kornia/geometry/subpix/nms.pyindex 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.Teclass 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 = Fdef 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.pyindex 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 usingthe 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, aldef 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 usingthe specified matrix:.. math::diff --git a/kornia/losses/focal.py b/kornia/losses/focal.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pynew file mode 100644index 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+ )