`ShapeStim`¶

Attributes¶

`ShapeStim`(win[, units, lineWidth, ...])	A class for arbitrary shapes defined as lists of vertices (x,y).
`ShapeStim.win`	The `Window` object in which the stimulus will be rendered by default.
`ShapeStim.units`	None, ‘norm’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, or ‘pix’
`ShapeStim.vertices`	A list of lists or a numpy array (Nx2) specifying xy positions of each vertex, relative to the center of the field.
`ShapeStim.closeShape`	True or False
`ShapeStim.pos`	The position of the center of the stimulus in the stimulus
`ShapeStim.ori`	The orientation of the stimulus (in degrees).
`ShapeStim.size`	Int/Float or x,y-pair.
`ShapeStim.contrast`	A value that is simply multiplied by the color
`ShapeStim.lineColor`	Sets the color of the shape lines.
`ShapeStim.lineColorSpace`	Sets color space for line color.
`ShapeStim.fillColor`	Sets the color of the shape fill.
`ShapeStim.fillColorSpace`	Sets color space for fill color.
`ShapeStim.opacity`	Determines how visible the stimulus is relative to background
`ShapeStim.interpolate`	True or False If True the edge of the line will be antialiased.
`ShapeStim.name`	String or None.
`ShapeStim.autoLog`	Whether every change in this stimulus should be auto logged.
`ShapeStim.draw`([win, keepMatrix])	Draw the stimulus in the relevant window.
`ShapeStim.autoDraw`	Determines whether the stimulus should be automatically drawn on every frame flip.

Details¶

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

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.

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. closeShape cannot be changed dynamically, but individual vertices can be changed on a frame-by-frame basis. The stimulus as a whole can be rotated, translated, or scaled dynamically (using .ori, .pos, .size).

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). This is relevant only for self-crossing or multi-loop shapes. Cannot be set dynamically.

See Coder demo > stimuli > shapes.py

Changed Nov 2015: v1.84.00. Now allows filling of complex shapes. This is almost completely backwards compatible (see changelog). The old version is accessible as psychopy.visual.BaseShapeStim.

autoDraw¶

Determines whether the stimulus should be automatically drawn on every frame flip.

Value should be: True or False. You do NOT need to set this on every frame flip!

autoLog¶

Whether every change in this stimulus should be auto logged.

Value should be: True or False. Set to False if your stimulus is updating frequently (e.g. updating its position every

frame) and you want to avoid swamping the log file with

messages that aren’t likely to be useful.

closeShape¶

True or False Should the last vertex be automatically connected to the first?

If you’re using Polygon, Circle or Rect, closeShape=True is assumed and shouldn’t be changed.

color¶

Color of the stimulus

Value should be one of:

string: to specify a Colors by name. Any of the standard html/X11 color names <http://www.w3schools.com/html/html_colornames.asp> can be used.
Colors by hex value
numerically: (scalar or triplet) for DKL, RGB or

other Color spaces. For these, operations are supported.

When color is specified using numbers, it is interpreted with respect to the stimulus’ current colorSpace. If color is given as a single value (scalar) then this will be applied to all 3 channels.

Examples::

# ... for whatever stim you have: stim.color = ‘white’ stim.color = ‘RoyalBlue’ # (the case is actually ignored) stim.color = ‘#DDA0DD’ # DDA0DD is hexadecimal for plum stim.color = [1.0, -1.0, -1.0] # if stim.colorSpace=’rgb’:

# a red color in rgb space

stim.color = [0.0, 45.0, 1.0] # if stim.colorSpace=’dkl’:: # DKL space with elev=0, azimuth=45
stim.color = [0, 0, 255] # if stim.colorSpace=’rgb255’:: # a blue stimulus using rgb255 space
stim.color = 255 # interpreted as (255, 255, 255): # which is white in rgb255.

Operations work as normal for all numeric colorSpaces (e.g. ‘rgb’, ‘hsv’ and ‘rgb255’) but not for strings, like named and hex. For example, assuming that colorSpace=’rgb’:

stim.color += [1, 1, 1]  # increment all guns by 1 value
stim.color *= -1  # multiply the color by -1 (which in this
                    # space inverts the contrast)
stim.color *= [0.5, 0, 1]  # decrease red, remove green, keep blue

You can use setColor if you want to set color and colorSpace in one line. These two are equivalent:

stim.setColor((0, 128, 255), 'rgb255')
# ... is equivalent to
stim.colorSpace = 'rgb255'
stim.color = (0, 128, 255)

colorSpace¶

The name of the color space currently being used

Value should be: a string or None

For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).

Please note that changing colorSpace does not change stimulus parameters. Thus you usually want to specify colorSpace before setting the color. Example:

# A light green text
stim = visual.TextStim(win, 'Color me!',
                       color=(0, 1, 0), colorSpace='rgb')

# An almost-black text
stim.colorSpace = 'rgb255'

# Make it light green again
stim.color = (128, 255, 128)

contains(x, y=None, units=None)¶

Returns True if a point x,y is inside the stimulus’ border.

Can accept variety of input options:

two separate args, x and y
one arg (list, tuple or array) containing two vals (x,y)
an object with a getPos() method that returns x,y, such

as a Mouse.

Returns True if the point is within the area defined either by its border attribute (if one defined), or its vertices attribute if there is no .border. This method handles complex shapes, including concavities and self-crossings.

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

See Coder demos: shapeContains.py See Coder demos: shapeContains.py

contrast¶

A value that is simply multiplied by the color

Value should be: a float between -1 (negative) and 1 (unchanged).: Operations supported.

Set the contrast of the stimulus, i.e. scales how far the stimulus deviates from the middle grey. You can also use the stimulus opacity to control contrast, but that cannot be negative.

