function canvas.__init__(experiment, bgcolor=None, fgcolor=None, auto_prepare=True)

Constructor to create a new canvas object.

Example:

# Example 1: Show a central fixation dot.
from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot()
my_canvas.show()

# Example 2: Show many randomly positioned fixation dot. Here we
# disable `auto_prepare`, so that drawing goes more quickly.
from openexp.canvas import canvas
from random import randint
my_canvas = canvas(exp, auto_prepare=False)
for i in range(1000):
        x = randint(0, self.get('width'))
        y = randint(0, self.get('height'))
        my_canvas.fixdot(x, y)
my_canvas.prepare()
my_canvas.show()

Arguments:

• experiment – The experiment object.
  • Type: experiment

Keywords:

• bgcolor – A human-readable background color or None to use experiment default.
  • Type: str, unicode, NoneType
  • Default: None
• fgcolor – A human-readable foreground color or None to use experiment default.
  • Type: str, unicode, NoneType
  • Default: None
• auto_prepare – Indicates whether the canvas should be automatically prepared after each drawing operation, so that canvas.show will be maximally efficient. If auto_prepare is turned off, drawing operations may be faster, but canvas.show will take longer, unless canvas.prepare is explicitly called in advance. Generally, it only makes sense to disable auto_prepare when you want to draw a large number of stimuli, as in the second example below. Currently, the auto_prepare parameter only applies to the xpyriment backend, and is ignored by the other backends.
  • Type: bool
  • Default: True

function canvas.arrow(sx, sy, ex, ey, color=None, arrow_size=5, penwidth=None)

Draws an arrow. An arrow is a line, with an arrowhead at (ex, ey). The angle between the arrowhead lines and the arrow line is 45 degrees.

Arguments:

• sx – The left X coordinate.
  • Type: int
• sy – The top Y coordinate.
  • Type: int
• ex – The right X coordinate.
  • Type: int
• ey – The bottom Y coordinate.
  • Type: int

Keywords:

• arrow_size – The length of the arrow-head lines in pixels.
  • Type: int
  • Default: 5
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.circle(x, y, r, color=None, penwidth=None, fill=False)

Draws a circle.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.circle(100, 100, 50, fill=True, color='red')

Arguments:

• x – The center X coordinate of the circle.
  • Type: int
• y – The center Y coordinate of the circle.
  • Type: int
• r – The radius of the circle.
  • Type: int

Keywords:

• fill – Specifies whether the shape should be filled (True) or consist of an outline (False).
  • Type: bool
  • Default: False
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.clear(color=None)

Clears the canvas with the current background color. Note that it is generally faster to use a different canvas for each experimental display than to use a single canvas and repeatedly clear and redraw it.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot(color='green')
my_canvas.show()
self.sleep(1000)
my_canvas.clear()
my_canvas.fixdot(color='red')
my_canvas.show()

Keywords:

• color – A human-readable background color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default background as set by canvas.set_bgcolor.
  • Type: str, unicode, NoneType
  • Default: None

function canvas.copy(canvas)

Turns the current canvas into a copy of the passed canvas.

Note:

If you want to create a copy of a sketchpad canvas, you can also use the inline_script.copy_sketchpad function.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot(x=100, color='green')
my_copied_canvas = canvas(exp)
my_copied_canvas.copy(my_canvas)
my_copied_canvas.fixdot(x=200, color="blue")
my_copied_canvas.show()

Arguments:

• canvas – The canvas to copy.
  • Type: canvas

function canvas.ellipse(x, y, w, h, color=None, penwidth=None, fill=False)

Draws an ellipse.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
w = self.get('width')-10
h = self.get('height')-10
my_canvas.ellipse(10, 10, w, h, fill=True)

Arguments:

• x – The left X coordinate.
  • Type: int
• y – The top Y coordinate.
  • Type: int
• w – The width.
  • Type: int
• h – The height.
  • Type: int

Keywords:

• fill – Specifies whether the shape should be filled (True) or consist of an outline (False).
  • Type: bool
  • Default: False
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.fixdot(y=None, x=None, style=u’default’, color=None)

Draws a fixation dot.

