Table Of Contents

Previous topic

psychopy.core - basic functions (clocks etc.)

Next topic

psychopy.data - functions for storing/saving/analysing data

Quick links

psychopy.visual - many visual stimuli

To control the screen and visual stimuli for experiments

Window

class psychopy.visual.Window(size=(800, 600), pos=None, color=(0, 0, 0), colorSpace='rgb', rgb=None, dkl=None, lms=None, fullscr=None, allowGUI=None, monitor={}, bitsMode=None, winType=None, units=None, gamma=None, blendMode='avg', screen=0, viewScale=None, viewPos=None, viewOri=0.0, waitBlanking=True)

Used to set up a context in which to draw objects, using either PyGame (python’s SDL binding) or pyglet.

The pyglet backend allows multiple windows to be created, allows the user to specify which screen to use (if more than one is available, duh!) and allows movies to be rendered.

Pygame has fewer bells and whistles, but does seem a little faster in text rendering. Pygame is used for all sound production and for monitoring the joystick.

Parameters:
size : (800,600)

Size of the window in pixels (X,Y)

pos : None or (x,y)

Location of the window on the screen

rgb : [0,0,0]

Color of background as [r,g,b] list or single value. Each gun can take values betweeen -1 and 1

fullscr : None, True or False

Better timing can be achieved in full-screen mode

allowGUI : None, True or False (if None prefs are used)

If set to False, window will be drawn with no frame and no buttons to close etc...

winType : None, ‘pyglet’, ‘pygame’

If None then PsychoPy will revert to user/site preferences

monitor : None, string or a ~psychopy.monitors.Monitor object

The monitor to be used during the experiment

units : None, ‘norm’ (normalised),’deg’,’cm’,’pix’

Defines the default units of stimuli drawn in the window (can be overridden by each stimulus) See Units for the window and stimuli for explanation of options.

screen : 0, 1 (or higher if you have many screens)

Specifies the physical screen that stimuli will appear on (pyglet winType only)

viewScale : None or [x,y]

Can be used to apply a custom scaling to the current units of the Window.

viewPos : None, or [x,y]

If not None, redefines the origin for the window

viewOri : 0 or any numeric value

A single value determining the orientation of the view in degs

waitBlanking : None, True or False.

After a call to flip() should we wait for the blank before the script continues

gamma : 1.0,

Monitor gamma for linearisation (will use Bits++ if possible). Overrides monitor settings

bitsMode : None, ‘fast’, (‘slow’ mode is deprecated).

Defines how (and if) the Bits++ box will be used. ‘fast’ updates every frame by drawing a hidden line on the top of the screen.

note:Preferences. Some parameters (e.g. units) can now be given default values in the user/site preferences and these will be used if None is given here. If you do specify a value here it will take precedence over preferences.
clearBuffer()
Clear the back buffer (to which you are currently drawing) without flipping the window. Useful if you want to generate movie sequences from the back buffer without actually taking the time to flip the window.
close()
Close the window (and reset the Bits++ if necess).
flip(clearBuffer=True)

Flip the front and back buffers after drawing everything for your frame. (This replaces the win.update() method, better reflecting what is happening underneath).

win.flip(clearBuffer=True)#results in a clear screen after flipping win.flip(clearBuffer=False)#the screen is not cleared (so represent the previous screen)

fps()
Report the frames per second since the last call to this function (or since the window was created if this is first call)
getMovieFrame(buffer='front')

Capture the current Window as an image. This can be done at any time (usually after a .update() command).

Frames are stored in memory until a .saveMovieFrames(filename) command is issued. You can issue getMovieFrame() as often as you like and then save them all in one go when finished.

saveFrameIntervals(fileName=None, clear=True)

Save recorded screen frame intervals to disk, as comma-separated values.

Parameters:
fileName : None or the filename (including path if necessary) in which to store the data.
If None then ‘lastFrameIntervals.log’ will be used.
saveMovieFrames(fileName, mpgCodec='mpeg1video', fps=30)

Writes any captured frames to disk. Will write any format that is understood by PIL (tif, jpg, bmp, png...)

Parameters:
filename: name of file, including path (required)

