sharpedge.frame_image
=====================

.. py:module:: sharpedge.frame_image


Functions
---------

.. autoapisummary::

   sharpedge.frame_image._format_conversion
   sharpedge.frame_image._image_resize
   sharpedge.frame_image._color_padding
   sharpedge.frame_image.frame_image


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

.. py:function:: _format_conversion(img, color)

   Private function to be invoked by frame_image().

   Convert grayscale image to RGB if necessary, and ensure color format is valid.

   This function checks if the image is grayscale and converts it to RGB if needed.
   It also validates and converts the color input for the border to RGB format.

   :param img: The input image as a 2D numpy array (grayscale) or 3D numpy array (RGB).
   :type img: ndarray
   :param color: The color of the border. Can be:
                 - A single value for grayscale frames (e.g., 0 for black, 255 for white).
                 - A tuple of 3 values for RGB frames (e.g., (0, 0, 0) for black).
   :type color: int or tuple of int

   :returns: * **img** (*ndarray*) -- The image in RGB format (3D array).
             * **color** (*tuple of int*) -- The color for the border in RGB format (3 integers).

   :raises ValueError: If the color is not in the correct format (for RGB or grayscale).
   :raises TypeError: If the color is not of the correct type (integer for grayscale, tuple/list for RGB).


.. py:function:: _image_resize(img, h_border, w_border, inside)

   Private function to be invoked by frame_image().

   Resize the image by adding borders either inside or outside.

   This function handles resizing the image, ensuring that if borders are added inside,
   the image size is reduced, and if borders are added outside, the image size increases.

   :param img: The input image array (either 2D or 3D).
   :type img: ndarray
   :param h_border: The height of the border in pixels.
   :type h_border: int
   :param w_border: The width of the border in pixels.
   :type w_border: int
   :param inside: If True, the border is added **inside** the image (maintaining the image size).
                  If False, the border is added **outside** the image (increasing the image size).
   :type inside: bool

   :returns: **img** -- The resized image, with borders applied.
   :rtype: ndarray

   :raises ValueError: If the inside border is too large for the image dimensions.
       If the `h_border` or `w_border` is negative or invalid.
   :raises TypeError: If the `h_border` or `w_border` is not an integer.


.. py:function:: _color_padding(img, h_border, w_border, color)

   Private function to be invoked by frame_image().

   Apply color padding by adding a border around the image.

   This function adds a border of the specified color around the image, either inside
   or outside the image.

   :param img: The input image array (3D array with 3 color channels).
   :type img: ndarray
   :param h_border: The height of the border in pixels.
   :type h_border: int
   :param w_border: The width of the border in pixels.
   :type w_border: int
   :param color: The RGB color for the border.
   :type color: tuple of int

   :returns: **frame** -- The image with the color border applied.
   :rtype: ndarray


.. py:function:: frame_image(img, h_border=20, w_border=20, inside=False, color=0)

   Add a decorative frame around the image with a customizable color.

   This function adds a border around the input image, either inside the image
   (preserving its original size) or outside (increasing its size). The border
   color can be specified for both grayscale and RGB images.

   :param img: The input image as a 2D numpy array (grayscale) or 3D numpy array (RGB).
   :type img: ndarray
   :param h_border: The height of the border in pixels. Default is 20.
   :type h_border: int, optional
   :param w_border: The width of the border in pixels. Default is 20.
   :type w_border: int, optional
   :param inside: If True, the border is added **inside** the image (maintaining the image size).
                  If False, the border is added **outside** the image (increasing the image size).
                  Default is False.
   :type inside: bool, optional
   :param color: The color of the border. Can be:
                 - A single value for grayscale frames (e.g., 0 for black, 255 for white).
                 - A tuple of 3 values for RGB frames (e.g., (0, 0, 0) for black).
                 Default is 0 (black) for grayscale frames.
   :type color: int or tuple of int, optional

   :returns: The framed image with the applied border.
   :rtype: ndarray

   .. rubric:: Examples

   >>> img = np.random.rand(100, 100)
   >>> framed_img = frame_image(img, h_border=30, w_border=30, inside=True, color=255)
   >>> framed_img_rgb = frame_image(img_rgb, h_border=20, w_border=20, inside=False, color=(255, 0, 0))