• ‘large-filled’ is a filled circle with a 16px radius.
• ‘medium-filled’ is a filled circle with an 8px radius.
• ‘small-filled’ is a filled circle with a 4px radius.
• ‘large-open’ is a filled circle with a 16px radius and a 2px hole.
• ‘medium-open’ is a filled circle with an 8px radius and a 2px hole.
• ‘small-open’ is a filled circle with a 4px radius and a 2px hole.
• ‘large-cross’ is 16px cross.
• ‘medium-cross’ is an 8px cross.
• ‘small-cross’ is a 4px cross.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot()

Keywords:

• x – The X coordinate of the dot center, or None to draw a horizontally centered dot.
  • Type: int, NoneType
  • Default: None
• y – The Y coordinate of the dot center, or None to draw a vertically centered dot.
  • Type: int, NoneType
  • Default: None
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• style – The fixation-dot style. One of: default, large-filled, medium-filled, small-filled, large-open, medium-open, small-open, large-cross, medium-cross, or small-cross. default equals medium-open.
  • Type: str, unicode
  • Default: u’default’

function canvas.gabor(x, y, orient, freq, bgmode=u’avg’, col2=u’black’, col1=u’white’, env=u’gaussian’, stdev=12, phase=0, size=96)

Draws a Gabor patch. Note: The exact rendering of the Gabor patch depends on the back-end.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.gabor(100, 100, 45, .05)

Arguments:

• x – The center X coordinate.
  • Type: int
• y – The center Y coordinate.
  • Type: int
• orient – Orientation in degrees [0 .. 360].
  • Type: float, int
• freq – Frequency in cycles/px of the sinusoid.
  • Type: float, int

Keywords:

• env – The envelope that determines the shape of the patch. Can be “gaussian”, “linear”, “circular”, or “rectangular”.
  • Type: str, unicode
  • Default: u’gaussian’
• size – A size in pixels.
  • Type: float, int
  • Default: 96
• stdev – Standard deviation in pixels of the gaussian. Only applicable to gaussian envelopes.
  • Type: float, int
  • Default: 12
• phase – Phase of the sinusoid [0.0 .. 1.0].
  • Type: float, int
  • Default: 0
• col1 – A color for the peaks.
  • Type: str, unicode
  • Default: u’white’
• col2 – A color for the troughs. Note: The psycho back-end ignores this parameter and always uses the inverse of col1 for the throughs.
  • Type: str, unicode
  • Default: u’black’
• bgmode – Specifies whether the background is the average of col1 col2 (‘avg’, corresponding to a typical Gabor patch), or equal to col2 (‘col2’), useful for blending into the background. Note: this parameter is ignored by the psycho backend, which uses increasing transparency for the background.
  • Type: str, unicode
  • Default: u’avg’

function canvas.image(fname, y=None, x=None, scale=None, center=True)

Draws an image from file. This function does not look in the file pool, but takes an absolute path.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
# Determine the absolute path:
path = exp.get_file(u'image_in_pool.png')
my_canvas.image(path)

Arguments:

• fname – The filename of the image. If this is a str it is assumed to be in utf-8 encoding.
  • Type: str, unicode

Keywords:

• center – A bool indicating whether coordinates indicate the center (True) or top-left (False).
  • Type: bool
  • Default: True
• x – The X coordinate, or None to draw a horizontally centered image.
  • Type: int, NoneType
  • Default: None
• y – The Y coordinate, or None to draw a vertically centered image.
  • Type: int, NoneType
  • Default: None
• scale – The scaling factor of the image. None or 1 indicate the original size. 2.0 indicates a 200% zoom, etc.
  • Type: float, int, NoneType
  • Default: None

function canvas.line(sx, sy, ex, ey, color=None, penwidth=None)

Draws a line.

Arguments:

• sx – The left X coordinate.
  • Type: int
• sy – The top Y coordinate.
  • Type: int
• ex – The right X coordinate.
  • Type: int
• ey – The bottom Y coordinate.
  • Type: int

Keywords:

• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.noise_patch(x, y, bgmode=u’avg’, col2=u’black’, col1=u’white’, env=u’gaussian’, stdev=12, size=96)

