GratingStim¶
|
Stimulus object for drawing arbitrary bitmaps that can repeat (cycle) in either dimension. |
The |
|
Texture to used on the stimulus as a grating (aka carrier). |
|
The alpha mask (forming the shape of the image). |
|
Spatial frequency of the grating texture. |
|
The position of the center of the stimulus in the stimulus units |
|
The orientation of the stimulus (in degrees). |
|
The size (width, height) of the stimulus in the stimulus units |
|
A value that is simply multiplied by the color. |
|
Alternative way of setting foreColor. |
|
The name of the color space currently being used |
|
Determines how visible the stimulus is relative to background. |
|
Whether to interpolate (linearly) the texture in the stimulus. |
|
Power-of-two int. |
|
The name (str) of the object to be using during logged messages about this stim. |
|
Whether every change in this stimulus should be auto logged. |
|
|
Draw the stimulus in its relevant window. |
Determines whether the stimulus should be automatically drawn on every frame flip. |
Stimulus object for drawing arbitrary bitmaps that can repeat (cycle) in either dimension. This is a lazy-imported class, therefore import using full path from psychopy.visual.grating import GratingStim when inheriting from it.
One of the main stimuli for PsychoPy.
Formally GratingStim 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.
A GratingStim 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 GratingStim objects can be combined (e.g. to form a plaid.)
Using GratingStim with images from disk (jpg, tif, png, …)
Ideally texture images to be rendered should be square with ‘power-of-2’ dimensions e.g. 16 x 16, 128 x 128. Any image that is not will be up-scaled (with linear interpolation) 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 ratio the same as the image (if you don’t want it stretched!).
win (Window) – Window this shape is being drawn to. The stimulus instance will allocate
its required resources using that Windows context. In many cases, a
stimulus instance cannot be drawn on different windows unless those
windows share the same OpenGL context, which permits resources to be
shared between them.
tex (str or None) – Texture to use for the primary carrier. Values may be one of ‘sin’, ‘sin’, ‘sqr’, ‘saw’, ‘tri’, or None.
mask (str or None) – Optional mask to control the shape of the grating. Values may be one of ‘circle’, ‘sin’, ‘sqr’, ‘saw’, ‘tri’, or None.
units (str) – Units to use when drawing. This will affect how parameters and attributes pos, size and radius are interpreted.
anchor (str) – Anchor string to specify the origin of the stimulus.
pos (array_like) – Initial position (x, y) of the shape on-screen relative to the origin located at the center of the window or buffer in units. This can be updated after initialization by setting the pos property. The default value is (0.0, 0.0) which results in no translation.
size (array_like, float, int or None) – Width and height of the shape as (w, h) or [w, h]. If a single value is provided, the width and height will be set to the same specified value. If None is specified, the size will be set with values passed to width and height.
sf (float) – Spatial frequency for the grating. Values are dependent on the units in use to draw the stimuli.
ori (float) – Initial orientation of the shape in degrees about its origin. Positive values will rotate the shape clockwise, while negative values will rotate counterclockwise. The default value for ori is 0.0 degrees.
phase (ArrayLike) – Initial phase of the grating along the vertical and horizontal dimension (x, y).
texRes (int) – Resolution of the texture. The higher the resolutions, the less aliasing artifacts will be visible. However, this comes at the expense of higher video memory use. Power-of-two values are recommended (e.g. 256, 512, 1024, etc.)
color (array_like, str, Color or None) – Sets both the initial lineColor and fillColor of the shape.
colorSpace (str) – Sets the colorspace, changing how values passed to lineColor and fillColor are interpreted.
contrast (float) – Contrast level of the shape (0.0 to 1.0). This value is used to modulate the contrast of colors passed to lineColor and fillColor.
opacity (float) – Opacity of the shape. A value of 1.0 indicates fully opaque and 0.0 is fully transparent (therefore invisible). Values between 1.0 and 0.0 will result in colors being blended with objects in the background. This value affects the fill (fillColor) and outline (lineColor) colors of the shape.
depth (int) – Depth layer to draw the shape when autoDraw is enabled. DEPRECATED
rgbPedestal (ArrayLike) – Pedestal color (r, g, b), presently unused.
interpolate (bool) – Enable smoothing (anti-aliasing) when drawing shape outlines. This produces a smoother (less-pixelated) outline of the shape.
draggable (bool) – Can this stimulus be dragged by a mouse click?
lineRGB (ArrayLike, Color or None) – Deprecated. Please use lineColor and fillColor. These arguments
may be removed in a future version.
fillRGB (ArrayLike, Color or None) – Deprecated. Please use lineColor and fillColor. These arguments
may be removed in a future version.
name (str) – Optional name of the stimuli for logging.
autoLog (bool) – Enable auto-logging of events associated with this stimuli. Useful for debugging and to track timing when used in conjunction with autoDraw.
autoDraw (bool) – Enable auto drawing. When True, the stimulus will be drawn every frame
without the need to explicitly call the
draw() method.
Examples
Creating a circular grating with a sinusoidal pattern:
myGrat = GratingStim(tex='sin', mask='circle')
Create a ‘Gabor’:
myGabor = GratingStim(tex='sin', mask='gauss')
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
DEPRECATED
DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix.
DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix
Create a new OpenGL 2D image texture.
tex (Any) – Texture data. Value can be anything that resembles image data.
id (int or GLint) – Texture ID.
pixFormat (GLenum or int) – Pixel format to use, values can be GL_ALPHA or GL_RGB.
stim (Any) – Stimulus object using the texture.
res (int) – The resolution of the texture (unless a bitmap image is used).
maskParams (dict or None) – Additional parameters to configure the mask used with this texture.
forcePOW2 (bool) – Force the texture to be stored in a square memory area. For grating stimuli (anything that needs multiple cycles) forcePOW2 should be set to be True. Otherwise the wrapping of the texture will not work.
dataType (class:~pyglet.gl.GLenum, int or None) – None, GL_UNSIGNED_BYTE, GL_FLOAT. Only affects image files (numpy arrays will be float).
wrapping (bool) – Enable wrapping of the texture. A texture will be set to repeat (or tile).
Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast
DEPRECATED. Return a list of vertices as rendered.
Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.
DEPRECATED since 1.80.04 + 1. Use setAttribute() and val2array() instead.
The user shouldn’t need this method since it gets called after every call to .set() Chooses between using and not using shaders each call.
The user shouldn’t need this method since it gets called after every call to .set() Basically it updates the OpenGL representation of your stimulus if some parameter of the stimulus changes. Call it if you change a property manually rather than using the .set() command
Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz
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!
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.
Alternative way of setting fillColor
Deprecated, please use colorSpace to set color space for the entire object.
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
DEPRECATED
Alternative way of setting fillColor
The OpenGL mode in which the stimulus is draw
Can the ‘avg’ or ‘add’. Average (avg) places the new stimulus over the old one with a transparency given by its opacity. Opaque stimuli will hide other stimuli transparent stimuli won’t. Add performs the arithmetic sum of the new stimulus and the ones already present.
Deprecated, please use colorSpace to set color space for the entire object
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
DEPRECATED
Clear all textures associated with the 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.
Alternative way of setting foreColor.
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)
Returns True if a point x,y is inside the stimulus’ border.
two separate args, x and y
one arg (list, tuple or array) containing two vals (x,y)
as a Mouse.
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 your stimulus 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 See Coder demos: shapeContains.py
A value that is simply multiplied by the color.
Operations supported.
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
DEPRECATED, depth is now controlled simply by drawing order.
If this stimulus is draggable, do the necessary actions on a frame flip to drag it.
Can this stimulus be dragged by a mouse click?
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.
win (~psychopy.visual.Window or None) – Window to draw the stimulus to. Context sharing must be enabled if any other window beside the one specified during creation of this stimulus is specified.
Set the fill color for the shape.
Deprecated, please use colorSpace to set color space for the entire object.
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
DEPRECATED
1x2 array for flipping vertices along each axis; set as True to flip or False to not flip. If set as a single value, will duplicate across both axes. Accessing the protected attribute (._flip) will give an array of 1s and -1s with which to multiply vertices.
Alternative way of setting foreColor.
Foreground 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.
Examples
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
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 # interpreted as (255, 255, 255)
# which is white in rgb255.
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)
Deprecated, please use colorSpace to set color space for the entire object.
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
DEPRECATED
Whether to interpolate (linearly) the texture in the stimulus.
If set to False then nearest neighbour will be used when needed, otherwise some form of interpolation will be used.
Alternative way of setting borderColor.
Deprecated, please use colorSpace to set color space for the entire object
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
DEPRECATED
The alpha mask (forming the shape of the image).
‘circle’, ‘gauss’, ‘raisedCos’, ‘cross’
None (resets to default)
the name of an image file (most formats supported)
a numpy array (1xN or NxN) ranging -1:1
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.
The name (str) 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.
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.
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.
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
Phase of the stimulus in each dimension of the texture.
Should be an x,y-pair or scalar
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.
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)
Sets autoDraw. Usually you can use ‘stim.attribute = value’ syntax instead, but use this method to suppress the log message.
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
DEPRECATED since v1.60.05: Please use the color attribute
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
DEPRECATED since v1.60.05: Please use the color attribute
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
Hard setter for opacity, allows the suppression of log messages and calls the update method
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
DEPRECATED. Use ‘stim.parameter = value’ syntax instead
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
DEPRECATED. Use ‘stim.parameter = value’ syntax instead
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
Spatial frequency of the grating texture.
Should be a x,y-pair or scalar or None. If units == ‘deg’ or ‘cm’ units are in cycles per deg or cm as appropriate. If units == ‘norm’ then sf units are in cycles per stimulus (and so SF scales with stimulus size). If texture is an image loaded from a file then sf=None defaults to 1/stimSize to give one cycle of the image.
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
Texture to used on the stimulus as a grating (aka carrier).
‘sin’,’sqr’, ‘saw’, ‘tri’, None (resets to default)
the name of an image file (most formats supported)
a numpy array (1xN or NxN) ranging -1:1
If specifying your own texture using an image or numpy array you should ensure that the image has square power-of-two dimensions (e.g. 256 x 256). If not then PsychoPy will up-sample your stimulus to the next larger power of two.
Power-of-two int. Sets the resolution of the mask and texture. texRes is overridden if an array or image is provided as mask.
Operations supported.
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox.
This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units
The Window object in which the
stimulus will be rendered by default. (required)
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)