Previous topic

DotStim

Next topic

GratingStim

This Page

Quick links

ElementArrayStim

class psychopy.visual.ElementArrayStim(win, units=None, fieldPos=(0.0, 0.0), fieldSize=(1.0, 1.0), fieldShape='circle', nElements=100, sizes=2.0, xys=None, rgbs=None, colors=(1.0, 1.0, 1.0), colorSpace='rgb', opacities=1.0, depths=0, fieldDepth=0, oris=0, sfs=1.0, contrs=1, phases=0, elementTex='sin', elementMask='gauss', texRes=48, interpolate=True, name=None, autoLog=None, maskParams=None)

This stimulus class defines a field of elements whose behaviour can be independently controlled. Suitable for creating ‘global form’ stimuli or more detailed random dot stimuli.

This stimulus can draw thousands of elements without dropping a frame, but in order to achieve this performance, uses several OpenGL extensions only available on modern graphics cards (supporting OpenGL2.0). See the ElementArray demo.

Parameters:
win :
a Window object (required)
units : None, ‘height’, ‘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.
nElements :
number of elements in the array.
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 logged automatically

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.

clearTextures()

Clear all textures associated with the stimulus. As of v1.61.00 this is called automatically during garbage collection of your stimulus, so doesn’t need calling explicitly by the user.

colorSpace

The type of color specified is the same as those in other stimuli (‘rgb’,’dkl’,’lms’...) but note that for this stimulus you cannot currently use text-based colors (e.g. names or hex values).

Keeping this exception in mind, see Color spaces for more info.

colors

Specifying the color(s) of the elements. Should be Nx1 (different intensities), Nx3 (different colors) or 1x3 (for a single color).

See other stimuli (e.g. GratingStim.color) for more info on the color attribute which essentially works the same on all PsychoPy stimuli. Remember that they describe just this case but here you can provide a list of colors - one color for each element.

Use setColors() if you want to set colors and colorSpace simultaneously or use operations on colors.

contrs

The contrasts of the elements, ranging -1 to +1. Should either be:

  • a single value
  • an Nx1 array/list

Operations are supported.

depth

(Nx1) list/array of ints. The depths of the elements, relative the overall depth of the field (fieldDepth).

operations are supported.

draw(win=None)

Draw the stimulus in its relevant window. You must call this method after every MyWin.update() if you want the stimulus to appear on that frame and then update the screen again.

elementMask

The mask, to be used by all elements (e.g. ‘circle’, ‘gauss’,... , ‘myTexture.tif’, numpy.ones([48,48])).

This is just a synonym for ElementArrayStim.mask. See doc there.

elementTex

The texture, to be used by all elements (e.g. ‘sin’, ‘sqr’,.. , ‘myTexture.tif’, numpy.ones([48,48])). Avoid this during time-critical points in your script. Uploading new textures to the graphics card can be time-consuming.

fieldDepth

Int. The depth of the field (will be added to the depths of the elements).

operations are supported.

fieldPos

x,y-pair. Set the centre of the array of elements.

Operations are supported.

fieldShape

The shape of the array (‘circle’ or ‘sqr’). Will only have effect if xys=None.

fieldSize

Scalar or x,y-pair. The size of the array of elements. This will be overridden by setting explicit xy positions for the elements.

Operations are supported.

mask

The alpha mask (forming the shape of the image)

This can be one of various options:
  • ‘circle’, ‘gauss’, ‘raisedCos’, ‘cross’, None (resets to default)
  • the name of an image file (most formats supported)
  • a numpy array (1xN or NxN) ranging -1:1
maskParams

Various types of input. Default to None. This is used to pass additional parameters to the mask if those are needed.

  • For ‘gauss’ mask, pass dict {‘sd’: 5} to control standard deviation.

  • For the ‘raisedCos’ mask, pass a dict: {‘fringeWidth’:0.2},

    where ‘fringeWidth’ is a parameter (float, 0-1), determining the proportion of the patch that will be blurred by the raised cosine edge.

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.

opacities

Set the opacity for each element. Should either be a single value or an Nx1 array/list

Operations are supported.

oris

(Nx1 or a single value) The orientations of the elements. Oris are in degrees, and can be greater than 360 and smaller than 0. An ori of 0 is vertical, and increasing ori values are increasingly clockwise.

operations are supported.

phases

The spatial phase of the texture on each element. Should either be:

  • a single value
  • an Nx1 array/list
  • an Nx2 array/list (for separate X and Y phase)

Operations are supported.

setAutoDraw(value, log=None)

Sets autoDraw. Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need 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

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

See color for more info on the color parameter and colorSpace for more info in the colorSpace parameter.

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

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

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

setMask(value, log=None)

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

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

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

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

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

Obselete - users should use setFieldPos or instead of setPos.

setRgbs(value, operation='')

DEPRECATED (as of v1.74.00). Please use setColors() instead

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

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

setTex(value, log=None)

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

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

sfs

The spatial frequency for each element. Should either be:

  • a single value
  • an Nx1 array/list
  • an Nx2 array/list (spatial frequency of the element in X and Y).

If the units for the stimulus are ‘pix’ or ‘norm’ then the units of sf are cycles per stimulus width. For units of ‘deg’ or ‘cm’ the units are c/cm or c/deg respectively.

operations are supported.

sizes

Set the size for each element. Should either be:

  • a single value
  • an Nx1 array/list
  • an Nx2 array/list

Operations are supported.

texRes

Power-of-two int. Sets the resolution of the mask and texture. texRes is overridden if an array or image is provided as mask.

Operations supported.

updateElementColors()

Create a new array of self._RGBAs based on self.rgbs. Not needed by the user (simple call setColors())

For element arrays the self.rgbs values correspond to one element so this function also converts them to be one for each vertex of each element

updateTextureCoords()

Create a new array of self._maskCoords

xys

The xy positions of the elements centres, relative to the field centre Values should be:

  • None
  • an array/list of Nx2 coordinates.

If value is None then the xy positions will be generated automatically, based on the fieldSize and fieldPos. In this case opacity will also be overridden by this function (it is used to make elements outside the field invisible).

operations are supported.