When drawing in Luxor you'll usually be creating paths and polygons. It can be easy to confuse the two.
In Luxor, a path is something that you manipulate by calling functions that control Cairo's path-drawing engine. There isn't a Luxor struct or datatype that contains or maintains a path (although see below). Cairo keeps track of the current path, the current point, and the current graphics state, in response to the functions you call.
A path can contain one or more sequences of straight lines and Bézier curves. There's always a single active path. It starts off being empty.
The following figure was drawn using this function, which creates a single path consisting of three separate shapes - a line, a rectangular box, and a circle:
function make_path() move(Point(-220, 50)) line(Point(-170, -50)) line(Point(-120, 50)) move(Point(0, 0)) box(O, 100, 100, :path) move(Point(180, 0) + polar(40, 0)) # pt on circumference circle(Point(180, 0), 40, :path) end
move() function as used here is essentially a "pick up the pen and move it elsewhere" instruction.
The top path, in purple, is drawn when
strokepath() is applied to this path. Each of the three shapes is stroked with the same current settings (color, line thickness, dash pattern, and so on).
The middle row shows a duplicate of this path, and
fillpath() has been applied to fill each of the three shapes in the path with orange.
Many functions in Luxor have an
action keyword argument or parameter. If you want to add that shape to the current path, use
:path. If you want to both add the shape and finish and draw the current path, use one of
After the path is stroked or filled, it's emptied out, ready for you to start over again. But you can also use one of the '-preserve' varsions,
:strokepreserve to continue working with the current defined path after drawing it. You can convert the path to a clipping path using
A single path can contain multiple separate graphic shapes. These can make holes. If you want a path to contain holes, you add the hole shapes to the current path after reversing their direction. For example, to put a square hole inside a circle, first create a circular shape, then draw a square shape inside, making sure that the square runs in the opposite direction to the circle. When you finally draw the path, the interior shape forms a hole.
sethue("purple") circle(O, 200, :path) box(O, 100, 100, :path, reversepath=true) fillpath()
If you're constructing the path from simple path commands, this is easy, and the functions that provide a
reversepath keyword argument can help. If not, you can do things like this:
circle(O, 100, :path) # add a circle to the current path poly(reverse(box(O, 50, 50)), :path) # create polygon, add to current path after reversing fillpath() # finally fill the two-part path
Many methods, including
star(), offer a
vertices keyword argument. With these you can specify
vertices=true to return a list of points instead of constructing a path.
Note that methods to functions might vary in how they operate: whereas
box(Point(0, 0), 50, 50) returns a polygon (a list of points),
box(Point(0, 0), 50, 50, :path) adds a rectangle to the current path and returns a polygon. However,
box(Point(0, 0), 50, 50, 5 ... ) constructs a path with Bézier-curved corners, so this method doesn't return any vertex information - you'll have to flatten the Béziers via
getpathflat() or obtain the path with intact Béziers via
The Luxor function
getpath() retrieves the current Cairo path and returns a Cairo path object, which you could iterate through using code like this:
import Cairo o = getpath() x, y = currentpoint() for e in o if e.element_type == Cairo.CAIRO_PATH_MOVE_TO (x, y) = e.points move(x, y) elseif e.element_type == Cairo.CAIRO_PATH_LINE_TO (x, y) = e.points # straight lines line(x, y) strokepath() circle(x, y, 1, :stroke) elseif e.element_type == Cairo.CAIRO_PATH_CURVE_TO (x1, y1, x2, y2, x3, y3) = e.points # Bézier control lines circle(x1, y1, 1, :stroke) circle(x2, y2, 1, :stroke) circle(x3, y3, 1, :stroke) move(x, y) curve(x1, y1, x2, y2, x3, y3) strokepath() (x, y) = (x3, y3) # update current point elseif e.element_type == Cairo.CAIRO_PATH_CLOSE_PATH closepath() else error("unknown CairoPathEntry " * repr(e.element_type)) error("unknown CairoPathEntry " * repr(e.points)) end end
But the current Cairo path isn't otherwise accessible in Luxor.
A polygon isn't an existing Luxor struct or datatype either. It always appears as a plain Vector (Array) of
Points. There are no lines or curves, just 2D coordinates in the form of
Points. When a polygon is eventually drawn, it's converted into a path, and the points are usually connected with short straight lines.
pathtopoly() function extracts the current path that Cairo is in the process of constructing and returns an array of Vectors of points - a set of one or more polygons (remember that a single path can contain multiple shapes). Internally this function uses
getpathflat(), which is similar to
getpath() but it returns a Cairo path object in which all Bézier curve segments have been reduced to sequences of short straight lines.
circle(O, 100, :path) p = pathtopoly() poly(first(p), :stroke)
is more or less equivalent to:
ngon(O, 100, 129, 0, :stroke) # a 129agon with radius 100
Luxor draws as many short straight lines as necessary (here about 129) so as to render the curve smooth at reasonable magnifications.