The 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)
The following functions can be used to configure the overall drawing behavior of the canvas. You typically begin any drawing by calling set_size().
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.
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.
Using these functions affects any drawing operations that follow. For example, calling set_fill_color() with a red color will make any following call to 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.
(see also set_alpha())
Sets the fill color.
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_line(), add_curve(), etc. and then fill or stroke the path with fill_path() or draw_path(). If you intend to fill a path, you might want to close it first with close_path().
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 xrange(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)
Adds a cubic bezier curve to (x, y) to the current path, with the control points (cp1x, cp1y) and (cp2x, cp2y).
Adds an ellipse to the current path.
Adds a straight line to the current path.
Adds a quadratic bezier curve to (x, y) to the current path with (cpx, cpy) as the control point.
Adds a rectangle to the current path.
Draws an ellipse in a rectangle
Draws a line between two points
Draws the outline of the current path with the active line width and color.
Draws the outline of a rectangle
Fills the current path with the active fill color.
Fills a pixel with the current fill color
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() and restore_gstate() functions. 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 stack.
In case you want to completely reset any transformations, but you didn’t save the graphics state, you can use the set_size() function.
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 xrange(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 save_gstate().
Rotates the current transformation matrix.
Pushes a copy of the current graphics state (transformation, selected colors etc.) onto the graphics state stack.
(see also restore_gstate())
Scales the current transformation matrix.
Although it is primarily designed for vector graphics, the canvas module also has some functions for drawing bitmap images, similar to the scene module. You can draw named images or the current contents of the clipboard.
Draws the image with the given name in a rectangle. If width and height are omitted, the image is drawn at its natural size.
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.
The canvas module has two simple functions for drawing and measuring text.
Draw a single line of text at a given point. The point represents the origin of the line, i.e. its lower-left corner.
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 set_blend_mode():