canvas module contains functions for creating non-interactive, 2D vector graphics on iOS. It is suitable for drawing simple graphs/diagrams or line art.
All functions work on a single canvas that is shown in the output area of Pythonista. Images created this way can be exported to the device’s photo library or copied to the clipboard, though it is currently not possible to do this programmatically.
The coordinate system has its origin in the bottom-left corner, coordinates are floats. Colors are generally represented as RGB(A) with components in the range 0.0 - 1.0.
Minimal example that draws a red circle:
#Draw a red circle filling the entire canvas import canvas w = h = 512 canvas.set_size(w, h) canvas.set_fill_color(1, 0, 0) canvas.fill_ellipse(0, 0, w, h)
Configuring the Canvas#
The following functions can be used to configure the overall drawing behavior
of the canvas. You typically begin any drawing by calling
If you want to improve the performance of your drawing, you might want to add
a call to
begin_updates() before you start drawing, balanced by a call to
end_updates() at the end. This will basically avoid showing intermediate
results, which speeds things up, but it might also often be helpful to see
these intermediate results while working on your drawing code.
Clears the canvas. You can also clear the canvas with the
set_size()function, which also resets all graphics state (e.g. transformations, fill color, etc.).
Return the size of the canvas as a tuple of width and height.
- canvas.set_size(width, height)#
Set the size of the canvas (min. 16x16, max. 2048x2048) and reset all graphics state (e.g. transformations, fill color, etc.).
Begins a group of drawing operations. Results will not be visible until
end_updates()is called. This can significantly improve performance.
Forces all buffered drawing to be displayed on the screen
Save the current content of the canvas to a PNG file.
Setting Drawing Parameters#
Using these functions affects any drawing operations that follow. For example,
set_fill_color() with a red color will make any following
fill_rect() draw a red rectangle, until you set a different color.
Enables or disables antialiasing.
Sets the active blend mode. Can be one of the constants listed under Blend Modes.
- canvas.set_fill_color(r, g, b[, a])#
Sets the fill color.
Vector Drawing Functions#
The following functions are used for drawing vector paths and shapes.
The canvas always has a current path that can be manipulated with the
add_… functions. You can construct arbitrarily complex paths using
add_curve(), etc. and then fill or stroke the path
draw_path(). If you intend to fill a path,
you might want to close it first with
Filling or drawing a path has the side effect of clearing the current path.
The following example draws a star shape with some configurable parameters:
#Draw a star import canvas from math import sin, cos, pi def draw_star(x, y, inner_r, outer_r, jags): canvas.move_to(w / 2, h / 2 + inner_r) for i in range(jags * 2): angle = (2 * pi / jags) * i / 2 r = inner_r if i % 2 == 0 else outer_r x = w / 2 + r * sin(angle) y = h / 2 + r * cos(angle) canvas.add_line(x, y) canvas.close_path() canvas.set_line_width(3) canvas.draw_path() w = h = 600 jags = 7 #Number of jags inner_r = 120 #Inner radius outer_r = 250 #Outer radius canvas.set_size(w, h) draw_star(w/2, h/2, inner_r, outer_r, jags)
- canvas.add_curve(cp1x, cp1y, cp2x, cp2y, x, y)#
Adds a cubic bezier curve to (x, y) to the current path, with the control points (cp1x, cp1y) and (cp2x, cp2y).
- canvas.add_ellipse(x, y, width, height)#
Adds an ellipse to the current path.
- canvas.add_line(x, y)#
Adds a straight line to the current path.
- canvas.add_quad_curve(cpx, cpy, x, y)#
Adds a quadratic bezier curve to (x, y) to the current path with (cpx, cpy) as the control point.
- canvas.add_rect(x, y, width, height)#
Adds a rectangle to the current path.
- canvas.draw_ellipse(x, y, width, height)#
Draws an ellipse in a rectangle
- canvas.draw_line(x1, y1, x2, y2)#
Draws a line between two points
Draws the outline of the current path with the active line width and color.
- canvas.draw_rect(x, y, width, height)#
Draws the outline of a rectangle
Fills the current path with the active fill color.
- canvas.fill_pixel(x, y)#
Fills a pixel with the current fill color
- canvas.fill_rect(x, y, width, height)#
Fills a rectangle
Using the following transformation functions, you can manipulate the current transformation matrix (CTM) of your canvas. This can for example be used to draw rotated or scaled shapes. When you transform the canvas, you’re essentially changing the coordinate system which affects all drawing that follows this change.
It is often useful to be apply a transformation only temporarily. This can
be done with the
save_gstate() takes a snapshot of the current transformation (and other
graphics state parameters, such as fill color) and puts it on a stack. Calling
restore_gstate() afterwards restores the last state that was put on the
In case you want to completely reset any transformations, but you didn’t save
the graphics state, you can use the
The following example draws a clock face with rotated labels:
# Draw a clock face import canvas from math import pi canvas.set_size(600, 600) canvas.set_fill_color(0.7, 0.7, 0.7) canvas.fill_ellipse(0, 0, 600, 600) canvas.set_fill_color(0, 0, 0) canvas.fill_ellipse(290, 290, 20, 20) for i in range(12): canvas.save_gstate() canvas.translate(300, 300) canvas.rotate(-2 * pi / 12.0 * i) canvas.set_fill_color(0, 0, 0) s = 40 fnt = 'Helvetica-Bold' n = str(12 if i == 0 else i) w, h = canvas.get_text_size(n, fnt, s) canvas.draw_text(n, -w/2, 240, fnt, s) canvas.restore_gstate()
Sets the current graphics state to the state most recently saved with
Rotates the current transformation matrix.
Pushes a copy of the current graphics state (transformation, selected colors etc.) onto the graphics state stack.
- canvas.scale(sx, sy)#
Scales the current transformation matrix.
Drawing Bitmap Images#
Although it is primarily designed for vector graphics, the
also has some functions for drawing bitmap images, similar to the
module. You can draw named images or the current contents of the clipboard.
- canvas.draw_image(image_name, x, y[, width, height])#
Draws the image with the given name in a rectangle. If width and height are omitted, the image is drawn at its natural size.
- canvas.draw_clipboard(x, y, width, height)#
Draw the image in the clipboard in a given rectangle.
Return the size of the image in the clipboard as a tuple of width and height, in points. On a retina screen, one point corresponds to two pixels. Returns (0,0) if the clipboard is empty.
Returns the size of the image with the given name as a tuple of width and height, in points. On a retina screen, one point corresponds to two pixels. Returns (0, 0) if no image with this name exists.
canvas module has two simple functions for drawing and measuring
- canvas.draw_text(text, x, y, font_name='Helvetica', font_size=16.0)#
Draw a single line of text at a given point. The point represents the origin of the line, i.e. its lower-left corner.
- canvas.get_text_size(text, font_name='Helvetica', font_size=16.0)#
Get the size of a line of text as it was drawn by the draw_text() function as a tuple of (width, height).
The following blend modes can be used with