Sp: User Manual and Reference

Sp (‘simply plot’) transforms a plot description in a simple language into a picture in either of Encapsulated PostScript (EPS) or SVG vector graphics formats.

Sp aims at being simple and straightforward in use. Learning the input language for sp takes minutes. Points, straight lines, polylines, polygons, and circles are specified through respective coordinates. Drawing other curves and figures can be achieved by straight-line approximation. Colour, line type and width and other visual attributes can be chosen separately for each part of the drawing.

Typically, the input for sp is generated programmatically, but simple plots can be prepared by hand. The default coordinate system can be translated, rotated, and scaled within a drawing as convenience dictates, at as many places as needed.

The two output data formats, PostScript and SVG, are widely used for representing vector graphics. Being geometry-based, as opposed to pixel-based formats, pictures retain quality under up- and downscaling. PostScript is a standard for desktop publishing, EPS being the subset particularly suited to embedding illustrations in printed documents. SVG is the standard for web-based vector graphics: an SVG picture can be viewed individually or embedded in web documents in any web browser. Thus sp caters for the needs of both desktop and web-centred publishing.

A distinctive feature of sp is the separation of geometric magnitude, as expressed in coordinates and lengths, from dimensions of denotational character – namely, line width and point size. While magnitude is effected by scaling, denotational dimension is not.


Running sp

Sp reads its input from the standard input stream and writes the result file on the standard output. Typically, one would run sp from the command line using redirection (<, >) or piping (|). For example, if the input file is input,

sp eps <input >result.eps

would generate a result file result.eps in EPS format, and

sp svg <input >result.svg

would generate a result file result.svg in SVG format. The word eps or svg can be either lower- or uppercase. EPS is the default, so if this is the required output format, eps can be omitted.

A numeric argument to sp, such as in

sp .8 ...

or

sp svg 2 ...

establishes an overall scaling factor that applies to all coordinates and lengths in the drawing (but not to line widths, line types, and point sizes).

When the output is in EPS, it is possible to move the picture to a specific location. An invocation such as

sp 10 20 ...

moves the picture so that its centre becomes the point with coordinates (10mm,20mm). As the size of the picture does not change, moving the picture is irrelevant to its uses, except when it is displayed individually on a computer screen or printed on a sheet of paper. Embedding the picture is not effected by moving it.

It is also possible to both move and scale the whole picture as in

sp x y k ...

In this form, the first two numbers, x and y, specify the new location for the drawing's centre, and the third one, k, is the scaling factor. The latter applies after the picture is moved, i.e., with respect to its new centre.

Moving is allowed in EPS mode only, not SVG, where it does not make much sense. Specifying overall moving in SVG mode results in an error message from sp.

As the overall scaling and (or) moving result in a picture that differs from what the input file specifies, a note about the said transformation is written as a comment in the output file for user information.

When an output mode argument (eps, svg) is given to sp along with numeric arguments, the former must precede the latter.


Input file format

The sp input file is a sequence of text lines, each containing a command or data. Empty lines are allowed and have no consequence.

There are two types of commands. Construction commands specify points and geometric figures, and contextual commands set transformational and visualization parameters.

Commands take data as their arguments. Construction commands expect their arguments on separate lines, following the line with the name. These lines can be arbitrarily many, according to the number of objects or their parts. The data for a contextual command is always of a fixed volume and follows the command name on the same line.

A minus () sign at the very beginning or end of a line, or separated by spaces from its context, it and everything after it until the end of the line are skipped by sp. Also skipped is the remainder of a line after a command or data. This makes it possible to include comments in the input as seen appropriate. To prevent non-ascii encodings interfering with the correctness of the input, it is recommended that comments are always preceded by a .

Input lines that do not comply with the above rules, or ones that cannot be recognized as valid commands or data, are treated as errors and are signaled by messages on the system's standard error device. No graphical file is produced if an error is encountered.


Coordinate systems

In general, sp assumes that constructions take place in a coordinate system whose x axis points to the right, y axis points upwards, and both axes' scaling unit is 1mm. The coordinate space is ‘just enough’ wide and high. This coordinate system is called absolute.

The absolute coordinate system is the current one at the very beginning of a drawing. Certain commands can change the current coordinate system by translating, rotating and uniform scaling. The three kinds of transformations can be combined, but transformations of the same kind do not accumulate. I.e., translation, rotation, and scaling, each taken in isolation, are always carried out with respect to the absolute coordinate system: see the details in the descriptions of the respective commands move, rotate, and unit below.

As explained above, global translation and (or) scaling can be specified externally with respect to the drawing, through command-line arguments to sp. If present, such a transformation adds to each transformation specified in the drawing itself (or to a lacking such transformation), as if changing each current coordinate system accordingly.


Construction commands

All coordinates and magnitudes are interpreted with respect to the current coordinate system.