Draws a patch of noise, with an envelope. The exact rendering of the noise patch depends on the back-end.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.noise_patch(100, 100, env='circular')

Arguments:

• x – The center X coordinate.
  • Type: int
• y – The center Y coordinate.
  • Type: int

Keywords:

• env – The envelope that determines the shape of the patch. Can be “gaussian”, “linear”, “circular”, or “rectangular”.
  • Type: str, unicode
  • Default: u’gaussian’
• size – A size in pixels.
  • Type: float, int
  • Default: 96
• stdev – Standard deviation in pixels of the gaussian. Only applicable to gaussian envelopes.
  • Type: float, int
  • Default: 12
• col1 – The first color.
  • Type: str, unicode
  • Default: u’white’
• col2 – The second color. Note: The psycho back-end ignores this parameter and always uses the inverse of col1.
  • Type: str, unicode
  • Default: u’black’
• bgmode – Specifies whether the background is the average of col1 col2 (‘avg’, corresponding to a typical Gabor patch), or equal to col2 (‘col2’), useful for blending into the background. Note: this parameter is ignored by the psycho backend, which uses increasing transparency for the background.
  • Type: str, unicode
  • Default: u’avg’

function canvas.polygon(vertices, color=None, penwidth=None, fill=False)

Draws a polygon that defined by a list of vertices. I.e. a shape of points connected by lines.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
n1 = 0,0
n2 = 100, 100
n3 = 0, 100
my_canvas.polygon([n1, n2, n3])

Arguments:

• vertices – A list of tuples, where each tuple corresponds to a vertex. For example, [(100,100), (200,100), (100,200)] will draw a triangle.
  • Type: list

Keywords:

• fill – Specifies whether the shape should be filled (True) or consist of an outline (False).
  • Type: bool
  • Default: False
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.prepare()

Finishes pending canvas operations (if any), so that a subsequent call to canvas.show is extra fast. It’s only necessary to call this function if you have disabled auto_prepare in canvas.init.

function canvas.rect(x, y, w, h, color=None, penwidth=None, fill=False)

Draws a rectangle.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
w = self.get('width')-10
h = self.get('height')-10
my_canvas.rect(10, 10, w, h, fill=True)

Arguments:

• x – The left X coordinate.
  • Type: int
• y – The top Y coordinate.
  • Type: int
• w – The width.
  • Type: int
• h – The height.
  • Type: int

Keywords:

• fill – Specifies whether the shape should be filled (True) or consist of an outline (False).
  • Type: bool
  • Default: False
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• penwidth – A penwidth in pixels, or None to use the canvas default. This argument will not change the canvas default penwidth as set by canvas.set_penwidth.
  • Type: int
  • Default: None

function canvas.set_bgcolor(color)

Sets the default background color for subsequent drawing operations, notably canvas.clear.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.set_bgcolor('gray')
my_canvas.clear()

Arguments:

• color – A human-readable background color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default background as set by canvas.set_bgcolor.
  • Type: str, unicode

function canvas.set_bidi(bidi)

Enables or disables bi-directional text support.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.set_bidi(True)
my_canvas.text(u'חלק מטקסט')

Arguments:

• bidi – True to enable bi-directional text support, False to disable.
  • Type: bool

function canvas.set_fgcolor(color)

Sets the default foreground color for subsequent drawing operations.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.set_fgcolor('green')
my_canvas.text('Green text', y=200)
my_canvas.set_fgcolor('red')
my_canvas.text('Red text', y=400)

Arguments:

• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode

function canvas.set_font(style=None, underline=None, bold=None, italic=None, size=None)

Sets the default font for subsequent drawing operations, notably canvas.text.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.set_font(style='serif', italic=True)
my_canvas.text('Text in italic serif')

Keywords:

• style – A font family. This can be one of the default fonts (e.g., ‘mono’), a system font (e.g., ‘arial’), the name of a .ttf font file in the file pool (without the .ttf extension), or None to use the experiment default.
  • Type: str, unicode
  • Default: None
• size – A font size in pixels, or None to use the experiment default.
  • Type: int
  • Default: None
• italic – A bool indicating whether the font should be italic, or None to use the experiment default.
  • Type: bool, NoneType
  • Default: None
