psychopy 2024.2.4__py3-none-any.whl → 2025.1.0__py3-none-any.whl

psychopy/visual/shape.py

@@ -4,10 +4,9 @@
 """Create geometric (vector) shapes by defining vertex locations."""
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL)
 
-import copy
 import numpy
 
 # Ensure setting pyglet.options['debug_gl'] to False is done prior to any
@@ -18,23 +17,25 @@ import pyglet
 
 import psychopy  # so we can get the __path__
 from psychopy import logging
-from psychopy.colors import Color
 
 # tools must only be imported *after* event or MovieStim breaks on win32
 # (JWP has no idea why!)
 # from psychopy.tools.monitorunittools import cm2pix, deg2pix
 from psychopy.tools.attributetools import (attributeSetter,  # logAttrib,
-                                           setAttribute)
-from psychopy.tools.arraytools import val2array
+                                           setAttribute, undefined)
+from psychopy.tools import gltools as gt
 from psychopy.visual.basevisual import (
     BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin, WindowMixin
 )
+from psychopy.colors import Color
 # from psychopy.visual.helpers import setColor
 import psychopy.visual
 
 pyglet.options['debug_gl'] = False
 GL = pyglet.gl
 
+USE_LEGACY_GL = pyglet.version < '2.0'
+
 
 knownShapes = {
     "triangle": [
@@ -113,15 +114,12 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
 
     """
 
-    _defaultFillColor = None
-    _defaultLineColor = "black"
-
     def __init__(self,
                  win,
                  units='',
                  lineWidth=1.5,
-                 lineColor=False, # uses False in place of None to distinguish between "not set" and "transparent"
-                 fillColor=False, # uses False in place of None to distinguish between "not set" and "transparent"
+                 lineColor="black",
+                 fillColor=None,
                  colorSpace='rgb',
                  vertices=((-0.5, 0), (0, +0.5), (+0.5, 0)),
                  closeShape=True,
@@ -138,11 +136,11 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
                  autoLog=None,
                  autoDraw=False,
                  # legacy
-                 color=False,
-                 lineRGB=False,
-                 fillRGB=False,
-                 fillColorSpace=None,
-                 lineColorSpace=None
+                 color=undefined,
+                 lineRGB=undefined,
+                 fillRGB=undefined,
+                 fillColorSpace=undefined,
+                 lineColorSpace=undefined,
                  ):
         """ """  # all doc is in the attributes
         # what local vars are defined (these are the init params) for use by
@@ -161,34 +159,34 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
         self.lineWidth = lineWidth
         self.interpolate = interpolate
 
+        # handle legacy fill color attributes
+        if color is not undefined:
+            fillColor = color
+        if fillColorSpace is not undefined:
+            logging.warning(
+                "fillColorSpace parameter is deprecated. Please use colorSpace instead."
+            )
+            fillColor = Color(fillColor, space=fillColorSpace)
+        if fillRGB is not undefined:
+            logging.warning(
+                "fillRGB parameter is deprecated. Please use lineColor and colorSpace instead"
+            )
+            fillColor = Color(fillColor, space="rgb")
+        # handle legacy border color attributes
+        if lineColorSpace is not undefined:
+            logging.warning(
+                "lineColorSpace parameter is deprecated. Please use colorSpace instead."
+            )
+            lineColor = Color(lineColor, space=lineColorSpace)
+        if lineRGB is not undefined:
+            logging.warning(
+                "lineRGB parameter is deprecated. Please use lineColor and colorSpace instead"
+            )
+            lineColor = Color(lineColor, space="rgb")
         # Appearance
         self.colorSpace = colorSpace
-        if fillColor is not False:
-            self.fillColor = fillColor
-        elif color is not False:
-            # Override fillColor with color if not set
-            self.fillColor = color
-        else:
-            # Default to None if neither are set
-            self.fillColor = self._defaultFillColor
-        if lineColor is not False:
-            self.lineColor = lineColor
-        elif color is not False:
-            # Override lineColor with color if not set
-            self.lineColor = color
-        else:
-            # Default to black if neither are set
-            self.lineColor = self._defaultLineColor
-        if lineRGB is not False:
-            # Override with RGB if set
-            logging.warning("Use of rgb arguments to stimuli are deprecated."
-                            " Please use color and colorSpace args instead")
-            self.setLineColor(lineRGB, colorSpace='rgb', log=None)
-        if fillRGB is not False:
-            # Override with RGB if set
-            logging.warning("Use of rgb arguments to stimuli are deprecated."
-                            " Please use color and colorSpace args instead")
-            self.setFillColor(fillRGB, colorSpace='rgb', log=None)
+        self.fillColor = fillColor
+        self.lineColor = lineColor
         self.contrast = contrast
         if opacity is not None:
             self.opacity = opacity
@@ -322,8 +320,8 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
         # Angles in a shape add up to 360, so theta is 360/2n, solve for n
         return int((360 / theta) / 2)
 
-    def draw(self, win=None, keepMatrix=False):
-        """Draw the stimulus in its relevant window.
+    def _drawLegacyGL(self, win, keepMatrix):
+        """Legacy draw the stimulus in its relevant window.
 
         You must call this method after every MyWin.flip() if you want the
         stimulus to appear on that frame and then update the screen again.
@@ -336,13 +334,16 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
         if win._haveShaders:
             _prog = self.win._progSignedFrag
             GL.glUseProgram(_prog)
+
         # will check if it needs updating (check just once)
         vertsPix = self.verticesPix
         nVerts = vertsPix.shape[0]
+
         # scale the drawing frame etc...
         if not keepMatrix:
             GL.glPushMatrix()  # push before drawing, pop after
             win.setScale('pix')
+
         # load Null textures into multitexteureARB - or they modulate glColor
         GL.glActiveTexture(GL.GL_TEXTURE0)
         GL.glEnable(GL.GL_TEXTURE_2D)
@@ -357,7 +358,7 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
         else:
             GL.glDisable(GL.GL_LINE_SMOOTH)
             GL.glDisable(GL.GL_MULTISAMPLE)
-        # .data_as(ctypes.POINTER(ctypes.c_float)))
+
         GL.glVertexPointer(2, GL.GL_DOUBLE, 0, vertsPix.ctypes)
 
         GL.glEnableClientState(GL.GL_VERTEX_ARRAY)
@@ -366,6 +367,7 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
                 # then draw
                 GL.glColor4f(*self._fillColor.render('rgba1'))
                 GL.glDrawArrays(GL.GL_POLYGON, 0, nVerts)
+
         if self._borderColor != None and self.lineWidth != 0.0:
             # then draw
             GL.glLineWidth(self.lineWidth)
@@ -379,12 +381,92 @@ class BaseShapeStim(BaseVisualStim, DraggingMixin, ColorMixin, ContainerMixin):
                 GL.glDrawArrays(GL.GL_LINE_LOOP, 0, nVerts)
             else:
                 GL.glDrawArrays(GL.GL_LINE_STRIP, 0, nVerts)
+
         GL.glDisableClientState(GL.GL_VERTEX_ARRAY)
+
         if win._haveShaders:
             GL.glUseProgram(0)
+
         if not keepMatrix:
             GL.glPopMatrix()
 
+    def draw(self, win=None, keepMatrix=False):
+        """Draw the stimulus in its relevant window.
+
+        You must call this method after every MyWin.flip() if you want the
+        stimulus to appear on that frame and then update the screen again.
+        """
+        # The keepMatrix option is needed by Aperture
+        if win is None:
+            win = self.win
+        self._selectWindow(win)
+
+        if USE_LEGACY_GL:
+            self._drawLegacyGL(win, keepMatrix)
+            return
+
+        win.setOrthographicView()
+
+        # will check if it needs updating (check just once)
+        vertsPix = self.verticesPix
+
+        if vertsPix is None or vertsPix.shape[0] < 2:  # nothing to draw
+            return
+
+        if self.interpolate:
+            gt.enable('GL_LINE_SMOOTH')
+            gt.enable('GL_MULTISAMPLE')
+        else:
+            gt.disable('GL_LINE_SMOOTH')
+            gt.disable('GL_MULTISAMPLE')
+
+        # bind shader program
+        _prog = self.win._progSignedFrag
+        gt.useProgram(_prog)
+
+        # if vertsPix.shape[0] > 2:  # draw a filled polygon first
+        if self._fillColor != None:
+            gt.setUniformValue(
+                _prog, 
+                b'uColor', 
+                self._fillColor.render('rgba1'))
+            gt.setUniformMatrix(
+                _prog, 
+                b'uProjectionMatrix',
+                win._projectionMatrix,
+                transpose=True)
+            gt.setUniformMatrix(
+                _prog, 
+                b'uModelViewMatrix',
+                win._viewMatrix,
+                transpose=True)
+            gt.drawClientArrays(
+                {'gl_Vertex': self.verticesPix},
+                'GL_TRIANGLES')
+
+        # draw the border
+        if self._borderColor != None and self.lineWidth != 0.0:
+            gt.setLineWidth(self.lineWidth)
+            borderRGBA = self._borderColor.render('rgba1')
+            if self.opacity is not None:
+                borderRGBA[-1] = self.opacity  # override opacity
+            gt.setUniformValue(_prog, b'uColor', borderRGBA)
+            gt.setUniformMatrix(
+                _prog, 
+                b'uProjectionMatrix', 
+                win._projectionMatrix,
+                transpose=True)
+            gt.setUniformMatrix(
+                _prog, 
+                b'uModelViewMatrix', 
+                win._viewMatrix,
+                transpose=True)
+            gt.drawClientArrays(
+                {'gl_Vertex': self.verticesPix},
+                'GL_LINE_LOOP' if self.closeShape else 'GL_LINE_STRIP')
+
+        gt.useProgram(None)
+
 
 class ShapeStim(BaseShapeStim):
     """A class for arbitrary shapes defined as lists of vertices (x,y).
@@ -492,18 +574,10 @@ class ShapeStim(BaseShapeStim):
         frame without the need to explicitly call the
         :py:meth:`~psychopy.visual.ShapeStim.draw` method.
     color : array_like, str, :class:`~psychopy.colors.Color` or None
-        Sets both the initial `lineColor` and `fillColor` of the shape.
-    lineRGB, fillRGB: array_like, :class:`~psychopy.colors.Color` or None
-        *Deprecated*. Please use `lineColor` and `fillColor`. These
-        arguments may be removed in a future version.
-    lineColorSpace, fillColorSpace : str
-        Colorspace to use for the outline and fill. These change how the
-        values passed to `lineColor` and `fillColor` are interpreted.
-        *Deprecated*. Please use `colorSpace` to set both outline and fill
-        colorspace. These arguments may be removed in a future version.
-
+        Synonymous with `fillColor`
     """
     # Author: Jeremy Gray, November 2015, using psychopy.contrib.tesselate
+    _tesselMode = 'triangle'  # best for most shapes
 
     def __init__(self,
                  win,
@@ -528,43 +602,50 @@ class ShapeStim(BaseShapeStim):
                  autoLog=None,
                  autoDraw=False,
                  # legacy
-                 color=False,
-                 lineRGB=False,
-                 fillRGB=False,
-                 fillColorSpace=None,
-                 lineColorSpace=None
+                 color=undefined,
+                 lineRGB=undefined,
+                 fillRGB=undefined,
+                 fillColorSpace=undefined,
+                 lineColorSpace=undefined
                  ):
 
         # what local vars are defined (init params, for use by __repr__)
         self._initParamsOrig = dir()
         self._initParamsOrig.remove('self')
 
-        super(ShapeStim, self).__init__(win,
-                                        units=units,
-                                        lineWidth=lineWidth,
-                                        colorSpace=colorSpace,
-                                        lineColor=lineColor,
-                                        lineColorSpace=lineColorSpace,
-                                        fillColor=fillColor,
-                                        fillColorSpace=fillColorSpace,
-                                        vertices=None,  # dummy verts
-                                        closeShape=self.closeShape,
-                                        pos=pos,
-                                        size=size,
-                                        anchor=anchor,
-                                        ori=ori,
-                                        opacity=opacity,
-                                        contrast=contrast,
-                                        depth=depth,
-                                        interpolate=interpolate,
-                                        draggable=draggable,
-                                        name=name,
-                                        autoLog=False,
-                                        autoDraw=autoDraw)
+        super(ShapeStim, self).__init__(
+            win,
+            units=units,
+            lineWidth=lineWidth,
+            colorSpace=colorSpace,
+            lineColor=lineColor,
+            fillColor=fillColor,
+            vertices=None,  # dummy verts
+            closeShape=self.closeShape,
+            pos=pos,
+            size=size,
+            anchor=anchor,
+            ori=ori,
+            opacity=opacity,
+            contrast=contrast,
+            depth=depth,
+            interpolate=interpolate,
+            draggable=draggable,
+            name=name,
+            autoLog=False,
+            autoDraw=autoDraw,
+            # legacy
+            color=color,
+            lineRGB=lineRGB,
+            fillRGB=fillRGB,
+            fillColorSpace=fillColorSpace,
+            lineColorSpace=lineColorSpace
+        )
 
         self.closeShape = closeShape
         self.windingRule = windingRule
         self.vertices = vertices
+        self.border = vertices
 
         # remove deprecated params (from ShapeStim.__init__):
         self._initParams = self._initParamsOrig
@@ -575,14 +656,14 @@ class ShapeStim(BaseShapeStim):
         if self.autoLog:
             logging.exp("Created %s = %s" % (self.name, str(self)))
 
-    def _tesselate(self, newVertices):
-        """Set the `.vertices` and `.border` to new values, invoking
-        tessellation.
+    def _legacyTesselate(self, newVertices):
+        """Legacy tessellation method for ShapeStim.
         """
         # TO-DO: handle borders properly for multiloop stim like holes
         # likely requires changes in ContainerMixin to iterate over each
         # border loop
         from psychopy.contrib import tesselate
+        import copy
 
         self.border = copy.deepcopy(newVertices)
         tessVertices = []  # define to keep the linter happy
@@ -613,6 +694,33 @@ class ShapeStim(BaseShapeStim):
             initVertices = tessVertices
         self.__dict__['_tesselVertices'] = numpy.array(initVertices, float)
 
+    def _tesselate(self, newVertices):
+        """Set the `.vertices` and `.border` to new values, invoking
+        tessellation.
+
+        Parameters
+        ----------
+        newVertices : array_like
+            Nx2 array of points (eg., `[[-0.5, 0], [0, 0.5], [0.5, 0]`).
+
+        """
+        if USE_LEGACY_GL:
+            self._legacyTesselate(newVertices)
+            return
+
+        if len(newVertices) < 3:
+            self.closeShape = False
+
+        if not hasattr(self, '_tesselMode'):
+            self._tesselMode = 'triangle'
+        
+        vertices, _, _, faces = gt.tesselate(newVertices, mode=self._tesselMode)
+
+        # unpack the vertices into a numpy array
+        initVertices = numpy.ascontiguousarray(vertices)[faces.flatten()]
+
+        self.__dict__['_tesselVertices'] = numpy.array(initVertices, float)
+
     @property
     def vertices(self):
         """A list of lists or a numpy array (Nx2) specifying xy positions of
@@ -639,8 +747,8 @@ class ShapeStim(BaseShapeStim):
         self._needVertexUpdate = True
         self._tesselate(self.vertices)
 
-    def draw(self, win=None, keepMatrix=False):
-        """Draw the stimulus in the relevant window.
+    def _drawLegacyGL(self, win, keepMatrix):
+        """Legacy draw the stimulus in the relevant window.
 
         You must call this method after every `win.flip()` if you want the
         stimulus to appear on that frame and then update the screen again.
@@ -650,10 +758,6 @@ class ShapeStim(BaseShapeStim):
         # border) keepMatrix is needed by Aperture, although Aperture
         # currently relies on BaseShapeStim instead
 
-        if win is None:
-            win = self.win
-        self._selectWindow(win)
-
         # scale the drawing frame etc...
         if not keepMatrix:
             GL.glPushMatrix()
@@ -664,6 +768,9 @@ class ShapeStim(BaseShapeStim):
             _prog = self.win._progSignedFrag
             GL.glUseProgram(_prog)
 
+        # will check if it needs updating (check just once)
+        vertsPix = self.verticesPix
+
         # load Null textures into multitexteureARB - or they modulate glColor
         GL.glActiveTexture(GL.GL_TEXTURE0)
         GL.glEnable(GL.GL_TEXTURE_2D)
@@ -678,6 +785,7 @@ class ShapeStim(BaseShapeStim):
         else:
             GL.glDisable(GL.GL_LINE_SMOOTH)
             GL.glDisable(GL.GL_MULTISAMPLE)
+
         GL.glEnableClientState(GL.GL_VERTEX_ARRAY)
 
         # fill interior triangles if there are any
@@ -700,7 +808,90 @@ class ShapeStim(BaseShapeStim):
             GL.glDrawArrays(gl_line, 0, self._borderPix.shape[0])
 
         GL.glDisableClientState(GL.GL_VERTEX_ARRAY)
+
         if win._haveShaders:
             GL.glUseProgram(0)
+
         if not keepMatrix:
             GL.glPopMatrix()
+
+    def draw(self, win=None, keepMatrix=False):
+        """Draw the stimulus in the relevant window.
+
+        You must call this method after every `win.flip()` if you want the
+        stimulus to appear on that frame and then update the screen again.
+
+        Parameters
+        ----------
+        win : :class:`~psychopy.visual.Window`, optional
+            Window to draw the stimulus in. If not specified, the stimulus
+            will be drawn in the window specified at initialization.
+        keepMatrix : bool, optional
+            *DEPRECATED* If `True`, the current transformation matrix will be 
+            preserved. This is useful when drawing multiple stimuli with the 
+            same transformation matrix. Default is `False`. 
+            
+        """
+        if win is None:
+            win = self.win
+        self._selectWindow(win)
+
+        # legacy pipeline
+        if USE_LEGACY_GL:
+            self._drawLegacyGL(win, keepMatrix)
+            return
+
+        # scale the drawing frame etc...
+        win.setScale('pix')
+        win.setOrthographicView()
+
+        _prog = self.win._progSignedFrag  # shader program handle
+        gt.useProgram(_prog)
+
+        if self.interpolate:
+            gt.enable('GL_LINE_SMOOTH')
+            gt.enable('GL_MULTISAMPLE')
+        else:
+            gt.disable('GL_LINE_SMOOTH')
+            gt.disable('GL_MULTISAMPLE')
+
+        # fill interior triangles if there are any
+        if (self.closeShape and
+                self.verticesPix.shape[0] > 2 and
+                self._fillColor != None):
+            gt.setUniformValue(
+                _prog, b'uColor', self._fillColor.render('rgba1'))
+            gt.setUniformMatrix(
+                _prog, 
+                b'uProjectionMatrix', 
+                win._projectionMatrix, 
+                transpose=True)
+            gt.setUniformMatrix(
+                _prog, 
+                b'uModelViewMatrix', 
+                win._viewMatrix, 
+                transpose=True)
+            gt.drawClientArrays(
+                {'gl_Vertex': self.verticesPix},
+                'GL_TRIANGLES')
+
+        # draw the border (= a line connecting the non-tesselated vertices)
+        if self._borderColor != None and self.lineWidth:
+            GL.glLineWidth(self.lineWidth)
+            gt.setUniformValue(
+                _prog, b'uColor', self._borderColor.render('rgba1'))
+            gt.setUniformMatrix(
+                _prog, 
+                b'uProjectionMatrix', 
+                win._projectionMatrix, 
+                transpose=True)
+            gt.setUniformMatrix(
+                _prog, 
+                b'uModelViewMatrix', 
+                win._viewMatrix, 
+                transpose=True)
+            gt.drawClientArrays(
+                {'gl_Vertex': self._borderPix},
+                'GL_LINE_LOOP' if self.closeShape else 'GL_LINE_STRIP')
+
+        gt.useProgram(None)

psychopy/visual/simpleimage.py

@@ -6,7 +6,7 @@ the resolution and color in the file (subject to gamma correction if set).
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 import os