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.
• 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.
• Contextual commands: visualization attributes
) (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.) (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 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.