yta-image-base 0.0.1__py3-none-any.whl

yta_image_base/converter.py

@@ -0,0 +1,283 @@
+from yta_validation import PythonValidator
+from PIL import Image
+from io import BytesIO
+
+import numpy as np
+import base64
+import cv2
+
+
+class ImageConverter:
+    """
+    Class to encapsulate and simplify the image
+    conversion methods.
+    """
+
+    @staticmethod
+    def numpy_image_to_pil(
+        image: np.ndarray
+    ):
+        """
+        This method checks if the provided 'image' is a numpy array and if its
+        values are in the [0, 255] range or in the [0, 1] (normalized) range.
+        It will raise an Exception if any of those conditions are not
+        satisfied.
+
+        This method will return the image converted into a Pillow image.
+        """
+        validate_numpy_image(image)
+
+        return (
+            # TODO: How do I know if the values are normalized or just [0, 255]
+            # but with values below 1 (?)
+            Image.fromarray((image * 255).astype(np.uint8))
+            if np.all((image >= 0) & (image <= 1)) else
+            Image.fromarray((image).astype(np.uint8))
+        )
+    
+    @staticmethod
+    def numpy_image_to_base64(
+        image: np.ndarray
+    ):
+        """
+        Turns the provided numpy 'image' into a base64 str image.
+        """
+        validate_numpy_image(image)
+
+        buffer = BytesIO()
+        image = ImageConverter.numpy_image_to_pil(image).save(buffer, format = 'PNG')
+        buffer.seek(0)
+        image_bytes = buffer.read()
+
+        image_base64 = base64.b64encode(image_bytes).decode('utf-8')
+        image_base64_str = f'data:image/png;base64,{image_base64}'
+
+        return image_base64_str
+    
+    @staticmethod
+    def numpy_image_to_opencv(
+        image: np.ndarray
+    ):
+        validate_numpy_image(image)
+    
+        # This is also a way:
+        # pil_data = PIL.Image.open('Image.jpg').convert('RGB')
+        # image = numpy.array(pil_data)[:, :, ::-1].copy()
+
+        # I need to know if image is RGB or RGBA
+        return (
+            cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+            if image.ndim == 3 and image.shape[2] == 3 else # RGB
+            cv2.cvtColor(image, cv2.COLOR_RGBA2BGRA)
+            if image.ndim == 2 and image.shape[2] == 4 else # RGBA 
+            None # TODO: Maybe raise an Exception (?)
+        )
+    
+    @staticmethod
+    def pil_image_to_numpy(
+        image: Image.Image
+    ):
+        """
+        Turns the 'image' to a numpy array. The PIL image must be an
+        array produced by the code 'Image.open(image_filename)'.
+        """
+        validate_pillow_image(image)
+
+        # This will return it as RGB if (4, 4, 3) or as RGBA if (4, 4, 4)
+        return np.asarray(image)
+    
+    @staticmethod
+    def pil_image_to_base64(
+        image: Image.Image
+    ):
+        """
+        Turns the 'image' to a base64 image by turning it into a numpy
+        image first. The PIL image must be an array produced by the code
+        'Image.open(image_filename)'.
+        """
+        validate_pillow_image(image)
+
+        return ImageConverter.numpy_image_to_base64(ImageConverter.pil_image_to_numpy(image))
+
+    @staticmethod
+    def pil_image_to_opencv(
+        image: Image.Image
+    ):
+        """
+        Turns the 'image' to a opencv image by turning it into a numpy
+        image first. The PIL image must be an array produced by the code
+        'Image.open(image_filename)'.
+        """
+        validate_pillow_image(image)
+
+        return ImageConverter.numpy_image_to_opencv(ImageConverter.pil_image_to_numpy(image))
+    
+    @staticmethod
+    def base64_image_to_pil(
+        image
+    ):
+        """
+        Turns the 'image' to a PIL Image, to be able
+        to work with, and returns it.
+        """
+        validate_base64_image(image)
+
+        return Image.open(BytesIO(base64.b64decode(image)))
+    
+    @staticmethod
+    def base64_image_to_numpy(
+        image
+    ):
+        """
+        Turns the 'image' to a numpy image (np.ndarray),
+        to be able to work with, and returns it. 
+        """
+        validate_base64_image(image)
+        
+        return ImageConverter.pil_image_to_numpy(ImageConverter.base64_image_to_pil(image))
+    
+    @staticmethod
+    def base64_image_to_opencv(
+        image
+    ):
+        """
+        Turns the 'image' to an opencv image by turning it
+        into a numpy array first.
+        """
+        validate_base64_image(image)
+
+        return ImageConverter.pil_image_to_base64(ImageConverter.base64_image_to_pil)
+
+    @staticmethod
+    def opencv_image_to_numpy(
+        image: np.ndarray
+    ):
+        """
+        Turns the 'image' to an opencv image by turning it
+        into a numpy array first.
+        """
+        validate_opencv_image(image)
+
+        # An opencv image is just a numpy array with a meta param
+
+        # I need to know if image is RGB or RGBA
+        return (
+            cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+            if image.ndim == 3 and image.shape[2] == 3 else # RGB
+            cv2.cvtColor(image, cv2.COLOR_BGRA2RGBA)
+            if image.ndim == 2 and image.shape[2] == 4 else # RGBA
+            None # TODO: Maybe raise an Exception (?)
+        )
+
+    @staticmethod
+    def opencv_image_to_pillow(
+        image: np.ndarray
+    ):
+        """
+        Turns the 'image' to a pillow image by turning it
+        into a numpy array first.
+        """
+        validate_opencv_image(image)
+
+        return ImageConverter.numpy_image_to_pil(ImageConverter.opencv_image_to_numpy(image))
+    
+    @staticmethod
+    def opencv_image_to_base64(
+        image: np.ndarray
+    ):
+        """
+        Turns the 'image' to a base64 image by turning it
+        into a numpy array first.
+        """
+        validate_opencv_image(image)
+
+        return ImageConverter.numpy_image_to_base64(ImageConverter.opencv_image_to_numpy(image))
+    
+    # TODO: Move this below to another file as it is
+    # not a conversion but a checking
+    @staticmethod
+    def is_base64_image(
+        image: str
+    ):
+        """
+        Check if the provided 'image' is a base64 image,
+        the type of images that can be received from a
+        server during a request.
+        """
+        is_valid = False
+
+        if image_can_be_base64(image):
+            base64_string = image.split(';base64,')[1]
+            try:
+                base64.b64decode(base64_string, validate = True)
+                is_valid = True
+            except Exception:
+                pass
+
+        return is_valid
+    
+def validate_numpy_image(image: np.ndarray):
+    """
+    This method checks if the provided 'image' is
+    a numpy array, that the array has 3 or 4
+    elements in each cell and if its values are in the 
+    [0, 255] range or in the [0, 1] (normalized) range.
+    It will raise an Exception if any of those
+    conditions are not satisfied.
+    """
+    if not PythonValidator.is_numpy_array(image):
+        raise Exception('The provided "image" parameter is not a numpy np.ndarray instance.')
+    
+    if image.ndim != 3 or image.shape[2] not in [3, 4]:
+        raise Exception('The provided "image" parameter does not represent a RGB or RGBA image.')
+
+    if not np.all((image >= 0) & (image <= 255)):
+        raise Exception('The provided numpy array is not a valid image as its values are not between 0 and 255.')
+
+    # TODO: What about '.astype('uint8')', maybe we can check if it is that type (?)
+
+def validate_opencv_image(image: np.ndarray):
+    """
+    This method checks if the provided 'image' is a
+    numpy array, that the array has 3 or 4 elements
+    on each cell and if its values are in the [0, 255]
+    range or in the [0, 1] (normalized) range. It will
+    raise an Exception if any of those conditions are
+    not satisfied.
+
+    An opencv image is just a numpy array with some
+    meta param.
+    """
+    # The only thing that could change is the message and I don't want
+    # to duplicate code for a single 'opencv' word in a message
+    return validate_numpy_image(image)
+
+def validate_base64_image(image: str):
+    """
+    This method validates if the provided image is
+    a valid base64 image by getting the prefix, the
+    'base64' str and also trying to decode it. It
+    will raise an Exception if the image is not a
+    valid base64 image.
+    """
+    if not ImageConverter.is_base64_image(image):
+        raise Exception('The provided "image" parameter is not a valid base64 image.')
+
+def validate_pillow_image(image: Image.Image):
+    if not PythonValidator.is_instance(image, Image.Image):
+        raise Exception('The provided "image" is not an instance of a Pillow image.')
+    
+    if image.mode not in ['RGB', 'RGBA']:
+        raise Exception('The provided pillow image is not in a valid mode for our software. Valid modes are: "RGB", "RGBA".')
+
+def image_can_be_base64(image: str):
+    """
+    Check if the provided 'image' can be a base64
+    image.
+    """
+    return (
+        PythonValidator.is_string(image) and
+        image.startswith('data:image/') and
+        ';base64,' in image
+    )
+    

