psychopy.visual.Progress

Stimulus class for drawing progress bars. This is a lazy-imported class, therefore import using full path from psychopy.visual.progress import Progress when inheriting from it.

Overview

Progress(win[, name, progress, direction, ...])

A basic progress bar, consisting of two rectangles: A background and a foreground.

Progress.name

The name (str) of the object to be using during logged messages about this stim.

Progress.progress

How far along the progress bar is

Progress.direction

What direction is this progress bar progressing in? Use in combination with "anchor" to control which direction the bar fills up from.

Progress.pos

The position of the center of the stimulus in the stimulus units

Progress.size

The size (width, height) of the stimulus in the stimulus units

Progress.anchor

Progress.units

Progress.barColor

Progress.backColor

Alternative way of setting fillColor

Progress.borderColor

Progress.colorSpace

The name of the color space currently being used

Progress.lineWidth

Width of the line in pixels.

Progress.opacity

Determines how visible the stimulus is relative to background.

Details

class psychopy.visual.progress.Progress(win, name='pb', progress=0, direction='horizontal', pos=(-0.5, 0), size=(1, 0.1), anchor='center-left', units=None, barColor=False, backColor=False, borderColor=False, colorSpace=None, lineWidth=1.5, opacity=1.0, ori=0.0, depth=0, autoLog=None, autoDraw=False, foreColor='white', fillColor=False, lineColor='white')[source]

A basic progress bar, consisting of two rectangles: A background and a foreground. The foreground rectangle fill the background as progress approaches 1.

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

  • name (str) – Name to refer to this Progress bar by

  • progress (float) – Value between 0 (not started) and 1 (complete) to set the progress bar to.

  • direction (str) – Which dimension the bar should fill along, either “horizontal” (also accepts “horiz”, “x” or 0) or “vertical” (also accepts “vert”, “y” or 1)

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

  • anchor (str) – Point within the shape where size and pos are set from. This also affects where the progress bar fills up from (e.g. if anchor is “left” and direction is “horizontal”, then the bar will fill from left to right)

  • units (str) – Units to use when drawing. This will affect how parameters and attributes pos and size are interpreted.

  • barColor (array_like, str, Color or None) – Color of the full part of the progress bar.

  • foreColor (array_like, str, Color or None) – Color of the full part of the progress bar.

  • backColor (array_like, str, Color or None) – Color of the empty part of the progress bar.

  • fillColor (array_like, str, Color or None) – Color of the empty part of the progress bar.

  • borderColor (array_like, str, Color or None) – Color of the outline around the outside of the progress bar.

  • lineColor (array_like, str, Color or None) – Color of the outline around the outside of the progress bar.

  • colorSpace (str) – Sets the colorspace, changing how values passed to foreColor, lineColor and fillColor are interpreted.

  • lineWidth (float) – Width of the shape outline.

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

property RGB

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

Type:

DEPRECATED

static _calcEquilateralVertices(edges, radius=0.5)

Get vertices for an equilateral shape with a given number of sides, will assume radius is 0.5 (relative) but can be manually specified

_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

static _calculateMinEdges(lineWidth, threshold=180)

Calculate how many points are needed in an equilateral polygon for the gap between line rects to be < 1px and for corner angles to exceed a threshold.

In other words, how many edges does a polygon need to have to appear smooth?

lineWidthint, float, np.ndarray

Width of the line in pixels

thresholdint

Maximum angle (degrees) for corners of the polygon, useful for drawing a circle. Supply 180 for no maximum angle.

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

static _sanitizeDirection(direction)[source]

Take a value indicating direction and convert it to a human readable string

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

_tesselate(newVertices)

Set the .vertices and .border to new values, invoking tessellation.

_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

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

closeShape

Should the last vertex be automatically connected to the first?

If you’re using Polygon, Circle or Rect, closeShape=True is assumed and shouldn’t be changed.

color

Set the color of the shape. Sets both fillColor and lineColor simultaneously if applicable.

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.

direction

What direction is this progress bar progressing in? Use in combination with “anchor” to control which direction the bar fills up from.

Parameters:

value (str, int, bool) – Is progress bar horizontal or vertical? Accepts the following values: * horizontal: “horizontal”, “horiz”, “x”, “0”, “False”, 0, False * vertical: “vertical”, “vert”, “y”, “1”, “True”, 1, True

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, keepMatrix=False)[source]

Draw the stimulus in the relevant window.

You must call this method after every win.flip() if you want the stimulus to appear on that frame and then update the screen again.

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 fontColor

Alternative way of setting foreColor.

property foreColor

Color of the full part of the progress bar.

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

interpolate

If True the edge of the line will be anti-aliased.

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

Width of the line in pixels.

Operations supported.

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

How far along the progress bar is

Parameters:

value (float) – Between 0 (not complete) and 1 (fully complete)

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.

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

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

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

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

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

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

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

Sets both the line and fill to be the same color.

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

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

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

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

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

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

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

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

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

setLMS(color, operation='')

DEPRECATED since v1.60.05: Please use the color attribute

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

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

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

setVertices(value=None, operation='', log=None)

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

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

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

A list of lists or a numpy array (Nx2) specifying xy positions of each vertex, relative to the center of the field.

Assigning to vertices can be slow if there are many vertices.

Operations supported with .setVertices().

property verticesPix

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

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)

Back to top