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='', autoLog=True)

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.

fieldPos :

The centre of the array of elements

fieldSize :

The size of the array of elements (this will be overridden by setting explicit xy positions for the elements)

fieldShape :

The shape of the array (‘circle’ or ‘sqr’)

nElements :

number of elements in the array

sizes :

an array of sizes Nx1, Nx2 or a single value

xys :

the xy positions of the elements, relative to the field centre (fieldPos)

colors :

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

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)

opacities :

the opacity of each element (Nx1 or a single value)

depths :

the depths of the elements (Nx1), relative the overall depth of the field (fieldDepth)

fieldDepth :

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

oris :

the orientations of the elements (Nx1 or a single value)

sfs :

the spatial frequencies of the elements (Nx1, Nx2 or a single value)

contrs :

the contrasts of the elements, ranging -1 to +1 (Nx1 or a single value)

phases :

the spatial phase of the texture on the stimulus (Nx1 or a single value)

elementTex :

the texture, to be used by all elements (e.g. ‘sin’, ‘sqr’,.. , ‘myTexture.tif’, numpy.ones([48,48]))

elementMask :

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

texRes :

the number of pixels in the textures (overridden if an array or image is provided)

name : string

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

clearTextures()

Clear the textures associated with the given 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.

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.

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

Set the color of the stimulus. See Color spaces for further information about the various ways to specify colors and their various implications.

Parameters :

color :

Can be specified in one of many ways.

You must provide a triplet of values, which refer to the coordinates in one of the Color spaces. If no color space is specified then the color space most recently used for this stimulus is used again.

myStim.setColor([1.0,-1.0,-1.0], ‘rgb’)#a red color in rgb space myStim.setColor([0.0,45.0,1.0], ‘dkl’) #DKL space with elev=0, azimuth=45 myStim.setColor([0,0,255], ‘rgb255’) #a blue stimulus using rgb255 space

Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].

myStim.setColor(255, ‘rgb255’) #all guns o max

colorSpace : string or None

defining which of the Color spaces to use. For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).

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

for colors specified as a triplet of values (or single intensity value) the new value will perform this operation on the previous color

thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value thisStim.setColor(-1, ‘rgb’, ‘*’) #multiply the color by -1 (which in this space inverts the contrast) thisStim.setColor([10,0,0], ‘dkl’, ‘+’)#raise the elevation from the isoluminant plane by 10 deg

setContrs(value, operation='')

Set the contrast for each element. Should either be:

• a single value
• an Nx1 array/list

setFieldPos(value, operation='')

Set the centre of the array (X,Y)

setFieldSize(value, operation='')

Set the size of the array on the screen (will override current XY positions of the elements)

setMask(value)

Change the mask (all elements have the same mask). Avoid doing this during time-critical points in your script. Uploading new textures to the graphics card can be time-consuming.

setOpacities(value, operation='')

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

setOris(value, operation='')

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

setPhases(value, operation='')

Set the phase for each element. Should either be:

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

setPos(newPos=None, operation='', units=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='')

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

setSizes(value, operation='')

Set the size for each element. Should either be:

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

setTex(value)

Change the texture (all elements have the same base texture). Avoid this during time-critical points in your script. Uploading new textures to the graphics card can be time-consuming.

setXYs(value=None, operation='')

Set the xy values of the element centres (relative to the centre of the field). 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.

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

updateElementVertices()

updateTextureCoords()

Create a new array of self._maskCoords