DOC for ShapeStim migration

psychopy/demos/coder/stimuli/filled_shapes.py

@@ -22,24 +22,27 @@
 
 # lines are ok; use closeShape=False
 line1Vert = [(0,0),(.1,.1),(.1,.2),(.1,.1),(.1,-.1),(0,.1)]
+boxedVert = [(0,0),(0,.2),(.2,.2),(.2,0)]
 
-arrow = ShapeStim(win, vertices=arrowVert, fillColor='darkred', size=.5)#  , lineWidth=2, lineColor='red')
+arrow = ShapeStim(win, vertices=arrowVert, fillColor='darkred', size=.5, lineColor='red')
 star7 = ShapeStim(win, vertices=star7Vert, fillColor='green', lineWidth=2, lineColor='white')
-selfx = ShapeStim(win, vertices=selfxVert, fillColor='yellow', opacity=.6)
-thing = ShapeStim(win, vertices=thingVert, fillColor='blue', opacity=.3) #,lineWidth=0.5,lineColor='white')
-donut = ShapeStim(win, vertices=donutVert, fillColor='orange', size=.75, pos=(-.2,-.2))
-line1 = ShapeStim(win, vertices=line1Vert, fillColor='white', closeShape=False, lineWidth=2, pos=(-.5,0), ori=180)
+selfx = ShapeStim(win, vertices=selfxVert, fillColor='yellow', opacity=.6, pos=(.2,.1))
+thing = ShapeStim(win, vertices=thingVert, fillColor='blue', lineWidth=0, opacity=.3)
+donut = ShapeStim(win, vertices=donutVert, fillColor='orange', lineWidth=0, size=.75, pos=(-.2,-.2))
+line1 = ShapeStim(win, vertices=line1Vert, closeShape=False, lineWidth=2, pos=(-.5,0), ori=180)
+boxed = ShapeStim(win, vertices=boxedVert, lineWidth=2, pos=(.5,-.3))
 
 #m = event.Mouse()
 while not event.getKeys():
     star7.setOri(1,'-')  # rotate
-    star7.setSize(-star7.ori%360 / 360)  # expand
+    star7.setSize(-star7.ori%720 / 720)  # expand
     star7.draw()
     thing.setOri(-star7.ori/7)  # rotate slowly
     thing.draw()
     arrow.draw()
     selfx.draw()
     donut.draw()
     line1.draw()
+    boxed.draw()
     win.flip()
     #if thing.contains(m): break

psychopy/visual/__init__.py

@@ -24,7 +24,7 @@
 
 lazyImports = """
 # stimuli derived from object or MinimalStim
-from psychopy.visual.aperture import Aperture
+from psychopy.visual.aperture import Aperture  # uses BaseShapeStim or ImageStim
 from psychopy.visual.custommouse import CustomMouse
 from psychopy.visual.elementarray import ElementArrayStim
 from psychopy.visual.ratingscale import RatingScale
@@ -37,13 +37,16 @@
 from psychopy.visual.movie import MovieStim
 from psychopy.visual.movie2 import MovieStim2
 from psychopy.visual.movie3 import MovieStim3
-from psychopy.visual.shape import ShapeStim
+from psychopy.visual.shape import BaseShapeStim
 
 # stimuli derived from GratingStim
 from psychopy.visual.bufferimage import BufferImageStim
 from psychopy.visual.patch import PatchStim
 from psychopy.visual.radial import RadialStim
 
+# stimuli derived from BaseShapeStim
+from psychopy.visual.shape import ShapeStim
+
 # stimuli derived from ShapeStim
 from psychopy.visual.line import Line
 from psychopy.visual.polygon import Polygon

psychopy/visual/shape.py

@@ -36,6 +36,9 @@ class BaseShapeStim(BaseVisualStim, ColorMixin, ContainerMixin):
     They can also be rotated (stim.setOri(__)), translated (stim.setPos(__)),
     and scaled (stim.setSize(__)) like any other stimulus.
 
+    BaseShapeStim is currently used by ShapeStim and Aperture (for basic shapes).
+    It is also retained in case backwards compatibility is needed.
+
     v1.84.00: ShapeStim became BaseShapeStim.
     """
     def __init__(self,
@@ -298,26 +301,33 @@ class ShapeStim(BaseShapeStim):
     """A class for arbitrary shapes defined as lists of vertices (x,y).
 
     Shapes can be lines, polygons (concave, convex, self-crossing), or have
-    holes or multiple regions (discontinuous).
+    holes or multiple regions.
 
     `vertices` is typically a list of points (x,y). By default, these are
     assumed to define a closed figure (polygon); set `closeShape=False` for a line.
     Individual vertices cannot be changed dynamically, but the stimulus as a whole
     can be rotated, translated, or scaled dynamically (using .ori, .pos, .size).
 
-    `vertices` can also be a list of loops, where each loop is a list of points
+    Advanced shapes: `vertices` can also be a list of loops, where each loop is a list of points
     (x,y), e.g., to define a shape with a hole. Borders and contains() are not
     supported for multi-loop stimuli.
 
     `windingRule` is an advanced feature to allow control over the GLU
-    tesselator winding rule (default: GLU_TESS_WINDING_ODD).
+    tesselator winding rule (default: GLU_TESS_WINDING_ODD). This is relevant
+    only for self-crossing or multi-loop shapes.
 
     See Coder demo > stimuli > filled_shapes.py
+
+    Changed Nov 2015: v1.84.00. Now allows filling of complex shapes. This
+    is almost completely backwards compatible, with one known exception:
+    Dynamically changing individual vertices is no longer supported. The
+    old version is accessible as `psychopy.visual.BaseShapeStim`.
     """
+    # Author: Jeremy Gray, November 2015, using psychopy.contrib.tesselate
     def __init__(self,
                  win,
                  units='',
-                 lineWidth=0,
+                 lineWidth=1.5,
                  lineColor='white',
                  lineColorSpace='rgb',
                  fillColor=None,
@@ -406,10 +416,11 @@ def draw(self, win=None, keepMatrix=False):
         """
         # mostly copied from ShapeStim. Uses GL_TRIANGLES and depends on
         # two arrays of vertices: tesselated (for fill) & original (for border)
-        # keepMatrix is needed by Aperture; retained here
+        # keepMatrix is needed by Aperture, although Aperture currently
+        # relies on BaseShapeStim instead
 
         if win is None:
-            win=self.win
+            win = self.win
         self._selectWindow(win)
 
         #scale the drawing frame etc...