points
Points placement. On each of the following lines, a pair of coordinates of a point is given.
polyline
Constructing a polyline. The vertices of the polyline are given as point coordinates, a pair a line.
polygon
Similar to the above command, but constructs a closed figure – a polygon.
polygon*
Similar to polygon, but the figure is filled rather than stroked.
lines
Line segments construction. On each of the following lines, one segment is specified by its end points, i.e. four coordinates.
lines>
Similar to lines, but an arrow head is drawn at the end point of each segment.
lines<>
Similar to lines>, but an arrow head is also drawn at the start point of each segment.
circles
Circles construction. Each circle is specified by its centre's coordinates and its radius – a circle a line.
circles*
Similar to circles, but the circles are filled rather than stroked.


Contextual commands: transformations

Each of the following commands changes the current coordinate system, so that data (coordinates, lengths) in the subsequent construction commands is interpreted in the new system.

move
The current coordinate system is changed by a translation: the direction of the axes and the scaling remain the same while the origin moves to a specified point. The command's arguments are the coordinates of that point in the absolute coordinate system (with neither translation nor scaling).
rotate
The coordinate system is rotated about its origin. The command's argument is the angle in degrees which the x axis of the new coordinate system should make with that of the absolute system (positive values measure counterclockwise).
unit
Sets a scaling unit for coordinates and lengths – a number in millimeters. For example, if the scaling unit is set to 5, a coordinate pair 12 7 corresponds to (60mm,35mm), and a radius of 6 means 30mm.


Contextual commands: visualization attributes

colour
Colour selection. The command can be given one or three number arguments, all in the range [0,1]. One number specifies a level of grey, from 0 for black to 1 for white. Three numbers choose the amounts of the basic ingredients – red, green, and blue – to be mixed for obtaining the colour.
A colour can also be specified by name as follows:
 black   silver   gray   white 
 maroon   red   purple   fuchsia 
 green   lime   olive   yellow 
 navy   blue   teal   aqua 
All following points, lines, etc. are drawn in the specified colour.
Black is used by default.
width
The argument is the width in millimeters. All following figures are drawn with this line width. The default line width is 0.2mm.
linetype
Sets a line pattern to be used for drawing all kinds of lines. The command's arguments are numbers – sizes in millimeters. If there are arguments, there must be at least two of them. The second, third, etc. numbers set the lengths to draw, skip, draw, skip, etc. along a line. (In actual drawing, the list of numbers is repeated until the line end is reached.) The first argument sets the offset from the beginning of the so established drawing pattern where the pattern starts actually applying when drawing a line. Arguments cannot be negative but may be zero. If no arguments are given, a solid line type is set – same as the one used by default.
cap
Sets how the ends of the open lines are drawn. The argument is a single character as follows: ) (right parenthesis) sets a round ending – a semicircle that extends the actual line; ] (right bracket) sets a similarly extending (half-)square ending. Any other argument or no argument means ‘butt ends’, i.e. no extension, which is also what is done by default.
join
Sets how the joins of line segments in polylines and polygons are drawn. The argument is a single character as follows: ) (right parenthesis) sets a round join – a circular wedge extending the two lines; > (right angle bracket or the ‘greater than’ sign) sets a mitre (angular) join. Any other argument or no argument means a beveled join, which is also what is done by default.


Geometry vs denotation

Normally a drawing, such as mathematical, construction, or engineering plot, and most kinds of flowcharts, must admit scaling up or down while maintaining the same line widths. The drawing may have to be scaled to fit a certain overall space, but the line widths will still have to comply with technical requirements, independent of scaling. The same holds of line types.

Sp meets such needs by keeping the notions of line width and line type separate from that of geometric magnitude. Line widths, as well as the lengths of the parts of line type patterns, are always set in millimeters rather than current units, and so are not affected by scaling, be it through unit commands or through a command-line argument. Arrow head sizes fit the respective line widths, and therefore are also unaffected by scaling.

Point marks are always the same, predefined in sp kind and size, not dependent on scaling or line width. Only the colour of point marks can be varied.

Point marks are special in yet another way. Unlike all othet objects, which get drawn, and will overlay each other, in the order of their appearance in the sp input file, points are drawn last, and therefore on top of everything that may happen to be at the same place, as this is what a user would normally expect to see. This behaviour is enforced by sp regardless of where points appear in the input. On the other hand, of course, the location and the colour of a point mark are always determined from the context in which the point is encountered in the input.


Examples

Here are several examples of SVG pictures produced by sp, along with the respective input files.

 



The picture is a series of horizontal line segments (of greatly varying widths) along the same line.

 Click here for the SP code for this picture 

 



Lines, points, varying colours and line widths.

 Click here for the SP code for this picture 

 



Rotating the coordinate system uniformly around the centre of the figure makes it possible to draw the ‘same’ circle many times.

 Click here for the SP code for this picture 

 



Line types, widths, caps, fills, arrows, rotations. Clock tick marks are just two instances of the same circle with properly chosen line types, caps, and widths.

 Click here for the SP code for this picture 

 



The program

Here are the executables for GNU/Linux and MS Windows, and here is the source text.

The program is written in standard C++ language. With this note I grant everyone the right to use the program, in source or executable, for what they see fit. There is only one restriction: if you change the program in any way, please notify me and distribute your version under a name different from sp.


Boyko Bantchev