The extension at the end of the file determines the type of file(s) created. If an image type is given the multiple static frames are created. If it is .gif then an animated GIF image is created (although you will get higher quality GIF by saving PNG files and then combining them in dedicated image manipulation software (e.g. GIMP). On windows and linux .mpeg files can be created if pymedia is installed. On OS X .mov files can be created if the pyobjc-frameworks-QTKit is installed.

mpgCodec: the code to be used by pymedia if the filename ends in .mpg

fps: the frame rate to be used throughout the movie only for quicktime (.mov) movies

Examples::
myWin.saveMovieFrames(‘frame.tif’)#writes a series of static frames as frame001.tif, frame002.tif etc... myWin.saveMovieFrames(‘stimuli.mov’, fps=25)#on OS X only myWin.saveMovieFrames(‘stimuli.gif’)#but not great quality myWin.saveMovieFrames(‘stimuli.mpg’)#not on OS X
setColor(color, colorSpace=None, operation='')

Set the color of the window.

NB This command sets the color that the blank screen will have on the next clear operation. As a result it effectively takes TWO flip() operations to become visible (the first uses the color to create the new screen the second presents that screen to the viewer).

See Color spaces for further information about the 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
setGamma(gamma)
Set the monitor gamma, using Bits++ if possible
setMouseVisible(visibility)

Sets the visibility of the mouse cursor.

If Window was initilised with noGUI=True then the mouse is initially set to invisible, otherwise it will initially be visible.

Usage:
setMouseVisible(False) setMouseVisible(True)
setRGB(newRGB)
Deprecated: As of v1.61.00 please use setColor() instead
setRecordFrameIntervals(value=True)

To provide accurate measures of frame intervals, to determine whether frames are being dropped. Set this to False while the screen is not being updated e.g. during event.waitkeys() and set to True during critical parts of the script

see also:
Window.saveFrameIntervals()
setScale(units, font='dummyFont', prevScale=(1.0, 1.0))

This method is called from within the draw routine and sets the scale of the OpenGL context to map between units. Could potentially be called by the user in order to draw OpenGl objects manually in each frame.

The units can be ‘norm’(normalised),’pix’(pixels),’cm’ or ‘stroke_font’. The font parameter is only used if units=’stroke_font’


PatchStim (images that can be rotated and blended)

class psychopy.visual.PatchStim(win, tex='sin', mask='none', units='', pos=(0.0, 0.0), size=None, sf=None, ori=0.0, phase=(0.0, 0.0), texRes=128, rgb=None, dkl=None, lms=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', contrast=1.0, opacity=1.0, depth=0, rgbPedestal=(0.0, 0.0, 0.0), interpolate=False)

Stimulus object for drawing arbitrary bitmaps, textures and shapes. One of the main stimuli for PsychoPy.

Formally PatchStim is just a texture behind an optional transparency mask (an ‘alpha mask’). Both the texture and mask can be arbitrary bitmaps and their combination allows an enormous variety of stimuli to be drawn in realtime.

Examples:

myGrat = PatchStim(tex='sin',mask='circle') #gives a circular patch of grating
myGabor = PatchStim(tex='sin',mask='gauss') #gives a 'Gabor' patchgrating
myImage = PatchStim(tex='face.jpg',mask=None) #simply draws the image face.jpg

An PatchStim can be rotated scaled and shifted in position, its texture can be drifted in X and/or Y and it can have a spatial frequency in X and/or Y (for an image file that simply draws multiple copies in the patch).

Also since transparency can be controlled two PatchStims can combine e.g. to form a plaid.

Using Patchstim with images from disk (jpg, tif, pgn...)

Ideally images to be rendered should be square with ‘power-of-2’ dimensions e.g. 16x16, 128x128. Any image that is not will be upscaled (with linear interp) to the nearest such texture by PsychoPy. The size of the stimulus should be specified in the normal way using the appropriate units (deg, pix, cm...). Be sure to get the aspect ration the same as the image (if you don’t want it stretched!).

Why can’t I have a normal image, drawn pixel-by-pixel? PatchStims are rendered using OpenGL textures. This is more powerful than using simple screen blitting - it allows the rotation, masking, transparency to work. It is still necessary to have power-of-2 textures on most graphics cards.

Parameters:
win :

a Window object (required)

tex :

The texture forming the image

  • ‘sin’,’sqr’, ‘saw’, ‘tri’, None
  • or the name of an image file (most formats supported)
  • or a numpy array (1xN or NxN) ranging -1:1
mask :

The alpha mask (forming the shape of the image)

  • None, ‘circle’, ‘gauss’
  • or the name of an image file (most formats supported)
  • or a numpy array (1xN or NxN) ranging -1:1
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.

pos :

a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. The origin is the screen centre, the units are determined by units (see above). Stimuli can be position beyond the window!

size :

a tuple (0.5,0.5) or a list [0.5,0.5] for the x and y OR a single value (which will be applied to x and y). Units are specified by ‘units’ (see above). Sizes can be negative and can extend beyond the window.

sf:

a tuple (1.0,1.0) or a list [1.0,1.0] for the x and y OR a single value (which will be applied to x and y). Where units == ‘deg’ or ‘cm’ units are in cycles per deg/cm. If units == ‘norm’ then sf units are in cycles per stimulus (so scale with stimulus size). If texture is an image loaded from a file then sf defaults to 1/stim size to give one cycle of the image.

ori:

orientation of stimulus in degrees

phase:

a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y OR a single value (which will be applied to x and y). Phase of the stimulus in each direction. NB phase has modulus 1 (rather than 360 or 2*pi) This is a little unconventional but has the nice effect that setting phase=t*n drifts a stimulus at n Hz

texRes:

resolution of the texture (if not loading from an image file)

color:

Could be a the web name for a color (e.g. ‘FireBrick’); a hex value (e.g. ‘#FF0047’); a tuple (1.0,1.0,1.0); a 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

contrast:

How far the stimulus deviates from the middle grey. Contrast can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).

opacity:

1.0 is opaque, 0.0 is transparent

depth:

This can potentially be used (not tested!) to choose which stimulus overlays which. (more negative values are nearer). At present the window does not do perspective rendering but could do if that’s really useful(?!)

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.flip() if you want the stimulus to appear on that frame and then update the screen again.
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setContrast(value, operation='')
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setMask(value)
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPhase(value, operation='')
setPos(newPos, operation='', units=None)
Set the stimulus position in the specified (or inheritted) units
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setSF(value, operation='')
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) units
setTex(value)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.

SimpleImageStim - for drawing simple images

class psychopy.visual.SimpleImageStim(win, image='', units='', pos=(0.0, 0.0), contrast=1.0, opacity=1.0, flipHoriz=False, flipVert=False)

A simple stimulus for loading images from a file and presenting at exactly the resolution and color in the file (subject to gamma correction if set).

Unlike the PatchStim, this type of stimulus cannot be rescaled, rotated or masked (although flipping horizontally or vertically is possible). Drawing will also tend to be marginally slower, because the image isn’t preloaded to the gfx card. The advantage, however is that the stimulus will always be in its original aspect ratio, with no interplotation or other transformation. It is always

SimpleImageStim does not support a depth parameter (the OpenGL method that draws the pixels does not support it). Simple images will obscure any other stimulus type.

Also, unlike the PatchStim (whose textures should be square and power-of-two in size, there is no restriction on the size of images for the SimpleImageStim

Parameters:
win :

a Window object (required)

image :

The filename, including relative or absolute path. The image can be any format that the Python Imagin Library can import (which is almost all).

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.

pos :

a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. The origin is the screen centre, the units are determined by units (see above). Stimuli can be position beyond the window!

contrast :

How far the stimulus deviates from the middle grey. Contrast can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus)

opacity :

1.0 is opaque, 0.0 is transparent

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.
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setFlipHoriz(newVal=True)
If set to True then the image will be flipped horiztonally (left-to-right). Note that this is relative to the original image, not relative to the current state.
setFlipVert(newVal=True)
If set to True then the image will be flipped vertically (top-to-bottom). Note that this is relative to the original image, not relative to the current state.
setImage(filename=None)
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPos(newPos, operation='', units=None)
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) units
setUseShaders(val=True)
Set this stimulus to use shaders if possible.

