Overview¶
The Canvas¶
The Canvas
class is the first thing you will need to create - it is
the base upon which everything else is created. If you’ve ever used HTML or GUI
canvases, they work in much the same way.
>>> import omnicanvas
>>> canvas = omnicanvas.Canvas(600, 400)
>>> canvas.width()
600
>>> canvas.height()
400
Canvases need width and height information, in pixels. You can also specify the background color:
>>> canvas = omnicanvas.Canvas(600, 400, background_color="#0000DD")
>>> canvas.background_color()
'#0000DD'
Graphics¶
Canvases contain a list of graphics (which all inherit from class
Graphic
), and it is these objects which make up the image.
Currently, there are the following types.
Rectangles¶
Rectangle
objects are... rectangles. Boxes, defined with the
coordinates of their top-left corner, and width and height:
>>> canvas.add_rectangle(10, 10, 300, 200)
>>> canvas.graphics()[0]
<Rectangle 300×200 at (10,10)>
>>> canvas.graphics()[0].width()
300
Rectangles inherit from ShapeGraphic
which means they have a fill
color and opacity:
>>> canvas.add_rectangle(10, 10, 300, 200, fill_color="#3344EE", opacity=0.5)
>>> canvas.graphics()[-1].fill_color()
'#3344EE'
>>> canvas.graphics()[-1].opacity()
0.5
They also, like all classes which inherit from class Graphic
,
have properties relating to their lines:
>>> canvas.add_rectangle(10, 10, 300, 200, line_width=2, line_style="--")
>>> canvas.graphics()[-1].line_width()
2
>>> canvas.graphics()[-1].line_style()
'--'
>>> canvas.graphics()[-1].line_color("#FFFF00")
>>> canvas.graphics()[-1].line_color()
'#FFFF00'
Lines¶
Line
objects are even more straightforward. They are lines defined
by a start coordinate and an end coordinate:
>>> canvas.add_line(10, 10, 90, 90)
>>> canvas.x1()
10
>>> canvas.y1()
10
>>> canvas.x2()
90
>>> canvas.y2()
90
Lines inherit directly from Graphic
and have the same properties
relating to line width etc. as above.
Polygons¶
Polygon
objects are two-dimensional shapes with an arbitrary number
of points. These are given as a sequence of coordinates:
>>> canvas.add_polygon(60, 60, 90, 120, 30, 120) # Creates a triangle
>>> canvas.graphics()[-1].coordinates()
(60, 60, 90, 120, 30, 120)
>>> canvas.graphics()[-1].coordinates(xy_pairs=True)
((60, 60), (90, 120), (30, 120))
You must supply an even number of points, and there must be at least three vertices.
Otherwise they behave much like Rectangles - they inherit from
ShapeGraphic
and Graphic
and so have the above
properties relating to fill and border.
Text¶
Text
objects are used to hold text. Unlike other Graphics, their
default fill_color
is black, not white, and their default line_width
is
0, not 1.
>>> canvas.add_text(50, 50, "OmniCanvas is sexy", font_size=32)
>>> canvas.graphics()[-1].text()
'OmniCanvas is sexy'
>>> canvas.graphics()[-1].font_size()
32
>>> canvas.graphics()[-1].fill_color()
'#000000'
>>> canvas.graphics()[-1].line_width()
0
The coordinate given by default will be the centre of the text. This can be changed by specifying the desired horizontal and vertical alignment:
>>> canvas.add_text(50, 50, "X", vertical_align="top", horizontal_align="left")
Polylines¶
These are very similar to Polygon
, except the last vertex is not
joined to the first one, and so they have no interior space. They are just lines
with an arbitrary number of vertices.
They behave very similarly to Polygons:
>>> canvas.add_polyline(60, 60, 90, 120, 30, 120)
>>> canvas.graphics()[-1].coordinates()
(60, 60, 90, 120, 30, 120)
>>> canvas.graphics()[-1].coordinates(xy_pairs=True)
((60, 60), (90, 120), (30, 120))
Graphic Retrieval¶
All of the above graphic adding methods will return the graphic they have just added, if you need a reference to it later.
>>> rectangle = canvas.add_rectangle(10, 10, 300, 200)
>>> rectangle
<Rectangle 300×200 at (10,10)>
Additionally, all graphics can be given names, which can then be used to
retrieve them from the Canvas using two methods -
get_graphic_by_name()
and
get_graphics_by_name()
:
>>> canvas.add_line(10, 10, 90, 90, name="Line 1")
>>> canvas.add_line(20, 10, 90, 90, name="Line 2")
>>> canvas.add_line(10, 20, 90, 90, name="A Line")
>>> canvas.add_line(20, 20, 90, 90, name="A Line")
>>> canvas.get_graphic_by_name("Line 1")
<Line (10,10) to (90,70)>
>>> canvas.get_graphic_by_name("Line 2")
<Line (20,10) to (90,70)>
>>> canvas.get_graphic_by_name("A Line")
<Line (10,20) to (90,70)>
>>> canvas.get_graphics_by_name("A Line")
[<Line (10,20) to (90,70)>, <Line (20,20) to (90,70)>]
Outputs¶
Once the canvas has been decorated with whatever Graphics you see fit, it can be saved to file:
>>> canvas.save("example.svg")
Most browsers will have no trouble displaying SVG files once created.
If you want to get the text of the SVG directly, you can use the to_svg()
method of canvases, which will return this raw text.