Examples:

stim.contrast =  1.0  # unchanged contrast
stim.contrast =  0.5  # decrease contrast
stim.contrast =  0.0  # uniform, no contrast
stim.contrast = -0.5  # slightly inverted
stim.contrast = -1.0  # totally inverted

Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds the monitor limits.:

stim.contrast =  1.2  # increases contrast
stim.contrast = -1.2  # inverts with increased contrast

depth¶: DEPRECATED. Depth is now controlled simply by drawing order.

draw(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.

fillColor¶

Sets the color of the shape fill.

See psychopy.visual.GratingStim.color() for further details of how to use colors.

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

fillColorSpace¶: Sets color space for fill color. See documentation for fillColorSpace

interpolate¶: True or False If True the edge of the line will be antialiased.

lineColor¶

Sets the color of the shape lines.

See psychopy.visual.GratingStim.color() for further details of how to use colors.

lineColorSpace¶: Sets color space for line color. See documentation for lineColorSpace

lineWidth¶

int or float specifying the line width in pixels

Operations supported.

name¶

String or None. The name of the object to be using during logged messages about this stim. If you have multiple stimuli in your experiment this really helps to make sense of log files!

If name = None your stimulus will be called “unnamed <type>”, e.g. visual.TextStim(win) will be called “unnamed TextStim” in the logs.

opacity¶

Determines how visible the stimulus is relative to background

The value should be a single float ranging 1.0 (opaque) to 0.0 (transparent). Operations are supported. Precisely how this is used depends on the Blend Mode.

ori¶

The orientation of the stimulus (in degrees).

Should be a single value (scalar). Operations are supported.

Orientation convention is like a clock: 0 is vertical, and positive values rotate clockwise. Beyond 360 and below zero values wrap appropriately.

overlaps(polygon)¶

Returns True 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 typically very good, but it can fail with very pointy shapes in a crossed-swords configuration.

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

pos¶

The position of the center of the stimulus in the stimulus units

value should be an x,y-pair. Operations are also supported.

Example:

stim.pos = (0.5, 0)  # Set slightly to the right of center
stim.pos += (0.5, -1)  # Increment pos rightwards and upwards.
    Is now (1.0, -1.0)
stim.pos *= 0.2  # Move stim towards the center.
    Is now (0.2, -0.2)

Tip: If you need the position of stim in pixels, you can obtain it like this:

from psychopy.tools.monitorunittools import posToPix posPix = posToPix(stim)

setAutoDraw(value, log=None)¶: Sets autoDraw. Usually you can use ‘stim.attribute = value’ syntax instead, but use this method to suppress the log message.

setAutoLog(value=True, log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setColor(color, colorSpace=None, operation='')¶: For ShapeStim use lineColor() or fillColor()

setContrast(newContrast, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setDKL(newDKL, operation='')¶: DEPRECATED since v1.60.05: Please use the color attribute

setDepth(newDepth, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

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

Sets the color of the shape fill.

See psychopy.visual.GratingStim.color() for further details.

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

setFillRGB(value, operation='')¶: DEPRECATED since v1.60.05: Please use fillColor()

setLMS(newLMS, operation='')¶: DEPRECATED since v1.60.05: Please use the color attribute

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

Sets the color of the shape edge.

See psychopy.visual.GratingStim.color() for further details.

setLineRGB(value, operation='')¶: DEPRECATED since v1.60.05: Please use lineColor()

setLineWidth(value, operation='', log=None)¶

setOpacity(newOpacity, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setOri(newOri, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setPos(newPos, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setRGB(newRGB, operation='', log=None)¶: DEPRECATED since v1.60.05: Please use the color attribute

setSize(value, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setUseShaders(value=True, log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setVertices(value=None, operation='', log=None)¶: Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

size¶

Int/Float or x,y-pair. 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.

Operations supported.

units¶

None, ‘norm’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, 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.

Note that when you change units, you don’t change the stimulus parameters and it is likely to change appearance. Example:

# This stimulus is 20% wide and 50% tall with respect to window
stim = visual.PatchStim(win, units='norm', size=(0.2, 0.5)

# This stimulus is 0.2 degrees wide and 0.5 degrees tall.
stim.units = 'deg'

useShaders¶

Should shaders be used to render the stimulus (typically leave as True)

If the system support the use of OpenGL shader language then leaving this set to True is highly recommended. If shaders cannot be used then various operations will be slower (notably, changes to stimulus color or contrast)

vertices¶

A list of lists or a numpy array (Nx2) specifying xy positions of each vertex, relative to the center of the field.

Assigning to vertices can be slow if there are many vertices.

Operations supported with .setVertices().

verticesPix¶: This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units

win¶

The Window object in which the: stimulus will be rendered by default. (required)

Example, drawing same stimulus in two different windows and display simultaneously. Assuming that you have two windows and a stimulus (win1, win2 and stim):

   stim.win = win1  # stimulus will be drawn in win1
   stim.draw()  # stimulus is now drawn to win1
   stim.win = win2  # stimulus will be drawn in win2
   stim.draw()  # it is now drawn in win2
   win1.flip(waitBlanking=False)  # do not wait for next
                # monitor update
   win2.flip()  # wait for vertical blanking.

Note that this just changes **default** window for stimulus.
You could also specify window-to-draw-to when drawing::

   stim.draw(win1)
   stim.draw(win2)

Table Of Contents

Previous topic

Next topic

This Page

Quick links

`ShapeStim`¶

Attributes¶

Details¶

Navigation

Table Of Contents

Previous topic

Next topic

This Page

Quick links

ShapeStim¶

Attributes¶

Details¶

Navigation

`ShapeStim`¶