The basics

Create a new drawing, and optionally specify file type (PNG, PDF, SVG, or EPS) and dimensions.

Drawing()

creates a drawing, defaulting to PNG format, default filename "luxor-drawing.png", default size 800 pixels square.

You can specify dimensions, and use the default target filename:

Drawing(400, 300)

creates a drawing 400 pixels wide by 300 pixels high, defaulting to PNG format, default filename "luxor-drawing.png".

Drawing(400, 300, "my-drawing.pdf")

creates a PDF drawing in the file "my-drawing.pdf", 400 by 300 pixels.

Drawing(1200, 800, "my-drawing.svg")`

creates an SVG drawing in the file "my-drawing.svg", 1200 by 800 pixels.

Drawing(1200, 1200/golden, "my-drawing.eps")

creates an EPS drawing in the file "my-drawing.eps", 1200 wide by 741.8 pixels (= 1200 ÷ ϕ) high.

Drawing("A4", "my-drawing.pdf")

creates a drawing in ISO A4 size (595 wide by 842 high) in the file "my-drawing.pdf". Other sizes available are: "A0", "A1", "A2", "A3", "A4", "A5", "A6", "Letter", "Legal", "A", "B", "C", "D", "E". Append "landscape" to get the landscape version.

Drawing("A4landscape")

creates the drawing A4 landscape size.

PDF files default to a white background, but PNG defaults to transparent, unless you specify one using background().

finish()

Finish the drawing, and close the file. You may be able to open it in an external viewer application with preview().

preview()

If working in Jupyter (IJUlia), display a PNG file in the notebook. On macOS, open the file, which probably uses the default, Preview.app. On Unix, open the file with xdg-open. On Windows, pass the filename to the shell.

background(color)

Fill the canvas with a single color. Returns the (red, green, blue, alpha) values.

Examples:

background("antiquewhite")
background("ivory")

If Colors.jl is installed:

background(RGB(0, 0, 0))
background(Luv(20, -20, 30))

If you don't specify a background color for a PNG drawing, the background will be transparent. You can set a partly or completely transparent background for PNG files by passing a color with an alpha value, such as this 'transparent black':

background(RGBA(0, 0, 0, 0))

Draw and label two axes lines starting at O, the current 0/0, and continuing out along the current positive x and y axes.

origin()

Reset the current matrix, and then set the 0/0 origin to the center of the drawing (otherwise it will stay at the top left corner, the default).

You can refer to the 0/0 point as O. (O = Point(0, 0)),

tiles = Tiler(areawidth, areaheight, nrows, ncols, margin=20)

A Tiler is an iterator that, for each iteration, returns a tuple of:

• the x/y point of the center of each tile in a set of tiles that divide up a rectangular space such as a page into rows and columns (relative to current 0/0)

• the number of the tile

areawidth and areaheight are the dimensions of the area to be tiled, nrows/ncols are the number of rows and columns required, and margin is applied to all four edges of the area before the function calculates the tile sizes required.

tiles = Tiler(1000, 800, 4, 5, margin=20)
for (pos, n) in tiles
# the point pos is the center of the tile
end

You can access the calculated tile width and height like this:

tiles = Tiler(1000, 800, 4, 5, margin=20)
for (pos, n) in tiles
  ellipse(pos.x, pos.y, tiles.tilewidth, tiles.tileheight, :fill)
end

gsave()

Save the current color settings on the stack.

grestore()

Replace the current graphics state with the one on top of the stack.

rect(xmin, ymin, w, h, action)

Create a rectangle with one corner at (xmin/ymin) with width w and height h and then do an action.

See box() for more ways to do similar things, such as supplying two opposite corners, placing by centerpoint and dimensions.

rect(cornerpoint, w, h, action)

Create a rectangle with one corner at cornerpoint with width w and height h and do an action.

box(cornerpoint1, cornerpoint2, action=:nothing)

Create a rectangle between two points and do an action.

box(points::Array, action=:nothing)

Create a box/rectangle using the first two points of an array of Points to defined opposite corners.

box(pt::Point, width, height, action=:nothing; vertices=false)

Create a box/rectangle centered at point pt with width and height. Use vertices=true to return an array of the four corner points rather than draw the box.

box(x, y, width, height, action=:nothing)

Create a box/rectangle centered at point x/y with width and height.

Find the bounding box of a polygon (array of points).

polybbox(pointlist::Array)

Return the two opposite corners (suitable for box(), for example).

circle(x, y, r, action=:nothing)

Make a circle of radius r centred at x/y.

action is one of the actions applied by do_action, defaulting to :nothing. You can also use ellipse() to draw circles and place them by their centerpoint.

circle(pt, r, action)

Make a circle centred at pt.

circle(pt1::Point, pt2::Point, action=:nothing)

Make a circle that passes through two points that define the diameter:

Make an ellipse, centered at xc/yc, fitting in a box of width w and height h.

ellipse(xc, yc, w, h, action=:none)

Make an ellipse, centered at point c, with width w, and height h.

ellipse(cpt, w, h, action=:none)

ellipse(focus1::Point, focus2::Point, k, action=:none;
         stepvalue=pi/100,
         vertices=false,
         reversepath=false)

Build a polygon approximation to an ellipse, given two points and a distance, k, which is the sum of the distances to the focii of any points on the ellipse (or the shortest length of string required to go from one focus to the perimeter and on to the other focus).

circlepath(center::Point, radius, action=:none;
    reversepath=false,
    kappa = 0.5522847)

Draw a circle using Bézier curves.

sector(innerradius, outerradius, startangle, endangle, action=:none)

Make an annular sector centered at the current 0/0 point.

sector(innerradius, outerradius, startangle, endangle, cornerradius, action=:none)

Draw an annular sector with rounded corners, basically a bent sausage shape.

TODO: The results aren't 100% accurate at the moment. There are small discontinuities where the curves join.

The cornerradius is reduced from the supplied value if neceesary to prevent overshoots.

pie(x, y, radius, startangle, endangle, action=:none)

Make a pie shape centered at x/y. Angles start at the positive x-axis and are measured clockwise.

pie(centerpoint, radius, startangle, endangle, action=:none)

Make a pie shape centered at centerpoint.

Angles start at the positive x-axis and are measured clockwise.

Make a squircle (basically a rectangle with rounded corners). Specify the center position, horizontal radius (distance from center to a side), and vertical radius (distance from center to top or bottom):

squircle(center::Point, hradius, vradius, action=:none; rt = 0.5, vertices=false)

The rt option defaults to 0.5, and gives an intermediate shape. Values less than 0.5 make the shape more square. Values above make the shape more round.

Add an arc to the current path from angle1 to angle2 going clockwise.

arc(xc, yc, radius, angle1, angle2, action=:nothing)

Angles are defined relative to the x-axis, positive clockwise.

Arc with centerpoint.

arc(centerpoint::Point, radius, angle1, angle2, action=:nothing)

  arc2r(c1, p2, p3, action=:nothing)

Make a circular arc centered at c1 that starts at p2 and ends at p3, going clockwise.

c1-p2 really determines the radius. If p3 doesn't lie on the circular path, it will be used only as an indication of the arc's length, rather than its position.

Add an arc to the current path from angle1 to angle2 going counterclockwise.

carc(xc, yc, radius, angle1, angle2, action=:nothing)

Angles are defined relative to the x-axis, positive clockwise.

Draw a Bézier curve.

 curve(x1, y1, x2, y2, x3, y3)
 curve(p1, p2, p3)

The spline starts at the current position, finishing at x3/y3 (p3), following two control points x1/y1 (p1) and x2/y2 (p2)

move(x, y)
move(pt)

Move to a point.

rmove(x, y)

Move by an amount from the current point. Move relative to current position by x and y:

Move relative to current position by the pt's x and y:

rmove(pt)

line(x, y)
line(x, y, :action)
line(pt)

Create a line from the current position to the x/y position and optionally apply an action:

line(pt1::Point, pt2::Point, action=:nothing)

Make a line between two points, pt1 and pt2 and do an action.

rline(x, y)
rline(x, y, :action)
rline(pt)

Create a line relative to the current position to the x/y position and optionally apply an action:

midpoint(p1, p2)

Find the midpoint between two points.

midpoint(a)

Find midpoint between the first two elements of an array of points.

between(p1::Point, p2::Point, x)

Find the point between point p1 and point p2 for x, where x is typically between 0 and 1, so these two should be equivalent:

between(p1, p2, 0.5)

and

midpoint(p1, p2)

center3pts(a::Point, b::Point, c::Point)

Find the radius and center point for three points lying on a circle.

returns (centerpoint, radius) of a circle. Then you can use circle() to place a circle, or arc() to draw an arc passing through those points.

If there's no such circle, then you'll see an error message in the console and the function returns (Point(0,0), 0).

intersection(p1::Point, p2::Point, p3::Point, p4::Point)

Find intersection of two lines p1-p2 and p3-p4

This returns a tuple: (boolean, point(x, y)).

Keyword options and default values:

crossingonly = false

returns (true, Point(x, y)) if the lines intersect somewhere. If crossingonly = true, returns (false, intersectionpoint) if the lines don't cross, but would intersect at intersectionpoint if continued beyond their current endpoints.

commonendpoints = false

If commonendpoints= true, will return (false, Point(0, 0)) if the lines share a common end point (because that's not so much an intersection, more a meeting).

Function returns (false, Point(0, 0)) if the lines are undefined,

intersection_line_circle(p1::Point, p2::Point, cpoint::Point, r)

Find the intersection points of a line (extended through points p1 and p2) and a circle.

Return a tuple of (n, pt1, pt2)

where

• n is the number of intersections, 0, 1, or 2

• pt1 is first intersection point, or Point(0, 0) if none

• pt2 is the second intersection point, or Point(0, 0) if none

The calculated intersection points wont necessarily lie on the line segment between p1 and p2.

getnearestpointonline(pt1::Point, pt2::Point, startpt::Point)

Given a line from pt1 to pt2, and startpt is the start of a perpendicular heading to meet the line, at what point does it hit the line?

arrow(startpoint::Point, endpoint::Point;
    linewidth = 1.0,
    arrowheadlength = 10,
    arrowheadangle = pi/8)

Draw a line between two points and add an arrowhead at the end. The arrowhead length will be the length of the side of the arrow's head, and the arrowhead angle is the angle between the sloping side of the arrowhead and the arrow's shaft.

Arrows don't use the current linewidth setting (setline()), and defaults to 1, but you can specify another value. It doesn't need stroking/filling, the shaft is stroke()d and the head fill()ed with the current color.

arrow(centerpos::Point, radius, startangle, endangle;
    linewidth = 1.0,
    arrowheadlength = 10,
    arrowheadangle = pi/8)

Draw a curved arrow, an arc centered at centerpos starting at startangle and ending at endangle with an arrowhead at the end. Angles are measured clockwise from the positive x-axis.

Arrows don't use the current linewidth setting (setline()); you can specify the linewidth.

newpath()

Create a new path. This is Cairo's new_path() function.

newsubpath()

Add a new subpath to the current path. This is Cairo's new_sub_path() function. It can be used for example to make holes in shapes.

closepath()

Close the current path. This is Cairo's close_path() function.

getpath()

Get the current path and return a CairoPath object, which is an array of element_type and points objects. With the results you can step through and examine each entry:

o = getpath()
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)
          stroke()
          circle(x, y, 1, :stroke)
      elseif e.element_type == Cairo.CAIRO_PATH_CURVE_TO
          (x1, y1, x2, y2, x3, y3) = e.points
          # Bezier 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)
          stroke()
          (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

getpathflat()

Get the current path, like getpath() but flattened so that there are no Bèzier curves.

Returns a CairoPath which is an array of element_type and points objects.

julialogo(;action=:fill, color=true)

Draw the Julia logo. The logo's dimensions are about 330 wide and 240 high:

translate(-330/2, -240/2)
julialogo()

The default action is to fill the logo and use colors:

julialogo()

To use the logo as a clipping mask:

julialogo(action=:clip)

(In this case the color setting is automatically ignored.)

If color is false, the logo will use the current color.

juliacircles(radius=100)

Draw the three Julia circles in color at the origin using the given radius.

hypotrochoid(R, r, d, action=:none; stepby=0.1, period=0)

Draw a hypotrochoid with short line segments. (Like a Spirograph.) The curve is traced by a point attached to a circle of radius r rolling around the inside of a fixed circle of radius R, where the point is a distance d from the center of the interior circle.

stepby controls the detail level. If period is not supplied, or 0, the lowest period is calculated (somewhat approximately at the moment), and also returned in terms of 2pi.

Special cases include the hypocycloid, if d = r, and an ellipse, if R = 2r.

The polygon might be split if the number of line segments gets too large (currently over 1200).