ShapeStim

class psychopy.visual.ShapeStim(win, units='', lineWidth=1.0, lineColor=(1.0, 1.0, 1.0), lineColorSpace='rgb', fillColor=None, fillColorSpace='rgb', vertices=((-0.5, 0), (0, 0.5), (0.5, 0)), closeShape=True, pos=(0, 0), size=1, ori=0.0, opacity=1.0, contrast=1.0, depth=0, interpolate=True, lineRGB=None, fillRGB=None, name='', autoLog=True)

Create geometric (vector) shapes by defining vertex locations.

Shapes can be outlines or filled, by setting lineRGB and fillRGB to rgb triplets, or None. They can also be rotated (stim.setOri(__)) and translated (stim.setPos(__)) like any other stimulus.

NB for now the fill of objects is performed using glBegin(GL_POLYGON) and that is limited to convex shapes. With concavities you get unpredictable results (e.g. add a fill color to the arrow stim below). To create concavities, you can combine multiple shapes, or stick to just outlines. (If anyone wants to rewrite ShapeStim to use glu tesselators that would be great!)

Parameters :

win :

A Window object (required)

units : None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’

If None then the current units of the Window will be used. See Units for the window and stimuli for explanation of other options.

lineColor :

Could be a:

• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.

If the last three are used then the color space should also be given See Color spaces

lineColorSpace:

The color space controlling the interpretation of the lineColor. See Color spaces

fillColor :

Could be a:

• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.

If the last three are used then the color space should also be given See Color spaces

lineWidth : int (or float?)

specifying the line width in pixels

vertices : a list of lists or a numpy array (Nx2)

specifying xy positions of each vertex

closeShape : True or False

Do you want the last vertex to be automatically connected to the first?

pos : tuple, list or 2x1 array

the position of the anchor for the stimulus (relative to which the vertices are drawn)

size : float, int, tuple, list or 2x1 array

Scales the ShapeStim up or down. Size is independent of the units, i.e. setting the size to 1.5 will make the stimulus to be 1.5 times it’s original size as defined by the vertices. Use a 2-tuple to scale asymmetrically.

ori : float or int

the shape can be rotated around the anchor

opacity : float (default= 1.0 )

1.0 is opaque, 0.0 is transparent

contrast: float (default= 1.0 )

How far the stimulus deviates from the middle grey. Contrast can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).

depth:

The depth argument is deprecated and may be removed in future versions. Depth is controlled simply by drawing order.

interpolate : True or False

If True the edge of the line will be antialiased.

name : string

The name of the object to be using during logged messages about this stim

contains(x, y=None)

Determines if a point x,y is inside the extent of the stimulus.

Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos() method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices. This handles complex shapes, including concavities and self-crossings.

Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings (and by the vertices for shape stimuli).

See coder demo, shapeContains.py

draw(win=None)

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.

overlaps(polygon)

Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can fail with pointy shapes. Returns True if the two shapes overlap.

Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings (and by the vertices for shape stimuli).

See coder demo, shapeContains.py

setAutoDraw(val, log=True)

Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do NOT need to call this on every frame flip!

Parameters :

• val: True/False

  True to add the stimulus to the draw list, False to remove it

setAutoLog(val=True)

Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an individual set() operation using the log=False argument.

Parameters :

• val: True (default) or False

setColor(color, colorSpace=None, operation='')

For ShapeStim use setLineColor() or setFillColor()

setContrast(newContrast, operation='', log=True)

” Set the contrast of the stimulus.

Parameters :

newContrast : float

The contrast of the stimulus:

# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged

# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.

# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)

WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus to blacker-than-black or whiter-than-white.

operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)

setDKL(newDKL, operation='')

DEPRECATED since v1.60.05: Please use setColor

setDepth(newDepth, operation='', log=True)

setFillColor(color, colorSpace=None, operation='', log=True)

Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further details of how to use this function.

Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.

setFillRGB(value, operation='')

DEPRECATED since v1.60.05: Please use setFillColor()

setLMS(newLMS, operation='')

DEPRECATED since v1.60.05: Please use setColor

setLineColor(color, colorSpace=None, operation='', log=True)

Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further details of how to use this function.

setLineRGB(value, operation='')

DEPRECATED since v1.60.05: Please use setLineColor()

setOpacity(newOpacity, operation='', log=True)

Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).

operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)

setOri(newOri, operation='', log=True)

Set the stimulus orientation in degrees

setPos(newPos, operation='', units=None, log=True)

Set the stimulus position in the specified (or inherited) units

setRGB(newRGB, operation='')

DEPRECATED since v1.60.05: Please use setColor

setSize(value, operation='', log=True)

Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.

setUseShaders(val=True)

Set this stimulus to use shaders if possible.

setVertices(value=None, operation='', log=True)

Set the xy values of the vertices (relative to the centre of the field). Values should be:

• an array/list of Nx2 coordinates.