# psychopy.visual.Polygon¶

Stimulus class for drawing regular polygons.

## Overview¶

 Polygon(win[, edges, radius, units, …]) Creates a regular polygon (triangles, pentagons, …). Polygon.radius float, int, tuple, list or 2x1 array Radius of the Polygon (distance from the center to the corners). Polygon.edges Number of edges of the polygon. Polygon.units Units to use when drawing. Polygon.lineWidth Width of the line in pixels. Polygon.lineColor Alternative way of setting borderColor. Polygon.lineColorSpace Deprecated, please use colorSpace to set color space for the entire object. Polygon.fillColor Set the fill color for the shape. Polygon.fillColorSpace Deprecated, please use colorSpace to set color space for the entire object. Polygon.pos The position of the center of the stimulus in the stimulus units Polygon.size Sets the size of the shape. Polygon.ori The orientation of the stimulus (in degrees). Polygon.opacity Determines how visible the stimulus is relative to background. Polygon.contrast A value that is simply multiplied by the color. Polygon.depth DEPRECATED, depth is now controlled simply by drawing order. Polygon.interpolate If True the edge of the line will be anti-aliased. Polygon.name The name (str) of the object to be using during logged messages about this stim. Polygon.autoLog Whether every change in this stimulus should be auto logged. Polygon.autoDraw Determines whether the stimulus should be automatically drawn on every frame flip. Polygon.color Set the color of the shape. Polygon.colorSpace The name of the color space currently being used

## Details¶

class psychopy.visual.polygon.Polygon(win, edges=3, radius=0.5, units='', lineWidth=1.5, lineColor=None, lineColorSpace=None, fillColor=None, fillColorSpace=None, pos=(0, 0), size=1.0, ori=0.0, opacity=None, contrast=1.0, depth=0, interpolate=True, lineRGB=False, fillRGB=False, name=None, autoLog=None, autoDraw=False, color=None, colorSpace='rgb')[source]

Creates a regular polygon (triangles, pentagons, …).

This class is a special case of a ShapeStim that accepts the same parameters except closeShape and vertices.

Parameters
• win (Window) – Window this shape is being drawn to. The stimulus instance will allocate its required resources using that Windows context. In many cases, a stimulus instance cannot be drawn on different windows unless those windows share the same OpenGL context, which permits resources to be shared between them.

• edges (int) – Number of sides for the polygon (for instance, edges=3 will result in a triangle).

• radius (float) – Initial radius of the polygon in units. This specifies how far out to place the corners (vertices) of the shape.

• units (str) – Units to use when drawing. This will affect how parameters and attributes pos, size and radius are interpreted.

• lineWidth (float) – Width of the polygon’s outline.

• lineColor (array_like, str, Color or None) – Color of the shape’s outline and fill. If None, a fully transparent color is used which makes the fill or outline invisible.

• fillColor (array_like, str, Color or None) – Color of the shape’s outline and fill. If None, a fully transparent color is used which makes the fill or outline invisible.

• lineColorSpace (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.

• 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.

• pos (array_like) – Initial position (x, y) of the shape on-screen relative to the origin located at the center of the window or buffer in units. This can be updated after initialization by setting the pos property. The default value is (0.0, 0.0) which results in no translation.

• size (float or array_like) – Initial scale factor for adjusting the size of the shape. A single value (float) will apply uniform scaling, while an array (sx, sy) will result in anisotropic scaling in the horizontal (sx) and vertical (sy) direction. Providing negative values to size will cause the shape being mirrored. Scaling can be changed by setting the size property after initialization. The default value is 1.0 which results in no scaling.

• ori (float) – Initial orientation of the shape in degrees about its origin. Positive values will rotate the shape clockwise, while negative values will rotate counterclockwise. The default value for ori is 0.0 degrees.

• opacity (float) – Opacity of the shape. A value of 1.0 indicates fully opaque and 0.0 is fully transparent (therefore invisible). Values between 1.0 and 0.0 will result in colors being blended with objects in the background. This value affects the fill (fillColor) and outline (lineColor) colors of the shape.

• contrast (float) – Contrast level of the shape (0.0 to 1.0). This value is used to modulate the contrast of colors passed to lineColor and fillColor.

• depth (int) – Depth layer to draw the stimulus when autoDraw is enabled.

• interpolate (bool) – Enable smoothing (anti-aliasing) when drawing shape outlines. This produces a smoother (less-pixelated) outline of the shape.

• lineRGB (array_like, Color or None) – Deprecated. Please use lineColor and fillColor. These arguments may be removed in a future version.

• fillRGB (array_like, Color or None) – Deprecated. Please use lineColor and fillColor. These arguments may be removed in a future version.

• name (str) – Optional name of the stimuli for logging.

• autoLog (bool) – Enable auto-logging of events associated with this stimuli. Useful for debugging and to track timing when used in conjunction with autoDraw.

• autoDraw (bool) – Enable auto drawing. When True, the stimulus will be drawn every frame without the need to explicitly call the draw() method.

• color (array_like, str, Color or None) – Sets both the initial lineColor and fillColor of the shape.

• colorSpace (str) – Sets the colorspace, changing how values passed to lineColor and fillColor are interpreted.

_calcPosRendered()

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix.

_calcSizeRendered()

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix

_getDesiredRGB(rgb, colorSpace, contrast)

Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast

_getPolyAsRendered()

DEPRECATED. Return a list of vertices as rendered.

_selectWindow(win)

Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.

_set(attrib, val, op='', log=None)

DEPRECATED since 1.80.04 + 1. Use setAttribute() and val2array() instead.

_updateList()

The user shouldn’t need this method since it gets called after every call to .set() Chooses between using and not using shaders each call.

_updateVertices()

Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz

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.

property backColor

Alternative way of setting fillColor

closeShape

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

Set the color of the shape. Sets both fillColor and lineColor simultaneously if applicable.

property 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

property 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 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.

edges

Number of edges of the polygon. Floats are rounded to int.

Operations supported.

property fillColor

Set the fill color for the shape.

property fillColorSpace

Deprecated, please use colorSpace to set color space for the entire object.

property foreColor

Foreground color of the stimulus

Value should be one of:

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)

interpolate

If True the edge of the line will be anti-aliased.

property lineColor

Alternative way of setting borderColor.

property lineColorSpace

Deprecated, please use colorSpace to set color space for the entire object.

lineWidth

Width of the line in pixels.

Operations supported.

name

The name (str) 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.

property 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)

radius

float, int, tuple, list or 2x1 array Radius of the Polygon (distance from the center to the corners). May be a -2tuple or list to stretch the polygon asymmetrically.

Operations supported.

Usually there’s a setAttribute(value, log=False) method for each attribute. Use this if you want to disable logging.

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.

setBorderColor(color, colorSpace=None, operation='', log=None)

Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

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

Sets both the line and fill to be the same color.

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

setEdges(edges, operation='', log=None)[source]

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()

setForeColor(color, colorSpace=None, operation='', log=None)

Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

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()

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

Hard setter for opacity, allows the suppression of log messages and calls the update method

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

setRadius(radius, operation='', log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

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

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

Units to use when drawing.

Possible options are: 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'

updateColors()

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox

updateOpacity()

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox.

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.

If you’re using Polygon, Circle or Rect, this shouldn’t be used.

Operations supported.

property 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)