53
PsychoPy - Psychology software for Python, Release 1.84.0
Value should be one of:
• string: to specify a a Colors by name.
Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used.
• Colorsbyhexvalue
• numerically: (scalar or triplet) for DKL,RGB or otherColorspaces. For these,operations
are supported.
When color is specified using numbers, it is interpreted with respect to the stimulus’ current colorSpace.
If color is given as a single value (scalar)thenthis will be applied to all 3channels.
Examples:: # ... for whatever stim you have: stim.color = ‘white’ stim.color = ‘RoyalBlue’ # (the case
is actually ignored) stim.color =‘#DDA0DD’# DDA0DD is hexadecimal for plumstim.color = [1.0,
-1.0, -1.0] # if stim.colorSpace=’rgb’:
#a red color in rgb space
stim.color = [0.0, 45.0,1.0] # if stim.colorSpace=’dkl’: # DKL space with elev=0,azimuth=45
stim.color = [0, 0, 255] # if stim.colorSpace=’rgb255’: # a blue stimulus using rgb255 space
stim.color = 255 # interpretedas (255,255, 255) # which is white in rgb255.
OperationsworkasnormalforallnumericcolorSpaces(e.g.‘rgb’,‘hsv’and‘rgb255’)butnotforstrings,
like named and hex. For example,assuming that colorSpace=’rgb’:
stim.color += [1, , 1, , 1]
# increment all guns by 1 value
stim.color
*
= -1
# multiply the color by -1 (which in this
# space inverts the contrast)
stim.color
*
= [0.5, 0, 1]
# decrease red, remove green, keep blue
You can use setColor if you want to set colorand colorSpace in one line. These two are equivalent:
stim.setColor((0, 128, , 255), 'rgb255')
# ... is equivalent to
stim.colorSpace = 'rgb255'
stim.color = (0, , 128, 255)
colorSpace
The name of the color space currently being used
Value should be: a string orNone
For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used
(defined during initialisation).
Please note that changing colorSpace does not change stimulus parameters. Thus you usually want to
specify colorSpace before setting the color. Example:
# A light green text
stim = visual.TextStim(win, , 'Color me!',
color=(0, 1, , 0), colorSpace='rgb')
# An almost-black text
stim.colorSpace = 'rgb255'
# Make it light green again
stim.color = (128, 255, 128)
contains(x,y=None, units=None)
Returns True ifa point x,y is inside the stimulus’ border.
88
Chapter 8. Reference Manual (API)
58
PsychoPy - Psychology software for Python, Release 1.84.0
Canaccept variety ofinput options:
• two separate args,x and y
• one arg (list, tuple or array) containing two vals (x,y)
• an object with a getPos()methodthat returns x,y, such as aMouse.
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 yourstimulus 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
contrast
Avalue that is simply multiplied by the color
Value should be: a float between -1 (negative) and 1 (unchanged). . Operationssupported.
Set the contrast of the stimulus, i.e. scales how far the stimulus deviates from the middle grey. You can
also use the stimulus opacity to control contrast, but that cannot be negative.
Examples:
stim.contrast =
1.0
# unchanged contrast
stim.contrast =
0.5
# decrease contrast
stim.contrast =
0.0
# uniform, no contrast
stim.contrast = -0.5
# slightly inverted
stim.contrast = -1.0
# totally inverted
Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds
the monitorlimits.:
stim.contrast =
1.2
# increases contrast
stim.contrast = -1.2
# inverts with increased contrast
depth
DEPRECATED. Depth is now controlled simply by drawing order.
draw(win=None)
Draws the BufferImage on the screen, similar to ImageStim .draw(). Allows dynamic position,
size, rotation, mirroring, and opacity. Limitations / bugs: not sure what happens with shaders and
self._updateList()
flipHoriz
If set to True then the image will be flipped horizontally (left-to-right). Note that this is relative to the
original image,not relative to the current state.
flipVert
Ifset toTrue thenthe image willbe flipped vertically (left-to-right). Notethatthis is relative to the original
image, not relative to the current state.
image
The image file to be presented (most formats supported).
interpolate
Whetherto interpolate (linearly) the texture in the stimulus
Ifset to False then nearestneighbourwill be usedwhen needed,otherwise some formofinterpolationwill
be used.
8.2. psychopy.visual - many visual stimuli
89
47
PsychoPy - Psychology software for Python, Release 1.84.0
mask
The alpha mask that can be used to control the outer shape of the stimulus
•None,‘circle’,‘gauss’,‘raisedCos’
•or the name of an image file (most formats supported)
•or 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.
opacity
Determines how visible the stimulus is relative to background
The value should be a single float ranging 1.0 (opaque) to 0.0 (transparent). . Operationsare supported.
Precisely how this is used depends on theBlendMode.
ori
The orientation of the stimulus (in degrees).
Should be a single value (scalar).Operationsare supported.
Orientation convention is like a clock: 0 is vertical, and positive values rotate clockwise. Beyond 360 and
below zero values wrap appropriately.
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
pos
The position of the centerof the stimulus in the stimulusunits
value should be anx,y-pair.Operationsare also supported.
Example:
stim.pos = (0.5, 0)
# Set slightly to the right of center
stim.pos += (0.5, -1)
# Increment pos rightwards and upwards.
Is now (1.0, -1.0)
90
Chapter 8. Reference Manual (API)
50
PsychoPy - Psychology software for Python, Release 1.84.0
stim.pos
*
= 0.2
# Move stim towards the center.
Is now (0.2, -0.2)
Tip: Ifyou need the position of stimin pixels,you can obtain it like this:
frompsychopy.tools.monitorunittools import posToPix posPix = posToPix(stim)
setAutoDraw(value,log=None)
Sets autoDraw. Usuallyyoucanuse ‘stim.attribute= value’ syntaxinstead,but use this methodtosuppress
the log message.
setAutoLog(value=True, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
setColor(color, colorSpace=None, operation=’‘, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message and/orset colorSpace simultaneously.
setContrast(newContrast, operation=’‘, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
setDKL(newDKL, operation=’‘)
DEPRECATED since v1.60.05: Please use the color attribute
setDepth(newDepth,operation=’‘,log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
setFlipHoriz(newVal=True, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
setFlipVert(newVal=True, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
setImage(value,log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
setLMS(newLMS, operation=’‘)
DEPRECATED since v1.60.05: Please use the color attribute
setMask(value,log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
setOpacity(newOpacity, operation=’‘, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
setOri(newOri,operation=’‘,log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
setPos(newPos, operation=’‘, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message.
8.2. psychopy.visual - many visual stimuli
91
48
PsychoPy - Psychology software for Python, Release 1.84.0
setRGB(newRGB, operation=’‘, log=None)
DEPRECATED since v1.60.05: Please use the color attribute
setSize(newSize,operation=’‘, units=None, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
setUseShaders(value=True, log=None)
Usually you canuse ‘stim.attribute =value’syntax instead, but use this methodif you need to suppress the
log message
size
The size (width, height) of the stimulus in the stimulusunits
Value should bex,y-pair,scalar (applies to both dimensions) or None (resets to default).Operationsare
supported.
Sizes can be negative (causing a mirror-image reversal) and can extend beyond the window.
Example:
stim.size = 0.8
# Set size to (xsize, ysize) = (0.8, 0.8)
print(stim.size)
# Outputs array([0.8, 0.8])
stim.size += (0.5, -0.5)
# make wider and flatter: (1.3, 0.3)
Tip: if you can see the actual pixel range this corresponds to by looking at stim._sizeRendered
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.
Operationssupported.
units
None, ‘norm’,‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, or‘pix’
If None then the current units of theWindow will be used. SeeUnitsforthewindowandstimulifor
explanation of other options.
Note that when you change units, you don’t change the stimulus parameters and it is likely to change
appearance. Example:
# This stimulus is 20% wide and 50% tall with respect to window
stim = visual.PatchStim(win, units='norm', size=(0.2, 0.5)
# This stimulus is 0.2 degrees wide and 0.5 degrees tall.
stim.units = 'deg'
useShaders
Should shaders be used to render the stimulus (typically leave as True)
If the system support the use of OpenGL shader language then leaving this set to True is highly recom-
mended. If shaders cannot be used then various operations will be slower (notably, changes to stimulus
color orcontrast)
verticesPix
This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori,
pos and units
win
TheWindow object in which the stimulus will be rendered by default. (required)
92
Chapter 8. Reference Manual (API)
58
PsychoPy - Psychology software for Python, Release 1.84.0
Example, drawing same stimulus in two different windows and display simultaneously. Assuming that
you have two windows and a stimulus (win1,win2 and stim):
stim.win = win1
# stimulus will be drawn in win1
stim.draw()
# stimulus is now drawn to win1
stim.win = win2
# stimulus will be drawn in win2
stim.draw()
# it is now drawn in win2
win1.flip(waitBlanking=False)
# do not wait for next
# monitor update
win2.flip()
# wait for vertical blanking.
Note that this just changes
**
default
**
window for stimulus.
You could also specify window-to-draw-to when drawing::
stim.draw(win1)
stim.draw(win2)
8.2.3 Circle
class psychopy.visual.Circle(win, radius=0.5, edges=32, **kwargs)
Creates a Circle with a given radius as a special case of aShapeStim
(New in version 1.72.00)
Circle accepts all input parameters that ~psychopy.visual.ShapeStim accept,except for vertices and closeShape.
mro() → list
returna type’s method resolution order
8.2.4 CustomMouse
class psychopy.visual.CustomMouse(win,
newPos=None,
visible=True,
leftLimit=None,
topLimit=None,
rightLimit=None,
bottomLimit=None,
showLimitBox=False,
clickOnUp=False,
pointer=None,
name=None,autoLog=None)
Class for more control over the mouse, including the pointer graphic and bounding box.
Seems to work with pyglet or pygame. Not completely tested.
Known limitations: - only norm units are working - getRel() always returns [0,0] - mouseMoved() is always
False; maybe due to
self.mouse.visible == False ->held at [0,0]
•no idea if clickReset()works
Author: Jeremy Gray, 2011
Class for customizing the appearance and behavior ofthe mouse.
Use a custom mouse for extra control over the pointer appearance and function. It’s probably slower to render
than the regular system mouse. Create your visual.Window before creating a CustomMouse.
Parameters
win [required, visual.Window] the window to which this mouse is attached
visible [True orFalse] makes the mouse invisible if necessary
8.2. psychopy.visual - many visual stimuli
93
42
PsychoPy - Psychology software for Python, Release 1.84.0
newPos [None or [x,y]]gives the mouse a particular starting position
leftLimit : left edge of a virtual box within which the mouse canmove
topLimit : top edge of virtual box
rightLimit: right edge of virtual box
bottomLimit : lower edge of virtual box
showLimitBox [default is False] display the boundary within which the mouse can move.
pointer : The visualdisplay itemtouse as the pointer; must have .draw() and setPos()methods.
If your item has .setOpacity(),you can alter the mouse’s opacity.
clickOnUp [when to count a mouse click as having occurred] default is False, record a click
when the mouse is first pressed down. True means record a click when the mouse button is
released.
Note CustomMouse is a new feature, and subject to change. setPos() does not work yet. getRel()
returns [0,0] and mouseMoved()always returns False. clickReset() may not be working.
mro() → list
returna type’s method resolution order
8.2.5 DotStim
class psychopy.visual.DotStim(win, units=’‘, nDots=1, coherence=0.5, fieldPos=(0.0, 0.0), field-
Size=(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’, opac-
ity=1.0, contrast=1.0, depth=0, element=None, signalDots=’same’,
noiseDots=’direction’, name=None,autoLog=None)
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 forhow 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 seeDots(RDK)Componentin the Builder Components
section of the documentation.
If further customisation is required, then the DotStim should be subclassed and its _update_dotsXY and _new-
DotsXY methods overridden.
Parameters
fieldSize [(x,y)or[x,y] or singlevalue (applied to both]dimensions). Sizes can be negative and
can extend beyond the window.
mro() → list
returna type’s method resolution order
94
Chapter 8. Reference Manual (API)
Documents you may be interested
Documents you may be interested
