MovieStim
¶
Class for presenting movie clips as stimuli. This is a lazy-imported class, therefore import using full path from psychopy.visual.movies import MovieStim when inheriting from it.
Attributes¶
|
Class for presenting movie clips as stimuli. |
The |
|
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 |
|
Determines how visible the stimulus is relative to background. |
|
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 current frame to a particular window. |
Determines whether the stimulus should be automatically drawn on every frame flip. |
|
|
Load a movie file from disk. |
|
Start or continue a paused movie from current position. |
|
Seek to a particular timestamp in the movie. |
|
Pause the current point in the movie. |
|
Stop the current point in the movie (sound will stop, current frame will not advance and remain on-screen). |
|
|
|
Details¶
- class psychopy.visual.MovieStim(win, filename='', movieLib='ffpyplayer', units='pix', size=None, pos=(0.0, 0.0), ori=0.0, anchor='center', draggable=False, flipVert=False, flipHoriz=False, color=(1.0, 1.0, 1.0), colorSpace='rgb', opacity=1.0, contrast=1, volume=1.0, name='', loop=False, autoLog=True, depth=0.0, noAudio=False, interpolate=True, autoStart=True)[source]¶
Class for presenting movie clips as stimuli.
- Parameters:
win (
Window
) – Window the video is being drawn to.filename (str) – Name of the file or stream URL to play. If an empty string, no file will be loaded on initialization but can be set later.
movieLib (str or None) – Library to use for video decoding. By default, the ‘preferred’ library by PsychoPy developers is used. Default is ‘ffpyplayer’. An alert is raised if you are not using the preferred player.
units (str) – Units to use when sizing the video frame on the window, affects how size is interpreted.
size (ArrayLike or None) – Size of the video frame on the window in units. If None, the native size of the video will be used.
draggable (bool) – Can this stimulus be dragged by a mouse click?
flipVert (bool) – If True then the movie will be top-bottom flipped.
flipHoriz (bool) – If True then the movie will be right-left flipped.
volume (int or float) – If specifying an int the nominal level is 100, and 0 is silence. If a float, values between 0 and 1 may be used.
loop (bool) – Whether to start the movie over from the beginning if draw is called and the movie is done. Default is False.
autoStart (bool) – Automatically begin playback of the video when flip() is called.
- 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
- _drawRectangle()[source]¶
Draw the video frame to the window.
This is called by the draw() method to blit the video to the display window.
- _freeBuffers()[source]¶
Free texture and pixel buffers. Call this when tearing down this class or if a movie is stopped.
- _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.
- _pixelTransfer()[source]¶
Copy pixel data from video frame to texture.
- _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.
- _setupTextureBuffers()[source]¶
Setup texture buffers which hold frame data. This creates a 2D RGB texture and pixel buffer. The pixel buffer serves as the store for texture color data. Each frame, the pixel buffer memory is mapped and frame data is copied over to the GPU from the decoder.
This is called every time a video file is loaded. The _freeBuffers method is called in this routine prior to creating new buffers, so it’s safe to call this right after loading a new movie without having to _freeBuffers first.
- _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.
- _updateVertices()¶
Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz
- alphaThreshold¶
Threshold for alpha values.
If the alpha value of a pixel is below this threshold, the pixel will be rejected (not drawn). This can be useful for creating a mask from an image with an alpha channel. The default value is 0.0, which means that no thresholding will be applied.
- property anchor¶
- 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 autoStart¶
Start playback when .draw() is called (bool).
- 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¶
- 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]¶
Draw the current frame to a particular window.
The current position in the movie will be determined automatically. This method should be called on every frame that the movie is meant to appear. If .autoStart==True the video will begin playing when this is called.
- property duration¶
Duration of the loaded video in seconds (float). Not valid unless the video has been started.
- fastForward(seconds=5, log=True)[source]¶
Fast-forward the video.
- property filename¶
File name for the loaded video (str).
- 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.
- property flipHoriz¶
- property flipVert¶
- 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.
- 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
- property fps¶
Movie frames per second (float).
- property frameIndex¶
Current frame index being displayed (int).
- property frameRate¶
Frame rate of the movie in Hertz (float).
- property frameSize¶
Size of the video (w, h) in pixels (tuple). Alias of videoSize.
- property frameTexture¶
Texture ID for the current video frame (GLuint). You can use this as a video texture. However, you must periodically call updateVideoFrame to keep this up to date.
- getAlphaThreshold()¶
- getAnchor()¶
- getAutoDraw()¶
- getAutoLog()¶
- getAutoStart()¶
- getBackColor()¶
- getBackColorSpace()¶
- getBackRGB()¶
- getBackgroundColor()¶
- getBorderColor()¶
- getBorderColorSpace()¶
- getBorderRGB()¶
- getBorderWidth()¶
- getColor()¶
- getColorSpace()¶
- getContrast()¶
- getCurrentFrameNumber()[source]¶
Get the current movie frame number (int), same as frameIndex.
- getDepth()¶
- getDraggable()¶
- getDuration()¶
- getFPS()[source]¶
Movie frames per second.
- Returns:
Nominal number of frames to be displayed per second.
- Return type:
- getFilename()¶
- getFillColor()¶
- getFillColorSpace()¶
- getFillRGB()¶
- getFlip()¶
- getFlipHoriz()¶
- getFlipVert()¶
- getFontColor()¶
- getForeColor()¶
- getForeColorSpace()¶
- getForeRGB()¶
- getFps()¶
- getFrameIndex()¶
- getFrameRate()¶
- getFrameSize()¶
- getFrameTexture()¶
- getHeight()¶
- getIsFinished()¶
- getIsNotStarted()¶
- getIsPaused()¶
- getIsPlaying()¶
- getIsStopped()¶
- getLineColor()¶
- getLineColorSpace()¶
- getLineRGB()¶
- getLineWidth()¶
- getLoopCount()¶
- getMuted()¶
- getName()¶
- getOpacity()¶
- getOri()¶
- getOrigSize()¶
- getPercentageComplete()[source]¶
Provides a value between 0.0 and 100.0, indicating the amount of the movie that has been already played (float).
- getPos()¶
- getPts()¶
- getRGB()¶
- getSize()¶
- getUnits()¶
- getVertices()¶
- getVerticesPix()¶
- getVideoSize()¶
- getVolume()¶
- getWidth()¶
- getWin()¶
- get_borderPix()¶
- get_hasPlayer()¶
- property height¶
- isDragging = False¶
- property isFinished¶
True if the video is finished (bool).
- property isNotStarted¶
True if the video may not have started yet (bool). This status is given after a video is loaded and play has yet to be called.
- property isPaused¶
True if the video is presently paused (bool).
- property isPlaying¶
True if the video is presently playing (bool).
- property isStopped¶
True if the video is stopped (bool). It will resume from the beginning if play() is called.
- 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¶
- load(filename)[source]¶
Load a movie file from disk (alias of loadMovie).
- Parameters:
filename (str) – Path to movie file. Must be a format that FFMPEG supports.
- loadMovie(filename)[source]¶
Load a movie file from disk.
- Parameters:
filename (str) – Path to movie file. Must be a format that FFMPEG supports.
- property loopCount¶
Number of loops completed since playback started (int). Incremented each time the movie begins another loop.
Examples
Compute how long a looping video has been playing until now:
totalMovieTime = (mov.loopCount + 1) * mov.pts
- property muted¶
True if the stream audio is muted (bool).
- 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.
- property origSize¶
Alias of videoSize
- 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
- pause(log=True)[source]¶
Pause the current point in the movie. The image of the last frame will persist on-screen until play() or stop() are called.
- Parameters:
log (bool) – Log this event.
- play(log=True)[source]¶
Start or continue a paused movie from current position.
- Parameters:
log (bool) – Log the play event.
- 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)
- property pts¶
Presentation timestamp of the most recent frame (float).
This value corresponds to the time in movie/stream time the frame is scheduled to be presented.
- replay(log=True)[source]¶
Replay the movie from the beginning.
- Parameters:
log (bool) – Log this event.
Notes
This tears down the current media player instance and creates a new one. Similar to calling stop() and loadMovie(). Use seek(0.0) if you would like to restart the movie without reloading.
- rewind(seconds=5, log=True)[source]¶
Rewind the video.
- seek(timestamp, log=True)[source]¶
Seek to a particular timestamp in the movie.
- setAlphaThreshold(value, log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
- 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.
- setAutoStart(value, log=None, operation=False, stealth=False)¶
- 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)¶
- setFilename(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(value, log=None, operation=False, stealth=False)¶
- setFlipVert(value, log=None, operation=False, stealth=False)¶
- 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)¶
- 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)¶
- setMovie(value)[source]¶
- setMuted(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
- setUnits(value, log=None, operation=False, stealth=False)¶
- setVertices(value, log=None, operation=False, stealth=False)¶
- setVolume(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
- stop(log=True)[source]¶
Stop the current point in the movie (sound will stop, current frame will not advance and remain on-screen). Once stopped the movie can be restarted from the beginning by calling play().
- Parameters:
log (bool) – Log this event.
- toggle(log=True)[source]¶
Switch between playing and pausing the movie. If the movie is playing, this function will pause it. If the movie is paused, this function will play it.
- Parameters:
log (bool) – Log this event.
- property units¶
- unload(log=True)[source]¶
Stop and unload the movie.
- Parameters:
log (bool) – Log this event.
- 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.
- updateVideoFrame()[source]¶
Update the present video frame. The next call to draw() will make the retrieved frame appear.
- Returns:
If True, the video texture has been updated and the frame index is advanced by one. If False, the last frame should be kept on-screen.
- Return type:
- 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 videoSize¶
Size of the video (w, h) in pixels (tuple). Returns (0, 0) if no video is loaded.
- property volume¶
Volume for the audio track for this movie (int or float).
- volumeDown(amount=0.05)[source]¶
Decrease the volume by a fixed amount.
- volumeUp(amount=0.05)[source]¶
Increase the volume by a fixed amount.
- 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)