Add Image API

docs/source/core.rst

@@ -0,0 +1,12 @@
+kornia.core
+===========
+
+.. currentmodule:: kornia.core
+
+.. autoclass:: ImageColor
+    :members:
+    :undoc-members:
+
+.. autoclass:: Image
+    :members:
+    :undoc-members:

kornia/color/gray.py

@@ -15,18 +15,19 @@
     The image data is assumed to be in the range of (0, 1).
 
     Args:
-        image: grayscale image to be converted to RGB with shape :math:`(*,1,H,W)`.
+        image: grayscale image tensor to be converted to RGB with shape :math:`(*,1,H,W)`.
 
     Returns:
         RGB version of the image with shape :math:`(*,3,H,W)`.
 
     Example:
+        >>> import torch
         >>> input = torch.randn(2, 1, 4, 5)
         >>> gray = grayscale_to_rgb(input) # 2x3x4x5
     """
     KORNIA_CHECK_IS_TENSOR(image)
 
-    if image.dim() < 3 or image.size(-3) != 1:
+    if len(image.shape) < 3 or image.shape[-3] != 1:
         raise ValueError(f"Input size must have a shape of (*, 1, H, W). " f"Got {image.shape}.")
 
     return concatenate([image, image, image], -3)
@@ -51,6 +52,7 @@
        color_conversions.html>`__.
 
     Example:
+        >>> import torch
         >>> input = torch.rand(2, 3, 4, 5)
         >>> gray = rgb_to_grayscale(input) # 2x1x4x5
     """
@@ -81,7 +83,7 @@
     return w_r * r + w_g * g + w_b * b
 
 
-def bgr_to_grayscale(image: torch.Tensor) -> torch.Tensor:
+def bgr_to_grayscale(image: Tensor) -> Tensor:
     r"""Convert a BGR image to grayscale.
 
     The image data is assumed to be in the range of (0, 1). First flips to RGB, then converts.
@@ -93,6 +95,7 @@
         grayscale version of the image with shape :math:`(*,1,H,W)`.
 
     Example:
+        >>> import torch
         >>> input = torch.rand(2, 3, 4, 5)
         >>> gray = bgr_to_grayscale(input) # 2x1x4x5
     """
@@ -118,6 +121,7 @@
         https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html
 
     Example:
+        >>> import torch
         >>> input = torch.rand(2, 1, 4, 5)
         >>> rgb = GrayscaleToRgb()
         >>> output = rgb(input)  # 2x3x4x5
@@ -140,13 +144,16 @@
         https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html
 
     Example:
+        >>> import torch
         >>> input = torch.rand(2, 3, 4, 5)
         >>> gray = RgbToGrayscale()
         >>> output = gray(input)  # 2x1x4x5
     """
 
     def __init__(self, rgb_weights: Optional[Tensor] = None) -> None:
         super().__init__()
+        if rgb_weights is None:
+            rgb_weights = Tensor([0.299, 0.587, 0.114])
         self.rgb_weights = rgb_weights
 
     def forward(self, image: Tensor) -> Tensor:
@@ -166,6 +173,7 @@
         https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html
 
     Example:
+        >>> import torch
         >>> input = torch.rand(2, 3, 4, 5)
         >>> gray = BgrToGrayscale()
         >>> output = gray(input)  # 2x1x4x5

kornia/contrib/io.py

@@ -0,0 +1,25 @@
+try:
+    import kornia_rs
+except ImportError:
+    kornia_rs = None
+
+import torch
+
+from kornia.core import Tensor
+
+
+def read_image(path_file: str) -> Tensor:
+    """Read an image file and decode using the Kornia Rust backend.
+
+    Args:
+        path_file: Path to a valid image file.
+
+    Return:
+        Returns an image tensor with shape :math:`(3,H,W)`.
+    """
+    if kornia_rs is None:
+        raise ModuleNotFoundError("The io API is not available: `pip install kornia_rs` in a Linux system.")
+
+    cv_tensor = kornia_rs.read_image_rs(path_file)
+    th_tensor = torch.utils.dlpack.from_dlpack(cv_tensor)  # HxWx3
+    return th_tensor.permute(2, 0, 1)  # CxHxW

kornia/core/_backend.py

@@ -1,8 +1,6 @@
-from typing import Union
+from __future__ import annotations
 
 import torch
-import torch.nn.functional as F
-from torch import device
 
 # classes
 Tensor = torch.Tensor
@@ -15,8 +13,8 @@
 concatenate = torch.cat
 stack = torch.stack
 linspace = torch.linspace
-normalize = F.normalize
-pad = F.pad
+normalize = torch.nn.functional.normalize
+pad = torch.nn.functional.pad
 eye = torch.eye
 zeros = torch.zeros
 zeros_like = torch.zeros_like
@@ -30,5 +28,5 @@
 rand = torch.rand
 
 # type alias
-Device = Union[str, device, None]
-Dtype = Union[torch.dtype, None]
+Device = str | torch.device | None
+Dtype = torch.dtype | None