Canvas draw library

From FlightGear wiki
Revision as of 10:56, 22 December 2018 by Hooray (talk | contribs) (→‎Motivation)
Jump to navigation Jump to search
Note  Canvas draw is currently work in progress. You can test and improve it by downloading the CanvasDrawDev add-on. The canvas.draw library will hopefully be ready to use in FG version 2019.1

CanvasDrawDev add-on

The purpose of this add-on is to develop a nasal library of canvas drawing functions. This lib should eventually be moved to FGDATA/Nasal once it has reached a sufficient quality.


There are basically two ways to populate a canvas, loading an SVG file which has been created with some tool like inkscape, or by writing a nasal program that calls drawing functions of the canvas API.

Both ways are valid and have their pros and cons.

The canvas API is quite limited (at the time of writing), only a few basic commands are available. There should be more drawing commands to allow rapid development of canvas instruments for other aircraft.


  • Make the code flexible and powerful so people will like to use it
  • Provide complex drawing commands needed for e.g. compass rose or speed tapes
  • Provide easy to use styles
  • Support API versioning to allow later extensions of the library

canvas.draw API

Note  This API is subject to change without notice until it has been released with FG in FGDATA

draw module

All draw methods expect a canvas group element 'cgroup' as first parameter to draw on.


A hash with some standard colors like white, black, red, green, blue, cyan, magenta, yellow, orange. Just in case you need them ;)


circle(cgroup, radius, center_x = nil, center_y = nil)

radius in pixel

center_x, center_y optional center of circle


ellipse(cgroup, radius, center_x = nil, center_y = nil)

radius_x, radius_y in pixel

center_x, center_y optional center of ellipse


arc(cgroup, radius, center, from_deg = nil, to_deg = nil)

draw an arc (part of a circle) with given radius around center

center center point of circle as vector [x,y]

from_deg, to_deg start and end of arc in degree of compass rose (0 = North, 90 = East, ...); defaults to 0, 360 (full circle)


rectangle(cgroup, width, height, x = 0, y = 0, rounded = nil)

width, height dimensions in pixels

x, y top-left corner of rectangle

rounded optional radius of corners in pixel


square(cgroup, length, center_x = 0, center_y = 0, cfg = nil)

shorthand for rectangle with width = height = length


deltoid (cgroup, dx, dy1, dy2, x = 0, y = 0)

Deltoid draws a kite (dy1 > 0 and dy2 > 0) or a arrow head (dy2 < 0).

dx width

dy1 height of "upper" triangle

dy2 height of "lower" triangle, < 0 draws an arrow head

x, y position of tip

rhombus() / diamond()

rhombus: func(cgroup, dx, dy, center_x = 0, center_y = 0)

draws a diamond

dx width

dy height


Draw horizontal and verical lines. Two signatures are available

1) (cgroup, [sizeX, sizeY], dx, dy, border = 1)

2) (cgroup, nx, ny, dx, dy, border = 1)

size [width, height] of grid in pixels.

nx, ny number of lines in x/y direction

dx, dy distance between lines in pixels.

border optional boolean, draw lines at sizeX and sizeY, true by default.


Marks can be used to create scales / gauges.


marksLinear(cgroup, orientation, num_marks, interval, style)

Draw marks for a linear scale on a canvas group, e.g. speed tape. Mark lines are draws perpendicular to baseline.

orientation of baseline, 0 = horizontal, 1 = vertical

num_marks number of marks to draw

interval distance between marks (pixel)

style marksStyle hash with more parameters


marksCircular(cgroup, radius, interval, phi_start = 0, phi_stop = 360, style = nil)

draw marks along an arc or circle of given radius

radius of baseline (circle)

interval distance of marks in degree

phi_start position of first mark in degree (default 0 = north)

phi_stop position of last mark in degree (default 360)

Base class for styles.


Parameter hash for drawing marks (see above).


Create a new style instance.

var myMarkStyle =


Set length of marker in %interval or %radius


Set alignment of markers.

You can use marksStyle.MARK_LEFT marks left of vertical baseline

MARK_UP marks above horizontal baseline

MARK_CENTER marks centered on baseline

MARK_RIGHT marks right of vertical baseline

MARK_DOWN marks below horizontal baseline

var myMarkStyle =


Set line width in pixel.


Set number of subdivisions (default = 0).


Set length of subdivision marker in %marker_length