canvas - OpenSesame
This PDF was auto-generated on 2015-01-22 16:39:36 +0100. A more recent version of this page may be
available at http://osdoc.cogsci.nl/python/canvas/.
Canvas functions
class canvas
The canvas class is used for display presentation.
Important note:
When using a canvas all coordinates are specified relative to the top-left of the
display, and not, as in sketchpads, relative to the display center.
Example:
# Create a canvas with a central fixation dot and show it.
from openexp.canvas import canvas
my_canvas = canvas(exp)
my_canvas.fixdot()
my_canvas.show()
Function list:
function canvas.__init__(experiment, bgcolor=None, fgcolor=None,
auto_prepare=True)
function canvas.arrow(sx, sy, ex, ey, color=None, arrow_size=5, penwidth=None)
function canvas.circle(x, y, r, color=None, penwidth=None, fill=False)
function canvas.clear(color=None)
function canvas.copy(canvas)
function canvas.ellipse(x, y, w, h, color=None, penwidth=None, fill=False)
function canvas.fixdot(y=None, x=None, style=u’default’, color=None)
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)
function canvas.image(fname, y=None, x=None, scale=None, center=True)
function canvas.line(sx, sy, ex, ey, color=None, penwidth=None)
function canvas.noise_patch(x, y, bgmode=u’avg’, col2=u’black’, col1=u’white’,
env=u’gaussian’, stdev=12, size=96)
function canvas.polygon(vertices, color=None, penwidth=None, fill=False)
function canvas.prepare()
function canvas.rect(x, y, w, h, color=None, penwidth=None, fill=False)
function canvas.set_bgcolor(color)
function canvas.set_bidi(bidi)
function canvas.set_fgcolor(color)
function canvas.set_font(style=None, underline=None, bold=None, italic=None,
size=None)
function canvas.set_penwidth(penwidth)
function canvas.show()
function canvas.text(text, center=True, color=None, max_width=None,
html=True, bidi=None, y=None, x=None)
function canvas.text_size(text, html=True, bidi=None, max_width=None)
function canvas.xcenter()
function canvas.ycenter()
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.
default.
Default: None
Type: str, unicode, NoneType
fgcolor – A human-readable foreground color or None to use experiment
default.
Default: None
Type: str, unicode, NoneType
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.
Default: True
Type: bool
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:
sy – The top Y coordinate.
Type: int
sx – The left X coordinate.
Type: int
ey – The bottom Y coordinate.
Type: int
ex – The right X 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.
Default: None
Type: str, unicode, NoneType
arrow_size – The length of the arrow-head lines in pixels.
Default: 5
Type: int
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.
Default: None
Type: int
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:
y – The center Y coordinate of the circle.
Type: int
x – The center X coordinate of the circle.
Type: int
r – The radius of the circle.
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.
Default: None
Type: str, unicode, NoneType
fill – Specifies whether the shape should be filled (True) or consist of an
outline (False).
Default: False
Type: bool
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.
Default: None
Type: int
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.
Default: None
Type: str, unicode, NoneType
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:
y – The top Y coordinate.
Type: int
x – The left X coordinate.
Type: int
w – The width.
Type: int
h – The height.
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.
Default: None
Type: str, unicode, NoneType
fill – Specifies whether the shape should be filled (True) or consist of an
outline (False).
Default: False
Type: bool
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.
Default: None
Type: int
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:
y – The Y coordinate of the dot center, or None to draw a vertically centered
dot.
Default: None
Type: int, NoneType
x – The X coordinate of the dot center, or None to draw a horizontally
centered dot.
Default: None
Type: int, NoneType
style – The fixation-dot style. One of: default, large-filled, medium-filled,
small-filled, large-open, medium-open, small-open, large-cross, mediumcross, or small-cross. default equals medium-open.
Default: u’default’
Type: str, unicode
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.
Default: None
Type: str, unicode, NoneType
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:
y – The center Y coordinate.
Type: int
x – The center X coordinate.
Type: int
freq – Frequency in cycles/px of the sinusoid.
Type: float, int
orient – Orientation in degrees [0 .. 360].
Type: float, int
Keywords:
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.
Default: u’avg’
Type: str, unicode
env – The envelope that determines the shape of the patch. Can be
“gaussian”, “linear”, “circular”, or “rectangular”.
Default: u’gaussian’
Type: str, unicode
stdev – Standard deviation in pixels of the gaussian. Only applicable to
gaussian envelopes.
Default: 12
Type: float, int
phase – Phase of the sinusoid [0.0 .. 1.0].
Default: 0
Type: float, int
size – A size in pixels.
Default: 96
Type: float, int
col2 – A color for the troughs. Note: The psycho back-end ignores this
parameter and always uses the inverse of col1 for the throughs.
Default: u’black’
Type: str, unicode
col1 – A color for the peaks.
Default: u’white’
Type: str, unicode
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:
y – The Y coordinate, or None to draw a vertically centered image.
Default: None
Type: int, NoneType
x – The X coordinate, or None to draw a horizontally centered image.
Default: None
Type: int, NoneType
scale – The scaling factor of the image. None or 1 indicate the original size. 2.0
indicates a 200% zoom, etc.
Default: None
Type: float, int, NoneType
center – A bool indicating whether coordinates indicate the center (True) or
top-left (False).
Default: True
Type: bool
function canvas.line(sx, sy, ex, ey, color=None, penwidth=None)
Draws a line.
Arguments:
sy – The top Y coordinate.
Type: int
sx – The left X coordinate.
Type: int
ey – The bottom Y coordinate.
Type: int
ex – The right X 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.
Default: None
Type: str, unicode, NoneType
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.
Default: None
Type: int
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:
y – The center Y coordinate.
Type: int
x – The center X coordinate.
Type: int
Keywords:
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.
Default: u’avg’
Type: str, unicode
env – The envelope that determines the shape of the patch. Can be
“gaussian”, “linear”, “circular”, or “rectangular”.
Default: u’gaussian’
Type: str, unicode
stdev – Standard deviation in pixels of the gaussian. Only applicable to
gaussian envelopes.
Default: 12
Type: float, int
size – A size in pixels.
Default: 96
Type: float, int
col2 – The second color. Note: The psycho back-end ignores this parameter
and always uses the inverse of col1.
Default: u’black’
Type: str, unicode
col1 – The first color.
Default: u’white’
Type: str, unicode
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:
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.
Default: None
Type: str, unicode, NoneType
fill – Specifies whether the shape should be filled (True) or consist of an
outline (False).
Default: False
Type: bool
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.
Default: None
Type: int
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:
y – The top Y coordinate.
Type: int
x – The left X coordinate.
Type: int
w – The width.
Type: int
h – The height.
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.
Default: None
Type: str, unicode, NoneType
fill – Specifies whether the shape should be filled (True) or consist of an
outline (False).
Default: False
Type: bool
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.
Default: None
Type: int
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)
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.
Default: None
Type: str, unicode
size – A font size in pixels, or None to use the experiment default.
Default: None
Type: int
underline – A bool indicating whether the font should be underlined, or None
to use the experiment default.
Default: None
Type: bool, NoneType
italic – A bool indicating whether the font should be italic, or None to use
the experiment default.
Default: None
Type: bool, NoneType
bold – A bool indicating whether the font should be bold, or None to use the
experiment default.
Default: None
Type: bool, NoneType
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:
y – The Y coordinate, or None to draw vertically centered text.
Default: None
Type: int, NoneType
html – A bool indicating whether a subset of HTML tags should be
interpreted. For more information, see </usage/text/>.
Default: True
Type: bool
center – A bool indicating whether the coordinates reflect the center (True)
or top-left (False) of the text.
Default: True
Type: bool
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.
Default: None
Type: bool, NoneType
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.
Default: None
Type: str, unicode, NoneType
x – The X coordinate, or None to draw horizontally centered text.
Default: None
Type: int, NoneType
max_width – The maximum width of the text in pixels, before wrapping to a
new line, or None to wrap at screen edge.
Default: None
Type: int, NoneType
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:
html – A bool indicating whether a subset of HTML tags should be
interpreted. For more information, see </usage/text/>.
Default: True
Type: bool
max_width – The maximum width of the text in pixels, before wrapping to a
new line, or None to wrap at screen edge.
Default: None
Type: int, NoneType
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.
Default: None
Type: bool, NoneType
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
Copyright 2010-2015 Sebastiaan Mathôt // Download as .tar.gz // Revision #1e5642 on Thu Jan 22 15:39:08 2015
© Copyright 2024