psychopy.visual.PatchStim

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.

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.

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. It is still necessary to have power-of-2 textures on most graphics cards.

init(self, 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)
(Constructor)

source code


:Parameters:

    win : 
        a :class:`~psychopy.visual.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'
        + 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 :class:`~psychopy.visual.Window` will be used. 
        See :ref:`units` 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.                
    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 the web name for a color (e.g. 'FireBrick');
        a hex value (e.g. '#FF0047');
        a tuple (1.0,1.0,1.0); a 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 :ref:`colorspaces`
    colorSpace:
        the color space controlling the interpretation of the `color`
        See :ref:`colorspaces`
    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:
        This can potentially be used (not tested!) to choose which
        stimulus overlays which. (more negative values are nearer).
        At present the window does not do perspective rendering
        but could do if that's really useful(?!)

Overrides: _BaseVisualStim.__init__

Class PatchStim

draw(self, win=None)

clearTextures(self)

Class PatchStim

__init__(self, 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) (Constructor)

draw(self, win=None)

clearTextures(self)