yta_image_base/edition/editor.py

@@ -0,0 +1,376 @@
+"""
+Image edition module.
+
+Interesting links below:
+- https://www.geeksforgeeks.org/image-enhancement-techniques-using-opencv-python/
+- https://www.geeksforgeeks.org/changing-the-contrast-and-brightness-of-an-image-using-python-opencv/
+
+TODO: Change the methods inside and make the 
+ones wrapped into a class contain the limit
+validations.
+
+TODO: Make the internal 'non-wrapped' methods
+to work with the expected parameter 'np.ndarray'
+and not to validate them or to parse, that 
+should be done by the wrapped methods.
+"""
+from yta_image_base.edition.settings import COLOR_TEMPERATURE_CHANGE_LIMIT, COLOR_HUE_CHANGE_LIMIT, CONTRAST_LIMIT, SHARPNESS_LIMIT, BRIGHTNESS_LIMIT
+from yta_image_base.parser import ImageParser
+from yta_validation.number import NumberValidator
+from yta_file.handler import FileHandler
+from yta_constants.enum import YTAEnum as Enum
+from PIL import Image, ImageEnhance
+from pillow_lut import load_cube_file
+from typing import Union
+
+import cv2
+import numpy as np
+import colorsys
+
+
+class LutTable(Enum):
+    """
+    Image LUT tables definition to be able to handle them
+    and apply to images to modify those images.
+
+    You create a table in which you set the new values
+    for all the 256 pixels so the previous 0 will be
+    other number (or maybe 0 in that case).
+    """
+
+    INVERSE = 'inverse'
+    SQUARE_ROOT = 'square_root'
+    CUBE = 'cube'
+
+    def get_lut_table(
+        self
+    ):
+        """
+        Obtain the LUT table array, which is a 2D table with 256
+        indexes containing the pixel color in which the original
+        color must be converted.
+        """
+        functions = {
+            LutTable.INVERSE: lambda pixel: 255 - pixel,
+            LutTable.SQUARE_ROOT: lambda pixel: (pixel * 255) ** (1 / 2),
+            LutTable.CUBE: lambda pixel: (pixel ** 3) / (255 ** 2)
+        }
+
+        return np.array([
+            functions[self](i)
+            for i in range(256)
+        ], dtype = np.uint8)
+        
+    def apply_to_image(
+        self,
+        image: any
+    ) -> np.ndarray:
+        """
+        Apply the lut table to the provided image.
+
+        Result is a numpy array in RGB format.
+        """
+        # We obtain a result in GBR format and we transform
+        # it into an RGB
+        return cv2.LUT(ImageParser.to_opencv(image), self.get_lut_table())[:, :, ::-1]
+    
+class ImageEditor:
+    """
+    Class to simplify and encapsulate all the functionality
+    related to image edition.
+    """
+    
+    @staticmethod
+    def modify_color_temperature(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_color_temperature(image, factor)
+
+    @staticmethod
+    def modify_color_hue(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_color_hue(image, factor)
+    
+    @staticmethod
+    def modify_brightness(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_brightness(image, factor)
+
+    @staticmethod
+    def modify_contrast(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_contrast(image, factor)
+    
+    @staticmethod
+    def modify_sharpness(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_sharpness(image, factor)
+    
+    @staticmethod
+    def modify_white_balance(
+        image: Union[str, Image.Image, np.ndarray],
+        factor: int = 0
+    ):
+        # TODO: Apply the limit validation here
+        return change_image_white_balance(image, factor)
+    
+    @staticmethod
+    def apply_lut(
+        image: Union[str, Image.Image, np.ndarray],
+        lut_table: LutTable
+    ):
+        """
+        Apply the 2D Lut table provided in the 'lut_table'
+        parameter to the also given 'image'.
+
+        Thanks to:
+        - https://gist.github.com/blroot/b22abc23526af2711d92cc3b3f13b907
+        """
+        lut_table = LutTable.to_enum(lut_table)
+
+        return lut_table.apply_to_image(image)
+    
+    @staticmethod
+    def apply_3d_lut(
+        image: Union[str, Image.Image, np.ndarray],
+        lut_3d_filename: str
+    ):
+        """
+        Apply a 3D Lut table, which is loaded from the
+        provided 'lut_3d_filename' .cube file, to the
+        also given 'image'.
+
+        Thanks to:
+        - https://stackoverflow.com/questions/73341263/apply-3d-luts-cube-files-into-an-image-using-python
+        """
+        if not FileHandler.is_file(lut_3d_filename):
+            raise Exception('The "lut_3d_filename" provided is not a valid file.')
+        # TODO: Improve the validation to check that is .cube
+        
+        return ImageParser.to_pillow(image).filter(load_cube_file(lut_3d_filename))
+
+def change_image_color_temperature(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    Change the 'image' color temperature by the
+    provided 'factor', that must be a value between
+    [-50, 50].
+
+    The color change consist of updating the red and
+    blue values, where red is calid and blue is cold.
+    Increasing the temperature means increasing the
+    red color, and decreasing it, decreasing the blue
+    color.
+    """
+    if not NumberValidator.is_number_between(factor, COLOR_TEMPERATURE_CHANGE_LIMIT[0], COLOR_TEMPERATURE_CHANGE_LIMIT[1]):
+        raise Exception(f'The "factor" parameter provided is not a number between [{COLOR_TEMPERATURE_CHANGE_LIMIT[0]}, {COLOR_TEMPERATURE_CHANGE_LIMIT[1]}].')
+    
+    # The '.copy()' makes it writeable
+    image = ImageParser.to_numpy(image).copy()
+
+    if factor == 0:
+        return image
+
+    # We want the factor being actually a value between 0.50 and 1.50,
+    # but multiplying by 1.5 is equal to divide by 0.75 so I need to
+    # manually do this calculation to apply the formula correctly
+    factor = (
+        1 - (0.25 - normalize(factor, COLOR_TEMPERATURE_CHANGE_LIMIT[0], 0, 0, 0.25))
+        if factor < 0 else
+        1 + normalize(factor, 0, COLOR_TEMPERATURE_CHANGE_LIMIT[1], 0, 0.5)
+    )
+    
+    r, b = image[:, :, 0], image[:, :, 2]
+    
+    # Min and max values are 0 and 255
+    r = np.clip(r * factor, 0, 255)
+    b = np.clip(b / factor, 0, 255)
+    
+    # Reconstruimos la imagen con los canales modificados
+    image[:, :, 0] = r
+    image[:, :, 2] = b
+
+    return image
+
+# These below are 2 functions to convert
+# TODO: Please, move these functions to a method
+# maybe in 'yta_general_utils' or in 'yta_multimedia'
+rgb_to_hsv = np.vectorize(colorsys.rgb_to_hsv)
+hsv_to_rgb = np.vectorize(colorsys.hsv_to_rgb)
+
+def change_image_color_hue(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    Change the 'image' color hue by the provided
+    'factor', that must be a value between [-50, 50].
+
+    Colorize PIL image `original` with the given
+    `factor` (hue within 0-360); returns another PIL image.
+    """
+    # TODO: This method is not working
+    if not NumberValidator.is_number_between(factor, COLOR_HUE_CHANGE_LIMIT[0], COLOR_HUE_CHANGE_LIMIT[1]):
+        raise Exception(f'The "factor" parameter provided is not a number between [{COLOR_HUE_CHANGE_LIMIT[0]}, {COLOR_HUE_CHANGE_LIMIT[1]}].')
+    
+    # The '.copy()' makes it writeable
+    image = ImageParser.to_numpy(image).copy()
+
+    factor = normalize(factor, COLOR_HUE_CHANGE_LIMIT[0], COLOR_HUE_CHANGE_LIMIT[1], 0, 360)
+    
+    # TODO: This code is not working well
+    # TODO: This method is very very slow
+    #arr = np.array(np.asarray(img).astype('float'))
+    #r, g, b, a = np.rollaxis(image, axis = -1)
+    print(image.size) # size is 6220800
+    r, g, b = np.rollaxis(image, axis = -1)
+    #r, g, b = np.moveaxis(image, -1, 0)
+    h, s, v = rgb_to_hsv(r, g, b)
+    h = factor / 360.0
+    r, g, b = hsv_to_rgb(h, s, v)
+    #arr = np.dstack((r, g, b, a))
+    arr = np.dstack((r, g, b)).astype(np.uint8)
+    print(arr.size) # size is 220800
+    print(arr)
+
+    # TODO: I don't like this line below
+    return arr
+    return Image.fromarray(arr.astype('uint8'), 'RGBA')
+
+def change_image_brightness(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    Change the 'image' brightness by the provided
+    'factor', that must be a value between [-100, 100].
+    """
+    image = ImageParser.to_pillow(image).copy()
+
+    # TODO: Check factor is between the limit
+    if not NumberValidator.is_number_between(factor, BRIGHTNESS_LIMIT[0], BRIGHTNESS_LIMIT[1]):
+        raise Exception(f'The provided factor must be a number between [{BRIGHTNESS_LIMIT[0]}, {BRIGHTNESS_LIMIT[1]}].')
+
+    # factor from -100 to 0 must be from 0.5 to 1
+    # factor from 0 to 100 must be from 1 to 2
+    factor = normalize(factor, BRIGHTNESS_LIMIT[0], 0, 0.5, 1.0) if factor <= 0 else normalize(factor, 0, BRIGHTNESS_LIMIT[1], 1.0, 2.0)
+
+    image = ImageEnhance.Brightness(image).enhance(factor)
+
+    return ImageParser.to_numpy(image)
+
+def change_image_contrast(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    Change the 'image' contrast by the provided
+    'factor', that must be a value between [-100, 100].
+    """
+    image = ImageParser.to_pillow(image).copy()
+
+    # TODO: Check factor is between the limit
+    if not NumberValidator.is_number_between(factor, CONTRAST_LIMIT[0], CONTRAST_LIMIT[1]):
+        raise Exception(f'The provided factor must be a number between [{CONTRAST_LIMIT[0]}, {CONTRAST_LIMIT[1]}].')
+
+    # factor from -100 to 0 must be from 0.5 to 1
+    # factor from 0 to 100 must be from 1 to 2
+    factor = normalize(factor, CONTRAST_LIMIT[0], 0, 0.5, 1.0) if factor <= 0 else normalize(factor, 0, CONTRAST_LIMIT[1], 1.0, 2.0)
+
+    image = ImageEnhance.Contrast(image).enhance(factor)
+
+    return ImageParser.to_numpy(image)
+
+def change_image_sharpness(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    Change the 'image' sharpness by the provided
+    'factor', that must be a value between [-100, 100].
+
+    A factor of -100 gives you a blurred image while
+    a factor of 100 gives you a sharped image.
+    """
+    image = ImageParser.to_pillow(image).copy()
+
+    # TODO: Check factor is between the limit
+    if not NumberValidator.is_number_between(factor, SHARPNESS_LIMIT[0], SHARPNESS_LIMIT[1]):
+        raise Exception(f'The provided factor must be a number between [{SHARPNESS_LIMIT[0]}, {SHARPNESS_LIMIT[1]}].')
+
+    
+    # factor from -100 to 0 must be from 0.5 to 1
+    # factor from 0 to 100 must be from 1 to 2
+    factor = normalize(factor, SHARPNESS_LIMIT[0], 0, 0.0, 1.0) if factor <= 0 else normalize(factor, 0, SHARPNESS_LIMIT[1], 1.0, 2.0)
+
+    image = ImageEnhance.Sharpness(image).enhance(factor)
+
+    return ImageParser.to_numpy(image)
+
+def change_image_white_balance(
+    image: any,
+    factor: int = 0
+) -> np.ndarray:
+    """
+    TODO: Explain
+    
+    The result is in RGB format.
+    """
+    # TODO: I'm not using the 'factor'
+    # TODO: I have a factor limit setting for this
+    
+    # TODO: Apply factor -> 0.0 means no change
+    image = ImageParser.to_opencv(image)
+    image = cv2.cvtColor(image, cv2.COLOR_BGR2LAB)
+    # Average of green channel
+    avg_a = np.average(image[:, :, 1])
+    # Average of red channel
+    avg_b = np.average(image[:, :, 2])
+    image[:, :, 1] = image[:, :, 1] - ((avg_a - 128) * (image[:, :, 0] / 255.0) * 1.2)
+    image[:, :, 2] = image[:, :, 2] - ((avg_b - 128) * (image[:, :, 0] / 255.0) * 1.2)
+
+    balanced_image = cv2.cvtColor(image, cv2.COLOR_LAB2RGB)
+
+    return balanced_image
+
+# TODO: I have a new ValueNormalizer class to handle normalization
+# so this has to be avoided and use that general function instead
+def normalize(
+    number: float,
+    input_lower_limit: float,
+    input_upper_limit: float,
+    output_lower_limit: float = 0.0,
+    output_upper_limit: float = 1.0
+):
+    """
+    Normalize the 'number' value to be between 'output_lower_limit'
+    and 'output_upper_limit', according to the input provided, that
+    is between the 'input_lower_limit' and 'input_upper_limit' 
+    values.
+    """
+    if not NumberValidator.is_number(number) or not NumberValidator.is_number(input_lower_limit) or not NumberValidator.is_number(input_upper_limit) or not NumberValidator.is_number(output_lower_limit) or not NumberValidator.is_number(output_upper_limit):
+        raise Exception('All the parameters must be numbers.')
+
+    if not NumberValidator.is_number_between(number, input_lower_limit, input_upper_limit):
+        raise Exception('The "number" parameter provided is not a number between the input limits provided.')
+    
+    if input_upper_limit <= input_lower_limit or output_upper_limit <= output_lower_limit:
+        raise Exception('The upper limit must be greater than the lower limit.')
+    
+    return (number - input_lower_limit) / (input_upper_limit - input_lower_limit) * (output_upper_limit - output_lower_limit) + output_lower_limit

yta_image_base/edition/settings.py

@@ -0,0 +1,16 @@
+"""
+These settings are used by the ImageEditor. Maybe this file must
+be renamed or moved to another path, but I keep this settings 
+here because I need them in another file and to avoid cyclic
+import issues.
+
+TODO: Are this limits real? I mean, is there any limit to change
+the temperature of an image or is this invented (?)
+"""
+COLOR_TEMPERATURE_CHANGE_LIMIT = (-50, 50)
+COLOR_HUE_CHANGE_LIMIT = (-50, 50)
+BRIGHTNESS_LIMIT = (-100, 100)
+CONTRAST_LIMIT = (-100, 100)
+SHARPNESS_LIMIT = (-100, 100)
+WHITE_BALANCE_LIMIT = (-100, 100)
+SPEED_FACTOR_LIMIT = (0.1, 10)