pyllusion 1.4__py3-none-any.whl

pyllusion/Autostereogram/Autostereogram.py

@@ -0,0 +1,109 @@
+import numpy as np
+import PIL.Image, PIL.ImageDraw, PIL.ImageFilter, PIL.ImageFont, PIL.ImageOps
+
+from ..image import image_noise, image_text
+
+
+class Autostereogram:
+    """
+    A class to generate Autostereograms based on a given depth map.
+
+    Autostereograms are images made of a pattern that is horizontally repeated (with slight variations)
+    which, when watched with the appropriate focus, will generate an illusion of depth.
+    """
+    def __init__(
+        self, stimulus="Hello", pattern=None, n_repetitions=14, depth=1, invert=False, **kwargs
+    ):
+
+        self.stimulus = stimulus
+        self.pattern = pattern
+        self.n_repetitions = n_repetitions
+        self.depth = depth
+        self.invert = invert
+
+        # If '/' and '.' in string, we assume it's a path
+        if "/" in self.stimulus and "." in self.stimulus:
+            depth_map = PIL.Image.open(self.stimulus)
+        else:  # Else a text
+            depth_map = image_text(text=self.stimulus, **kwargs)
+
+        # Convert to black and white
+        depth_map = depth_map.convert('L')
+        depth_map = PIL.ImageOps.autocontrast(depth_map)
+    
+        if invert is False:
+            self.depth_map = PIL.ImageOps.invert(depth_map)
+        else:
+            self.depth_map = depth_map
+
+        # Get size of depth map
+        self.width, self.height = self.depth_map.size
+    
+        # We want the strip width to be a multiple of the tile
+        # width so it repeats cleanly.
+        self.strip_width = int(self.width / self.n_repetitions)
+    
+        # Fix conflicting arguments
+        conflicting_args = ["width", "height", "font"]
+        kwargs = {key: kwargs[key] for key in kwargs if key not in conflicting_args}
+    
+        # Create strip of pattern
+        if pattern is None:
+            strip = image_noise(width=self.strip_width, height=self.height, **kwargs)
+        else:
+            strip = self.pattern(width=self.strip_width, height=self.height, **kwargs)
+        self.strip_pixels = strip.load()
+    
+
+    def draw(self, guide=True):
+        """Create a PIL image of Autostereograms.
+    
+        Parameters
+        ----------
+        guide : bool
+            Defaults to 'True' to activate two red dots as guidance, and 'False' to disable the guide.
+    
+        Returns
+        -------
+        Image
+            Image of the Autostereograms illusion, defaults to 800 x 600 pixels.
+            Can be resized
+            (`resize()`, See https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize)
+            and saved in different file formats
+            (`save()` See https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).
+    
+        Examples
+        ---------
+        >>> import pyllusion
+        >>>
+        >>> autostereograms = pyllusion.Autostereogram(stimulus="3D", width=1000, height=500, font="arialbd.ttf")
+        >>> autostereograms.draw(guide=True)
+        """
+
+        image = PIL.Image.new("RGB", (self.width, self.height))
+
+        # Load pixels for easy replacement
+        depth_pixels = self.depth_map.load()
+        image_pixels = image.load()
+    
+        for x in range(self.width):
+            for y in range(self.height):
+                # Need one full strip's worth to borrow from.
+                if x < self.strip_width:
+                    image_pixels[x, y] = self.strip_pixels[x, y]
+                else:
+                    shift_amplitude = self.depth * (depth_pixels[x, y] / self.n_repetitions)
+                    # Clip to stay within the image (can happen for narrow strips)
+                    source_x = int(x - self.strip_width + shift_amplitude)
+                    source_x = min(max(source_x, 0), self.width - 1)
+                    image_pixels[x, y] = image_pixels[source_x, y]
+    
+        # Add guide
+        if guide is True:
+            draw = PIL.ImageDraw.Draw(image)
+            for i in [-2, 0]:
+                diameter = 0.005 * self.width
+                center_x = (self.width / 2) + (i * self.strip_width / 2)
+                center_y = 0.5 * self.height
+                draw.ellipse([center_x-diameter, center_y-diameter, center_x+diameter, center_y+diameter], fill=(255, 0, 0))
+        return image

