mapchete-eo 2025.8.2__py2.py3-none-any.whl → 2025.8.3__py2.py3-none-any.whl

mapchete_eo/__init__.py

@@ -1 +1 @@
-__version__ = "2025.8.2"
+__version__ = "2025.8.3"

mapchete_eo/image_operations/blend_functions.py

@@ -0,0 +1,579 @@
+"""
+
+Original LICENSE:
+
+MIT License
+
+Copyright (c) 2016 Florian Roscheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation th
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+
+"""
+
+import numpy as np
+
+
+def _compose_alpha(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Calculate alpha composition ratio between two images."""
+
+    comp_alpha = np.minimum(fg[:, :, 3], bg[:, :, 3]) * opacity
+    new_alpha = fg[:, :, 3] + (1.0 - fg[:, :, 3]) * comp_alpha
+    np.seterr(divide="ignore", invalid="ignore")
+    ratio = comp_alpha / new_alpha
+    ratio[np.isnan(ratio)] = 0.0
+    return ratio
+
+
+def normal(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply "normal" blending mode of a layer on an image.
+
+    See Also:
+        Find more information on `Wikipedia <https://en.wikipedia.org/wiki/Alpha_compositing#Description>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+    """
+
+    # Extract alpha-channels and apply opacity
+    fg_alp = np.expand_dims(fg[:, :, 3], 2)  # alpha of b, prepared for broadcasting
+    bg_alp = (
+        np.expand_dims(bg[:, :, 3], 2) * opacity
+    )  # alpha of a, prepared for broadcasting
+
+    # Blend images
+    with np.errstate(divide="ignore", invalid="ignore"):
+        img_out = (bg[:, :, :3] * bg_alp + fg[:, :, :3] * fg_alp * (1 - bg_alp)) / (
+            bg_alp + fg_alp * (1 - bg_alp)
+        )
+        img_out[np.isnan(img_out)] = 0  # replace NaNs with 0
+
+    # Blend alpha
+    cout_alp = bg_alp + fg_alp * (1 - bg_alp)
+
+    # Combine image and alpha
+    img_out = np.dstack((img_out, cout_alp))
+
+    np.nan_to_num(img_out, copy=False)
+
+    return img_out
+
+
+def soft_light(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply soft light blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Soft_Light>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    # The following code does this:
+    #   multiply = fg[:, :, :3]*bg[:, :, :3]
+    #   screen = 1.0 - (1.0-fg[:, :, :3])*(1.0-bg[:, :, :3])
+    #   comp = (1.0 - fg[:, :, :3]) * multiply + fg[:, :, :3] * screen
+    #   ratio_rs = np.reshape(np.repeat(ratio,3),comp.shape)
+    #   img_out = comp*ratio_rs + fg[:, :, :3] * (1.0-ratio_rs)
+
+    comp = (1.0 - fg[:, :, :3]) * fg[:, :, :3] * bg[:, :, :3] + fg[:, :, :3] * (
+        1.0 - (1.0 - fg[:, :, :3]) * (1.0 - bg[:, :, :3])
+    )
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def lighten_only(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply lighten only blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Lighten_Only>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.maximum(fg[:, :, :3], bg[:, :, :3])
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def screen(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply screen blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Screen>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = 1.0 - (1.0 - fg[:, :, :3]) * (1.0 - bg[:, :, :3])
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def dodge(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply dodge blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Dodge_and_burn>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.minimum(fg[:, :, :3] / (1.0 - bg[:, :, :3]), 1.0)
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def addition(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply addition blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Addition>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = fg[:, :, :3] + bg[:, :, :3]
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = np.clip(comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs), 0.0, 1.0)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def darken_only(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply darken only blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Darken_Only>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.minimum(fg[:, :, :3], bg[:, :, :3])
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def multiply(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply multiply blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Multiply>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.clip(bg[:, :, :3] * fg[:, :, :3], 0.0, 1.0)
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def hard_light(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply hard light blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Hard_Light>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.greater(bg[:, :, :3], 0.5) * np.minimum(
+        1.0 - ((1.0 - fg[:, :, :3]) * (1.0 - (bg[:, :, :3] - 0.5) * 2.0)),
+        1.0,
+    ) + np.logical_not(np.greater(bg[:, :, :3], 0.5)) * np.minimum(
+        fg[:, :, :3] * (bg[:, :, :3] * 2.0), 1.0
+    )
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def difference(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply difference blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Difference>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = fg[:, :, :3] - bg[:, :, :3]
+    comp[comp < 0.0] *= -1.0
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def subtract(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply subtract blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Subtract>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = fg[:, :, :3] - bg[:, :, :3]
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = np.clip(comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs), 0.0, 1.0)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def grain_extract(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply grain extract blending mode of a layer on an image.
+
+    See Also:
+        Find more information in the `GIMP Documentation <https://docs.gimp.org/en/gimp-concepts-layer-modes.html>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.clip(fg[:, :, :3] - bg[:, :, :3] + 0.5, 0.0, 1.0)
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def grain_merge(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply grain merge blending mode of a layer on an image.
+
+    See Also:
+        Find more information in the `GIMP Documentation <https://docs.gimp.org/en/gimp-concepts-layer-modes.html>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.clip(fg[:, :, :3] + bg[:, :, :3] - 0.5, 0.0, 1.0)
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def divide(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply divide blending mode of a layer on an image.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=747749280#Divide>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.minimum(
+        (256.0 / 255.0 * fg[:, :, :3]) / (1.0 / 255.0 + bg[:, :, :3]),
+        1.0,
+    )
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out
+
+
+def overlay(fg: np.ndarray, bg: np.ndarray, opacity: float):
+    """Apply overlay blending mode of a layer on an image.
+
+    Note:
+        The implementation of this method was changed in version 2.0.0. Previously, it would be identical to the
+        soft light blending mode. Now, it resembles the implementation on Wikipedia. You can still use the soft light
+        blending mode if you are looking for backwards compatibility.
+
+    See Also:
+        Find more information on
+        `Wikipedia <https://en.wikipedia.org/w/index.php?title=Blend_modes&oldid=868545948#Overlay>`__.
+
+    Args:
+      fg(3-dimensional numpy array of floats (r/g/b/a) in range 0-255.0): Image to be blended upon
+      bg(3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0): Layer to be blended with image
+      opacity(float): Desired opacity of layer for blending
+      disable_type_checks(bool): Whether type checks within the function should be disabled. Disabling the checks may
+        yield a slight performance improvement, but comes at the cost of user experience. If you are certain that
+        you are passing in the right arguments, you may set this argument to 'True'. Defaults to 'False'.
+
+    Returns:
+      3-dimensional numpy array of floats (r/g/b/a) in range 0.0-255.0: Blended image
+
+    """
+
+    ratio = _compose_alpha(fg, bg, opacity)
+
+    comp = np.less(fg[:, :, :3], 0.5) * (
+        2 * fg[:, :, :3] * bg[:, :, :3]
+    ) + np.greater_equal(fg[:, :, :3], 0.5) * (
+        1 - (2 * (1 - fg[:, :, :3]) * (1 - bg[:, :, :3]))
+    )
+
+    ratio_rs = np.reshape(
+        np.repeat(ratio, 3), [comp.shape[0], comp.shape[1], comp.shape[2]]
+    )
+    img_out = comp * ratio_rs + fg[:, :, :3] * (1.0 - ratio_rs)
+    img_out = np.nan_to_num(
+        np.dstack((img_out, fg[:, :, 3]))
+    )  # add alpha channel and replace nans
+    return img_out

mapchete_eo/image_operations/compositing.py

@@ -8,7 +8,7 @@ import numpy.ma as ma
 from mapchete import Timer
 from rasterio.plot import reshape_as_image, reshape_as_raster
 
-from mapchete_eo.image_operations.blend_modes import blending_functions
+from mapchete_eo.image_operations import blend_functions
 
 
 logger = logging.getLogger(__name__)
@@ -55,14 +55,16 @@ def to_rgba(arr: np.ndarray) -> np.ndarray:
 def _blend_base(
     bg: np.ndarray, fg: np.ndarray, opacity: float, operation: Callable
 ) -> ma.MaskedArray:
-    # generate RGBA output and run compositing
+    # generate RGBA output and run compositing and normalize by dividing by 255
     out_arr = reshape_as_raster(
-        operation(
-            reshape_as_image(to_rgba(bg)),
-            reshape_as_image(to_rgba(fg)),
-            opacity,
-            disable_type_checks=True,
-        ).astype(np.uint8)
+        (
+            operation(
+                reshape_as_image(to_rgba(bg) / 255),
+                reshape_as_image(to_rgba(fg) / 255),
+                opacity,
+            )
+            * 255
+        ).astype(np.uint8, copy=False)
     )
     # generate mask from alpha band
     out_mask = np.where(out_arr[3] == 0, True, False)
@@ -70,63 +72,63 @@ def _blend_base(
 
 
 def normal(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.normal)
+    return _blend_base(bg, fg, opacity, blend_functions.normal)
 
 
 def soft_light(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.soft_light)
+    return _blend_base(bg, fg, opacity, blend_functions.soft_light)
 
 
 def lighten_only(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.lighten_only)
+    return _blend_base(bg, fg, opacity, blend_functions.lighten_only)
 
 
 def screen(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.screen)
+    return _blend_base(bg, fg, opacity, blend_functions.screen)
 
 
 def dodge(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.dodge)
+    return _blend_base(bg, fg, opacity, blend_functions.dodge)
 
 
 def addition(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.addition)
+    return _blend_base(bg, fg, opacity, blend_functions.addition)
 
 
 def darken_only(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.darken_only)
+    return _blend_base(bg, fg, opacity, blend_functions.darken_only)
 
 
 def multiply(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.multiply)
+    return _blend_base(bg, fg, opacity, blend_functions.multiply)
 
 
 def hard_light(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.hard_light)
+    return _blend_base(bg, fg, opacity, blend_functions.hard_light)
 
 
 def difference(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.difference)
+    return _blend_base(bg, fg, opacity, blend_functions.difference)
 
 
 def subtract(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.subtract)
+    return _blend_base(bg, fg, opacity, blend_functions.subtract)
 
 
 def grain_extract(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.grain_extract)
+    return _blend_base(bg, fg, opacity, blend_functions.grain_extract)
 
 
 def grain_merge(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.grain_merge)
+    return _blend_base(bg, fg, opacity, blend_functions.grain_merge)
 
 
 def divide(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.divide)
+    return _blend_base(bg, fg, opacity, blend_functions.divide)
 
 
 def overlay(bg: np.ndarray, fg: np.ndarray, opacity: float = 1) -> ma.MaskedArray:
-    return _blend_base(bg, fg, opacity, blending_functions.overlay)
+    return _blend_base(bg, fg, opacity, blend_functions.overlay)
 
 
 METHODS = {
@@ -212,11 +214,14 @@ def fuzzy_alpha_mask(
     gradient_position=GradientPosition.outside,
 ) -> np.ndarray:
     """Return an RGBA array with a fuzzy alpha mask."""
-    gradient_position = (
-        GradientPosition[gradient_position]
-        if isinstance(gradient_position, str)
-        else gradient_position
-    )
+    try:
+        gradient_position = (
+            GradientPosition[gradient_position]
+            if isinstance(gradient_position, str)
+            else gradient_position
+        )
+    except KeyError:
+        raise ValueError(f"unknown gradient_position: {gradient_position}")
 
     if arr.shape[0] != 3:
         raise TypeError("input array must have exactly three bands")

mapchete_eo/image_operations/fillnodata.py

@@ -6,7 +6,7 @@ import numpy.ma as ma
 from mapchete import Timer
 from rasterio.features import rasterize, shapes
 from rasterio.fill import fillnodata as rio_fillnodata
-from scipy.ndimage.filters import convolve
+from scipy.ndimage import convolve
 from shapely.geometry import shape
 
 logger = logging.getLogger(__name__)

{mapchete_eo-2025.8.2.dist-info → mapchete_eo-2025.8.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapchete-eo
-Version: 2025.8.2
+Version: 2025.8.3
 Summary: mapchete EO data reader
 Project-URL: Homepage, https://gitlab.eox.at/maps/mapchete_eo
 Author-email: Joachim Ungar <joachim.ungar@eox.at>, Petr Sevcik <petr.sevcik@eox.at>
@@ -12,6 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: GIS
 Requires-Dist: click
 Requires-Dist: croniter
@@ -43,6 +44,9 @@ Earth Observation–specific driver extensions for `Mapchete <https://github.com
 .. image:: https://img.shields.io/pypi/v/mapchete-eo.svg
   :target: https://pypi.org/project/mapchete-eo/
 
+.. image:: https://img.shields.io/conda/v/conda-forge/mapchete-eo
+  :target: https://anaconda.org/conda-forge/mapchete-eo
+
 .. image:: https://img.shields.io/pypi/l/mapchete-eo.svg
   :target: https://github.com/mapchete/mapchete-eo/blob/main/LICENSE
 

{mapchete_eo-2025.8.2.dist-info → mapchete_eo-2025.8.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-mapchete_eo/__init__.py,sha256=proat4RKhxlrOiUazmDvmlHqo8wGe3Jrpdv-JeH4vvs,25
+mapchete_eo/__init__.py,sha256=poKZZLAyfwEUXxc4xuORKXHhPmoth643BeBL6d8_ttg,25
 mapchete_eo/base.py,sha256=-bwBYkKCthr7Q48Y10KbExw7i9sXY8lc0UGo-fe08WA,18907
 mapchete_eo/blacklist.txt,sha256=6KhBY0jNjXgRpKRvKJoOTswvNUoP56IrIcNeCYnd2qo,17471
 mapchete_eo/eostac.py,sha256=5K08Mr4wm-VOXTEvTB6DQHX7rbFLYw8mjW1wlpPltC0,574
@@ -30,15 +30,14 @@ mapchete_eo/cli/s2_rgb.py,sha256=nzK5m4s0m2VOXgtit0uUOOhNJ14wquikWmbEQON5WJw,374
 mapchete_eo/cli/s2_verify.py,sha256=atfJA5luHZjDSqiM2udaufmnQ2B4uW2Tur_OgtYLa2g,4080
 mapchete_eo/cli/static_catalog.py,sha256=zq20fc0phjfjWMjSao-L6VVI-o2DPrMapvDmy6i30YQ,4291
 mapchete_eo/image_operations/__init__.py,sha256=c36Vs53mT5UQR9Iwd2Ln_vnT4K_Ni8g-K7J9Fl6UsJo,432
+mapchete_eo/image_operations/blend_functions.py,sha256=YaKLOEapMbsUR-_mkBatXwPcmim8GKpIAVua_GOdaHs,24131
 mapchete_eo/image_operations/color_correction.py,sha256=vMXxcdyH3qOJDSKcXGU3FgXWIcgQxMy-QVe2fGQTbdk,4447
-mapchete_eo/image_operations/compositing.py,sha256=LhTx6K7TY7KwiAY7vBznbno5B7w5TEUvkRn1YFEA16U,8306
+mapchete_eo/image_operations/compositing.py,sha256=K0bGCZqJuS39IBsjrRiJz5zowItI6RsiA-EBUVlbboo,8449
 mapchete_eo/image_operations/dtype_scale.py,sha256=_CCdTBkMLDkZdjV_PsVEkqLWT6jWuTJPeMzCcRwBOns,1243
-mapchete_eo/image_operations/fillnodata.py,sha256=IYCQkPlH-K6ri0G_-Xp8JJzvWz6HhBiA1DolWeGJVyc,4864
+mapchete_eo/image_operations/fillnodata.py,sha256=Xdd-kacfo7VKqX7HRP0hqnnvV5OwNqnHLRTW64QhG24,4856
 mapchete_eo/image_operations/filters.py,sha256=sa_Igv0zMIANHLEALVi8mxohZMoSrdQc6XVjXDYwzy8,7201
 mapchete_eo/image_operations/linear_normalization.py,sha256=-eQX3WLCUYWUv-um3s1u33rgjAwCz84Ht8gcPsMWtJE,2468
 mapchete_eo/image_operations/sigmoidal.py,sha256=IKU8F89HhQJWGUVmIrnkuhqzn_ztlGrTf8xXZaVQWzU,3575
-mapchete_eo/image_operations/blend_modes/blending_functions.py,sha256=hv3oWFwzha0aAfG0X9CTKc1Y4rfIC6J4v_xVSGu4XAE,5955
-mapchete_eo/image_operations/blend_modes/type_checks.py,sha256=KVJyE1jLsZ4qDMlylWMh40X9POcJy_e5aZYhhqgXH88,3445
 mapchete_eo/io/__init__.py,sha256=1-1g4cESZZREvyumEUABZhDwgVuSxtxdqbNlLuVKlow,950
 mapchete_eo/io/assets.py,sha256=8OrqvrCzJOY0pExh_vKRL7Bz_RGk6M_LfayQqxHo8ag,17014
 mapchete_eo/io/items.py,sha256=FDDMRtFvNNL3Iwf0xiaSI8G3s-54vhqfYKo7xzCQq-w,5657
@@ -82,8 +81,8 @@ mapchete_eo/search/s2_mgrs.py,sha256=5LWl9c7WzFvXODr9f8m37cv-8yyf-LvnN0-TSSPcXKM
 mapchete_eo/search/stac_search.py,sha256=YnISHpdvMJfrY_wfM1dHOtHYqgsbXsYLMYrRdJlAZTo,9551
 mapchete_eo/search/stac_static.py,sha256=P1C2OC33UopV80xIvFeL-HbOuaxxe7qsPDdnkU8IXcA,8613
 mapchete_eo/search/utm_search.py,sha256=wKrG2KwqL2fjSrkDUTZuRayiVAR27BtWpX-PFab0Dng,9646
-mapchete_eo-2025.8.2.dist-info/METADATA,sha256=t5fNQs5buszhui2sjovYtLu6gaaI8yzELrN58w4IGxY,3061
-mapchete_eo-2025.8.2.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
-mapchete_eo-2025.8.2.dist-info/entry_points.txt,sha256=ewk6R4FGdAclOnUpikhlPZGWI40MWeksVIIwu4jVebk,324
-mapchete_eo-2025.8.2.dist-info/licenses/LICENSE,sha256=TC5JwvBnFrUgsSQSCDFPc3cqlbth2N0q8MWrhY1EVd0,1089
-mapchete_eo-2025.8.2.dist-info/RECORD,,
+mapchete_eo-2025.8.3.dist-info/METADATA,sha256=U1m-qUKfGvm1CGV8RmUtAc8X_DuR9gMolvp2IJsR3NM,3235
+mapchete_eo-2025.8.3.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
+mapchete_eo-2025.8.3.dist-info/entry_points.txt,sha256=ewk6R4FGdAclOnUpikhlPZGWI40MWeksVIIwu4jVebk,324
+mapchete_eo-2025.8.3.dist-info/licenses/LICENSE,sha256=TC5JwvBnFrUgsSQSCDFPc3cqlbth2N0q8MWrhY1EVd0,1089
+mapchete_eo-2025.8.3.dist-info/RECORD,,

mapchete_eo/image_operations/blend_modes/blending_functions.py

@@ -1,198 +0,0 @@
-"""
-
-Original LICENSE:
-
-MIT License
-
-Copyright (c) 2016 Florian Roscheck
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
-documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
-rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
-persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
-Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
-OR OTHER DEALINGS IN THE SOFTWARE.
-
-Overview
---------
-
-.. currentmodule:: blend_modes.blending_functions
-
-.. autosummary::
-    :nosignatures:
-
-    addition
-    darken_only
-    difference
-    divide
-    dodge
-    grain_extract
-    grain_merge
-    hard_light
-    lighten_only
-    multiply
-    normal
-    overlay
-    screen
-    soft_light
-    subtract
-"""
-
-import numpy as np
-from typing import Callable
-from mapchete_eo.image_operations.blend_modes.type_checks import (
-    assert_image_format,
-    assert_opacity,
-)
-
-
-class BlendBase:
-    def __init__(
-        self,
-        opacity=1.0,
-        disable_type_checks=False,
-        dtype=np.float16,
-        fcn_name="BlendBase",
-    ):
-        self.opacity = opacity
-        self.disable_type_checks = disable_type_checks
-        self.dtype = dtype
-        self.fcn_name = fcn_name
-
-    def _prepare(self, src: np.ndarray, dst: np.ndarray):
-        if not self.disable_type_checks:
-            assert_image_format(src, fcn_name=self.fcn_name, arg_name="src")
-            assert_image_format(dst, fcn_name=self.fcn_name, arg_name="dst")
-            assert_opacity(self.opacity, fcn_name=self.fcn_name)
-        if src.dtype != self.dtype:
-            src = src.astype(self.dtype)
-        if dst.dtype != self.dtype:
-            dst = dst.astype(self.dtype)
-        return src, dst
-
-    def blend(self, src: np.ndarray, dst: np.ndarray, blend_func: Callable):
-        src, dst = self._prepare(src, dst)
-        blended = blend_func(src, dst)
-        result = (blended * self.opacity) + (dst * (1 - self.opacity))
-        return np.clip(result, 0, 1).astype(self.dtype)
-
-
-def make_blend_function(blend_func: Callable):
-    # This function returns a wrapper that uses a shared BlendBase instance
-    base = BlendBase()
-
-    def func(
-        src: np.ndarray,
-        dst: np.ndarray,
-        opacity: float = 1.0,
-        disable_type_checks: bool = False,
-        dtype: np.dtype = np.float16,
-    ) -> np.ndarray:
-        # If parameters differ from base, create new BlendBase (rare)
-        if (
-            opacity != base.opacity
-            or disable_type_checks != base.disable_type_checks
-            or dtype != base.dtype
-        ):
-            base_local = BlendBase(opacity, disable_type_checks, dtype)
-            return base_local.blend(src, dst, blend_func)
-        return base.blend(src, dst, blend_func)
-
-    return func
-
-
-normal = make_blend_function(lambda s, d: s)
-multiply = make_blend_function(lambda s, d: s * d)
-screen = make_blend_function(lambda s, d: 1 - (1 - s) * (1 - d))
-darken_only = make_blend_function(lambda s, d: np.minimum(s, d))
-lighten_only = make_blend_function(lambda s, d: np.maximum(s, d))
-difference = make_blend_function(lambda s, d: np.abs(d - s))
-subtract = make_blend_function(lambda s, d: np.clip(d - s, 0, 1))
-
-
-def divide_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    with np.errstate(divide="ignore", invalid="ignore"):
-        res = np.true_divide(d, s)
-        res[~np.isfinite(res)] = 0
-        return np.clip(res, 0, 1)
-
-
-divide = make_blend_function(divide_blend)
-
-
-def grain_extract_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    return np.clip(d - s + 0.5, 0, 1)
-
-
-grain_extract = make_blend_function(grain_extract_blend)
-
-
-def grain_merge_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    return np.clip(d + s - 0.5, 0, 1)
-
-
-grain_merge = make_blend_function(grain_merge_blend)
-
-
-def overlay_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    mask = d <= 0.5
-    result = np.empty_like(d)
-    result[mask] = 2 * s[mask] * d[mask]
-    result[~mask] = 1 - 2 * (1 - s[~mask]) * (1 - d[~mask])
-    return np.clip(result, 0, 1)
-
-
-overlay = make_blend_function(overlay_blend)
-
-
-def hard_light_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    mask = s <= 0.5
-    result = np.empty_like(d)
-    result[mask] = 2 * s[mask] * d[mask]
-    result[~mask] = 1 - 2 * (1 - s[~mask]) * (1 - d[~mask])
-    return np.clip(result, 0, 1)
-
-
-hard_light = make_blend_function(hard_light_blend)
-
-
-def soft_light_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    result = (1 - 2 * s) * d**2 + 2 * s * d
-    return np.clip(result, 0, 1)
-
-
-soft_light = make_blend_function(soft_light_blend)
-
-
-def dodge_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    with np.errstate(divide="ignore", invalid="ignore"):
-        res = np.true_divide(d, 1 - s)
-        res[~np.isfinite(res)] = 1
-        return np.clip(res, 0, 1)
-
-
-dodge = make_blend_function(dodge_blend)
-
-
-def burn_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    with np.errstate(divide="ignore", invalid="ignore"):
-        res = 1 - np.true_divide(1 - d, s)
-        res[~np.isfinite(res)] = 0
-        return np.clip(res, 0, 1)
-
-
-burn = make_blend_function(burn_blend)
-
-
-def addition_blend(s: np.ndarray, d: np.ndarray) -> np.ndarray:
-    return np.clip(s + d, 0, 1)
-
-
-addition = make_blend_function(addition_blend)

mapchete_eo/image_operations/blend_modes/type_checks.py

@@ -1,99 +0,0 @@
-"""This module includes functions to check if variable types match expected formats."""
-
-import numpy as np
-
-
-def assert_image_format(image, fcn_name: str, arg_name: str, force_alpha: bool = True):
-    """Assert if image arguments have the expected format.
-
-    Checks:
-        - Image is a numpy array
-        - Array is of floating-point type
-        - Array is 3D (height x width x channels)
-        - Array has the correct number of layers (3 or 4)
-
-    Args:
-        image: The image to be checked.
-        fcn_name (str): Calling function name for display in error messages.
-        arg_name (str): Relevant argument name for display in error messages.
-        force_alpha (bool): Whether the image must include an alpha layer.
-
-    Raises:
-        TypeError: If type or shape are incorrect.
-    """
-    if not isinstance(image, np.ndarray):
-        raise TypeError(
-            f"\n[Invalid Type]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f"Expected: numpy.ndarray\n"
-            f"Got: {type(image).__name__}\n"
-            f'Hint: Pass a numpy.ndarray for "{arg_name}".'
-        )
-
-    if image.dtype.kind != "f":
-        raise TypeError(
-            f"\n[Invalid Data Type]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f'Expected dtype kind: "f" (floating-point)\n'
-            f'Got dtype kind: "{image.dtype.kind}"\n'
-            f"Hint: Convert the array to float, e.g., image.astype(float)."
-        )
-
-    if len(image.shape) != 3:
-        raise TypeError(
-            f"\n[Invalid Dimensions]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f"Expected: 3D array (height x width x channels)\n"
-            f"Got: {len(image.shape)}D array\n"
-            f"Hint: Ensure the array has three dimensions."
-        )
-
-    if force_alpha and image.shape[2] != 4:
-        raise TypeError(
-            f"\n[Invalid Channel Count]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f"Expected: 4 layers (R, G, B, Alpha)\n"
-            f"Got: {image.shape[2]} layers\n"
-            f"Hint: Include all four channels if force_alpha=True."
-        )
-
-
-def assert_opacity(opacity, fcn_name: str, arg_name: str = "opacity"):
-    """Assert if opacity has the expected format.
-
-    Checks:
-        - Opacity is float or int
-        - Opacity is within 0.0 <= x <= 1.0
-
-    Args:
-        opacity: The opacity value to be checked.
-        fcn_name (str): Calling function name for display in error messages.
-        arg_name (str): Argument name for display in error messages.
-
-    Raises:
-        TypeError: If type is not float or int.
-        ValueError: If opacity is out of range.
-    """
-    if not isinstance(opacity, (float, int)):
-        raise TypeError(
-            f"\n[Invalid Type]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f"Expected: float (or int)\n"
-            f"Got: {type(opacity).__name__}\n"
-            f"Hint: Pass a float between 0.0 and 1.0."
-        )
-
-    if not 0.0 <= opacity <= 1.0:
-        raise ValueError(
-            f"\n[Out of Range]\n"
-            f"Function: {fcn_name}\n"
-            f"Argument: {arg_name}\n"
-            f"Expected: value in range 0.0 <= x <= 1.0\n"
-            f"Got: {opacity}\n"
-            f"Hint: Clamp or normalize the value to the valid range."
-        )