Introduction

Nell is a language for describing two dimensional vector drawings. We have been using versions of the language for several years to create illustrations for books, web pages and various art projects. It can even be used as a tool for physics and math simulations and experiments. You can for instance do optics ray tracing with it. There are a couple of examples later in the documentation that show how to do this.

We created the language because of our frustration with how tedious and time consuming it can be to create complex vector drawings. Why sit in front of a screen for hours clicking and dragging with a mouse when you can spend a few minutes thinking about your drawing, solving a few geometry and trigonometry problems and then writing a simple program that will create the drawing for you. It's less tedious and a lot more fun, plus you get to sharpen your math and programming skills.

A big advantage of using Nell is that you can parameterize the drawing. Lengths, angles, numbers of polygons, circles, ellipses, arcs, and curves can all be parameterized so you can easily experiment with different values and quickly see how the drawing changes. Another advantage is the simplicity of the language itself. It's so simple that it's easy to write programs that create Nell programs. We have used this technique to explore domains of possible drawings and have created thousands of interesting patterns in the process.

We usually use Nell to create just the basic outline of a complex drawing. Then if we want to decorate the drawing with different colors and line styles we use an interactive vector drawing program such as Inkscape. This is because there is currently no way to set stroke width and color for individual elements of a drawing or to set the fill color for individual polygons, circles and ellipses. We have thought about adding colors and styles to Nell but have decided against it to keep the language as simple as possible. Would you like to see colors and styles in the Nell language? Let us know what you think.

To understand how to use Nell it is helpful to be at least vaguely familiar with the rudiments of Cartesian or analytic geometry. This is geometry in which points, lines and curves are defined in a coordinate system. Coordinates are sets of numbers that are used to locate the position of a point in the coordinate system. Equations are often used to relate coordinates thus defining a set of points that make up a curve. Just the basics of high school algebra and geometry is all you need to use Nell. To be a power user you probably also need to know a little basic trigonometry.

Drawings in Nell are defined in a standard two dimensional Cartesian space where the positive x axis is to the right, the positive y axis is up and a point is represented by a pair of numbers (x,y). To keep things simple it is assumed that the final drawing will always be entirely in the positive first quadrant where x and y are greater than or equal to zero. Lines and curves can extend into quadrants with negative values for x and y but the final drawing, produced as an svg file, will always be clipped to the positive first quadrant.

Drawings by default start at the origin (0,0). The current position can easily be changed with the position command P(x,y). At each step during the execution of a drawing there is a current position and a current direction. The direction is an angle measured relative to the positive x axis. A drawing always starts out with direction along the positive x axis i.e. at angle 0. Positive angles are measured counterclockwise and negative angles are measured clockwise. Imagine yourself facing in the current direction. A command to turn by a positive angle then means a turn to your left and a negative angle means a turn to the right.

The current position and direction are changed when drawing and positioning commands are executed. For example the command L(1) will draw a line of length 1 in the current direction starting at the current position. The new current position is at the end of the line while the current direction is unchanged. The command T(a) will turn by an angle a with respect to the current direction and make the new direction the current direction. There are other commands that change the current position and direction. You can read about them in the command definitions and example sections that follow.

Creating a drawing is a two step process. First the command line program nell reads a drawing definition file that contains variable definition lines and named command strings that are used to create the drawing. Using the defined variables, the command strings are expanded out into one long string of primitive drawing commands that is written to standard output i.e. the terminal.

The string of primitive drawing commands is read by another command line program called nellsvg. This converts the drawing commands into an svg (scalable vector graphics) file which is also written to standard output. This two step process is used so that in the future it will be easier to produce output in other file formats such as pdf with a nellpdf program for example.

The nell program takes three command line parameters and is run as follows.

Usage: nell ddfile scs mrl
  ddfile = name of drawing definition file.
  scs = name of starting command string.
  mrl = maximum recursion level.

The parameter ddfile is the name of the drawing definition file. The name can be any valid filename but for all the example drawings in this documentation we use the file extension nll. The parameter scs is the name of the starting command string, see the description of the drawing definition file and the examples that follow for an explanation of this parameter. A named command string can substitute itself and this recursion must be stopped at some point. The parameter mrl sets the maximum recursion level.

The nellsvg program takes five command line parameters and is run as follows.

Usage: nellsvg width height units sw fh
  width = width of canvas.
  height = height of canvas.
  units = px pt pc cm mm in.
  sw = stroke width in given units.
  fh = 1 to flip about the horizontal.

The parameters width and height specify the width and height of the svg drawing. The parameter units gives the units of the width and height. The parameter sw gives the stroke width for all elements of the drawing. The parameter fh specifies if the drawing is to be flipped with respect to the horizontal. For fh=1 the drawing is executed with positive y going up and positive x going right. Otherwise positive y is in the downward direction as it is in svg drawings by default.

Both the nell and nellsvg programs are written in standard C. They do not require any additional software libraries and are platform independent i.e. you should be able to compile and run them on any computer running any operating system (e.g. Linux, macOS, Windows) that has a C compiler. The programs are free open source software released under the GPL license. You can download the source code from the book's website at http://www.abrazol.com/books/nell/ and compile the programs with any C compiler. There are many programs you can use to view the svg files ranging from a web browser like Firefox to the display program that comes with ImageMagick.

The following is a list of source code files needed to compile the nell and nellsvg programs.

If you're using the gcc compiler you can compile the two programs with the following commands.

gcc -lm -o nell calcfun.c nell.c
gcc -lm -o nellsvg nellsvg.c

Next we will describe the drawing definition file. This will be followed by many examples that show how to use the language.

In case you're wondering, the language is named after both Sister Plautilla Nelli (1524-1588), the first known female Renaissance painter of Florence, and the ladybug, which belongs to the family of small beetles called Coccinellidae.