TextStim

class psychopy.visual.TextStim(win, text='Hello World', font='', pos=(0.0, 0.0), depth=0, rgb=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', opacity=1.0, units='', ori=0.0, height=None, antialias=True, bold=False, italic=False, alignHoriz='center', alignVert='center', fontFiles=[], wrapWidth=None)

Class of text stimuli to be displayed in a Window

Parameters:
win: A Window object.

Required - the stimulus must know where to draw itself

text:

The text to be rendered

pos:

Position on the screen

depth:

Depth on the screen (if None it will be defined on .draw() to be in front of the last object drawn)

color:

The color of the text (ranging [-1,-1,-1] to [1,1,1]) NB: parameter rgb=() is deprecated.

colorSpace: ‘rgb’

The color-space to use.

opacity:

How transparent the object will be (0 for transparent, 1 for opaque)

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.

ori:

Orientation of the text

height:

Height of the characters (including the ascent of the letter and the descent)

antialias:

boolean to allow (or not) antialiasing the text

bold:

Make the text bold (better to use a bold font name)

italic:

Make the text italic (better to use an actual italic font)

alignHoriz:

The horizontal alignment (‘left’, ‘right’ or ‘center’)

alignVert:

The vertical alignment (‘top’, ‘bottom’ or ‘center’)

fontFiles:

A list of additional files if the font is not in the standard system location (include the full path)

wrapWidth:

The width the text should run before wrapping

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.

If win is specified then override the normal window of this stimulus.

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
setContr(newContr, operation='')
Set the contrast of the stimulus
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setFont(font)
Set the font to be used for text rendering. font should be a string specifying the name of the font (in system resources)
setHeight(height)
Set the height of the letters (including the entire box that surrounds the letters in the font). The width of the letters is then defined by the font.
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPos(newPos, operation='', units=None)
Set the stimulus position in the specified (or inheritted) units
setRGB(value, operation='')
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) units
setText(value=None)
Set the text to be rendered using the current font
setUseShaders(val=True)
Set this stimulus to use shaders if possible.