• bold – A bool indicating whether the font should be bold, or None to use the experiment default.
  • Type: bool, NoneType
  • Default: None
• underline – A bool indicating whether the font should be underlined, or None to use the experiment default.
  • Type: bool, NoneType
  • Default: None

function canvas.set_penwidth(penwidth)

Sets the default penwidth for subsequent drawing operations.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.set_penwidth(10)
my_canvas.line(100, 100, 200, 200)

Arguments:

• penwidth – A penwidth in pixels.
  • Type: int

function canvas.show()

Shows, or ‘flips’, the canvas on the screen.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot()
t = my_canvas.show()
exp.set('time_fixdot', t)

Returns:

A timestamp of the time at which the canvas actually appeared on the screen, or a best guess if precise temporal information is not available. For more information about timing, see </misc/timing>. Depending on the back-end the timestamp is an int or a float.

• Type: int, float

function canvas.text(text, center=True, color=None, max_width=None, html=True, bidi=None, y=None, x=None)

Draws text.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.text('Some text with <b>boldface</b> and <i>italics</i>')

Arguments:

• text – A string of text.
  • Type: str, unicode

Keywords:

• center – A bool indicating whether the coordinates reflect the center (True) or top-left (False) of the text.
  • Type: bool
  • Default: True
• x – The X coordinate, or None to draw horizontally centered text.
  • Type: int, NoneType
  • Default: None
• y – The Y coordinate, or None to draw vertically centered text.
  • Type: int, NoneType
  • Default: None
• max_width – The maximum width of the text in pixels, before wrapping to a new line, or None to wrap at screen edge.
  • Type: int, NoneType
  • Default: None
• color – A human-readable foreground color, such as ‘red’, an HTML-style color value, such as ‘#FF0000’, or None to use the canvas default. This argument will not change the canvas default foreground as set by canvas.set_fgcolor.
  • Type: str, unicode, NoneType
  • Default: None
• bidi – A bool indicating bi-directional text support should be enabled, or None to use the experiment default. This does not affect the canvas default bidi setting as set by canvas.set_bidi.
  • Type: bool, NoneType
  • Default: None
• html – A bool indicating whether a subset of HTML tags should be interpreted. For more information, see </usage/text/>.
  • Type: bool
  • Default: True

function canvas.text_size(text, html=True, bidi=None, max_width=None)

Determines the size of a text string in pixels.

Example:

from openexp.canvas import canvas
my_canvas = canvas(exp)
w, h = my_canvas.text_size('Some text')

Arguments:

• text – A string of text.
  • Type: str, unicode

Keywords:

• max_width – The maximum width of the text in pixels, before wrapping to a new line, or None to wrap at screen edge.
  • Type: int, NoneType
  • Default: None
• bidi – A bool indicating bi-directional text support should be enabled, or None to use the experiment default. This does not affect the canvas default bidi setting as set by canvas.set_bidi.
  • Type: bool, NoneType
  • Default: None
• html – A bool indicating whether a subset of HTML tags should be interpreted. For more information, see </usage/text/>.
  • Type: bool
  • Default: True

Returns:

A (width, height) tuple containing the dimensions of the text string.

• Type: tuple

function canvas.xcenter()

Returns the center X coordinate of the canvas in pixels.

Example:

# Draw a diagonal line through the center of the canvas
from openexp.canvas import canvas
my_canvas = canvas(exp)
x1 = my_canvas.xcenter() - 100
y1 = my_canvas.ycenter() - 100
x2 = my_canvas.xcenter() + 100
y2 = my_canvas.ycenter() + 100
my_canvas.line(x1, y1, x2, y2)

Returns:

The center X coordinate.

• Type: int

function canvas.ycenter()

Returns the center Y coordinate of the canvas in pixels.

Example:

# Draw a diagonal line through the center of the canvas
from openexp.canvas import canvas
my_canvas = canvas(exp)
x1 = my_canvas.xcenter() - 100
y1 = my_canvas.ycenter() - 100
x2 = my_canvas.xcenter() + 100
y2 = my_canvas.ycenter() + 100
my_canvas.line(x1, y1, x2, y2)

Returns:

The center Y coordinate.

• Type: int