|
|
|
|
|
TextStim¶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, contrast=1.0, units='', ori=0.0, height=None, antialias=True, bold=False, italic=False, alignHoriz='center', alignVert='center', fontFiles=(), wrapWidth=None, flipHoriz=False, flipVert=False, name=None, autoLog=None)¶Class of text stimuli to be displayed in a
Window
Performance OBS: in general, TextStim is slower than many other
visual stimuli, i.e. it takes longer to change some attributes.
In general, it’s the attributes that affect the shapes of the letters:
text, height, font, bold etc.
These make the next .draw() slower because that sets the text again.
You can make the draw() quick by calling re-setting the text
(myTextStim.text = myTextStim.text) when you’ve changed the
parameters.
In general, other attributes which merely affect the presentation of
unchanged shapes are as fast as usual. This includes pos,
opacity etc.
alignHoriz¶The horizontal alignment (‘left’, ‘right’ or ‘center’)
alignVert¶The vertical alignment (‘top’, ‘bottom’ or ‘center’)
antialias¶Allow antialiasing the text (True or False). Sets text, slow.
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 auto logged.
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.
bold¶Make the text bold (True, False). Better to use a bold font name).
boundingBox¶(read only) attribute representing the bounding box of the text (w,h). This differs from width in that the width represents the width of the margins, which might differ from the width of the text within them.
NOTE: currently always returns the size in pixels (this will change to return in stimulus units)
color¶Color of the stimulus
string: to specify a Colors by name. Any of the standard html/X11 color names <http://www.w3schools.com/html/html_colornames.asp> can be used.
other Color spaces. 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) then this will be applied to all 3 channels.
# ... for whatever stim you have: stim.color = ‘white’ stim.color = ‘RoyalBlue’ # (the case is actually ignored) stim.color = ‘#DDA0DD’ # DDA0DD is hexadecimal for plum stim.color = [1.0, -1.0, -1.0] # if stim.colorSpace=’rgb’:
# a red color in rgb space
Operations work as normal for all numeric colorSpaces (e.g. ‘rgb’, ‘hsv’ and ‘rgb255’) but not for strings, 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 color and 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 or None
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)
contrast¶A value that is simply multiplied by the color
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 monitor limits.:
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)¶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.
flipHoriz¶If set to True then the text will be flipped left-to-right. The flip is relative to the original, not relative to the current state.
flipVert¶If set to True then the text will be flipped top-to-bottom. The flip is relative to the original, not relative to the current state.
font¶String. Set the font to be used for text rendering. font should be a string specifying the name of the font (in system resources).
fontFiles¶A list of additional files if the font is not in the standard system location (include the full path).
OBS: fonts are added every time this value is set. Previous are not deleted.
E.g.:
stim.fontFiles = ['SpringRage.ttf'] # load file(s)
stim.font = 'SpringRage' # set to font
height¶The height of the letters (Float/int or None = set default).
Height includes the entire box that surrounds the letters in the font. The width of the letters is then defined by the font.
Operations supported.
italic¶True/False. Make the text italic (better to use a italic font name).
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). Operations are supported. Precisely how this is used depends on the Blend Mode.
ori¶The orientation of the stimulus (in degrees).
Should be a single value (scalar). Operations are supported.
Orientation convention is like a clock: 0 is vertical, and positive values rotate clockwise. Beyond 360 and below zero values wrap appropriately.
pos¶The position of the center of the stimulus in the stimulus units
value should be an x,y-pair. Operations are 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)
stim.pos *= 0.2 # Move stim towards the center.
Is now (0.2, -0.2)
Tip: If you need the position of stim in pixels, you can obtain it like this:
from psychopy.tools.monitorunittools import posToPix posPix = posToPix(stim)
posPix¶This determines the coordinates in pixels of the position for the current stimulus, accounting for pos and units. This property should automatically update if pos is changed
setAutoDraw(value, log=None)¶Sets autoDraw. Usually you can use ‘stim.attribute = value’ syntax instead, but use this method 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.
setColor(color, colorSpace=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 and/or set colorSpace simultaneously.
setContrast(newContrast, operation='', log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if 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 can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
setFlip(direction, log=None)¶(used by Builder to simplify the dialog)
setFlipHoriz(newVal=True, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setFlipVert(newVal=True, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
setFont(font, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setHeight(height, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setLMS(newLMS, operation='')¶DEPRECATED since v1.60.05: Please use the color attribute
setOpacity(newOpacity, operation='', log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
setOri(newOri, 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, operation='', log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setRGB(newRGB, operation='', log=None)¶DEPRECATED since v1.60.05: Please use the color attribute
setSize(newSize, operation='', units=None, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
setText(text=None, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setUseShaders(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
size¶The size (width, height) of the stimulus in the stimulus units
Value should be x,y-pair, scalar (applies to both dimensions) or None (resets to default). Operations are 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
text¶The text to be rendered. Use \n to make new lines.
Issues: May be slow, and pyglet has a memory leak when setting text. For these reasons, check and only update the text if it has changed. So scripts can safely set the text on every frame, no need to check.
units¶None, ‘norm’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, 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.
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 recommended. If shaders cannot be used then various operations will be slower (notably, changes to stimulus color or contrast)
win¶Window object in which theExample, 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)
wrapWidth¶Int/float or None (set default). The width the text should run before wrapping.
Operations supported.