MovieStim

class psychopy.visual.MovieStim(win, filename='', units='pix', size=None, pos=(0.0, 0.0), ori=0.0, flipVert=False, flipHoriz=False, opacity=1.0)

A stimulus class for playing movies (mpeg, avi, etc...) in PsychoPy.

examples:

mov = visual.MovieStim(myWin, 'testMovie.mp4', fliVert=False)
print mov.duration
print mov.format.width, mov.format.height #give the original size of the movie in pixels

mov.draw() #draw the current frame (automagically determined)

See MovieStim.py for demo.

Parameters:
win :

a Window object (required)

filename :

a string giving the relative or absolute path to the movie. Can be any movie that AVbin can read (e.g. mpeg, DivX)

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.

pos :

position of the centre of the movie, given in the units specified

flipVert : True or False

If True then the movie will be top-bottom flipped

flipHoriz : True or False

If True then the movie will be right-left flipped

ori :

Orientation of the stimulus in degrees

size :

Size of the stimulus in units given. If not specified then the movie will take its original dimensions.

opacity :

the movie can be made transparent by reducing this

draw(win=None)

Draw the current frame to a particular visual.Window (or to the default win for this object if not specified). The current position in the movie will be determined automatically.

This method should be called on every frame that the movie is meant to appear

loadMovie(filename)
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPos(newPos, operation='', units=None)
Set the stimulus position in the specified (or inheritted) units
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) units
setUseShaders(val=True)
Set this stimulus to use shaders if possible.

ShapeStim

class psychopy.visual.ShapeStim(win, units='', lineWidth=1.0, lineColor=(1.0, 1.0, 1.0), lineColorSpace='rgb', fillColor=(0.0, 0.0, 0.0), fillColorSpace='rgb', vertices=((-0.5, 0), (0, 0.5), (0.5, 0)), closeShape=True, pos=(0, 0), ori=0.0, opacity=1.0, depth=0, interpolate=True, lineRGB=None, fillRGB=None)

Create geometric (vector) shapes by defining vertex locations.

Shapes can be outlines or filled, by setting lineRGB and fillRGB to rgb triplets, or None. They can also be rotated (stim.setOri(__)) and translated (stim.setPos(__)) like any other stimulus.

NB for now the fill of objects is performed using glBegin(GL_POLYGON) and that is limited to convex shapes. With concavities you get unpredictable results (e.g. add a fill color to the arrow stim below). To create concavities, you can combine multiple shapes, or stick to just outlines. (If anyone wants to rewrite ShapeStim to use glu tesselators that would be great!)

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.

