Commit 2cf3c357 authored by narugo1992's avatar narugo1992
Browse files

dev(narugo): add pydocs

parent e5f5543e

docs/source/api_doc/data/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -15,4 +15,5 @@ imgutils.data 
    decode

    image

    layer

    pad

    url

docs/source/api_doc/data/pad.rst

0 → 100644
+15 −0
Original line number Diff line number Diff line 
imgutils.data.pad

==========================



.. currentmodule:: imgutils.data.pad



.. automodule:: imgutils.data.pad





pad_image_to_size

---------------------------



.. autofunction:: pad_image_to_size

imgutils/data/pad.py

+70 −0
Original line number Diff line number Diff line 
"""

Image padding and resizing utilities.



This module provides functions for padding and resizing images to specified dimensions

while maintaining aspect ratio. It includes utilities for parsing size specifications,

color values, and handling different image modes.

"""



from typing import Union, Tuple, Literal



from PIL import ImageColor, Image
@@ -10,6 +18,17 @@ __all__ = [ 




def _parse_size(size):

    """

    Parse size parameter into a tuple of width and height.



    :param size: Size specification as an integer or tuple of two integers

    :type size: Union[int, Tuple[int, int], list]



    :return: Tuple containing width and height

    :rtype: Tuple[int, int]



    :raises TypeError: If size is not an int or tuple/list of two ints

    """

    if isinstance(size, int):

        return size, size

    elif isinstance(size, (list, tuple)) and len(size) == 2:
@@ -19,6 +38,17 @@ def _parse_size(size): 




def _parse_color_to_rgba(color):

    """

    Convert various color formats to RGBA tuple.



    :param color: Color specification (string, integer, or tuple/list)

    :type color: Union[str, int, Tuple, list]



    :return: RGBA color tuple

    :rtype: Tuple[int, int, int, int]



    :raises TypeError: If color format is not supported

    """

    if isinstance(color, str):

        rgba = ImageColor.getrgb(color) + (255,)

        rgba = tuple([*rgba, *((255,) * (4 - len(rgba)))])
@@ -33,6 +63,19 @@ def _parse_color_to_rgba(color): 




def _parse_color_to_mode(color, mode: Literal['RGB', 'RGBA', 'L', 'LA']):

    """

    Convert color to the specified image mode format.



    :param color: Color specification (string, integer, or tuple/list)

    :type color: Union[str, int, Tuple, list]

    :param mode: Target image mode ('RGB', 'RGBA', 'L', or 'LA')

    :type mode: Literal['RGB', 'RGBA', 'L', 'LA']



    :return: Color value in the specified mode format

    :rtype: Union[int, Tuple[int, int], Tuple[int, int, int], Tuple[int, int, int, int]]



    :raises ValueError: If the specified image mode is not supported

    """

    rgba = _parse_color_to_rgba(color)

    if mode == 'L':

        return int(0.299 * rgba[0] + 0.587 * rgba[1] + 0.114 * rgba[2])
@@ -50,6 +93,33 @@ def _parse_color_to_mode(color, mode: Literal['RGB', 'RGBA', 'L', 'LA']): 
def pad_image_to_size(pic: ImageTyping, size: Union[int, Tuple[int, int]],

                      background_color: Union[str, int, Tuple[int, int, int], Tuple[int, int, int, int]] = 'white',

                      interpolation: int = Image.BILINEAR):

    """

    Resize and pad an image to the specified size while maintaining aspect ratio.



    The function first resizes the image to fit within the target dimensions while

    preserving the aspect ratio, then pads the result with the specified background

    color to reach the exact target size.



    :param pic: Input image (PIL Image, file path, or other supported format)

    :type pic: ImageTyping

    :param size: Target size as an integer or tuple of (width, height)

    :type size: Union[int, Tuple[int, int]]

    :param background_color: Color to use for padding (name, RGB tuple, etc.)

    :type background_color: Union[str, int, Tuple[int, int, int], Tuple[int, int, int, int]]

    :param interpolation: PIL interpolation method for resizing

    :type interpolation: int



    :return: Resized and padded image

    :rtype: PIL.Image.Image



    :example:



    >>> from PIL import Image

    >>> img = Image.new('RGB', (100, 50))

    >>> padded = pad_image_to_size(img, (200, 200), background_color='blue')

    >>> padded.size

    (200, 200)

    """

    pic = load_image(pic, force_background=None, mode=None)

    target_w, target_h = _parse_size(size)

    original_w, original_h = pic.size