add functions to process images

Author: DominiqueMakowski

pyllusion/__init__.py

@@ -19,11 +19,11 @@
 from .Ponzo import *
 from .psychopy import *
 from .RodFrame import *
+from .utilities import *
 from .VerticalHorizontal import *
 from .White import *
 from .Zollner import *
 
-
 # Maintainer info
 __author__ = "The Reality Bending League"
 __email__ = "[email protected]"

pyllusion/image/profile.stats

@@ -0,0 +1,13 @@
+"""
+Pyllusion submodule.
+"""
+
+from .analyze_color import analyze_color
+from .analyze_image import analyze_image
+from .analyze_luminance import analyze_luminance
+
+__all__ = [
+    "analyze_luminance",
+    "analyze_color",
+    "analyze_image",
+]

pyllusion/utilities/__init__.py

@@ -0,0 +1,90 @@
+import numpy as np
+
+
+def analyze_color(image, average=True):
+    """Amount of Color in an image
+
+    Compute the amount of color in an image (redness, greenness, blueness).
+
+    Parameters
+    ----------
+    image : ndarray
+        Array for R, G and B channels.
+    average : bool
+        If True, will average the color values of each pixel.
+
+    Returns
+    ----------
+    dict
+        Contains "Redness", "Greenness" and "Blueness" and more (TODO: document this list).
+
+    Example
+    ----------
+    >>> import pyllusion
+    >>>
+    >>> # Generate image (random pixels)
+    >>> image = np.random.rand(500, 500, 3) * 255
+    >>> image = image.astype(int)
+    >>> # Visualize: plt.imshow(image)
+    >>>
+    >>> # Compute color
+    >>> out = pyllusion.analyze_color(image, average=True)
+    >>> out["Redness"]
+    >>>
+    >>> # Get luminance per pixel
+    >>> out = pyllusion.analyze_color(image, average=False)
+    >>> # Visualize: plt.imshow(out["Redness"], cmap="Reds")
+
+    """
+    try:
+        import skimage.color
+    except ImportError:
+        raise ImportError(
+            "Pyllusion error: analyze_color(): the 'scikit-image' module is required for this function to run. ",
+            "Please install it first (`pip install scikit-image`).",
+        )
+
+    out = {}
+
+    # Convert to color space HSL (Hue, saturation, luminance)
+    hsv = skimage.color.rgb2hsv(image)
+
+    # Saturation and Luminance
+    out["Saturation"] = hsv[:, :, 1]
+    out["Brightness"] = hsv[:, :, 2]
+
+    # Get HUE
+    hue = np.radians(hsv[:, :, 0] * 360)
+
+    # Redness (peaks at 0°)
+    redness = np.rad2deg(_difference_between_angle(hue, np.radians(0)))
+    out["Redness"] = 1 - np.abs(redness / 180)
+
+    # Yellowness (peaks at 60)
+    yellowness = np.rad2deg(_difference_between_angle(hue, np.radians(60)))
+    out["Yellowness"] = 1 - np.abs(yellowness / 180)
+
+    # Blueness (peaks at 240)
+    blueness = np.rad2deg(_difference_between_angle(hue, np.radians(240)))
+    out["Blueness"] = 1 - np.abs(blueness / 180)
+
+    # Greenness (peaks at 120)
+    greenness = np.rad2deg(_difference_between_angle(hue, np.radians(120)))
+    out["Greenness"] = 1 - np.abs(greenness / 180)
+
+    lab = skimage.color.rgb2lab(image)
+    out["RedGreen"] = lab[:, :, 1]
+    out["BlueYellow"] = lab[:, :, 2]
+
+    if average is True:
+        # Average all elements
+        out = {key: np.mean(value) for (key, value) in out.items()}
+
+    return out
+
+
+def _difference_between_angle(x, y):
+    """Compute the angular difference between two angles (in radians)"""
+    vals = np.array([y - x, y - x + 2 * np.pi, y - x - 2 * np.pi])
+    idx = np.argmin(np.abs(vals), axis=0)
+    return np.take_along_axis(vals, np.array([idx]), axis=0)[0]

pyllusion/utilities/analyze_color.py