lineRGB :

  • (r,g,b) or [r,g,b]
  • or a single intensity value (which will be applied to all guns).

NB units range -1:1 (so 0.0 is GREY). See RGB color space for details.

fillRGB :

  • (r,g,b) or [r,g,b]
  • or a single intensity value (which will be applied to all guns).

NB units range -1:1 (so 0.0 is GREY). See RGB color space for details.

lineWidth : int (or float?)

specifying the line width in pixels

vertices : a list of lists or a numpy array (Nx2)

specifying xy positions of each vertex

closeShape : True or False

Do you want the last vertex to be automatically connected to the first?

pos : tuple, list or 2x1 array

the position of the anchor for the stimulus (relative to which the vertices are drawn)

ori : float or int

the shape can be rotated around the anchor

opacity : float

1.0 is opaque, 0.0 is transparent

depth : 0

This can be used to choose which stimulus overlays which. (more negative values are nearer). At present the window does not do perspective rendering but could do if that’s really useful(?!)

interpolate : True or False

If True the edge of the line will be antialiased.

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.
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setFillColor(color, colorSpace=None, operation='')
setFillRGB(value, operation='')
DEPRECATED since v1.60.05: Please use setFillColor
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color, colorSpace=None, operation='')
setLineRGB(value, operation='')
DEPRECATED since v1.60.05: Please use setLineColor
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPos(newPos, operation='', units=None)
Set the stimulus position in the specified (or inheritted) units
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) units
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None, operation='')

Set the xy values of the vertices (relative to the centre of the field). Values should be:

  • an array/list of Nx2 coordinates.

RadialStim

class psychopy.visual.RadialStim(win, tex='sqrXsqr', mask='none', units='', pos=(0.0, 0.0), size=(1.0, 1.0), radialCycles=3, angularCycles=4, radialPhase=0, angularPhase=0, ori=0.0, texRes=64, angularRes=100, visibleWedge=(0, 360), rgb=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', dkl=None, lms=None, contrast=1.0, opacity=1.0, depth=0, rgbPedestal=(0.0, 0.0, 0.0), interpolate=False)

Stimulus object for drawing radial stimuli, like an annulus, a rotating wedge, a checkerboard etc...

Ideal for fMRI retinotopy stimuli!

Many of the capabilities are built on top of the PatchStim.

This stimulus is still relatively new and I’m finding occasional gliches. it also takes longer to draw than a typical PatchStim, so not recommended for tasks where high frame rates are needed.

Parameters:
win :

a Window object (required)

tex :

The texture forming the image

  • ‘sqrXsqr’, ‘sinXsin’, ‘sin’,’sqr’,None
  • or the name of an image file (most formats supported)
  • or a numpy array (1xN or NxN) ranging -1:1
mask :

Unlike the mask in the PatchStim, this is a 1-D mask dictating the behaviour from the centre of the stimulus to the surround.

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.

pos :

a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. Stimuli can be position beyond the window!

size :

a tuple (0.5,0.5) or a list [0.5,0.5] for the x and y OR a single value (which will be applied to x and y). Sizes can be negative and stimuli can extend beyond the window.

ori :

orientation of stimulus in degrees.

texRes : (default= 128 )

resolution of the texture (if not loading from an image file)

angularRes : (default= 100 )

100, the number of triangles used to make the sti

radialPhase :

the phase of the texture from the centre to the perimeter of the stimulus

angularPhase :

the phase of the texture around the stimulus

rgb :

a tuple (1.0,1.0, 1.0) or a list [1.0,1.0, 1.0] or a single value (which will be applied to all guns). RGB vals are applied to simple textures and to greyscale image files but not to RGB images.

NB units range -1:1 (so 0.0 is GREY). See RGB color space for further info.

dkl : a tuple (45.0,90.0, 1.0) or a list [45.0,90.0, 1.0]

specifying the coordinates of the stimuli in cone-opponent space (Derrington, Krauskopf, Lennie 1984). See DKL color space for further info. Triplets represent [elevation, azimuth, magnitude]. Note that the monitor must be calibrated for this to be accurate (if not, example phosphors from a Sony Trinitron CRT will be used).

lms : a tuple (0.5, 1.0, 1.0) or a list [0.5, 1.0, 1.0]

specifying the coordinates of the stimuli in cone space Triplets represent relative modulation of each cone [L, M, S]. See LMS color space for further info. Note that the monitor must be calibrated for this to be accurate (if not, example phosphors from a Sony Trinitron CRT will be used).

contrast : (default= 1.0 )

How far the stimulus deviates from the middle grey. Contrast can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus)