pyllusion/Autostereogram/__init__.py

@@ -0,0 +1,5 @@
+"""
+Pyllusion submodule.
+"""
+
+from .Autostereogram import Autostereogram

pyllusion/Contrast/Contrast.py

@@ -0,0 +1,159 @@
+from .contrast_image import _contrast_image
+from .contrast_parameters import _contrast_parameters
+from .contrast_psychopy import _contrast_psychopy
+
+
+class Contrast:
+    """
+    A class to generate the Simultaneous Contrast illusion.
+
+    Simultaneous contrast, identified by Michel Eugène Chevreul, refers to the
+    manner in which the colors of two different objects affect each other.
+    Specifically, when comparing two targets with the same shade of grey, the one that is
+    embedded against a darker background appears lighter than the other target embedded against a lighter background.
+
+    Each instance of **Contrast** contains attributes corresponding to the parameters of the illusion.
+
+    Parameters
+    ----------
+    illusion_strength : float
+        The strength of the background, i.e., contrasting colours, in biasing the perception of inner rectangles of different grey shades.
+        Specifically, the difference in background colours, where large values create greater contrast in the two
+        grey backgrounds.
+        A positive sign means that the illusion will enhance the perception of the actual **difference** in brightness contrast
+        of the two inner rectangles, whereas a negative sign reduces this perception.
+    difference : float
+        The objective difference of the grey shades of the two inner rectangles.
+        Large positive signs reflect a darker lower rectangle relative to the upper rectangle, and negative signs reflect a darker upper
+        rectangle relative to the lower rectangle.
+    """
+
+    def __init__(
+        self, illusion_strength=0, difference=0
+    ):
+        """
+        Compute parameters for the Simultaneous Contrast illusion.
+
+        Parameters
+        ----------
+            illusion_strength : float
+                The strength of the background, i.e., contrasting colours, in biasing the perception of inner rectangles of different grey shades.
+                Specifically, the difference in background colours, where large values create greater contrast in the two
+                grey backgrounds.
+                A positive sign means that the illusion will enhance the perception of the actual **difference** in brightness contrast
+                of the two inner rectangles, whereas a negative sign reduces this perception.
+            difference : float
+                The objective difference of the grey shades of the two inner rectangles.
+                Large positive signs reflect a darker lower rectangle relative to the upper rectangle, and negative signs reflect a darker upper
+                rectangle relative to the lower rectangle.
+        """
+        self.parameters = _contrast_parameters(
+            illusion_strength=illusion_strength,
+            difference=difference,
+        )
+
+    def get_parameters(self):
+        """
+        Returns a dictionary of parameters passed into the Simultaneous Contrast illusion.
+
+        Returns
+        -------
+        dict
+            Dictionary of parameters of the Simultaneous Contrast illusion, including:
+
+            - **Difference** : Objective difference in the target features, by modifying `difference` of contrast_parameters().
+            - **Illusion** : Name of the illusion, Contrast.
+            - **Illusion_Strength** : The strength of the surrounding context in biasing illusion, by modifying `illusion_strength` of contrast_parameters().
+            - **Illusion_Type** : `Congruent` if the illusion enhances the perception of the objective difference in the illusion, and `Incongruent` if it reduces the perceived difference.
+            - **Rectangle_Top** : Luminance of the top inner rectangle.
+            - **Rectangle_Bottom** : Luminance of the bottom inner rectangle.
+            - **Background_Top** : Luminance of the top half of the background.
+            - **Background_Bottom** : Luminance of the bottom half of the background.
+            - **Rectangle_Top_RGB** : RGB value of the top inner rectangle.
+            - **Rectangle_Bottom_RGB** : RGB value of the bottom inner rectangle.
+            - **Background_Top_RGB** : RGB value of the top half of the background.
+            - **Background_Bottom_RGB** : RGB value of the bottom half of the background.
+        """
+        return self.parameters
+
+    def to_dict(self):
+        """
+        Alias for `get_parameters()`.
+        """
+        return self.get_parameters()
+
+    def to_image(self, width=800, height=600, **kwargs):
+        """Create a PIL image of the Simultaneous Contrast illusion.
+
+        Parameters
+        ----------
+        width : int
+            Width of the returned image.
+        height : int
+            Height of the returned image.
+        **kwargs
+            Additional arguments passed into `contrast_parameters()`.
+
+        Returns
+        -------
+        Image
+            Image of the Simultaneous Contrast illusion, defaults to 800 x 600 pixels.
+            Can be resized
+            (`resize()`, See https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize)
+            and saved in different file formats
+            (`save()` See https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).
+
+        Examples
+        ---------
+        >>> import pyllusion
+        >>>
+        >>> contrast = pyllusion.Contrast(illusion_strength=-50, difference=0)
+        >>> contrast.to_image()
+        """
+
+        img = _contrast_image(
+            parameters=self.parameters,
+            width=width,
+            height=height,
+            **kwargs
+        )
+        return img
+
+    def to_psychopy(self, window, **kwargs):
+        """Create a PsychoPy stimulus of the Simultaneous Contrast illusion.
+
+        Parameters
+        ----------
+        window : object
+            The window object in which the stimulus will be rendered.
+        **kwargs
+            Additional arguments passed into `contrast_parameters()`.
+
+        Returns
+        -------
+        In-place modification of the PsychoPy window (No explicit return).
+
+        Examples
+        ---------
+        >>> import pyllusion
+        >>> from psychopy import visual, event
+
+        >>> # Create parameters
+        >>> contrast = pyllusion.Contrast(difference=0, illusion_strength=-50)
+        >>> parameters = contrast.get_parameters()
+
+        >>> # Initiate Window
+        >>> window = visual.Window(size=[800, 600], winType='pygame',
+                                   color=parameters["Background_Top_RGB"],
+                                   colorSpace='rgb255')
+
+        >>> # Display illusion
+        >>> contrast.to_psychopy(window)
+
+        >>> # Refresh and close window
+        >>> window.flip()
+        >>> event.waitKeys()  # Press any key to close
+        >>> window.close()
+
+        """
+        _contrast_psychopy(window, self.parameters, **kwargs)

