BufferImageStim¶

Attributes¶

Details¶

class psychopy.visual.BufferImageStim(win, buffer='back', rect=(-1, 1, 1, -1), sqPower2=False, stim=(), interpolate=True, flipHoriz=False, flipVert=False, mask='None', pos=(0, 0), name=None, autoLog=None)[source]¶

Take a “screen-shot”, save as an ImageStim (RBGA object). This is a lazy-imported class, therefore import using full path from psychopy.visual.bufferimage import BufferImageStim when inheriting from it.

The screen-shot is a single collage image composed of static elements that you can treat as being a single stimulus. The screen-shot can be of the visible screen (front buffer) or hidden (back buffer).

BufferImageStim aims to provide fast rendering, while still allowing dynamic orientation, position, and opacity. It’s fast to draw but slower to init (same as an ImageStim).

You specify the part of the screen to capture (in norm units), and optionally the stimuli themselves (as a list of items to be drawn). You get a screenshot of those pixels. If your OpenGL does not support arbitrary sizes, the image will be larger, using square powers of two if needed, with the excess image being invisible (using alpha). The aim is to preserve the buffer contents as rendered.

Checks for OpenGL 2.1+, or uses square-power-of-2 images.

Example:

# define lots of stimuli, make a list:
mySimpleImageStim = ...
myTextStim = ...
stimList = [mySimpleImageStim, myTextStim]

# draw stim list items & capture (slow; see EXP log for times):
screenshot = visual.BufferImageStim(myWin, stim=stimList)

# render to screen (very fast, except for the first draw):
while <conditions>:
    screenshot.draw()  # fast; can vary .ori, .pos, .opacity
    other_stuff.draw() # dynamic
    myWin.flip()

See coder Demos > stimuli > bufferImageStim.py for a demo, with timing stats.

Author:

• 2010 Jeremy Gray, with on-going fixes

Parameters:

buffer :

the screen buffer to capture from, default is ‘back’ (hidden). ‘front’ is the buffer in view after win.flip()

rect :

a list of edges [left, top, right, bottom] defining a screen rectangle which is the area to capture from the screen, given in norm units. default is fullscreen: [-1, 1, 1, -1]

stim :

a list of item(s) to be drawn to the back buffer (in order). The back buffer is first cleared (without the win being flip()ed), then stim items are drawn, and finally the buffer (or part of it) is captured. Each item needs to have its own .draw() method, and have the same window as win.

interpolate :

whether to use interpolation (default = True, generally good, especially if you change the orientation)

sqPower2 :

• False (default) = use rect for size if OpenGL = 2.1+

• True = use square, power-of-two image sizes

flipHoriz :

horizontally flip (mirror) the captured image, default = False

flipVert :

vertically flip (mirror) the captured image; default = False

property RGB¶

Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb

Type:

DEPRECATED

_calcPosRendered()¶

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix.

_calcSizeRendered()¶

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix

_createTexture(tex, id, pixFormat, stim, res=128, maskParams=None, forcePOW2=True, dataType=None, wrapping=True)¶

Create a new OpenGL 2D image texture.

Parameters:

• 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).

_getDesiredRGB(rgb, colorSpace, contrast)¶

Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast

_getPolyAsRendered()¶

DEPRECATED. Return a list of vertices as rendered.

_movieFrameToTexture(movieSrc)¶

Convert a movie frame to a texture and use it.

This method is used internally to copy pixel data from a camera object into a texture. This enables the ImageStim to be used as a ‘viewfinder’ of sorts for the camera to view a live video stream on a window.

Parameters:

movieSrc (~psychopy.hardware.camera.Camera) – Movie source object.

_selectWindow(win)¶

Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.

_set(attrib, val, op='', log=None)¶

DEPRECATED since 1.80.04 + 1. Use setAttribute() and val2array() instead.

_updateList()¶

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.

_updateListShaders()¶

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

_updateVertices()¶

Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz

property anchor¶

property aspectRatio¶

Aspect ratio of original image, before taking into account the .size attribute of this object.

returns :

Aspect ratio as a (w, h) tuple, simplified using the smallest common denominator (e.g. 1080x720 pixels becomes (3, 2))

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.

property backColor¶

Alternative way of setting fillColor

property backColorSpace¶

Deprecated, please use colorSpace to set color space for the entire object.

property backRGB¶

Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb

Type:

DEPRECATED

property backgroundColor¶

Alternative way of setting fillColor

property borderColor¶

property borderColorSpace¶

Deprecated, please use colorSpace to set color space for the entire object

property borderRGB¶

Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb

Type:

DEPRECATED

borderWidth¶

clearTextures()¶

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.

property color¶

Alternative way of setting foreColor.

property 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)

contains(x, y=None, units=None)¶

Returns True if a point x,y is inside the stimulus’ border.

Can accept variety of input options:

• two separate args, x and y

• one arg (list, tuple or array) containing two vals (x,y)

• an object with a getPos() method that returns x,y, such

  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

property contrast¶

A value that is simply multiplied by the color.

Value should be: a float between -1 (negative) and 1 (unchanged).

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

depth¶

DEPRECATED, depth is now controlled simply by drawing order.

doDragging()¶

If this stimulus is draggable, do the necessary actions on a frame flip to drag it.

draggable¶

Can this stimulus be dragged by a mouse click?

draw(win=None)[source]¶

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()