opacity :

1.0 is opaque, 0.0 is transparent

depth :

This can potentially be used (not tested!) to choose which stimulus overlays which. (more negative values are nearer). At present the window does not do perspective rendering but could do if that’s really useful(?!)

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.flip() if you want the stimulus to appear on that frame and then update the screen again.

If win is specified then override the normal window of this stimulus.

setAngularCycles(value, operation='')
set the number of cycles going around the stimulus
setAngularPhase(value, operation='')
set the angular phase of the texture
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setContrast(value, operation='')
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth, operation='')
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setMask(value)
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPhase(value, operation='')
setPos(newPos, operation='', units=None)
Set the stimulus position in the specified (or inheritted) units
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setRadialCycles(value, operation='')
set the number of texture cycles from centre to periphery
setRadialPhase(value, operation='')
set the radial phase of the texture
setSF(value, operation='')
setSize(value, operation='')
setTex(value)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.

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=(1.0, 1.0, 1.0), opacities=1.0, depths=0, fieldDepth=0, oris=0, sfs=1.0, contrs=1, phases=0, elementTex='sin', elementMask='gauss', texRes=48)

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, ‘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)

rgbs :

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

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)

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()
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.
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='')

Set the rgb for each element. Should either be:

  • a single value
  • an Nx1 array/list
  • an Nx3 array/list
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.

updataElementColors()
Create a new array of self._RGBAs
updataTextureCoords()
Create a new array of self._maskCoords
updateElementVertices()

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='different', noiseDots='position')

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 standard 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’ from frame to 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).

‘Movshon’-type noise uses a random position, rather than random direction, for the noise dots and the signal dots are distinct (noiseDots=’different’). This has the disadvantage that the noise dots not only have a random direction but also a random speed (so differ in two ways from the signal dots). The default option for DotStim is that the dots follow a random walk, with the dot and noise elements being randomised each frame. This provides greater certainty that individual dots cannot be used to determine the motion direction.

When dots go out of bounds or reach the end of their life they are given a new random position. As a result, to prevent inhomogeneities arising in the dots distribution across the field, a limitted lifetime dot is strongly recommended.

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 : a single value, specifying the diameter of the field

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 chosen signal dots remain the same on each frame. If ‘different’ they are randomly chosen each frame. This paramater corresponds to Scase et al’s (1996) categories of RDK.

noiseDots : ‘position’,’direction’ 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.

rgb : (r,g,b) or [r,g,b] or a single intensity value

or a single value (which will be applied to all guns). RGB vals are applied to simple textures and to greyscale image files but not to RGB images. NB units range -1:1 (so 0.0 is GREY). See RGB color space for further info.

opacity : float

1.0 is opaque, 0.0 is transparent

depth : 0,

This can be used to choose which stimulus overlays which. (more negative values are nearer). At present the window does not do perspective rendering but could do if that’s really useful(?!)

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.

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.
set(attrib, val, op='')
DotStim.set() is obselete and may not be supported in future versions of PsychoPy. Use the specific method for each parameter instead (e.g. setFieldPos(), setCoherence()...)
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
setContr(newContr, operation='')
Set the contrast of the stimulus
setDKL(newDKL, operation='')
DEPRECATED since v1.60.05: Please use setColor
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='')
setLMS(newLMS, operation='')
DEPRECATED since v1.60.05: Please use setColor
setOpacity(newOpacity, operation='')
setOri(newOri, operation='')
Set the stimulus orientation in degrees
setPos(newPos=None, operation='', units=None)
Obselete - users should use setFieldPos or instead of setPos
setRGB(newRGB, operation='')
DEPRECATED since v1.60.05: Please use setColor
setSize(newSize, operation='', units=None)
Set the stimulus size [X,Y] in the specified (or inheritted) 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.

RatingScale

