PatchStim - the main stimulus class for presenting images

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, name='', autoLog=True, maskParams=None)

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, png...)

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

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’, ‘raisedCos’
• 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.

Note

If the mask is Gaussian (‘gauss’), then the ‘size’ parameter refers to the stimulus at 3 standard deviations on each side of the centre (ie. sd=size/6)

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:

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

The depth argument is deprecated and may be removed in future versions. Depth is controlled simply by drawing order.

name : string

The name of the object to be using during logged messages about this stim

maskParams: Various types of input. Default to None.

This is used to pass additional parameters to the mask if those are needed. - 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.

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.

setAutoDraw(val)

Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip

Parameters :

• val: True/False

  True to add the stimulus to the draw list, False to remove it

setAutoLog(val=True)

Turn on (or off) autoLogging for this stimulus.

Parameters :

• val: True (default) or False

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 inherited) 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 inherited) units

setTex(value)

setUseShaders(val=True)

Set this stimulus to use shaders if possible.