helios.data.functional
======================

.. py:module:: helios.data.functional


Functions
---------

.. autoapisummary::

   helios.data.functional.load_image
   helios.data.functional.load_image_pil
   helios.data.functional.tensor_to_numpy
   helios.data.functional.show_tensor
   helios.data.functional.show_tensors
   helios.data.functional.convert_to_hwc
   helios.data.functional.to_y_channel
   helios.data.functional.bgr2ycbcr
   helios.data.functional.rgb2ycbcr_torch


Module Contents
---------------

.. py:function:: load_image(path: pathlib.Path, flags: int = cv2.IMREAD_COLOR, as_rgb: bool = True) -> numpy.typing.NDArray

   Load the given image using OpenCV.

   ``flags`` correspond to the ``cv2.IMREAD_`` flags from OpenCV. Please see the full
   list of options
   `here <https://docs.opencv.org/3.4/d8/d6a/group__imgcodecs__flags.html>`__. If no
   value is passed, the image will be loaded using ``cv2.IMREAD_COLOR``, which will load
   it as an 8-bit BGR image.

   ``as_rgb`` can be used to automatically convert the image from OpenCV's default BGR to
   RGB using the following logic:
   * If the image is grayscale, then it is returned as is.
   * If the image is a 3-channel BGR, it is converted to RGB.
   * If the image is a 4-channel BGRA, it is converted to RGBA.
   If all these checks fail, the image is returned as is.

   :param path: the path to the image to load.
   :param flags: the OpenCV flags to use when loading.
   :param as_rgb: if true, the image will be converted from BGR/BGRA to RGB/RGBA, otherwise
                  the image is returned as is.

   :returns: The loaded image.


.. py:function:: load_image_pil(path: pathlib.Path, out_fmt: str = '', as_numpy: bool = True) -> numpy.typing.NDArray | PIL.Image.Image

   Load the given image using PIL.

   ``out_fmt`` is a format string that can be passed in to PIL.Image.convert. Please
   `here <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.convert>`__
   for the list of accepted strings.
   If no string is passed, the image will be converted to RGB format.
   By default, the output is a NumPY array. If you need a PIL image instead, set
   ``as_numpy`` to false.

   :param path: the path to the image to load.
   :param out_fmt: the format to convert the loaded image to. Defaults to empty.
   :param as_numpy: if true, the loaded image will be returned as a NumPY array, otherwise
                    it is returned as a PIL image. Defaults to true.

   :returns: The loaded image.


.. py:function:: tensor_to_numpy(x: torch.Tensor, squeeze: bool = True, clamp: tuple[float, float] | None = (0, 1), transpose: bool = True, dtype: torch.dtype | None = torch.float, as_uint8: bool = True) -> numpy.typing.NDArray

   Convert the given tensor to a numpy array.

   :param x: the tensor to convert.
   :param squeeze: if true, squeeze to remove all dimensions of size 1. Defaults to true.
   :param clamp: tuple containing min/max values to clamp the tensor to. Can be ``None`` if
                 no clamping is desired. Defaults to ``(0, 1)``.
   :param transpose: if true, transpose the tensor so the dimensions are :math:`H \times W
                     \times C` or :math:`B \times H \times W \times C`. Defaults to true.
   :param dtype: the type to convert the tensor to. Can be set to ``None`` if no conversion
                 is desired. Defaults to ``torch.float``.
   :param as_uint8: if true, convert the final array to be of type uint8 and in the range
                    :math:`[0, 255]`. Defaults to true.

   :returns: The converted array.


.. py:function:: show_tensor(tens: torch.Tensor, title: str = 'debug window') -> None

   Display the image held by the tensor. Useful for debugging purposes.

   :param tens: the image tensor to display in range :math:`[0, 1]`.
   :param title: the title of the displayed window. Defaults to "debug window".


.. py:function:: show_tensors(tens: torch.Tensor) -> None

   Show batches of tensors.

   :param tens: the batch of tensors to display in range :math:`[0, 1]`.


.. py:function:: convert_to_hwc(img: numpy.typing.NDArray, input_order: str = 'HWC') -> numpy.typing.NDArray

   Change the order of the input image channels so the result is in (h, w, c) order.

   If the input image is a single-channel image, then the return is (h, w, 1).

   :param img: input image.
   :param input_order: the order of the channels of the input image. Must be one of 'HWC'
                       or 'CHW'.

   :returns: The shuffled image.


.. py:function:: to_y_channel(img: numpy.typing.NDArray) -> numpy.typing.NDArray

   Return the Y (luma) channel of a YCbCr image.

   :param img: input image in YCbCr format. Must be in the range :math:`[0, 255]`.

   :returns: The luma channel of the input image.


.. py:function:: bgr2ycbcr(img: numpy.typing.NDArray, only_y: bool = False) -> numpy.typing.NDArray

   Convert the given numpy image array from BGR to YCBCR.

   If only the Y channel is required, set ``only_y`` to true.

   :param img: the BGR image to convert.
   :param only_y: if true, only the luma (Y) channel will be returned.

   :returns: The converted image.


.. py:function:: rgb2ycbcr_torch(img: torch.Tensor, only_y: bool = False) -> torch.Tensor

   Convert the given torch Tensor image array from RGB to YCBCR.

   If only the Y channel is required, set ``only_y`` to true.

   :param img: the BGR image to convert.
   :param only_y: if true, only the luma (Y) channel will be returned.

   :returns: The converted image.