class psychopy.visual.RatingScale(win, scale=None, low=1, high=7, precision=1, showValue=True, showScale=True, showAnchors=True, showAccept=True, acceptKeys=[, 'return'], acceptPreText='key click', acceptText='accept?', markerStyle='triangle', markerColor=None, markerExpansion=1, markerStart=False, allowSkip=True, escapeKeys=[, 'escape'], mouseOnly=False, displaySizeFactor=1.0, offsetVert=-0.40000000000000002, offsetHoriz=0.0, minTime=1.0)

A class for getting numeric subjective ratings, e.g., on a 1 to 7 scale.

Returns a rating-scale object, with display parameters defined at init().

The .draw() method displays the scale only (not the item to be rated), handles the subject’s response, and updates the display. When the subject responds, .noResponse goes False (i.e., there is a response). You can then call .getRating() to obtain the rating, or getRT() to get the decision time. The experimenter has to handle the item to be rated, and ensure its in the same visual window as the RatingScale. A RatingScale instance has no idea what else is on the screen.

The default settings should be good much of the time, but considerable customization is possible using the options. Auto-rescaling happens if the low-anchor is 0 and high-low is a multiple of 10.

Example:

myRatingScale = visual.RatingScale(myWin)
while myRatingScale.noResponse:
    myItem.draw()  # RatingScale knows nothing about the item(s) to be rated: text, image, movie, ...
    myRatingScale.draw()
    myWin.flip()
rating = myRatingScale.getRating()
decisionTime = myRatingScale.getRT()

See ‘ratingScale.py’ for a demo.

Author:
  • 2010 Jeremy Gray
Parameters:
win :

A Window object (required)

scale :

string, explanation of the numbers to display to the subject; None -> <low>=not at all, <high>=extremely

low :

lowest rating / low anchor (integer, default = 1)

high :

highest rating / high anchor (integer, default = 7; at least low+1)

precision :

portions of a tick to accept as input [1,10,100], default = 1 tick (no fractional part)

showValue :

show the currently selected number, default = True

showScale :

show the scale text, default = True

showAnchors :

show the two end points of the scale, default = True

showAccept :

show the button to accept the current value by using the mouse, default = True;

Note

If False, then you must have acceptKeys be non-empty (so that the subject can respond at all)

acceptKeys :

list of keys to accept as indicating “accept the current response”, default = [‘return’]

acceptPreText :

text to display before any value has been selected

acceptText :

text to display in the ‘accept’ button after a value has been selected

markerStyle :

‘triangle’ (DarkBlue), ‘circle’ (DarkRed), or ‘glow’ (White)

markerColor :

None = use defaults; or any legal RGB colorname, e.g., ‘#123456’, ‘DarkRed’

markerExpansion :

how much the glow marker expands when moving to the right; 0=none, negative shrinks; try 10 or -10

markerStart :

False, or the value in [low..high] to be pre-selected upon initial display

allowSkip :

if True, the subject can skip an item by pressing a key in escapeKeys, or <esc> if escapeKeys == []

escapeKeys :

list of keys the subject can use to skip a response, default = [‘escape’]

Note

Don’t use an empty list to make the subject respond to every item; use allowSkip=False

mouseOnly :

whether to require the subject to use only the mouse (no keys), default = False.

Note

MouseOnly=True and showAccept=False is a bad combination, so showAccept wins (mouseOnly ignored); mouseOnly and allowSkip conflict, because skipping an item is done via key press: mouseOnly wins

displaySizeFactor :

how much to expand or contract the overall rating scale display (not just the line length)

offsetVert :

how much to shift the rating line up or down on the screen, norm units; default -0.4, try -0.7 for images

offsetHoriz:

how much to shift right - left, norm units; default = 0.0 (centered)

minTime :

number of seconds that must elapse before a reponse can be accepted, default = 1.0s NB: to enforce a max response time (upper limit), just present the ratingScale for that long.

draw()
update visual display, check for subject response (key, mouse, skip), set self.noResponse as appropriate. draw() only draws the rating scale, not the item to be rated
getRT()
Returns the seconds taken to make the rating (or to indicate skip). Returns None if no rating available.
getRating()
Returns the numerical rating; None if the subject skipped this item; False if not available.
reset()
restores to post-init state; does not restore scaleDescription text needed between items when rating multiple items