DotStim

class psychopy.visual.DotStim(win, units='', nDots=1, coherence=0.5, fieldPos=(0.0, 0.0), fieldSize=(1.0, 1.0), fieldShape='sqr', dotSize=2.0, dotLife=3, dir=0.0, speed=0.5, rgb=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', opacity=1.0, depth=0, element=None, signalDots='same', noiseDots='direction', name='', autoLog=True)

This stimulus class defines a field of dots with an update rule that determines how they change on every call to the .draw() method.

This single class can be used to generate a wide variety of dot motion types. For a review of possible types and their pros and cons see Scase, Braddick & Raymond (1996). All six possible motions they describe can be generated with appropriate choices of the signalDots (which determines whether signal dots are the ‘same’ or ‘different’ on each frame), noiseDots (which determines the locations of the noise dots on each frame) and the dotLife (which determines for how many frames the dot will continue before being regenerated).

The default settings (as of v1.70.00) is for the noise dots to have identical velocity but random direction and signal dots remain the ‘same’ (once a signal dot, always a signal dot).

For further detail about the different configurations see Dots (RDK) Component in the Builder Components section of the documentation.

If further customisation is required, then the DotStim should be subclassed and its _update_dotsXY and _newDotsXY methods overridden.

Parameters :

win :

a Window object (required)

units : None, ‘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.

nDots : int

number of dots to be generated

fieldPos : (x,y) or [x,y]

specifying the location of the centre of the stimulus.

fieldSize : (x,y) or [x,y] or single value (applied to both dimensions)

Sizes can be negative and can extend beyond the window.

fieldShape : ‘sqr’ or ‘circle’

Defines the envelope used to present the dots

dotSize

specified in pixels (overridden if element is specified)

dotLife : int

Number of frames each dot lives for (default=3, -1=infinite)

dir : float (degrees)

direction of the coherent dots

speed : float

speed of the dots (in units/frame)

signalDots : ‘same’ or ‘different’

If ‘same’ then the signal and noise dots are constant. If different then the choice of which is signal and which is noise gets randomised on each frame. This corresponds to Scase et al’s (1996) categories of RDK.

noiseDots : ‘direction’, ‘position’ or ‘walk’

Determines the behaviour of the noise dots, taken directly from Scase et al’s (1996) categories. For ‘position’, noise dots take a random position every frame. For ‘direction’ noise dots follow a random, but constant direction. For ‘walk’ noise dots vary their direction every frame, but keep a constant speed.

color:

Could be a:

• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.

If the last three are used then the color space should also be given See Color spaces

colorSpace:

The color space controlling the interpretation of the color See Color spaces

opacity : float

1.0 is opaque, 0.0 is transparent

depth:

The depth argument is deprecated and may be removed in future versions. Depth is controlled simply by drawing order.

element : None or a visual stimulus object

This can be any object that has a .draw() method and a .setPos([x,y]) method (e.g. a PatchStim, TextStim...)!! See ElementArrayStim for a faster implementation of this idea.

name : string

The name of the object to be using during logged messages about this stimulus

draw(win=None)

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.

setAutoDraw(val)

Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip

Parameters :

• val: True/False

  True to add the stimulus to the draw list, False to remove it

setAutoLog(val=True)

Turn on (or off) autoLogging for this stimulus.

Parameters :

• val: True (default) or False

setColor(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. If a string is given then it is interpreted as the name of the color. Any of the standard html/X11 color names <http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:

myStim.setColor('white')
myStim.setColor('RoyalBlue')#(the case is actually ignored)

A hex value can be provided, also formatted as with web colors. This can be provided as a string that begins with # (not using python’s usual 0x000000 format):

myStim.setColor('#DDA0DD')#DDA0DD is hexadecimal for plum

You can also 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

setDepth(newDepth, operation='')

setDir(val, op='')

Change the direction of the signal dots (units in degrees)

setFieldCoherence(val, op='')

Change the coherence (%) of the DotStim. This will be rounded according to the number of dots in the stimulus.

setFieldPos(val, op='')

setOpacity(newOpacity, operation='')

setOri(newOri, operation='')

Set the stimulus orientation in degrees

setSize(newSize, operation='', units=None)

Set the stimulus size [X,Y] in the specified (or inherited) units

setSpeed(val, op='')

Change the speed of the dots (in stimulus units per second)

setUseShaders(val=True)

Set this stimulus to use shaders if possible.