pyllusion/Contrast/__init__.py

@@ -0,0 +1,5 @@
+"""
+Pyllusion submodule.
+"""
+
+from .Contrast import Contrast

pyllusion/Contrast/contrast_image.py

@@ -0,0 +1,45 @@
+import numpy as np
+import PIL.Image, PIL.ImageDraw, PIL.ImageFilter, PIL.ImageFont, PIL.ImageOps
+
+from ..image import image_rectangle
+from .contrast_parameters import _contrast_parameters
+
+
+def _contrast_image(parameters=None, width=800, height=600, **kwargs):
+
+    # Create white canvas and get drawing context
+    if parameters is None:
+        parameters = _contrast_parameters(**kwargs)
+
+    # Background upper
+    image = PIL.Image.new(
+        "RGB", (width, height), color=parameters["Background_Top_RGB"]
+    )
+    # Background lower
+    image = image_rectangle(
+        image=image,
+        y=-0.5,
+        size_height=1,
+        size_width=2,
+        color=parameters["Background_Bottom_RGB"],
+        antialias=False,
+    )
+
+    image = image_rectangle(
+        image=image,
+        y=0.5,
+        size_height=0.5,
+        size_width=1,
+        color=parameters["Rectangle_Top_RGB"],
+        antialias=False,
+    )
+    image = image_rectangle(
+        image=image,
+        y=-0.5,
+        size_height=0.5,
+        size_width=1,
+        color=parameters["Rectangle_Bottom_RGB"],
+        antialias=False,
+    )
+
+    return image

