Aperture

Stimulus class to restrict a stimulus visibility area to a basic shape or list of vertices. This is a lazy-imported class, therefore import using full path from psychopy.visual.aperture import Aperture when inheriting from it.

Attributes

Aperture(win[, size, pos, anchor, ori, ...])

Restrict a stimulus visibility area to a basic shape or list of vertices.

Aperture.size

Set the size (diameter) of the Aperture.

Aperture.pos

Set the pos (centre) of the Aperture.

Aperture.ori

Set the orientation of the Aperture.

Aperture.inverted

True / False.

Aperture.name

The name (str) of the object to be using during logged messages about this stim.

Aperture.autoLog

Whether every change in this stimulus should be auto logged.

Details

class psychopy.visual.Aperture(win, size=1, pos=(0, 0), anchor=None, ori=0, nVert=120, shape='circle', inverted=False, units=None, name=None, depth=0, autoLog=None)[source]

Restrict a stimulus visibility area to a basic shape or list of vertices.

When enabled, any drawing commands will only operate on pixels within the Aperture. Once disabled, subsequent draw operations affect the whole screen as usual.

Supported shapes:

  • ‘square’, ‘triangle’, ‘circle’ or None: a polygon with appropriate nVerts will be used (120 for ‘circle’)

  • integer: a polygon with that many vertices will be used

  • list or numpy array (Nx2): it will be used directly as the vertices to a ShapeStim

  • a filename then it will be used to load and image as a ImageStim. Note that transparent parts in the image (e.g. in a PNG file) will not be included in the mask shape. The color of the image will be ignored.

See demos/stimuli/aperture.py for example usage

Author:

2011, Yuri Spitsyn 2011, Jon Peirce added units options, Jeremy Gray added shape & orientation 2014, Jeremy Gray added .contains() option 2015, Thomas Emmerling added ImageStim option

_reset()[source]

Internal method to rebuild the shape - shouldn’t be called by the user. You have to explicitly turn resetting off by setting self._needReset = False

_updateVertices()

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

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

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

disable()[source]

Use Aperture.enabled = False instead.

enable()[source]

Use Aperture.enabled = True instead.

enabled

True / False. Enable or disable the aperture. Determines whether it is used in future drawing operations.

NB. The Aperture is enabled by default, when created.

property flip
getAnchor()
getAutoDraw()
getAutoLog()
getEnabled()
getFlip()
getInverted()
getName()
getOri()
getPos()
getPosPix()
getSize()
getSizePix()
getVertices()
getVerticesPix()
get_borderPix()
invert()[source]

Use Aperture.inverted = True instead.

inverted

True / False. Set to true to invert the aperture. A non-inverted aperture masks everything BUT the selected shape. An inverted aperture masks the selected shape.

NB. The Aperture is not inverted by default, when created.

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.

ori

Set the orientation of the Aperture.

This essentially controls a ShapeStim so see documentation for ShapeStim.ori.

Operations supported here as well as ShapeStim.

Use setOri() if you want to control logging and resetting.

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

property pos

Set the pos (centre) of the Aperture. Operations supported.

This essentially controls a ShapeStim so see documentation for ShapeStim.pos.

Operations supported here as well as ShapeStim.

Use setPos() if you want to control logging and resetting.

property posPix

The position of the aperture in pixels

setAnchor(value, log=None)[source]
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.

setEnabled(value, log=None, operation=False, stealth=False)
setFlip(value, log=None, operation=False, stealth=False)
setInverted(value, log=None, operation=False, stealth=False)
setName(value, log=None, operation=False, stealth=False)
setOri(ori, needReset=True, log=None)[source]

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

setPos(pos, needReset=True, 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(size, needReset=True, log=None)[source]

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

setVertices(value, log=None, operation=False, stealth=False)
property size

Set the size (diameter) of the Aperture.

This essentially controls a ShapeStim so see documentation for ShapeStim.size.

Operations supported here as well as ShapeStim.

Use setSize() if you want to control logging and resetting.

property sizePix

The size of the aperture in pixels

property vertices
property verticesPix

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


Back to top