@@ -0,0 +1,60 @@
+import numpy as np
+
+from .analyze_color import analyze_color
+from .analyze_luminance import analyze_luminance
+
+
+def analyze_image(image):
+    """Compute Objective Characteristics of an Image
+
+    Compute the physical characteristics of an image.
+
+    Parameters
+    ----------
+    image : ndarray
+        Array for R, G and B channels.
+
+    Returns
+    ----------
+    dict
+        Contains elements from `analyze_luminance()`, `analyze_color()` and more (TODO: document this list).
+
+
+    Example
+    ----------
+    >>> import pyllusion
+    >>>
+    >>> # Generate image (random pixels)
+    >>> image = np.random.rand(500, 500, 3) * 255
+    >>> image = image.astype(int)
+    >>> # Visualize: plt.imshow(image)
+    >>>
+    >>> # Compute color
+    >>> out = pyllusion.analyze_image(image)
+    >>> out["Entropy"]
+
+    """
+    try:
+        import skimage.color
+        import skimage.feature
+        import skimage.filters
+        import skimage.measure
+    except ImportError:
+        raise ImportError(
+            "Pyllusion error: analyze_color(): the 'scikit-image' module is required for this function to run. ",
+            "Please install it first (`pip install scikit-image`).",
+        )
+
+    out = analyze_luminance(image, average=True)
+    out.update(analyze_color(image, average=True))
+    out["Entropy"] = skimage.measure.shannon_entropy(image, base=2)
+    # SD of the HUE axis (the colors)
+    out["Colorfulness"] = np.std(skimage.color.rgb2hsv(image)[:, :, 0])
+    # SD of the Luminance axis
+    out["Contrast"] = np.std(skimage.color.rgb2lab(image)[:, :, 0])
+
+    # Edge detection
+    bw = skimage.color.rgb2gray(image)
+    edges = skimage.filters.sobel(bw)  # skimage.filters.roberts or skimage.feature.canny
+    out["Structure"] = skimage.measure.shannon_entropy(edges, base=2)
+    return out

pyllusion/utilities/analyze_image.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+
+def analyze_luminance(image, average=True):
+    """Image Luminance
+
+    Compute the average luminance of an image.
+
+    - Linear Luminance (L): linear measure of light, spectrally weighted for normal vision but not adjusted for the non-linear perception of lightness.
+    - Perceived Luminance (L*): non-linear measure of perceptual lightness that approximates the human vision non-linear response curve.
+
+    Parameters
+    ----------
+    image : ndarray
+        Array for R, G and B channels.
+    average : bool
+        If True, will average the luminance value of each pixel.
+
+    Returns
+    ----------
+    dict
+        Contains "Luminance" and "Luminance_Perceived".
+
+    See Also
+    ----------
+    - http://stackoverflow.com/questions/596216/formula-to-determine-brightness-of-rgb-color
+
+    Example
+    ----------
+    >>> import pyllusion
+    >>>
+    >>> # Generate image (random pixels)
+    >>> image = np.random.rand(500, 500, 3) * 255
+    >>> image = image.astype(int)
+    >>> # Visualize: plt.imshow(image, interpolation="nearest")
+    >>>
+    >>> # Compute luminance
+    >>> out = pyllusion.analyze_luminance(image, average=True)
+    >>> out["Luminance"]
+    >>> out["Luminance_Perceived"]
+    >>>
+    >>> # Get luminance per pixel
+    >>> out = pyllusion.analyze_luminance(image, average=False)
+    >>> # Visualize: plt.imshow(-1*out["Luminance"], cmap="Greys")
+
+    """
+    out = {}
+    # 1. Convert all sRGB integers to decimal 0-1
+    image = image / 255.0
+
+    # 2. Linearize: Convert gamma encoded RGB to a linear value. sRGB (computer standard) requires
+    # a power curve of approximately V^2.2
+    image[image <= 0.04045] = image[image <= 0.04045] / 12.92
+    image[image > 0.04045] = np.power((image[image > 0.04045] + 0.055) / 1.055, 2.4)
+
+    # 3. To find Luminance (Y) apply the standard coefficients for sRGB
+    L = 0.2126 * image[:, :, 0] + 0.7152 * image[:, :, 1] + 0.0722 * image[:, :, 2]
+
+    # 4. Perceived lightness
+    Lstar = (
+        0.299 * image[:, :, 0] ** 2.2
+        + 0.587 * image[:, :, 1] ** 2.2
+        + 0.114 * image[:, :, 2] ** 2.2
+    ) ** (1 / 2.2)
+    # Lstar = image.copy()
+    # Lstar[Lstar <= 216 / 24389] = Lstar[Lstar <= 216 / 24389] * (24389 / 27)
+    # Lstar[Lstar > 216 / 24389] = np.power(Lstar[Lstar > 216 / 24389], 1 / 3) * 116 - 16
+
+    if average is True:
+        L = np.mean(L)
+        Lstar = np.mean(Lstar)
+
+    return {"Luminance": L, "Luminance_Perceived": Lstar}

pyllusion/utilities/analyze_luminance.py

@@ -16,7 +16,7 @@ def find_version():
 
 dependencies = ["numpy", "pandas", "Pillow", "scipy"]
 setup_requirements = ["pytest-runner", "numpy"]
-test_requirements = dependencies + ["pytest", "matplotlib", "coverage"]
+test_requirements = dependencies + ["pytest", "matplotlib", "coverage", "scikit-image"]
 
 
 setup(