pyllusion/Contrast/contrast_parameters.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+from ..image import rescale
+
+
+def _contrast_parameters(illusion_strength=0, difference=0):
+
+    colors, rgb = _contrast_parameters_internal(
+        difference=difference, illusion_strength=illusion_strength
+    )
+
+    parameters = {
+        "Illusion": "Contrast",
+        "Illusion_Strength": illusion_strength,
+        "Difference": difference,
+        "Illusion_Type": "Congruent" if illusion_strength > 0 else "Incongruent",
+        "Rectangle_Top": colors[0],
+        "Rectangle_Bottom": colors[1],
+        "Background_Top": colors[2],
+        "Background_Bottom": colors[3],
+        "Rectangle_Top_RGB": rgb[0],
+        "Rectangle_Bottom_RGB": rgb[1],
+        "Background_Top_RGB": rgb[2],
+        "Background_Bottom_RGB": rgb[3],
+    }
+
+    return parameters
+
+
+def _contrast_parameters_internal(difference=0, illusion_strength=0):
+    # Targets
+    # A difference of 1 means a difference of 1%
+    up = 0.5 + difference / 200
+    low = 0.5 - difference / 200
+
+    # Backgrounds
+    # A illusion_strength of 1 means a difference of 1%
+    mod = np.sign(difference) if difference != 0 else 1
+    background_up = 0.5 + mod * illusion_strength / 200
+    background_low = 0.5 - mod * illusion_strength / 200
+
+    # Adjustments in case of same contrast between rectangle and background
+    if background_up == up:
+        if background_up > background_low:
+            background_up += 0.01
+        elif background_up < background_low:
+            background_up -= 0.01
+        else:
+            background_up -= 0.01
+            background_low -= 0.01
+    if background_low == low:
+        if background_low > background_up:
+            background_low += 0.01
+        elif background_low < background_up:
+            background_low -= 0.01
+        else:
+            background_low -= 0.01
+            background_up -= 0.01
+
+    # Transform to RGB tuples
+    background_up_rgb = tuple(
+        np.rint(rescale([background_up] * 3, scale=[0, 1], to=[0, 255])).astype(int)
+    )
+    background_low_rgb = tuple(
+        np.rint(rescale([background_low] * 3, scale=[0, 1], to=[0, 255])).astype(int)
+    )
+    up_rgb = tuple(np.rint(rescale([up] * 3, scale=[0, 1], to=[0, 255])).astype(int))
+    low_rgb = tuple(np.rint(rescale([low] * 3, scale=[0, 1], to=[0, 255])).astype(int))
+
+    return (
+        (up, low, background_up, background_low),
+        (up_rgb, low_rgb, background_up_rgb, background_low_rgb),
+    )

pyllusion/Contrast/contrast_psychopy.py

@@ -0,0 +1,24 @@
+import numpy as np
+
+from ..psychopy.psychopy_rectangle import psychopy_rectangle
+from .contrast_parameters import _contrast_parameters
+
+
+def _contrast_psychopy(window, parameters=None, **kwargs):
+
+    # Create white canvas and get drawing context
+    if parameters is None:
+        parameters = _contrast_parameters(**kwargs)
+
+    # Background lower
+    psychopy_rectangle(window, x=0, y=-0.5, size_height=1, size_width=2, color=parameters["Background_Bottom_RGB"],
+                       outline_color=parameters["Background_Bottom_RGB"],
+                       fillColorSpace='rgb255', lineColorSpace='rgb255')
+
+    psychopy_rectangle(window, x=0, y=0.5, size_height=0.5, size_width=1, color=parameters["Rectangle_Top_RGB"],
+                       outline_color=parameters["Rectangle_Top_RGB"],
+                       fillColorSpace='rgb255', lineColorSpace='rgb255')
+
+    psychopy_rectangle(window, x=0, y=-0.5, size_height=0.5, size_width=1, color=parameters["Rectangle_Bottom_RGB"],
+                       outline_color=parameters["Rectangle_Bottom_RGB"],
+                       fillColorSpace='rgb255', lineColorSpace='rgb255')

pyllusion/Delboeuf/Delboeuf.py