property fillColor¶

Set the fill color for the shape.

property fillColorSpace¶

Deprecated, please use colorSpace to set color space for the entire object.

property fillRGB¶

Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb

Type:

DEPRECATED

property flip¶

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.

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¶

If set to True then the image will be flipped vertically (left-to-right). Note that this is relative to the original image, not relative to the current state.

property fontColor¶

Alternative way of setting foreColor.

property foreColor¶

Foreground color of the stimulus

Value should be one of:

• 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.

• Colors by hex value

• numerically: (scalar or triplet) for DKL, RGB or

  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)

property foreColorSpace¶

Deprecated, please use colorSpace to set color space for the entire object.

property foreRGB¶

Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb

Type:

DEPRECATED

getAnchor()¶

getAspectRatio()¶

getAutoDraw()¶

getAutoLog()¶

getBackColor()¶

getBackColorSpace()¶

getBackRGB()¶

getBackgroundColor()¶

getBorderColor()¶

getBorderColorSpace()¶

getBorderRGB()¶

getBorderWidth()¶

getColor()¶

getColorSpace()¶

getContrast()¶

getDepth()¶

getDraggable()¶

getFillColor()¶

getFillColorSpace()¶

getFillRGB()¶

getFlip()¶

getFlipHoriz()¶

getFlipVert()¶

getFontColor()¶

getForeColor()¶

getForeColorSpace()¶

getForeRGB()¶

getHeight()¶

getImage()¶

getInterpolate()¶

getLineColor()¶

getLineColorSpace()¶

getLineRGB()¶

getLineWidth()¶

getMask()¶

getMaskParams()¶

getName()¶

getOpacity()¶

getOri()¶

getPos()¶

getRGB()¶

getSize()¶

getTexRes()¶

getUnits()¶

getVertices()¶

getVerticesPix()¶

getWidth()¶

getWin()¶

get_borderPix()¶

property height¶

image¶

The image file to be presented (most formats supported).

This can be a path-like object to an image file, or a numpy array of shape [H, W, C] where C are channels. The third dim will usually have length 1 (defining an intensity-only image), 3 (defining an RGB image) or 4 (defining an RGBA image).

If passing a numpy array to the image attribute, the size attribute of ImageStim must be set explicitly.

interpolate¶

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.

isDragging = False¶

property lineColor¶

Alternative way of setting borderColor.

property lineColorSpace¶

Deprecated, please use colorSpace to set color space for the entire object

property lineRGB¶

Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb

Type:

DEPRECATED

lineWidth¶

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¶

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.

property 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.

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

property 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)

setAnchor(value, log=None)¶

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.

setBackColor(color, colorSpace=None, operation='', log=None)¶

setBackColorSpace(value, log=None, operation=False, stealth=False)¶

setBackRGB(color, operation='', log=None)¶

DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb

setBackgroundColor(color, colorSpace=None, operation='', log=None)¶

setBorderColor(color, colorSpace=None, operation='', log=None)¶

Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

setBorderColorSpace(value, log=None, operation=False, stealth=False)¶

setBorderRGB(color, operation='', log=None)¶

DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb

setBorderWidth(newWidth, operation='', log=None)¶

setColor(color, colorSpace=None, operation='', log=None)¶

setColorSpace(value, log=None, operation=False, stealth=False)¶

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(color, 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

setDraggable(value, log=None, operation=False, stealth=False)¶

setFillColor(color, colorSpace=None, operation='', log=None)¶

Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

setFillColorSpace(value, log=None, operation=False, stealth=False)¶

setFillRGB(color, operation='', log=None)¶

DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb

setFlip(value, log=None, operation=False, stealth=False)¶

setFlipHoriz(newVal=True, log=None)[source]¶

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)[source]¶

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setFontColor(color, colorSpace=None, operation='', log=None)¶

setForeColor(color, colorSpace=None, operation='', log=None)¶

Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

setForeColorSpace(value, log=None, operation=False, stealth=False)¶

setForeRGB(color, operation='', log=None)¶

DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb

setHeight(value, log=None, operation=False, stealth=False)¶

setImage(value, log=None)¶

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setInterpolate(value, log=None, operation=False, stealth=False)¶

setLMS(color, operation='')¶

DEPRECATED since v1.60.05: Please use the color attribute

setLineColor(color, colorSpace=None, operation='', log=None)¶

setLineColorSpace(value, log=None, operation=False, stealth=False)¶

setLineRGB(color, operation='', log=None)¶

DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb

setLineWidth(newWidth, operation='', log=None)¶

setMask(value, log=None)¶

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setMaskParams(value, log=None, operation=False, stealth=False)¶

setName(value, log=None, operation=False, stealth=False)¶

setOpacity(newOpacity, operation='', log=None)¶

Hard setter for opacity, allows the suppression of log messages and calls the update method

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(color, operation='', log=None)¶

DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb

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

setTexRes(value, log=None, operation=False, stealth=False)¶

setUnits(value, log=None, operation=False, stealth=False)¶

setVertices(value, log=None, operation=False, stealth=False)¶

setWidth(value, log=None, operation=False, stealth=False)¶

setWin(value, log=None, operation=False, stealth=False)¶

property 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

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.

Operations supported.

property units¶

updateColors()¶

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox

updateOpacity()¶

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox.

property vertices¶

property verticesPix¶

This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units

property width¶

property win¶

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)