@@ -0,0 +1,211 @@
+from .delboeuf_image import _delboeuf_image
+from .delboeuf_parameters import _delboeuf_parameters
+from .delboeuf_psychopy import _delboeuf_psychopy
+
+
+class Delboeuf:
+    """
+    A class to generate the Delboeuf Illusion.
+
+    The Delboeuf illusion is an optical illusion of relative size perception,
+    where circles of identical size appear as different because of their surrounding context.
+    Specifically, the circle that is closely surrounded by a ring appears larger than the circle surrounded by a distant ring.
+
+    Each instance of Delboeuf contains attributes corresponding to the parameters of the illusion.
+
+    Parameters
+    ----------
+    illusion_strength : float
+        The strength of the surrounding context, i.e. outer circles, in biasing perception of unequally sized inner circles.
+        Specifically, the size of the outer circle relative to the inner circle (in percentage, e.g, if illusion_strength=1,
+        it means that the outer circle will be 100% bigger, i.e., 2 times bigger than the inner circle).
+        A negative sign means that the illusion will enhance the perception of the actual difference in circle sizes
+        whereas a positive sign reduces this perception.
+    difference : float
+        The objective size difference of the inner circles. Specifically, the size of left inner
+        circle relative to the right (in percentage, e.g., if difference=1, it means that the left
+        inner circle will be 100% bigger, i.e., 2 times bigger than the right). A negative sign
+        would make the left inner circle smaller than the right inner circle.
+    size_min : float
+        Size of smaller inner circle. Defaults to 0.25.
+    distance : float
+        Distance between circles. Defaults to 1.
+    distance_auto : bool
+        If true, distance is between edges (fixed spacing), if false (default), between centers (fixed location).
+    """
+
+    def __init__(
+        self,
+        illusion_strength=0,
+        difference=0,
+        size_min=0.25,
+        distance=1,
+        distance_auto=False,
+    ):
+        """
+        Compute attributes for the Delboeuf Illusion.
+
+        Parameters
+        ----------
+            illusion_strength : float
+                The strength of the surrounding context, i.e. outer circles, in biasing perception of unequally sized inner circles.
+                Specifically, the size of the outer circle relative to the inner circle (in percentage, e.g, if illusion_strength=1,
+                it means that the outer circle will be 100% bigger, i.e., 2 times bigger than the inner circle).
+                A negative sign means that the illusion will enhance the perception of the actual difference in circle sizes
+                whereas a positive sign reduces this perception.
+            difference : float
+                The objective size difference of the inner circles.
+                Specifically, the size of left inner circle relative to the right (in percentage, e.g., if difference=1,
+                it means that the left inner circle will be 100% bigger, i.e., 2 times bigger than the right).
+                A negative sign would make the left inner circle smaller than the right inner circle.
+            size_min : float
+                Size of smaller inner circle. Defaults to 0.25.
+            distance : float
+                Distance between circles. Defaults to 1.
+            distance_auto : bool
+                If true, distance is between edges (fixed spacing), if false (default), between centers (fixed location).
+        """
+        self.parameters = _delboeuf_parameters(
+            illusion_strength=illusion_strength,
+            difference=difference,
+            size_min=size_min,
+            distance=distance,
+            distance_auto=distance_auto,
+        )
+
+    def get_parameters(self):
+        """
+        Returns a dictionary of parameters passed into the Delboeuf illusion.
+
+        Returns
+        --------
+        dict
+            A dictionary of all parameters passed into the Delboeuf illusion, including:
+
+            - **Difference** : Objective difference in the target features, by modifying `difference` of delboeuf_parameters()
+            - **Illusion** : Name of the illusion, Delboeuf.
+            - **Illusion_Strength** : The strength of the surrounding context in biasing illusion, by modifying `illusion_strength` of delboeuf_parameters().
+            - **Illusion_Type** : `Congruent` if the illusion enhances the perception of the objective difference in the illusion, and `Incongruent` if it reduces the perceived  difference.
+            - **Size_Inner_Left** : Size of the inner left circle.
+            - **Size_Inner_Right** : Size of the inner right circle.
+            - **Sine_Inner_Difference** : Difference in areas of the left and right inner circles.
+            - **Size_Outer_Left** : Size of the outer left rim.
+            - **Size_Outer_Right** : Size of the outer right rim.
+            - **Distance** : Distance between the circles, by modifying `distance` of delboeuf_parameters().
+            - **Distance_Reference** : Distance between circles is computed 'Between Edges' or `Between Centers`, by modifying distance_auto of delboeuf_parameters().
+            - **Distance_Edges_Inner** : Distance between the edges of the inner left and right circles.
+            - **Distance_Edges_Outer** : Distance between the edges of the outer left and right rims.
+            - **Size_Inner_Smaller** : Size of the smaller inner circle, equates to size_min of delboeuf_parameters().
+            - **Size_Inner_Larger** : Size of the larger inner circle.
+            - **Size_Outer_Smaller** : Size of the smaller outer rim.
+            - **Size_Outer_Larger** : Size of the larger outer rim.
+            - **Position_Left** : Position of the left circle.
+            - **Position_Right** : Position of the right circle.
+        """
+        return self.parameters
+
+    def to_dict(self):
+        """
+        Alias for `get_parameters()`.
+        """
+        return self.get_parameters()
+
+    def to_image(
+        self, width=800, height=600, outline=10, background="white", target_only=False, **kwargs
+    ):
+        """Create a PIL image of the Delboeuf illusion.
+
+        Parameters
+        ----------
+        width : int
+            Width of the returned image.
+        height : int
+            Height of the returned image.
+        outline : float
+            The width of the outline of the circles in the illusion, passed into `image_circle()`.
+        background : str
+            Color of the background.
+        distractor_fill : str or tuple
+            Color of the outer distractor circles. Set to ``(0, 0, 0, 0)`` (transparent) by
+            default.
+        target_only : bool
+            If true, only draw the red circle.
+        **kwargs
+            Additional arguments passed into `delboeuf_parameters()`.
+
+        Returns
+        -------
+        Image
+            Image of the Delboeuf illusion, defaults to 800 x 600 pixels.
+            Can be resized
+            (`resize()`, See https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize)
+            and saved in different file formats
+            (`save()` See https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).
+
+        Examples
+        ---------
+        >>> import pyllusion
+        >>>
+        >>> delboeuf = pyllusion.Delboeuf(illusion_strength=3)
+        >>> delboeuf.to_image()
+        >>> delboeuf.get_parameters()
+        >>>
+        >>> # Display only the target (no illusion)
+        >>> delboeuf = pyllusion.Delboeuf(difference=2)
+        >>> delboeuf.to_image(target_only=True)
+        >>>
+        >>> # Alternative version
+        >>> delboeuf = pyllusion.Delboeuf(illusion_strength=3)
+        >>> delboeuf.to_image(background="grey", distractor_fill="white", outline=0)
+        >>>
+
+        """
+        img = _delboeuf_image(
+            parameters=self.parameters,
+            width=width,
+            height=height,
+            outline=outline,
+            background=background,
+            target_only=target_only,
+            **kwargs
+        )
+        return img
+
+    def to_psychopy(self, window, target_only=False, **kwargs):
+        """Create a PsychoPy stimulus of the Delboeuf illusion.
+
+        Parameters
+        ----------
+        window : object
+            The window object initiated by `psychopy.visual.Window` in which the stimulus will be
+            rendered.
+        target_only : bool
+            If true, only draw the red circle.
+        **kwargs
+            Additional arguments passed into `delboeuf_parameters()`.
+
+        Returns
+        -------
+        In-place modification of the PsychoPy window (No explicit return).
+
+        Examples
+        ---------
+        >>> import pyllusion
+        >>> from psychopy import visual, event
+
+        >>> # Create parameters
+        >>> delboeuf = pyllusion.Delboeuf(difference=2, illusion_strength=3)
+
+        >>> # Initiate Window
+        >>> window = visual.Window(size=[800, 600], winType='pygame', color='white')
+
+        >>> # Display illusion
+        >>> delboeuf.to_psychopy(window)
+
+        >>> # Refresh and close window
+        >>> window.flip()
+        >>> event.waitKeys()  # Press any key to close
+        >>> window.close()
+
+        """
+        _delboeuf_psychopy(window, self.parameters, target_only=target_only, **kwargs)

pyllusion/Delboeuf/__init__.py

@@ -0,0 +1,5 @@
+"""
+Pyllusion submodule.
+"""
+
+from .Delboeuf import Delboeuf