Goals

Visual communication is part of science and mathematics. As a result, many excellent tools have evolved for producing charts. Many package can aid the production of excellent data charts, often with fine control over their appearance. Any decent computer-aided-design package can aid the production of precise technical drawings. For the most part, we will not be concerned with charts that are easily produced with such packages.

When choosing a drawing tool, one would like to pick the right tool for the task. The tool varies by task and background. Here are some core considerations:

• Can this tool produce the type of drawing you need?
• How quickly can you learn the basic use of this tool?
• How quickly can you produce the type of drawing you need with this tool?
• If you need to produce several related drawings, can you leverage work on one of them into progress on another?

When faced with the need to produce a technical drawing, the first stop will often be a good point-and-click vector drawing program. There are many good ones, both free and commercial. However the need for geometric precision or complex geometric shapes sometimes renders difficult or tedious the use of point-and-click drawing. At that point, the use of a drawing language (or metalanguage) comes under consideration.

There are many good drawing languages, both free and commercial. The ideal language will be easy to learn yet powerful, allowing flexibility in the illustration of precise geometric relationships. As we will see, the PostScript page description language meets these criteria.

The right tool can also depend on personality: some people find use of a drawing language more painful than searching through a myriad of drawing-tool menus, while others find menu search frustrating and truly enjoy programming. PostScript drawing is most likely to appeal to those who take some pleasure in the process of programming. It will also appeal to those who have perfectionist leanings when it comes to scientific drawing.

This booklet constitutes a self-contained introduction to PostScript drawing that is an adequate starting point for those who wish to add PostScript drawings to documents such as lecture notes, theses, dissertations, academic books, and journal articles. It also briefly discusses some more advanced topics and suggests resources for further study. Finally, for those already familiar with popular metalanguages such as TikZ or PyX, it offers some code comparisons. However, it does not offer instruction in the use of these alternatives. Only the PostScript language is discussed in any detail.

What is PostScript?

PostScript combines a general-purpose programming language with page-description functionality specialized for the static visual display of information. As a page description language, PostScript provide a rich collection of useful graphics commands.

A typical PostScript program provides a description of visual information: shapes and colors on a page. (Some of the shapes may be text.) To turn this description into a visual display, we need a PostScript interpreter. The interpreter converts our description (our code) into a representation on a computer screen or a printed page. Some printers have built-in PostScript interpreters. Other interpreters are available as software applications, which can be used for screen display or printing. Such interpreters are available for most platforms, including Windows, Mac, and Linux.

The examples in this booklet assume that you have access to a computer with an installed PostScript interpreter. If you need an interpreter, you have many options available, including the free and open source Ghostscript.

Some Alternatives

In the 1990s, PostScript was an alternative to the LaTeX picture environment. The picture environment was very simple to use, but sometimes a more powerful drawing language was needed. [3] PostScript provided this power, and learning to draw in PostScript requires surprisingly low effort. One can very quickly learn to produce complex but precise drawings in the powerful PostScript page description language---nearly as quickly as one can learn the LaTeX picture environment and more quickly than one can learn precise drawing in many point-and-click environments.

However, LaTeX has also evolved and now supports the Portable Graphic Format (PGF), which has very strong drawing capabilities. These capabilities are further strengthened by a widely use library of macros for PGF, which is called TikZ. Together, TikZ can make complex drawing, including the placement of text, simple and convenient. This comes at some cost in complexity: the PDF/TikZ manual has more than 1000 pages. Nevertheless, simple basic constructs are often adequate even for complex drawings. Furthermore, PGF can produce either PostScript or PDF output, so it can be considered to be a PostScript metalanguage. This booklet provides some TikZ examples for comparison.

Essentials

While vector drawing applications can be expensive, tools for PostScript programming are available for free. However the true cost of producing any drawing will have little to do with monetary cost, since drawing can be very time consuming no matter what environment is chosen. For most economists, drawing by means of PostScript programming will be worthwhile only in those circumstances where simple programs can produce results that would require time-consuming point-and-click experimentation in a vector graphics application. After dealing with a few essentials and introducing some basic considerations, this booklet will provide a few examples of such programs.

To create and view PostScript drawings on a computer, you need only a text editor and an “interpreter” supporting screen display. [4]

The inexpensive options for interpreters that permit onscreen viewing are limited but high quality. The standard is the free Ghostscript interpreter, which allows previewing and printing PostScript files on many platforms. [5]

As for text editors, this booklet focuses on very simple examples, for which you can use the default editor on your computer (or even a word processor, if you remember to save what you type as ASCII text). [6]

Finally, for anyone intending to go beyond the most casual use of PostScript, I strongly recommend downloading [adobe-1999-plrm3], which is a precise yet usually readable reference manual.

Resources

There are many tutorials and books introducing PostScript. Here we list just a few, with short annotations. Many are available online. (See the reference section for the URIs I am aware of.) Anyone who finds the present booklet to be useful will undoubted find Bill Casselman’s wonderful book to be useful as well.

Canvas Coordinates

Locations on the page are designated in a familiar fashion: we use standard Cartesian coordinates. When we start drawing, the location \((0,0)\) is at the lower left corner of the page. Increases in the first coordinate produce more rightward locations; increases in the second coordinate produce more upward locations. The default unit of measurement in PostScript is the printer DTP point, which is 1/72 inches. So an 8.5 inch by 11 inch page measures 612 points by 792 points. We illustrate this in PostScript Page (Letter Size) by labeling a few locations on an image of a letter-size page. In geometry, dimensionless locations are usually called points, and these must not be confused with the DTP point unit of measurement.

PostScript Page (Letter Size)

The Process of Drawing

We create a PostScript drawing with PostScript operators. A PostScript operator may require one or more operands. For example, PostScript drawings often begin with the moveto operator. The moveto operator needs two operands, which provide the coordinates of a position on the page. So x0 y0 moveto moves the current point of our drawing to the position \((x_0,y_0)\). Note that the operands precede the operator. (PostScript is a stack-based languaged; we will explain this later.)

Consider the construction of a line segment between any two locations on the page. We can characterize a line segment by the coordinates of the two endpoints. To construct the corresponding PostScript path, we can use the moveto operator to move to one endpoint and then the lineto operator to construct a line segment to the other endpoint. (A PostScript operator will often have a name that resembles an ordinary language description of its function.) Like the moveto operator, the lineto operator needs two operands: the coordinates of a position on the page. It constructs a line segment from the current point to the coordinates specified by its operands, and the coordinates become the new current point of our drawing. We are now ready to under the following lines of PostScript.

x0 y0 moveto
x1 y1 lineto

The first line of code moves the current point of our drawing to the position \((x_0,y_0)\). The second line of code constructs a line segment from there to the position \((x_1,y_1)\), which becomes the new current point for our drawing. (Of course to use these lines of code, we need numerical values for x0, y0, x1, and y1.)

With just this information, you could readily construct any figure composed of straight line segments, as long as you know the coordinates of the endpoints of each line segment. The ability to draw straight lines encompasses a surprising number of drawing needs. Even plots of non-linear functions are frequently drawn as a sequence of short line segments.

Our discussion so far has focused on absolute coordinates. We can also work with relative coordinates. We often find it useful to construct paths using relative movements, and this is the basis of a second approach to line segment construction. For example, a line segment can be characterized by an endpoint and a displacement from that endpoint. To construct the corresponding PostScript path, we can again use the moveto operator to move to one endpoint, but then we can use the rlineto operator to construct a line segment to the other endpoint. The rlineto operator needs two operands: the horizontal and vertical displacements relative to the current point on the page. These determine the coordinates of the other end of the line segment. We are now ready to under the following lines of PostScript.

x0 y0 moveto
dx dy rlineto

The first line of code moves the current point of our drawing to the position \((x_0,y_0)\). The second line of code constructs a line segment from the current point to the position \((x_0+dx,y_0+dy)\), which then becomes the new current point for our drawing.

So far we have been focusing on path construction. Recall that there are two basic steps in creating a PostScript drawing: first construct a path, then paint it. We will not be able to actually view a constructed line segment until we add ink, as it were. We can use the stroke operator to do this.

72 72 moveto
288 288 line
stroke

Displaying Your Drawings

When working with a very small amount of code, it is quite feasible to simply enter PostScript at the Ghostscript command line. However, we generally want to store our code in an ASCII text file, which we can repeatedly modify and run. Here is what the contents of such a file could look like. Copy the following lines into a new text file, say project01.ps, and save the file to disk. (In the next section, we offer a detailed discussion of this code.)

%!                   %special comment (file is PostScript)
72 72 moveto         %set starting point for path
234 648 rlineto      %construct first line segment
234 -648 rlineto     %construct second line segment
closepath            %construct final line segment
4 setlinewidth       %set the line width to 4 points
stroke               %paint the constructed triangle
showpage             %render the drawing

You can use a GUI application (such as GhostView) to interactively choose a printer and print your drawing. Or you can send the file straight to a PostScript enabled printer. If you are sending your file to a printer, the showpage operator will produce (eject) a printed page. So we conclude our drawing with the showpage operator. Here we illustrate printing from a Windows computer. If you have a PostScript enabled printer, to print project01.ps, you can give the following command from the command line:

copy project01.ps lpt1:

However, most of the time we “print” our drawing to a monitor screen. In this booklet, we assume you are using the free and open source Ghostscript. At the Ghostscript command prompt, enter (project01.ps)run. [7]

After completing Isoceles Triangle (below), use your PostScript interpreter to view project01.ps. You will see a triangle, as in Isoceles Triangle. (For your convenience, we display the drawing as it would appear on a sheet of letter paper, with the page boundaries added as a light gray outline.)

Project: Isoceles Triangle

The drawings in this booklet are produced by simple PostScript programs, which are ASCII text files containing only a few lines of PostScript code. The % character delimits a single-line comment. Anything following the % character is a comment, which will be ignored when we run our program. Conventionally, each PostScript program begins with a special comment: a single line containing the two characters %!. [8]

Here we will explore the details with an extremely simple drawing that is a classic first project in PostScript: an isoceles triangle. In order to emphasize the precision of PostScript drawings, we will be very specific about certain details. We will assume a letter size page (8.5 inches by 11 inches). We will construct that largest isoceles triangle possible, subject to the contraint that the constructed path is within a one inch margin. [9] For example, we will place the first vertex of the triangle one inch (i.e., 72 points) from the bottom and one inch from the left side of our sheet of paper.

Begin this project by creating a new ASCII text file with any text editor. We might as well call it project01.ps. Next we enter the program code listed above. Recall that we want to construct a triangular path, and then paint it. In this example, we begin our path construction with the instructions 72 72 moveto, which sets the beginning of the path to the point \((72,72)\). Next we construct two line segments: the first side with 234 638 rlineto, and the second with 234 -638 rlineto. We construct the remaining side in a special way: we use the closepath operator, which constructs the line segment from our current point to our starting point (for this path). That completes our path construction.

Next we need to paint the constructed triangle. We will do this with the stroke operator, but first we use the setlinewidth operator set a nice thick line width of 4 points.

At this point we have completed our page description. We are done with our PostScript drawing. If you are using an interpreter that displays on screen each path as it is painted, you will see your triangle on the screen. To indicate that this is the end of our page description, we use the showpage operator. (More on this later.) Congratulations. You have produced your first PostScript drawing!

Isoceles Triangle

Key Lessons

Much of what we need to know in order to draw with PostScript is contained in our first simple program. Note in particular our use of units of measurement, a coordinate system, and postfix syntax.

By default, the basic unit of measurement is one point. [11] There are exactly 72 points per inch. So an 8.5 inch by 11 inch sheet of paper is 612 points by 792 points. The coordinate system is a standard Cartesian coordinate system, with the origin in the lower left corner of the page. The location \((72,504)\), for example, is one inch (72 points) to the right of the origin and 7 inches (504 points) above it.

As for the syntax, you probably noticed that we always state a position before doing something with it (e.g., moving to it, or constructing a line segment to it). More generally, the PostScript interpreter should always encounter an operator after the operands required by that operator. For this reason, we say PostScript uses a postfix notation: an operator follows its operands. First you state the operands; then you state operator that will use these operands. We say that you push the operands onto the operand stack, where they can be found by the operator. [12]

PostScript syntax is discussed in additional detail in Programming in PostScript.

Readers with programming experience will have noticed that we do not compile a PostScript program into an executable file that can run on a computer without an interpreter. We always use a PostScript interpreter to run our programs. We say that PostScript is an interpreted language.

We have already acquired enough tools to construct any drawing whose constituents are line segments, as long as we can specify the endpoints of each line segment. This includes graph axes, arbitrary polygons, linear functions, or even line graphs of time series. This drives home the flexibility of the PostScript page description language: after a few minutes of exposure, one is ready to create very complex drawings with great precision. This simplicity has another advantage: most vector drawing programs rely on proprietary and undocumented formats, whereas your own PostScript drawings will rely on a fully documented open standard and---since your code is simple ASCII text---will always be readable with any text editor. Of course one can usually export PostScript from a drawing application, but that PostScript is often filled with obscurities. Hand coded PostScript drawings will generally be easy to understand, easy to modify, and readily transportable. Finally, even if you once manage to produce a complex drawing in a vector drawing application, you may be unable to recall the sequence of actions that produced the drawing. In contrast, your PostScript program will always document the steps you took to produce a drawing, and you can add explanatory comments to enhance the value of this documentation.

Metalanguages: Isoceles Triangle

import pyx
pyx.unit.set(defaultunit='pt')

#construct the path
isoceles_path = pyx.path.path(
pyx.path.moveto(72, 72),
pyx.path.rlineto(234, 648),
pyx.path.rlineto(234, -648),
pyx.path.closepath()
)

#create a canvas to paint on
cvs = pyx.canvas.canvas()
#paint the path on our canvase
cvs.stroke(isoceles_path, attrs=[pyx.style.linewidth(4)])
#write a PostScript file
cvs.writePSfile('pyx-isocleles.ps')

\begin{tikzpicture}[x=1bp,y=1bp]
\path[draw,line width=4bp] (72,72) -- ++(234,648) -- ++(234,-648) -- cycle;
\end{tikzpicture}

pts = Accumulate[{{72, 72}, {234, 648}, {234, -648}}]
pth = JoinedCurve[Line[pts], CurveClosed -> True];
Graphics[{Thickness[4/612], pth},
  PlotRange -> {{0, 612}, {0, 792}},
  ImageSize -> {612, 792}
]

t1 = Polygon[pts];
t1style = Directive[EdgeForm[Thickness[4/612]], FaceForm[]];
Graphics[{t1style, t1},
  PlotRange -> {{0, 612}, {0, 792}},
  ImageSize -> {612, 792}
]

isoceles01 = "%!PS-Adobe-3.0 EPSF-3.0
%%BoundingBox: 0 0 612 792
72 72 moveto         %set starting point for path
234 648 rlineto      %construct first line segment
234 -648 rlineto     %construct second line segment
closepath            %construct final line segment
4 setlinewidth       %set the line width to 4 points
stroke               %paint the constructed triangle
showpage
%%EOF
";
ImportString[isoceles01, "EPS"]

<canvas id='isoceles01' width='612' height='792'> </canvas>
<script type='text/javascript'>
var canvas = document.getElementById('isoceles01');
var ctx = canvas.getContext("2d");
ctx.beginPath();
ctx.moveTo(72,72);
ctx.lineTo(306,720);
ctx.lineTo(540,72);
ctx.closePath();
ctx.lineWidth = 4;
ctx.stroke();
</script>

Postfix Notation and the Stack

PostScript is a stack-based language that uses postfix notation. The use of postfix notation just means that operators come after operands. For example, the moveto operator requires two operands, and the operator comes after these operands. As example is 72 72 moveto, where the two number that specify the point to move to come before the moveto operator.

Closely related to the use of postfix notation is another language feature: PostScript is stack-based. If you have ever used a reverse polish notation calculator, programming in PostScript will feel familiar. If not, familiarity with the stack is easily acquired. The operand stack is just a last-in-first-out (LIFO) structure---like a stack of dishes. In a PostScript program, we “push” objects onto the operand stack before invoking an operator that requires one or more operands. Since we refer the operand stack so often, we will nickname it the ostack.

When the interpreter encounters 72 72 moveto, it pushes 72 onto the ostack, then pushes another 72 onto the ostack, and then it executes the moveto operator. The moveto operator consumes the top two objects on the ostack (i.e., our two integers, which in this case happen to be equal).

So to get any operands it needs, a PostScript operator consumes objects from the top of the ostack. It removes from the top of the stack however many objects it consumes; we say the operator “pops” the objects off the top of the ostack.

Some PostScript operators also produce results that are pushed onto the top of the ostack after they are executed. These are not just intermediate values of a computation; they are final values that remain on the ostack after the operator has been executed. When an operator pushes final values on the ostack, we will say that it “returns” those values. As an example, suppose we wish to divide 108 by 9. We would use the following PostScript code: 108 9 div. When the PostScript interpreter encounters this code, it will first push the integers 108 and 9 onto the ostack. Then it will execute the div operator, which pops two values off the stack, divides them, and then pushes the (floating point) result of the division back onto the ostack.

Exploring the Stack Interactively

Our exploration of the stack will presume the reader is using Ghostscript, but any interactive interpreter will suffice. The Ghostscript interpreter can of course be used to run an entire PostScript program at once. However, it can also be used interactively. Interactive use is very primitive, but it is a convenient way for novices to gain some familiarity with the basics of the PostScript language.

When you launch Ghostscript, the terminal window appears. You can enter PostScript commands at the command prompt in the terminal window. For example, enter showpage. This will open the graphics window, which is a display area for our PostScript drawing. After entering showpage, you can enter an empty line at the command prompt to clear any drawing. (You can use the quit operator to quit the interpreter altogether.) Of course we often execute code that does not cause anything to be drawn.

To illustrate the use of the stack, we will use Ghostscript divide 108 by 9. Here we display the items on the ostack by repeatedly calling pstack. The pstack operator nondestructively prints a text representation of the current operand stack.

GS>108       %push 108 on the ostack
GS<1>pstack  %print what's on the ostack
108
GS<1>9       %push 9 on the ostack
GS<2>pstack  %print what's on the ostack
9
108
GS<2>div     %execute the `div` operator
GS<1>pstack  %print what's on the ostack
12.0
GS<1>pop     %pop one item off the ostack
GS>

As you can see, PostScript code affects the number of items on the operand stack. The Ghostscript terminal displays number of items currently on the ostack in angle brackets. In response to the pstack operator, PostScript produces you a text representation of these items. In response to the pop operator, it removes an item from the operand stack and discards it.

To illustrate the use of the stack, let us do something more oriented toward drawing. Here we just construct and paint a single line segment.

GS>72 72
GS<2>moveto
GS>288 288
GS<2>lineto
GS>stroke
GS>

We begin by placing two numbers on the operand stack. Ghostscript shows us that there are now two objects on the stack. We then use the moveto operator. Ghostscript then shows us that there are no objects on the stack. The moveto operator consumes the two numbers and leaves the stack empty. The current point for our drawing is now \((72,72)\). As we have not actually done any painting, the graphics window is still empty.

We continue by placing two new numbers on the operand stack. Ghostscript again tells us that there are two objects on the stack. We then use the lineto operator. Ghostscript then shows us that there are no objects on the stack. The lineto operator consumes the two numbers and leaves the stack empty. It also constructs a line segment from our old current point to the new point \((288,288)\). The current point for our drawing is now \((288,288)\). As we still have not actually done any painting, the graphics window remains empty. This changes when we use the stroke operator, which causes the line segment we have constructed to be drawn in the graphics window.

While working at the interpreter, one may make mistakes. To remove one value from the operand stack, use the pop operator. To clear the operand stack, use the clear operator. To start a new page for drawing, enter the showpage operator and then again press Enter.

5 4 3 2 1 0
6 2 roll

5 4 3 2 1 0
6 -2 roll

Some Useful Operators

The PostScript language includes many specialized operators, which are detailed in [adobe-1999-plrm3]. Here we cover a few that are particularly useful for occasional PostScript programming. (All are described in the Glossary of Useful Terms.) Note that PostScript is a case sensitive language, so you must use all lower case when using these operators.

Arithmetic and mathematical operators have self-evident names, take the expected number of operands, and have the expected number of returns. The arithmetic operators add, sub, mul, div, mod require two operands and have one return. The arithmetic operators abs, neg, ceiling, floor, round, and truncate require one operand and have one return. The mathematical operators sqrt, exp, ln, log, sin, cos, and atan require one operand and have one return. (Note that log is the base 10 logarithm.) The operator rand, which requires no operands, generates a (pseudo) random integer in the range 0 to 2^31 - 1. [15]

There are two possible surprises in the use of the arithmetic operators. A possible technical surprise is that floating point results are single precision (at least six significant digits). A possible syntactical surprise is that operands are used in the order pushed on the stack, rather than top down. For example, the arithmetic expression \(2 - 1\) becomes the PostScript expression 2 1 sub, and the arithmetic expression \(2 / 1\) becomes the PostScript expression 2 1 div.

Relational and boolean operators have fairly standard names, take the expected number of operands, and have the expected number of returns. The operators have a single return that is boolean (specifically, true or false). The equality and inequality relational operators eq, ne, ge, gt, le, and lt require two operands, which should be numbers (or strings). [26] The logical comparison operators and, or, and xor require two operands, which should be boolean. [16] The boolean not operator requires a single operand, which should be boolean.

When describing an operator, it is useful to indictate what is removed from and added to the ostack. For this purpose, Adobe uses a convenient convention for the presentation of operators: list the arguments, then the operator, then the results. In the case of the div operator, we have:

num1 num2 div real1

where real1=num1/num2. (PostScript conventionally refers to floating point numbers as “real”.) This means that the div operator consumes two numbers from the ostack and then pushes on it one number (the quotient). Of course you must make sure you have pushed the two operands onto the ostack before invoking the div operator.

When an operator returns no result, it is presented as returning ---. For example, recall our moveto operator. We can present it as

num1 num2 moveto ---

because it consumes two operands and pushes nothing on the stack. Generally operators that return no result have some side-effect. For example they may change the graphics state. The moveto operator of course changes the current point, the position of which is part of the graphics state.

Variables and Named Procedures

Stack based languages reduce (and often eliminate) our need to associate names and objects. Nevertheless, when desired, we can define “variables” by using the def operator to associate a name with a value. Similarly, we can define “procedures” by using the def operator to associate a name with a an executable value.

/mean2g {mul sqrt} def
2 8 mean2g
4 9 mean2g

/fromPolar2D { % r theta 
  2 copy       % r theta r theta
  cos mul      % r theta x
  3 1 roll     % x r theta
  sin mul      % x y
}bind def

Project: Simple Arrow

Arrows occur in many drawings. High level drawing languages and metalanguages often provide arrows. Low level drawing languages, including PostScript, do not include arrows. One reason is that there are multifarious understandings of what constitutes an arrow. In this next project, we will develop a minimalist arrow. Our arrow will be constructed from straight line segments, and the arrowhead will scale to the line width.

Mitre

Prerequisite to constructing such an arrow is understanding what happens when we join two line segments. Looking at Isoceles Triangle, this is the question of how the vertices are painted. The answer to this question is determined by three graphics state parameters: currentlinecap_, currentlinejoin_, and currentmiterlimit_. We control these with the setlinecap_, setlinejoin_, and setmiterlimit_ operators.

The line cap controls how the beginning and end of a path is painted. A line cap of 0 (“butt”) is simply squared off and does not extend beyond the path endpoints. This is the default. The other two values add caps to the ends. A line cap of 1 (“round”) adds a half-circle at each end. A line cap of 2 (“square”) add a half-square at each end.

Now consider what happens if we draw an angle with two line segments, using a butt cap. If the line segments were simply treated indpendently, stroking the line segments would result in a notch. This is so seldom desirable, that it is not even an available behavior. (Although, the segments could be separate drawn as multiple subpaths.) Instead, the stroked lines are joined as determined by the currentlinejoin_. A line join of 2 simply fills in the notch with a triangle. This is a “bevel” join. A line join of 1 fills in the notch with a circle (centered on the join point, with radius equal to the line width). This is a “round” join. A line join of 0 fills in the notch by extending the outside edges of the line segements until they meet, filling in the resulting polygon. This is a “miter” join, and it is the default behavior. With a miter join, the stroked line segments will meet at a sharp angle. See Miter Join for an illustration.

Miter Join

In Miter Join, the white lines represent the constructed line segments, and the gray area represents the results of stroking the path. In addition, we have overlaid a dashed right triangle. The height of this triangle is the line width of the stroked path. The hypotenuse of this triangle is called the miter length. The miter length is evidently proportional to the line width. If the segments meet with an angle of \(\theta\), then the relative miter length is \(1 / \sin(\theta / 2)\). [17]

[17]

When two line segments meet, there is some ambiguity when we refer to the angle at which they meet. Restricting ourselves to angles that are fractions of a complete turn, we still must choose between the reflex angle and its explement. We refer to the reflex angle as the exterior angle, and we refer to its explement as the interior angle. Intuitively, this angle is interior to the triangle formed as the convex hull (or “fill”) of these two segments. In this context, we also use the term ‘angle’ as a synonymous with ‘interior angle’.

The relative mitre length grows without bound as the two line segments become increasingly parallel. For this reason, PostScript honors a limit on the relative miter length. Whenever the relative miter length exceeds the miter limit, PostScript automatically replaces a miter join with a bevel join. The default limit is 10, and the value can be set with the setmiterlimit_ operator.

Exercise

To construct Isoceles Triangle, we constructed a single path consisting of three joined line segments. How will our figure change if we construct the three segements as three separate paths, stroking each? (Assume the default butt line cap.)

Exercise

How will setting the miter limit to 1 affect our line joins?

1 dict
begin
/x 250 def
end

/simpleArrowTo {12 dict begin
  /y exch def
  /x exch def
  currentpoint
  y sub neg /dy exch def                    %dy along arrow
  x sub neg /dx exch def                    %dx along arrow
  /alen dx dx mul dy dy mul add sqrt def    %total length of arrow
  /heading dy dx atan def                   %heading of arrow
  /theta 60 def                             %angle of arrowhead
  /turn 180 theta 2 div sub def             %turn angle of barb
  /width currentlinewidth def               %line width of arrow
  /blen 8 width mul def                     %barb length
  /mlen width theta 2 div sin div def       %miter length
  /slen alen mlen 2 div sub def             %shaft length
  slen heading fromPolar2D rlineto          %construct the shaft
  currentpoint                              %store pt A (end of shaft)
  blen heading turn add fromPolar2D rmoveto %move to end of one barb
  lineto                                    %construct one barb; consume pt A
  blen heading turn sub fromPolar2D rlineto %construct other barb
  x y moveto                                %move to tip of arrow
end}def

Arrays and Loops

We create an array by bracketing a sequence of objects. You can do any operations you wish as you create the array. For example,

[]                  %empty array
[ 1 pop ]           %empty array
[ 1 2 3 4 5 ]       %array of 5 integers
[ 1 2 add 3 4 mul ] %array of 2 integers

The left bracket just sets a mark, and the right bracket creates an array down to that mark, leaves that array on the ostack. More accurately, the item left on the stack is a reference to the array (which resides in `virtual memory`_).

Naturally you can retrieve objects from an array, using the get operator and an array index. Arrays use zero-based indexing: the index of the first object in the array is 0. For example, the following code fragment leaves 1 on the ostack.

[ 1 2 3] 0 get

Getting the first element of an array is common enough that we will create a named procedure for it. (This definition uses the bind operator, which we discussed in Bind.)

/head {0 get} bind def

We can also use the getinterval_ operator to extract any subinterval of the array. The getinterval_ operator consumes an array, an initial index, and a final index. It pushes on the ostack a new array, which contains the elements of the specified array interval. (The interval is specified as an initial index and a number of elements.)

Getting all but first element of an array is common enough that we will create a named procedure for it. In order to do so, we make use of the length operator, which returns the length of the array.

/tail {              % a0
  dup length 1 sub   % a0 len (len is a1's length)
  1 exch             % a0 1 len
  getinterval        % a1 (the tail of a0)
} bind def

Since the length operator consumes its operand, we begin by duplicating the array on the ostack. (This is very cheap; it just duplicates a reference to the array.) We then find the length and subtract 1, leaving the number of elements in the subarray. We then push 1 on the stack and exchange that with the number of elements, giving us the interval specification we need. Finally, we get that interval.

Arrays are mutable. We use the put operator to replace a single array element at a given index. Note that the put operator consumes three arguments from the ostack, but it does not push any. Consider the following lines of code.

1 1 5 iRange      %push array on ostack
dup               %push copy on ostack
0 99 put          %replace first element with 99 (consumes copy)
0 get             %get the first element of our "original" array

First we push an array on the stack. (The object on the stack is actually a reference to our array.) Then push a copy of that array on the stack. (This is actually a copy of the reference.) Next we change the copy. Remember, the put operator consumes three operands, so all that is left on the stack is our “original” array. Finally, we use the get operator to retrieve the first item of this array: it is 99. Arrays are mutable; the put operator changed an element in our original array.

[ 100 {0} repeat ]

[ 0 1 99 {}for ]  %array of positive integers

/iRange {[ 4 1 roll {}for ]} def

Basic Array Operations

PostScript provides the forall operator for iteration over arrays and dictionaries. For now, we focus on iteration over arrays. Used on arrays, forall is essentially the foreach loop common in other languages. Given an array and a procedure, starting with the first item (whose index is 0), an element is pushed on the ostack and the provided procedure applied to it. For example, we can define a sum procedure for numercal arrays as follows.

/sum {0 exch {add} forall} bind def

This works by pushing 0 on the ostack and then swapping the top two items, so that the array is back on top. Next we push on the top of the ostack the anonymous procedure {add}. The forall operator consumes the top two operand (i.e., the array and the procedure) and then iterates over the array items, pushing each item on the ostack and then executing the procedure.

We can define a map procedure for numerical arrays as follows.

% [num] (num -> num) *map* [num]
/map {
  [           %push mark on stack
  3 1 roll    %move mark before array
  forall      %execute function for each array item
  ]           %create array from new items on stack
} bind def

Developing a zip procedure gives us a change to explore our understanding of arrays.

% [num] (num -> num) *map* [num]
/map {
  [           %push mark on stack
  3 1 roll    %move mark before array
  forall      %execute function for each array item
  ]           %create array from new items on stack
} bind def

With map and zip in hand, we can readily implement basic elementwise operations on arrays.

% [num] (num -> num) *map* [num]
/map {
  [           %push mark on stack
  3 1 roll    %move mark before array
  forall      %execute function for each array item
  ]           %create array from new items on stack
} bind def

Arrays as Line Descriptions

In this booklet, we will use arrays of numbers to describe points. For example, we will use [0 0] to describe the origin. We can use an array of points to descibe a line. For example, [[0 0] [1 1]] describes a line from the origin to the point [1 1]. However we want to something different with the first point (move to it) than with the others (add a line sement to the path). In recogntion of this, we will create an deconstruction operator, which consumes an array and returns its tail and its head.

/uncons {     %arr
  dup         %arr arr
  tail exch   %tail arr
  head        %tail head
} bind def

Now if we have an array of points, we can apply our uncons procedure to get the first point on the top of the stack and an array of the others right below it. But PostScript drawing operators work with numbers on the ostack, not with arrays. In order to construct a line with our familiar PostScript operators, we are going to have to get our hands on the individual coordinates. In order to push the items of an array onto the ostack, we use the aload operator. The aload operator pushes all the array items individually on the ostack. The aload operator consumes an array and pushes all its elements onto the stack, but then it also pushes the array itself back onto the stack. We just want the elements, so we use the pop operator to discard the array on the top of the stack. Now we are ready to construct a line from a list of points.

/polyLine {
  uncons               %tail head
  aload pop moveto     %tail
    {aload pop lineto} %tail proc
  forall               % --
} bind def

Triangle with Medians

Project: Circle Points

This project is oriented more toward programming than toward drawing. We will produce a list of evenly spaced points drawn from the unit circle. There is a single integer argument, n, the number of points. The points are structured so that if used to draw a polygon, the polygon will have a horizontal base.

% n circlePoints [pt]
/circlePoints {3 dict begin /n exch def
  /angle 360 n div def
  /angle2 angle 2 div def
  [
  0 1 n 1 sub {[ exch angle mul angle2 add 270 add dup cos exch sin ]}for
  ]
end} def

The circlePoints procedure is a fun demonstration of some basic computations in PostScript. However, it is not yet very useful for drawing actual polygons. We could handle this in a few different ways, and we will. For the moment, let us consider simple procedures to scale up these points and translate them.

% [pt] s *scalePoints* [pt]
/scalePoints {1 dict begin /s exch def
  {s exch s:mul} map
}def

% [pt] pt *translatePoints* [pt]
/translatePoints {1 dict begin /t exch def
  {t a:add} map
end}def

Now we are ready to construct regular polygons of any size wherever we want.

% x y r n centeredRegularPolygon ---
/centeredRegularPolygon {
  circlePoints exch scalePoints
  [ 4 -2 roll ] translatePoints
  polyLine closepath
}def

E.g., to produce a dodecagon centered on the page, we could do the following.

306 396 216 12 centeredRegularPolygon

User Space

Our first PostScript examples illustrate the very natural coordinate system PostScript provides for describing positions on the page. We begin with a standard Cartesian coordinate system, with the origin at the bottom left corner of the page. This is the coordinate system we initially encounter---the default user space. The default user space is device-indpendent in the following sense: we do not need to know anything about how the output device characterizes its drawing space. We just attend to the user space; we do not need to understand the device space. This is very convenient: we can write one PostScript program and produce the output on many different devices.

Of course we cannot always hope for complete ignorance of the device. For example, a printer may handle only certain paper sizes, and it may not be able to print at the very edge of the page. And naturally, a low-resolution device may not be able to render all the high-resolution details of a drawing. Still, PostScript allows us to be as agnostic as possible about the device on which a drawing will be rendered.

Up to now we have mostly been drawing in the default user space. However, we are free to change the current user space with transformation operators. These change the coordinate system in which the programmer is drawing. We can translate the origin or rotate the orientation of our coordinate system. We can also scale the unit size. Such transformations affect subsequent path construction and painting, but they do not affect any path construction or painting that we have completed. For example, transformations do not move the location on the page of the current point or the current path. In this section we will see how this can be useful.

This section discusses three operators for simple coordinate system transformations. (For additional detail see [adobe-1985-pltc] [ch.6].) These are translate, scale, and rotate. These operators effectively allow us to move our axes for drawing around on the page: we can shift them horizontally or vertically, we can “stretch” or shrink them (so that the axes are not moved but their units are changed), or we can rotate them around the current origin. We can invoke these operators even in the midst path construction, and they will only affect the construction subsequent to the invocation. This section discusses the effects of these transformations and offers a simple but useful illustration.

Translate

The translate operator changes the location of the user space origin. Consider the location on the page associated with the coordinates \((dx,dy)\) in the current user space. The instructions dx dy translate will move the origin \((0,0)\) to that location. Each location on the page has its coordinates transformed in this fashion. The new coordinate system constitutes the new user space. The origin can be translated along both axes (i.e., both horizontally and vertically relative to the current user space). The two operands specify the x-axis translation the y-axis translation. For example, a location on the page that had coordinates \((x0,y0)\) will, subsequent to the translation, have coordinates (x0+dx, y0+dy).

Rotate

We can also rotate the coordinate axes of the user space. Use the command theta rotate to rotate the axes theta degrees counterclockwise. Every location on the page has its coordinates changed appropriately to produce the new user space. This does not move the origin or change the scale.

Scale

The scale operator allows us to change the units on the coordinate axes without affecting the origin or the orientation of the axes. The command sx sy scale imposes a “horizontal” scale factor of sx and a “vertical” scale factor of sy. For example, the location on the page that had coordinates \((x0,y0)\) will, subsequent to the scale operation, have coordinates \((x0/sx, y0/sy)\).

Clearly order matters when using scale and translate. If scale comes first, the scaled units will be used in translating the origin of the user coordinate system.

Project: Equilateral Triangle

In Isoceles Triangle, we drew an isoceles triangle. In the process, we gained the tools to draw any figure consisting of straight line segments as long as we can specify the endpoints (or relative endpoints) of each segment. Sometimes such specification can require avoidable effort, however. For example, instead of an isoceles triangle we may wish to draw an equilateral triangle. The equilateral triangle is a common representation of the two dimensional simplex, so it shows up in a diversity of contexts. [18]

Once we draw one side of an equilateral triangle, we must face the question of how to draw the second side. The brute force way is to trigonometrically compute the location of the second vertex and then draw a line segment to that point. [19] A simpler solution is to exploit our ability to characterize any triangle by a side, an angle, and a second side. In PostScript, after drawing the first side, we can translate the origin to the endpoint of the first line segment, rotate clockwise around the new origin by 120 degrees, and then draw the second side exactly like the first one. We will write the code to do this so that it makes use of our three transformation operators.

Equilateral Triangle: Stroked

%!
72 72 scale          %set units to inches
1.25 2.5 translate   %translate origin
0 0 moveto           %moveto origin
6 0 lineto           %construct first 6" line segment
6 0 translate        %translate origin to current point
120 rotate           %rotate axes 120 degrees counterclockwise
6 0 lineto           %construct second line segment
closepath            %construct final line segment
stroke               %paint the constructed triangle
showpage             %view the result

Fist consider the result of stroking the constructed path. You may be surprised by the display in Equilateral Triangle: Stroked. Specifically, why is the line width of the stroked triangle so large? The reason is that the default line width is one unit (along each axis), but we used the scale operator to scale the unit to one inch. (The drawing displays as it would on a sheet of letter paper, the boundary of which appears as a light gray outline.) So the line width used for stroking is a full inch. (We will learn how to deal with this when we discuss the graphics state.)

Graphics State

A bit like the man who discovered that he had been speaking prose all his life, we now acknowledge that we have been manipulating the graphics state all along. The current graphics state holds such things as the current path, the current line width, the current color, the current clipping path, the current font, and the current user space. ([adobe-1999-plrm3] [section 4.2] offers a full discussion.) Since the current color is part of the graphics state, 0.5 setgray changes the graphics state to specify a medium gray for any painting operations. We can choose fill or stroke as our painting operation.

Often it is useful to temporarily save at least part of the graphics state for reuse. Most of the time we do this with the gsave and grestore operators. [22] A common application arises when we wish to both stroke and fill the same path. Both stroke and fill perform an implicit newpath operation and thereby destroy the current path. We could of course explicitly construct the path twice, once for stroking and once for filling. A second approach proves more convenient. Since the current path is part of the graphics state, we can save the graphics state with the gsave operator before stroking the path. After stroking it, we can restore the path with the grestore operator, so that it is available for filling. Concretely, in the above code, replace stroke with gsave stroke grestore 1.0 setgray fill.

[22]	That is, we use the gsave operator to push the entire current graphics state onto a special stack, called the graphics state stack. We use the grestore operator to pop the saved graphics state from the graphics state stack when we need it again later.

Equilateral Triangle

%!
72 72 scale          %set units to inches
1.25 2.5 translate   %translate origin
0 0 moveto           %moveto origin
6 0 lineto           %construct first 6" line segment
6 0 translate        %translate origin to current point
120 rotate           %rotate axes 120 degrees counterclockwise
6 0 lineto           %construct second line segment
closepath            %construct final line segment
gsave                %save the graphics state
stroke               %paint the constructed triangle
grestore             %restore the graphics state
0.6 setgray          %change color to medium gray
fill                 %fill the path
showpage             %view the result

Program Details

from pyx import path, trafo
pyx.unit.set(defaultunit='inch')
triangle = path.path(path.moveto(0,0), path.rlineto(6,0))
#find the triangle apex as a relative location
x,y = pyx.trafo.rotate(120).apply(6,0)
triangle.extend([path.rlineto(x,y),path.closepath()])
#set the color, line width, and transformation of the whole path
strokeStyle = pyx.style.linewidth(1), trafo.translate(1.25,1)
fillStyle = pyx.color.gray(0.5), trafo.translate(1.25,1)
#we need a canvas to draw on
cvs.stroke(triangle, attrs=strokeStyle)
cvs.fill(triangle, attrs=fillStyle)

\begin{tikzpicture}[x=1in,y=1in]
\path[use as bounding box] (0,0) rectangle (8.5,11);
\path[shift={(1.25,2.25)},
      line width=1in,
      draw,
      postaction={fill=gray}
      ]
      (0,0)  -- ++(6,0) -- ([turn]120:6) -- cycle; 
\end{tikzpicture}

ctx.scale(72,72);
ctx.translate(1.25,2.5);
ctx.beginPath();
ctx.moveTo(0,0);
ctx.lineTo(6,0);
ctx.translate(6,0);
ctx.rotate(120*Math.PI/180);
ctx.lineTo(6,0);
ctx.closePath();
ctx.lineWidth = 1;
ctx.stroke();

deg2rad = \[Pi]/180
relpts = AnglePath[{0, 0}, {{6, 0}, {6, 120 deg2rad}}]

pth = Line[72*({5/4, 5/2} + # & /@ relpts)]
stroked = JoinedCurve[pth, CurveClosed -> True]
filled = FilledCurve[pth]
g1 = Graphics[{Black, Thickness[72/612], stroked, GrayLevel[0.6], filled},
  PlotRange -> {{0, 612}, {0, 792}},
  ImageSize -> {612, 792}
]

relpth = Line[relpts]
transform = Scale[Translate[#, {5/4, 5/2}], {72, 72}, {0, 0}] &
stroked = transform@JoinedCurve[relpth, CurveClosed -> True]
filled = transform@FilledCurve[relpth]

transform02 = GeometricTransformation[#,
  ScalingTransform[{72, 72}]@*TranslationTransform[{5/4, 5/2}]] &

Project: Pythagorean Theorem

Our next project will make use of some of our new PostScript programming skills. [isaacs-1975-mathmag] presents a classic “proof without words” of the Pythagorean theorem, illustrated here by Pythagorean Theorem.

Pythagorean Theorem

Since all of the triangles are congruent, the area of the dark square in the first subfigure evidentally equals the combined areas of the dark squares in the second subfigure. In attacking this project, we will use of coordinate system transformations. Additionally, we will need to some control over color and over the graphics state. color, and the graphics state.

/a 60 def        %triangle base
/b 120 def       %triangle height
/ab a b add def  %base + height

% x y s *square* --
% construct square at coordinates (x,y) with side length s
/square {1 dict begin /s exch def
  moveto s 0 rlineto 0 s rlineto s neg 0 rlineto closepath
end} def

% x y base height *rtTriangle* --
% construct upright right triangle at (x,y) with side lengths (base,height)
/uprightTriangle {2 dict begin [/height /base] {exch def}forall
  moveto base 0 rlineto base neg height rlineto closepath 
end} def

%stroke and fill styles for constructed figures
/styleTriangle {gsave 0.9 setgray fill grestore 0 setgray stroke} def
/styleSquare {gsave 0.6 setgray fill grestore 0 setgray stroke} def

Now consider the first subfigure.

0 0 ab square styleSquare
4 {0 0 a b uprightTriangle ab 0 translate 90 rotate} repeat
styleTriangle

Now consider the second subfigure.

0 0 ab square styleSquare
0 0 a b uprightTriangle ab b translate 90 rotate
0 0 a b uprightTriangle 0 b translate 90 rotate
0 0 a b uprightTriangle 0 a neg translate 90 rotate
0 0 a b uprightTriangle
styleTriangle

import pyx
from pyx import trafo, deco, style, color
from pyx.canvas import canvas
from pyx.path import path, moveto, rlineto, rmoveto, closepath
pyx.unit.set(defaultunit='pt')

#BEGIN definitions
a = 72
b = 144
ab = a + b
bigsquare = path(moveto(0,0), rlineto(ab,0), rlineto(0,ab), rlineto(-ab,0), closepath()) 
triangle = path(moveto(0,0), rlineto(a,0), rlineto(0,b), closepath())
triangle_style = [color.gray(0), deco.filled([color.gray(0.9)]) ]
square_style = [color.gray(0), deco.filled([color.gray(0.6)]) ]
#END definitions

#set defaults
cvs = canvas(attrs=[style.linejoin.bevel, pyx.style.linewidth(1)])

#BEGIN subfigure1
cvs.stroke( bigsquare, square_style)
triangles = [ triangle ]
for i in range(3):
  newpath = triangles[-1].transformed(trafo.rotate(90).translated(a,b))
  triangles.append(newpath)
cvs.stroke( sum(triangles,path()).transformed(trafo.translate(b,0))  , triangle_style)
#END subfigure1

#BEGIN subfigure2
figoffset = trafo.translate(234,0)
cvs.stroke( bigsquare.transformed(figoffset), square_style)
t2 = triangle + triangle.transformed(trafo.rotate(180).translated(a,b))
t4 = t2 + t2.transformed(trafo.rotate(90).translated(ab,b))
cvs.stroke( t4.transformed(figoffset), triangle_style)
#END subfigure2


cvs.writeEPSfile('d:/temp/temp.eps')

var a=60, b=120, ab=a+b;
var drawSquare = function(c, x, y, s) {
  c.moveTo(x,y); c.lineTo(x+s,y); c.lineTo(x+s,y+s); c.lineTo(x,y+s);
  c.closePath();
};
var drawTriangle = function(c, x, y, b, h) {
  c.moveTo(x,y); c.lineTo(x+b,y); c.lineTo(x,y+h);
  c.closePath();
};
var styleSquare = function(c) {
  c.fillStyle = 'DarkGray'; c.strokeStyle = 'Black';
};
var styleTriangle = function(c) {
  c.fillStyle = 'LightGray'; c.strokeStyle = 'Black';
};

ctx.save();
//draw the large square
ctx.beginPath();
drawSquare(ctx, 0, 0, ab);
styleSquare(ctx); ctx.fill(); ctx.stroke();
//draw the four triangles
ctx.beginPath();
let i=4; while(i--) {
  drawTriangle(ctx, 0, 0, a, b);
  ctx.translate(ab,0);
  ctx.rotate(Math.PI/2);
}
styleTriangle(ctx); ctx.fill(); ctx.stroke();
ctx.restore();

ctx.beginPath();
drawSquare(ctx, 0, 0, ab);
styleSquare(ctx); ctx.fill(); ctx.stroke();
ctx.beginPath(); //draw four triangles
drawTriangle(ctx, 0, 0, a, b); ctx.translate(ab, b); ctx.rotate(Math.PI/2);
drawTriangle(ctx, 0, 0, a, b); ctx.translate(0, b);  ctx.rotate(Math.PI/2);
drawTriangle(ctx, 0, 0, a, b); ctx.translate(0, -a); ctx.rotate(Math.PI/2);
drawTriangle(ctx, 0, 0, a, b);
styleTriangle(ctx); ctx.fill(); ctx.stroke();

a = 60; b = 120; ab = a + b;
pathSquare = Function[{x, y, s},
  Line@Accumulate[{{x, y}, {s, 0}, {0, s}, {-s, 0}}]];
pathTriangle = Function[{x, y, b, h},
  Line@Accumulate[{{x, y}, {b, 0}, {-b, h}}]];
styleSquare = Sequence[EdgeForm[{Thickness[1/ab], Black}],
   FaceForm[GrayLevel[0.6]]];
styleTriangle = Sequence[EdgeForm[{Thickness[1/ab], Black}],
   FaceForm[GrayLevel[0.9]]];
filledSquare = FilledCurve[pathSquare[0, 0, ab]];
(* base triangle, to rotate and translate *)
t1 = FilledCurve[ pathTriangle[0, 0, a, b]];
(* produce all the rotations *)
{t2, t3, t4} = Rotate[t1, #, {0, 0}] & /@ ({90, 180, 270} deg2rad);

t2a = Translate[t2, {ab, 0}];
t3a = Translate[t3, {ab, ab}];
t4a = Translate[t4, {0, ab}];
g1 = Graphics[{styleSquare, filledSquare, styleTriangle, t1, t2a, t3a, t4a}]

t2b = Translate[t2, {ab, b}];
t3b = Translate[t3, {a, b}];
t4b = Translate[t4, {a, ab}];
g2 = Graphics[{styleSquare, filledSquare, styleTriangle, t1, t2b, t3b, t4b}]

GraphicsRow[{g1, g2}]

Zero Is Not Zero

For drawing, zero has a special meaning. A line width of zero means the thinnest line the rendering device is capable of drawing. A line length of zero means a zero length line, but it still includes other features. Specifically, it includes the line cap, which determines what happens at the end of the line. There are three possible values.

This means we can create circles of a given radius by setting the line width to twice that radius and drawing a zero-length line. One might think that similarly we could create circles of a given radius by setting the line width to the side of the square and drawing a zero-length line. However this is not true, as the orientation of the resulting square would be unknown.

Storing Values for Later Use

Up to now, we have been placing operands on the stack when we are ready to use them. But we can push objects on the stack for later use as well. In our next project we will illustrate this by storing the current point several times during path construction. (We use the currentpoint operator to push the current point on the stack, as two numbers.) After that constructing the path, we will then retrieve these stored values for further use. It is common in PostScript drawing to store values for later use by pushing them on the stack.

Using the stack in this way is fast and cheap. A disadvantage to storing values on the stack for later use is that one must keep track of what is on the stack and where. Therefore we often store a value for later use by assigning it to a variable. The PostScript syntax for this is a bit unusual. We push a literal name on the stack by prepending a slash. Then we push a value on the stack. Then we use the def operator to associate the value with the name. (See Variables and Named Procedures for details.) For example,

/x 10 def    %assign value 10 to variable `x`

Project 3

The next project exercises our understanding of circles in PostScript by producing the Circumscribed Circles. We will approach this as follows: draw the triangle, then the small circles, and finally the large circle. We will specify that the small circles have a radius of 1 inch (72 points), and that the figure is centered on the (letter-sized) page.

Circumscribed Circles

The figure is centered on the page. So our first task is to draw an equilateral triangle centered on a point. We will do this by starting at that point and then moving to the top of the triangle. Recall that the hypotenuse and long leg of a 30,60,90 triangle have length (relative to the short leg) of \(2\) and \(\sqrt{3}\). Since the triangle we want to draw is equilateral with a base of 2, the top is \(2/\sqrt{3}\) inches above the centroid. This also implies that the diameter of the large circle is \(1+2/\sqrt{3}\) inches.

306 396 translate              %move origin to center of page
/tht 3 sqrt 72 mul def         %triangle height
/tht23 tht 2 mul 3 div def     %2/3 of triangle height
0 tht23 moveto                 %start at top of triangle
currentpoint                   %store 1st circle location
-72 tht neg rlineto            %construct 1st side
currentpoint                   %store 2nd circle location
144 0 rlineto                  %construct 2nd side
currentpoint                   %store 3rd circle location
closepath                      %construct 3rd side
stroke                         %stroke the triangle

72 0 360 arc closepath stroke  %stroke 3rd circle
72 0 360 arc closepath stroke  %stroke 2nd circle
72 0 360 arc closepath stroke  %stroke 1st circle
%finally, stroke the big circle
0 0 72 tht23 add 0 360 arc closepath stroke

\begin{tikzpicture}[x=1bp,y=1bp,shift={(306,396)}]
\pgfmathsetmacro{\tht}{72 * sqrt 3}
\pgfmathsetmacro{\thttt}{\tht * 2 / 3}
\path[draw,line width=1]
  (0,\thttt)coordinate(p1)
  -- ++(-72,-\tht)coordinate(p2)
  -- ++(144,0)coordinate(p3)
  -- cycle;
\path[draw,line width=1]
  (p1) circle[radius=72]
  (p2) circle[radius=72]
  (p3) circle[radius=72];
\path[draw,line width=1]
  (0,0) circle [radius=72 + \thttt];
\end{tikzpicture}

tht = 72 * math.sqrt(3)
tht23 = tht * 2 / 3.0
pth = path.path( path.moveto(0,tht23) )
p1 = pth.atend()
pth.append( path.rlineto(-72,-tht) )
p2 = pth.atend()
pth.append(path.rlineto(144,0))
p3 = pth.atend()
pth.append(path.closepath())
cvs = pyx.canvas.canvas()
cvs.stroke(pth, attrs=[pyx.style.linewidth(1)])
for pt in p1, p2, p3:
    circle = path.circle(*pt, 72)
    cvs.stroke(circle, attrs=[pyx.style.linewidth(1)])
circle = path.circle(0, 0, 72 + tht23)
cvs.stroke(circle, attrs=[pyx.style.linewidth(1)])

var tht = Math.sqrt(3) * 72; // triangle height
var tht23 = tht * 2 / 3;     // 2/3 of triangle height
var x1 = 0, y1 = tht23;
var x2 = x1-72, y2 = y1 - tht;
var x3 = x2+144, y3 = y2;
ctx.beginPath();
ctx.translate(306,396);
ctx.beginPath();
ctx.moveTo(x1,y1);
ctx.lineTo(x2,y2);
ctx.lineTo(x3,y3);
ctx.closePath();
ctx.stroke();
// three small circles
ctx.beginPath(); ctx.arc(x3,y3,72,0,360); ctx.stroke();
ctx.beginPath(); ctx.arc(x2,y2,72,0,360); ctx.stroke();
ctx.beginPath(); ctx.arc(x1,y1,72,0,360); ctx.stroke();
// one large circle
ctx.beginPath(); ctx.arc(0,0,72+tht23,0,360); ctx.stroke();

Application

Figure [fig:rectcirc]_ is based on Figure AI.1 of [hildenbrand.kirman-1988-elsevier]. A circle is exactly contained by a square and exactly contains a square. Our PostScript program to produce this figure is remarkably compact (and could be made more so).

%!
/r 250 def                         %define r=250
/r2 r 2 sqrt div def               %define r2=r/1.414
306 396 translate                  %move origin to page center
1 0 0 setrgbcolor                  %set color to red
3 setlinewidth                     %set thick line width
r r r -2 mul dup rectstroke        %stroke large rectangle
45 rotate                          %rotate
1 setlinewidth                     %set thin line width
r2 r2 r2 -2 mul dup rectstroke     %stroke smaller rectangle
0 setgray                          %set color to black
0 0 r 0 360 arc closepath stroke   %stroke large circle
0 0 5 0 360 arc fill               %fill small circle
showpage

We begin with something new: we define two variables, r and r2. The first is the radius of the circle and large square, which we have simply assigned an arbitrary value of 250, and the second is the radius of the small square, which is computed from the value of the first variable. Next we translate the origin of user space to the exact center of a sheet of letter paper. We set the current color to red and stroke a large rectangle with a thick line. Then we stroke a smaller rectangle with a thin line. We change the current color to black, and we stroke a large circle. Finally we place a small, filled circle at the origin.

Program Details

In addition to the new operators for drawing circles and squares, this example reviews the use of variables, some basic mathematical computation, and use of the setlinewidth operator.

Suppose we wish to assign the value 250 to the name r. Recall that the PostScript approach to assigning values to variables is to use the def operator to create name-value pairs. Details can be found in section on variables. So the code /r 250 def pushes the literal name r onto the ostack, then pushes the integer 250 onto the stack, and finally executes the def operator to associate the value 250 with the name r in the current dictionary.

=====  =====  =====  ======  ======
/r2    250      2    √2      250/√2
--     /r2    250    250     /r2
--     --     /r2    /r2     --
=====  =====  =====  ======  ======

Ellipses

We can produce an ellipse simply by rescaling a circle.

%!
/circle {0 0 72 0 360 arc} def     %procedure to draw circle with 1in radius
10 setlinewidth                     %set thick line width

gsave
306 504 translate                  %move origin to page center
2 1 scale
circle
stroke
grestore

gsave
306 288 translate                  %move origin below page center
matrix currentmatrix               %put current transformation matrix on stack
2 1 scale
circle
closepath
setmatrix
stroke
grestore

showpage

Here we make two attempts to draw an ellipse. Our first attempt has two flaws: it does not close the path, and it does not draw with a uniform line width. Because we draw with a thick line width and do not call closepath, you may be able to see a tiny “notch” on the far right of the ellipse. (If not, increase the line width until you can see it.) This is explained in footnote [39], and it is completely fixed just by calling closepath.

The second problem is a bit more subtle. The problem is that when we stroke the ellipse, the line width in the vertical and horizontal directions will reflect our choice of scaling. We might initially hope to fix this by saving the current graphics state, changing the scale and constructing our ellipse, and then restoring the graphics state before painting the ellipse. This solution fails because the path we constructed is part of the graphics state. However PostScript stores all current transformations in the current transformation matrix, so we can save just the transformation we need. First, save the current transformation matrix. Then transforming the scale of user space and construct the ellipse. Finllay, restore the original transformation matrix and stroke the ellipse.

Exercise

Draw a classic atom icon by drawing stroking three overlapping ellipses and placing a filled circle in the center.

Some Nuances

Most PostScript drawing relies on eleven commonly used path construction operators [adobe-1999-plrm3] [p.191]. We have already explored six path construction operators: moveto, rmoveto, lineto, rlineto, closepath, and arc. In principle that leaves five to go---all associated with drawing arcs and curves. However we will most often use arc for this.

Like the arc operator, arcn, arct_, and arcto_ operators each add an arc of a circle to the current path. Such arcs are actually drawn as an extremely close Bézier curve approximation to the true arc. As we will see in Bézier Curves, PostScript also allows direct drawing with Bézier curves by means of the curveto operator. [27] The curveto operator adds a section of a cubic Bézier curve to the current path, and rcurveto does the same operation with relative coordinate displacements.

The curveto operator appends a section of a cubic Bézier curve to the current path. A cubic Bézier curve has four control points, and the current point is taken to be the first of these. Following [adobe-1999-plrm3] , call this current point (x_0,y_0). The other three control points are supplied as operands to the curveto operator. We will call these (x_1,y_1), (x_2,y_2), and (x_3,y_3). The curve begins at the current point (x_0,y_0) and ends at the end point (x_3,y_3), which then becomes the new current point. The shape of the path between (x_0,y_0) and (x_3,y_3) is controlled by the other two points. Leaving (x_0,y_0), it moves toward (x_1,y_1). Ending at (x_3,y_3), it approaches from the direction of (x_2,y_2). Imagine line segments from (x_0,y_0) to (x_1,y_1) and from (x_2,y_2) to (x_3,y_3). The lengths of these segments might be thought of as the “force” with which the curve is pulled toward the control points (x_1,y_1) and (x_2,y_2). The curve is also tangent to these segments, which is a key property. Another property that can be useful is that the curve is enclosed by the convex hull of the four points. The next section contains a useful application.

Some Algebra

This section can be skipped by those not interested in the algebra.

The first plane curve most people encounter is the line segment. Given two points \(P_0\) and \(P_1\), we define the line segment from \(P_0\) to \(P_1\) as follows:

Equivalently, we can represent this curve by a function of two inputs: the sequence of control points, and the value of \(t\).

We call this the linear Bézier curve with control points \((P_0,P_1)\). This cuve comprises all the convex combinations of the two control points. The sent of all the possible convex combinations of a set of points is called the “convex hull” of the set. (We will return to this.)

Next, add a new control point, \(P_2\). Unless the points are colinear, the convex hull of a set of more than two points will not consitute a curve. We are going to characterize a curve that is a subset of the convex hull of the three points as as follows.

1. construct the linear Bézier curve from \(P_0\) to \(P_1\)
2. construct the linear Bézier curve from \(P_1\) to \(P_2\)
3. pair up points from these two line segments based on the value of \(t\) that produce them
4. for each pair, produce a weighted average of the two points, using the common value of \(t\),

The curve desribed in this way is called a quadratic Bézier curve. Let us sum up the weights:

So once again we have a convex combination of points. At any \(t\), we are taking the weighted average of two points, each of which is a weighted average of two of our original points. So we are definitely within the convex hull of the control points. That is, our curve consists of points in the interior of the triangles described by our three control points.

Any linear Bézier curve can be expressed as a quadratic Bézier curve. (This is called degree elevation.) To do so, we use the identity \(x = (1-t)x + t x\). So

where \(P_a = (P_0 + P_1)/2\). So quadratic Bézier curves are a generalization of linear Bézier curves. We can generalize further. Let us add another control point and produce the associated cubic Bézier curve as follows.

1. Construct the quadratic Bézier with control points \((P_0,P_1,P_2)\).
2. Construct the quadratic Bézier with control points \((P_1,P_2,P_3)\).
3. pair up points from these two curves segments based on the value of \(t\) that produce them
4. for each pair, produce a weighted average of the two points, using the common value of \(t\),

The curve desribed in this way is called a cubic Bézier curve. For any \(t\), let us sum up the weights:

So we are again forming each point of our curve as a convex combination of the control points, and that means all the points of the curve lie wihtin the convex hull of the control points.

As we should expect by now, a quadratic Bézier curve can be represented by a cubic. Let us again show this by degree elevation.

where \(P_a = (P_0 + 2P_1)/3\) and \(P_b = (P_2 + 2P_1)/3\). So cubic Bézier curves are a generalization of quadratic Bézier curves.

A pattern has emerged at this point: we can see how to produce a Bézier curve of degree \(N\) one we know how to produce a Bézier curve of degree \(N-1\). This gives us a recursive definition of a Bézier curve of any positive integer degree. The general case looks like this:

where \(C[N,n]\) is the binonmial coefficient (\(N\) take \(n\)), and \(b[N,t]=(C[N,0] (1-t)^{N-0} t^0, \dots, C[N,N] (1-t)^{N-N} t^N)\) is the sequence of coefficients (known as Bernstein polynomials), The final multiplication is elementwise, and the Bernstein polynomials at index \(n\) is

For each value of \(t\), this produces a weighted average of \(N+1\) control points, where the weights are polynomials (of degree \(N\)) in \(t\). The set of all the resuling points is called a Bézier curve of degree \(N\).

Cubic Bézier Curves

We are particularly interested in cubic Bézier curves, because PostScript supports them directly. Cubic Bézier curves a produced with four control points, \((P_0,P_1,P_2,P_3)\). We begin at \(P_0\), leaving directly toward \(P_1\). We end at \(P_3\), arriving directly away from \(P_2\). The entire Bézier curve lies in the convex hull of the three points.

Cubic Bézier Curves

Concatenation

Suppose we implement one affine tranformation and then another one. The result is another affine transformation. We can represent this result as the concatnation of the two affine transformations.

A sequence of transformations is easy to implement, but unless they are all linear, the representation qickly gets a little messy. Now consider the the same sequence of transformations represented in terms of augmented vectors and augmented matrices.

This matrix-multiplication representation of the concatenation of affine tranformations is clean and convenient.

We can do multiplication of PostScript matrices with the concatmatrix_ operators, which takes three operands: two PostScript matrices to multiply, and a third to hold the result. Try entering the following at the Ghostscript command line, and explain the difference in the results.

0 0 [1 0 0 1 288 396] [10 0 0 10 0 0] matrix concatmatrix transform ==
0 0 [10 0 0 10 0 0] [1 0 0 1 288 396] matrix concatmatrix transform ==

0 0 matrix defaultmatrix transform pstack

Let's create a procedure to show us where on the page a point in user space lies. A first thought about how to do this would probably be the following: push the coordinates on the stack, push the currentmatrix on the stack, and transform the point. For example,

0 0 matrix currentmatrix transform

This is the right basic idea, but it returns the coordinate in device space. The are the coordinates used by the actually rendering device, which need not match our page coordinates. So we now encounter another coordinate space: device space. The tranform of page coordinates to device coordinates provided by the defaultmatrix_ procedure. To go from device coordinates to page coordinates we need the inverese of that transform. So we end up with the following:

/pageLocation {matrix currentmatrix transform matrix defaultmatrix itransform} bind def

Similarly, we can determine what user coordinates correspond to a particular point on the page.

/userLocation {matrix defaultmatrix itransform matrix currentmatrix transform} bind def

Folds

Scope

Sometimes we want to use a name without overwriting any pre-existing value. For example, we may want a variable name to be local to a procedure. We can use a dictionary to limit the variable scope in this fashion. A dictionary of names and associated values can be put on the operator stack by bracketing these pairs with << and >>. [28] This dictionary can then be popped from the operand stack and pushed onto the dictionary stack with the begin operator. When we are done with it, we pop it from the dictionary stack with the end operator.

As an example, we can rewrite our factorial procedure in a more traditional way, using a variable and a for loop.

/factorial {    % n
  1 1 1         % n 1 1 1
  4 -1 roll     % 1 1 1 n
  {mul}for      % n!
} bind def

Of course this code looks rather ugly and inefficient after seeing the stack oriented approach above, but it does illustrate how a dictionary can be used by a procedure to limit the scope of a variable. The code has another pedagogical advantage as well: it effectively illustrates the difference between an executable name and a literal name. When the PostScript interpreter encounters the name nfac, it executes it. That is, it pushes on the ostack the value associated with it in the current dictionary. In contrast, when it encounters /nfac, it pushes on the ostack the literal name, to which we then assign a new value using the def operator. This updates the value of nfac, so each iteration through the for loop that value has changed.

Recursion

PostScript supports recursion (including tail call elimination), but it must be handled carefully. As in other languages, it is often simplest to rely on iterative equivalents of recursive algorithms. When a recursive algorithm with variables is for some reason desirable, you will need to carefully attend to variable scope. As a classic example, the following procedure fails because it does not localize the scope of the variable name.

/RDstackFailFactorial {
  /n exch def      %ooops! all calls will use same def!
    n 2 lt 
    {1} 
    {n 1 sub RDstackFailFactorial n mul} %bad 2nd val for n
  ifelse
} def

Instead, we need each recursive call to create its own dictionary on the dictionary stack and to remove it (with end) when done with it. Recall that names are resolved by looking down the dictonary stack until the name is first found.

/RDstackOKFactorial {
  1 dict         % create new local dict for 1 entry
  begin          % push it onto the dictonary stack
  /n exch def    % establish name n in new dict
    n 2 lt 
    {1} 
    {n 1 sub RDstackOKFactorial n mul} 
  ifelse
  end            % pop the new dict
} def

This still has a couple of problems. First of all, the allowabe depth of the dstack is implementation specific. (Early implementations of PostScript only allowed a depth of 20!) Second of all, lookup on the dstack is relatively slow.

So we usually use the ostack instead of the dstack. The maximum depth of the ostack is also limited, but even early interpreter implementations typically allowed 500 operands. Modern implementations may allow tens of thousands of items on the ostack. Consider the following code, which implements a standard recursive algorithm for computing the factorial of a positive integer. [29]

true {1}{0}ifelse

% int *ROstackFactorial* int
%                 %with ostack(... n) where n>1
/ROstackFactorial {
  dup             % n n
    2 lt          % n true
    {pop 1}       % n true proc
    {dup 1 sub ROstackFactorial mul}  % n true proc proc
  ifelse          % n*(n-1)! (*after* (n-1)! returns) 
} def

/factorial {    % n
  1 1 1         % n 1 1 1
  4 -1 roll     % 1 1 1 n
  {mul}for      % n!
} bind def

Sorting

Ghostscript ships with a bubble-sort implementation named .sort.

See: https://en.wikibooks.org/wiki/PostScript_FAQ#How_to_sort_an_array.3F for a PostScript sorting implementations.

See [casselman-2005-cup] ch. 9, which offers a quicksort implementation and applies it to the convex hulls problem.

Custom Stack

It is possible to use an array as a stack.

See line 45 of dr00g's https://github.com/luser-dr00g/ibis.ps/blob/0c0aa7d5bd683d21d9814b2b697a85028bcddc81/ibis.ps#L45

Debugging

Support for debugging is a PostScript weakness.

See: https://en.wikibooks.org/wiki/PostScript_FAQ#How_to_debug_a_PostScript_program.3F

Format Conversion

Format conversion using Ghostscript.

From: http://wwwimages.adobe.com/content/dam/Adobe/en/devnet/pdf/pdfs/PDF32000_2008.pdf

This postfix notation, in which an operator is preceded by its operands, is superficially the same as in the PostScript language. However, PDF has no concept of an ostack as PostScript has.

Nevertheless, PDF does provide for what are PostScript calculator functions. These are pure numerical functions with no side effects, computed using familiar PostScript operators.

Choose Your Font

In principle you can use any PostScript, TrueType, or OpenType font to add text to your PostScript drawings. [30]

For occasional drawing, however, the practical options are a fairly small set: you will want to use fonts that you can be confident are present in every PostScript interpreter that might be used to render your drawing. The original Apple LaserWriter (1985) had 13 built-in fonts: the Times, Helvetica, and Courier font families, plus the Symbol font. [adobe-1999-plrm3] [p.773] considers these to be “standard”. You can expect that any PostScript interpreter will have access to fonts using these names. Indeed, a superset of 35 fonts can be considered standard: add the Bookman, Palatino, New Century Schoolbook, Avant Garde, and Helvetica Narrow families, (this last being a simple rescaling of Helvetica to .82 of its usual width) along with Zapf Chancery Medium Italic and Zapf Dingbats. Adobe considers 136 fonts to be “core” in Adobe PostScript 3, but unless you know ahead of time which fonts will be available where your PostScript drawing will be interpreted, it is best to stick to the basic set of 35. [31]

The Adobe PostScript fonts typically come in families of four. The four members of the Times family are Times-Roman, Times-Italic, Times-Bold, and Times-BoldItalic. The Helvetica family comprises Helvetica, Helvetica-Oblique, Helvetica-Bold, and Helvetica-BoldOblique. The four members of the Courier family are Courier, Courier-Oblique, Courier-Bold, and Courier-BoldOblique. Some specialty fonts such as Symbol are not part of a family. At four typefaces for each of the eight families plus the three additional fonts we get a standard set of thirty-five fonts. [32]

Once you decide on a font face and size, you are ready to go. Just use the selectfont operator to select the font and font-size. For example, /Helvetica 25 selectfont sets the current font to Helvetica at 25 points.

Placing Text

To place text in your drawing, you need to create a string that contains the characters to be painted. The easiest way to create a string is by enclosing a set of characters in matched parentheses: (this is a string). [33]

The current point determines the placement of the lower left corner of your text when the string is “printed." Set the current point to where you wish your text to begin.

Note that when we quote a literal string object with parentheses, as with (Hello World), this does not print anything. Until we know what font we will use, it does not even tell us what will appear when we print. It is just a way to produce a sequence of character codes, which different fonts (e.g., the Symbol font) may interpret differently.

"Printing” Text

To print your string, use the show operator. The show operator takes one operand, a string. The show operator also requires that the current point and current font be defined. It prints the string in the current font, with the lower left corner at the current point. After the text has been printed, the current point is at the lower right of the string. As an example, to print the text “Print this." in 40 point Helvetica starting at the center of a sheet of letter paper we could use the code

%!
/Helvetica 40 selectfont     %select your font
306 396 moveto               %move to center of page
(Print this.) show           %print “Print this.” on the page
showpage                     %view your work

dup stringwidth pop -2 div 0 rmoveto

dup stringwidth pop neg 0 rmoveto

The Symbol Font

The standard PostScript font set does not support serious mathematics. Of course one can purchase specialized font sets, but even then it is best to rely on an application (such as LaTeX) for the typesetting of complex mathematics.

Occasionally however it is useful to place a few mathematical symbols or Greek letters on a drawing, and the standard Symbol font can often be used for this. The character names and character codes of this font are documented in Appendix E.12 of [adobe-1999-plrm3]. For occasional use, it is helpful that the characters can be accessed with the glyphshow operator, which allows you to work directly with the character name (in the current font). For example, the following code places the text ∑ α on the page.

%! /Symbol 40 selectfont %select Symbol font at 40 points 306 396 moveto %move to middle of page /summation glyphshow %print a summation sign on the page /alpha glyphshow %print a Greek alpha on the page showpage %view your work

We do not have to use glyphshow: we can use the character codes in a string with the show operator to achieve the same effect. For example, α has character code 141 and ∑ has character code 345 in the Symbol font, so the more compact (\345\141)show would also have painted the same text on the page. However for occasional drawing using the Symbol font, it is wiser to use the character names, as these aid in understanding and debugging your PostScript programs.

Adding Text with PyX

PyX does EPS import (and is workingon PDF import). Note that PyX (v.0.14) does not directly support TrueType fonts, but the FAQ offers a work around for this. The discussion of this section assumes you will use the default (Computer Modern) TeX fonts.

Create your EPS figures. Import them into PyX, and add whatever text you wish.

Ask PyX to export as EPS, and use Ghostscript to convert the format to PDF. You should reliably end up with a vector graphic this way.

Adding Text with TikZ

http://tex.stackexchange.com/questions/9559/drawing-on-an-image-with-tikz

Dashed Lines

Economists use dashed lines in their drawing almost as often as solid lines. Fortunately, PostScript makes painting a dashed line as simple as painting a solid line along any path. The key to this is the setdash operator.

The setdash operator takes two operands: an array of numbers that determines the dash pattern, and a number that determines the setdash offset for this pattern. The array is just a list of numbers surround by brackets. The numbers determine the dash lengths and gap lengths along a stroked path. For example the array [5] indicates a dash of 5 units followed by a gap of 5 units. (Note that the stroke operator “cycles” through the array.) As another example the array [5 1] indicates a dash of 5 units followed by a gap of 1 unit. There is no restriction the length of this array, so very complex dash patterns can be specified.

The dash pattern is repeated along the entire stroked path. The offset operand determines how far “into” the dash pattern we are at the beginning of the stroked path. For example, after [5] 5 setdash, a stroke operation would begin with a gap of 5 units. whereas after [5] 2 setdash, a stroke operation would begin with a dash of 3 units.

In section Transformations we learned how to construct equilateral triangle and, by implication, regular polygons with any number of sides. In patterns01 we use that knowledge to construct six pentagons, which we stroke or fill in various ways. In every case we make use of dash patterns.

The simplest case is pentagon 1. Any path we can construct we can also stroke with a dashed line. We illustrate this by stroking pentagon 1 with a line width of 2 after the instruction [15] 0 setdash. This dash pattern starts with a dash of 15 units, followed by a gap of 15 units. That initial pattern is then repeated around the entire pentagon.

Clipping Path

What happens if you stroke or fill a path that you have constructed in such a way that it goes beyond the boundaries of the page? The answer probably seems very natural: only the part of your drawing that is within the page boundary is painted. Anything beyond that boundary is “clipped": it has no effect on the drawing.

Part of the graphics state is the clipping path. (See gstate and clip.) While this is initially the page boundary, it can be constrained further by any path you might wish to construct. Simply construct the path and then invoke the clip operator. From then on, any painting will take place only within the new clipping path. You can do this as many times as you want, but the operation is one of repeated intersection: the clip operator can only reduce the area enclosed by the clipping path. If you need to temporarily shrink the clipping path, then you need to save and restore the larger path. Traditionally this is done by saving and restoring the entire graphics state with gsave and grestore, as discussed in Color. [34]

Bracketing every change to the clipping path between a gsave and a grestore is a reasonable practice, which we follow in this section.

Consider pentagon 2 in patterns01. This illustrates our first use of the clip operator. We are going to add “tic marks” to the inside of the pentagon, since this is one common method of highlighting a specific region. After constructing a pentagon shaped path, we proceed as follows.

gsave                 %save the graphics state
clip                  %clip to current path
[2 25] 12 setdash     %set dash pattern and offset
10 setlinewidth       %thick width produces “tics"
stroke                %stroke the “tics"
grestore              %restore the graphics state
stroke                %stroke path with solid line

First we save the graphics state, which includes our current path and clipping path. (Recall that the current path is the pentagon that we constructed.) We clip to this path so that any painting will take place only inside it. We then set a dash pattern: here we somewhat arbitrarily pick a 2 unit dash followed by a 25 unit gap. When we set the thick line width of 10 units and stroke the pentagon, our dashes show up as “tics” on the interior of the pentagon. Note how the dash length effectively appears as the line width of the tics. Note also how the clipping path restricts the painting to the interior: without this clip operator these tic marks would extend equally on both sides of our path. (Try it!) Of course the stroke operator issues an implicit newpath operation, thereby destroying our constructed pentagon. However since this path was part of the graphics state when we used the gsave operator, we can restore it with the grestore operator. After restoring our constructed pentagon as the current path, we stroke it. Since the dash pattern and line width are part of the graphics state, this stroke operation uses their original values. The grestore operation similarly restores the original clipping path, so we get the full line width when we stroke our pentagon. The result is pentagon 2 in patterns01.

Pattern Fills

Economists' drawings often contain shaded areas, where the shading follows a variety of conventions. Section Color_ discussed how arbitrary paths can be filled with arbitrary colors, including arbitrary shades of gray, and this is one common approach to shading. This section discusses some alternatives to such color fills.

Color fills are currently the best choice of shading for electronic documents, since the resolution of computer monitors is inadequate to effectively display most pattern fills at standard magnifications. For the moment, economists should generally reserve their use of pattern fills for print media.

PostScript is capable of tiling the inside of an arbitrary path with an arbitrary pattern. This facility goes far beyond the needs of occasional drawing is beyond the scope of this booklet. [35]

However certain simple pattern fills are common in economic illustrations. For example, hatching and cross-hatching are often used by economists to shade regions of a drawing. [36]

This section shows how to produce simple pattern fills simply by using very wide dashed lines.

newpath                  %start a new path
-108 -108 moveto         %start path at lower left
108 108 lineto           %construct line to upper right
216 setlinewidth         %very wide line width
[2 20] 0 setdash         %set narrow dash with wide gap
0.5 setgray              %set color to medium gray
stroke                   %stroke the line segment

0 setgray fill           %black filled pentagon
-108 -108 moveto         %start path lower left
108 108 lineto           %construct line to upper right
108 -108 moveto          %start subpath lower right
-108 108 lineto          %construct line to upper left
216 setlinewidth         %set very wide line width
[20 10] 0 setdash        %set dash pattern and offset
1 setgray                %set color to white
stroke                   %stroke the line segments

newpath
-108 -108 moveto         %start path lower left
108 108 lineto           %construct line to upper right
108 -108 moveto          %start subpath lower right
-108 108 lineto          %construct line to upper left
216 setlinewidth         %set line width very wide
[36] 0 setdash           %set dash pattern to 0.5" bands
strokepath               %set path to outline of bands
0.5 setgray              %set current color to gray
eofill                   %paint points inside a single band

Including EPS Files

The basic process to include an EPS file in another PostScript file is the following:

save mark
% include your EPS file here
cleartomark restore

You can literally copy the EPS file content into your PostScript file. Or if your workflow permits file dependencies, you can use the PostScript run operator to include the file. (Use forward slashes for path separators, even on Windows.)

save mark
(myfigures/myEPSfile.eps) run
cleartomark restore

Recall however that many EPS files include a showpage operator, which instruct the printer to eject a page. It is wise to disable this by redefining showpage.

save mark
/showpage {} def
% include your EPS file here
cleartomark restore

There are still some details to attend to. For one thing, you will likely require some transformation to make it appear in the location, size, and orientation that you want. As a detail, it is wise to disable the setpagedevice operator. You may therefore wish to proceed as follows. (See [deubert-200411-aj36b]) for more details.)

%%BeginDocument
/myOldDocumentState save def
mark
/showpage {} def
/setpagedevice /pop load def
%translate, scale, and rotate as needed
% include your EPS file here
cleartomark
myOldDocumentState restore
%%EndDocument

Finally, on Windows some EPS files include a (TIFF or WMF) “preview” as part of the file, and if it does the file should begin with a 30-byte header of directory information. On the Mac, some EPS files include a preview in the file’s “resource fork”. On other systems, there may be an Encapsulated PostScript Screen Image (EPSI) preview included in the file as a special series of comment lines. This booklet does not explore preview generation. To work in a Windows environment with an EPS file that includes a preview, it is generally simplest to strip off the header and preview.

Grayscale Images

An image is a rectangular array of sample values. The image data is stored as a hexadecimal string: a sequence of character pairs, where each pair represents a number from 0 to 256.

Grayscale images can be produced with the image operator. An image is represented as a sequence of components, where each component represents a sample from the image. You need to specify:

• image width
• image height
• color depth as bits per sample, one of 1, 2, 4, 8, or 12. (Based on number of color components per sample, and number of bits per color component)
• transformation matrix, expressing the transformation from your user space to the source image space
• data source

The image is placed based on its lower left hand corner.

The data source can just be a hexadecimal string, or it can be a procedure. If is it a procedure, it must return a string. If the string is too short, it will be used repeatedly to get all the data needed. If it is too long, the extra data will be discarded. The strings represent the image samples, from left to right, starting at the bottom.

Let us start by considering a simple example: a black and white image. We allocate one bit to each sample, which specifies either black (0) or white (1). A single hexadecimal character represents 8 bits. For example, 00 has the bit representation 00000000, while ff has the bit representation 11111111. Suppose we want to represent the following image.

10000000
01000000
00100000
00010000
00001000
00000100
00000010
00000001

We need to start at the bottom left and work left to right, then bottom to top. Note that an entire row can be represented by a single hexidecimal pair. The first row can be represented by 01, the second row by 02, and so forth until the representation of the last row by 80. Our hexidecimal string to represent this figure can therefore be <0102040810204080>, if we use 1 bit per sample.

So the simplest representation of this figure will be

8 8 1 [1 0 0 1 0 0] <0102040810204080> image

However by default a sample will be represented as a 1 point by 1 point square. So by default, our figure will just be a tiny square in the bottom left of our page. Suppose instead we want to map our image to a unit square located at the bottom left but just inside one-inch margins. One way to do that is to change the transformation matrix from the identify matrix to [1 9 div 0 0 1 9 div -8 -8]. (Remember, it is the tranformation from user space to image space!) Here is a more intuitive way to do the same thing.

gsave
72 72 translate
9 9 scale
8 8 1 [1 0 0 1 0 0] <0102040810204080> image
grestore

This simple figure provides a nice opportunity to explore the role of the color depth argument of image. If we change this from 1 to 2, then we will be allocating two bits to each sample. This allows us to represent four colors: black (bin00), dark gray (bin01), light gray (bin10), and white (bin11). Of course if we change the color depth in this way but keep our hexidecimal string unchanged, it will contain only half the information we need. But that is alright: it will just be used twice.

With a color depth of two, one pair of hexidecimal digits no longer represents an entire 8 sample row of a figure. Instead it only represents half a row. So if our image changes to 8 8 2 [1 0 0 1 0 0] <0102040810204080> image, the bottom row is now represent by two hexidecimal numbers (01 and 02). Let B be black, D dark gray, L light gray, and W white. Then since hex01 is bin00000001 and hex02 is bin 00000010, our first row is BBBDBBBL.

If we allocate 8 bits to each sample, we can support 256 different shades of gray (from black (0) to white (255)). To represent all these possible shades, we can put the associated character codes into a string of length 256,

/mystr 256 string def
0 1 255 {mystr exch dup put} for

Then we can use the image operator to create a 16 by 16 grid of these different shades.

16 16 8 [1 9 div 0 0 1 9 div -8 -8] mystr image

We can also use substrings to create an effective “fountain fill”. Here is an example using 150 different shades.

/fillvals mystr 10 150 getinterval def
gsave
72 72 translate
1 150 scale
150 1 8 [1 0 0 1 0 0] fillvals image
grestore

Of course a given device may or may not display so many shades of gray.

Application: Drawing Arrows

We now put a few of these programming concepts to work to create a useful procedure. Economists often need to draw an arrow just as we can draw a line in PostScript: from the current point to a specified endpoint. PostScript does not offer a built in operator for this. The most obvious reason is that the problem of drawing such an arrow is not well specified: there are as many different ideas of what constitutes a nice arrowhead as there are people who have thought about it. Additionally, there is the problem of scaling. An arrowhead that looks nice on a 10 point line may look quite wrong on a 1 point line, despite being appropriately scaled. As can be seen in figure [fig:arrows]_, the following procedure definition produces arrowheads that look good over a reasonable range of line widths. It has also been written to allow easy modification to reflect the tastes of the user. Specifically the relative width of the arrowhead can be set to another value---e.g., a larger value to go with small line widths---or computed based on the current line width. This is a pedagogical implementation, so it has limitations (e.g., in the handling of dashed lines), but it is still very useful.

This sections contains the most complex code in this booklet, and it has been written to illustrate a few programming possibilities. We will carefully consider a few of the details. The object is to define a procedure arrowto that we can use just like we are used to using lineto. So we begin by pushing the literal name arrowto on the stack, followed by a procedure, followed by the def operator. In broadest outline, we have /arrowto { ... } def, where the dots indicate the procedure body. Of course the procedure body is where we will be doing all our work. We want the procedure body to construct a line segment from the current point to an endpoint specified by the top two operands on the ostack.

Take a look at the procedure body. The first thing we do there is start a dictionary by pushing a mark object on the ostack with the << operator. This dictionary is going to hold all the variable definitions used by our procedure. Put another way, we are going to make sure that all the variables in this procedure are strictly local to the procedure. (It is possible to write this procedure to just use the stack and avoid defining any variables, but the use of variables will be a great aid to understanding the procedure.) Our procedure anticipates the presence of two numbers on the top of the ostack, which are the coordinates of the end point for our arrow. We will assign these to the variables tipy and tipx in our dictionary.

Once we have pushed a mark object on the ostack with the << operator, we push the literal name tipy on the stack and roll the y coordinate to the top of the stack. Then we push the literal name tipx on the stack and roll the x coordinate to the top of the stack. To see how this works, let us suppose that we are drawing an arrow to the point (72,144) and watch how the stack changes. (This stack illustration leaves out the transient changes involving the operands for the roll operators.)

144       <<   /tipy    144   /tipx        72
 72      144      <<  /tipy     144     /tipx
 --       72     144     <<   /tipy       144
 --       --      72     72      <<     /tipy
 --       --      --     --      72        <<

The crucial thing to notice is that the mark object can be manipulated on the ostack like any other object. Thus we can use the roll operator to move the endpoint coordinates above the mark, so that each can be used as the value of a name-value pair. The dictionary we will therefore associate the value 72 with the name tipx and the value 144 with the name tipy.

We continue to accumulate name-value pairs on the stack in this fashion. Note that the currentpoint operator pushes on the stack two values representing the current point. The exch operator is a stack manipulation operator that switches the order of the top two objects on the ostack. Note that while the mark object << is on the ostack, we can engage in any calculations we wish to produce the value to be associated with a name. For example, we use the cos and sin operators to produce the cotangent of 22.5 degrees as the value of tip (which is the (relative) extension of the arrowhead beyond the arrow tail) since a total angle of 45 degrees for the arrow tip is visually pleasing. The >> operator will place all the name-value pairs in a dictionary and then pop the mark from the stack. At this point there is an unnamed dictionary object on the top of the ostack. The begin operator pushes this dictionary on the dictionary stack. Since this (unnamed) dictionary is at the top of the dictionary stack, it will hold all new definitions (or redefinitions) until we pop it from the dictionary stack with an end operator.

/arrowto {                         %tipx tipy  *arrowto*  ---
<<                                 %push mark on stack
/tipy 3 -1 roll                    %arrow tip y coordinate
/tipx 5 -1 roll                    %arrow tip x coordinate
/tailx currentpoint                %arrow start x coordinate
/taily exch                        %arrow start y coordinate
/tip 22.5 cos 22.5 sin div         %arrow tip: 45 degree angle
/headwidth 3                       %head width is 3 line widths
>>                                 %create dictionary of “local variables"
begin                              %push on dictionary stack
/dx tipx tailx sub def             %define dx along arrow
/dy tipy taily sub def             %define dy along arrow
/angle dy dx atan def              %arrow angle relaitve to origin
/arrowlength
  dx dx mul dy dy mul add sqrt     %compute length of arrow
def
/tiplength
  tip currentlinewidth 2 div mul   %compute length of arrow tip
def
/base
  arrowlength tiplength sub        %Compute where the arrowhead joins the tail.
def
/headlength
  tip headwidth mul neg            %compute arrowhead length given head width
def
gsave                              %save graphics state
currentpoint translate             %translation to start of arrow
angle rotate                       %rotate user space so arrow points right
base 0 translate                   %translation to end of arrow base
0 0 lineto stroke                  %construct and stroke line
tiplength 0 translate              %translation to tip of arrow
0 0 moveto                         %move to tip of arrow
currentlinewidth 2 div dup scale   %scale to 1/2 line width
headlength headwidth lineto        %construct side of arrowhead
headlength tip add 1
headlength tip add -1
headlength headwidth neg curveto   %construct back of arrowhead
closepath                          %construct side of arrowhead
fill                               %fill arrowhead
grestore                           %restore graphics state
tipx tipy moveto                   %move current point to arrow tip
end                                %pop dictionary fr dictionary stack
} def                              %define the arrowto procedure

Once all our definitions are in place, we begin construction of the arrow. Construction of our arrow is broken into pieces: first we stroke a line up to the arrowhead, and then we construct the arrowhead. We start construction of our arrowhead from its end point. The arrowhead has straight sides, and we get a nice looking arrowhead by constructing the back with the curveto operator. Once we have completed the arrowhead construction, we restore the graphics state and move the current point to the tip of our arrow. We complete our procedure by popping its dictionary off the dictionary stack with the end operator.

PostScript Error Messages

If your programming gets complex, you are likely to commit errors. In this case the PostScript error messages may be helpful. See section 4.3.3 of [adobe-1999-plrm3].

File Input

Occasionally it may prove useful to read in data from another file. The basic procedure is to open a file for reading, read in the data, and then close the file. For example, the following code looks reads in white-space separated numbers that represent points and constructs a path between the points.

0 0 moveto
/myfile (test.dat)(r) file def
     {                                 %begin loop
     myfile token                      %get data
          {                            %if true
          myfile token                 %get data
               {lineto}{exit}ifelse
          }
          {exit}                       %if false
          ifelse
     }loop
myfile closefile

Efficiency Considerations

Generally efficiency is not a primary consideration in simple PostScript drawing. Nevertheless, here are a couple possible considerations.

/mean2g{mul sqrt}bind def

Coordinate Transformations as Matrix Multiplication

The effects of the coordinate transformation operators translate, scale, and rotate can be represented as matrix multiplications. See section 4.3.3 of [adobe-1999-plrm3].

Playing with Text

A font is essentially a set of drawing instructions: in PostScript, there is no real distinction between text and graphics. For example, the current graphics state applies to any text added to your drawing. This allows very powerful graphical effects with text.

PostScript includes an operator called charpath_. This operator requires two operands: a string and a boolean. (The latter is usually true.). It then constructs a path at the current point that is a trace of the glyphs represented by the string in the current font. This path is like any other: you can stroke, fill, or clip it. Clipping to text can also be used to provide some startling graphical effects for the dramatic presentation of text. (See ch.8 of [smith90learnps].) The following example fills a string with red and strokes it with black.

%!
/Helvetica 40 selectfont             %select font face and size
306 396 moveto                       %set current point at page center
(Print this string.) true charpath   %produce outline of text
gsave                                %save graphics state
1 0 0 setrgbcolor fill               %fill outline with red
grestore                             %restore graphics state
stroke                               %stroke outline with black
showpage

Multiple Paths

Our triangle drawings construct from line segments a single, connected path. We painted our drawing by either stroking the path with the stroke operator or filling it with the fill operator. The stroke and fill operators terminate the current path by implicitly performing a newpath operation.

A path need not be connected: it can comprise disconnected subpaths, each begun with the moveto operator. But since a stroke or fill operator affects the entire current path, we cannot set different line widths or colors for different parts of a single path. [46]

Most PostScript drawings will therefore comprise several paths.

Arcs

Example: Yin Yang Symbol

Start a new program. Draw the Yin Yang symbol, centered on a sheet of letter paper. [45]

%!
clippath
1 0 0 setrgbcolor fill
/rad 216 def                  %assign rad=216
/rad2 rad 2 div def           %assign rad2=rad/2
/rad12 rad 12 div def         %assign rad12=rad/12
306 396 translate             %move origin to page center
0 0 rad 0 360 arc             %construct large circle
1 setgray fill                %fill it with white
0 rad2 neg rad2 270 90 arc    %construct small half circle
0 rad2 rad2 270 90 arcn       %construct small half circle
0 0 rad 90 270 arc            %construct large half circle
0 rad2 neg rad12 0 360 arc    %construct little circle
0 setgray eofill
0 rad2 rad12 0 360 arc        %construct little circle
fill                          %fill path with black
0 0 rad 0 360 arc             %construct large circle
stroke                        %stroke with black “ink"
showpage

The code for this example includes our first example of the assignment of a value to a variable in PostScript. (This is discussed in more detail in the section on Variables.) We choose the name rad for the radius of our symbol. The PostScript code /rad 216 def uses the def operator to associate the number 216 with this name. The is the PostScript syntax for “assigning” the number 216 to the “variable” rad.

The next line assigns half the radius to the variable rad2. The PostScript code rad 2 div uses PostScripts division operator (div) to divide the value of rad by 2. One twelfth the figure's radius is similarly assigned to rad12. These assignments make the code more flexible: we can easily change the figure size simply by changing a single number (the radius of the figure).

We get ready to draw by translating the origin to the center of a sheet of letter paper. Our first use of the arc command constructs a full-radius semi-circle. The arc is constructed from an initial angle of 90 degrees to a terminal angle of 270 degrees, so it describes a semi-circle. This is the first operation in example [eg:yinyang]_. We then continue this path with a half-radius semi-circle. In each case we provide the coordinates of the center of our half-circle, then we place the remaining three operands on the stack and invoke the arc operator. The fill operator implicitly closes the current path, so we do not have to use the closepath operator before filling what we have constructed so far.

All that remains to be done is to draw four circles: a half-size white filled circle at the top, tiny white and black filled circles, and a black stroked circle to border the entire symbol. The construction of the Yin-Yang symbol nicely illustrates how simply we can achieve great precision by drawing with the arc operator.

Here are some useful questions to ask about this example. [#]_

What would happen if we added 180 rotate right after our translation of the origin? What would happen if we added 0.5 0.5 scale right after our translation of the origin? How would such rescaling differ from simply changing the radius definition to 108?

Standalone Pictures from PostScript

If you want to do everything by hand, create an EPS template. Create your PostScript drawing in the template, and add an appropriate bounding box. See the discussion of Encapsulated PostScript.

Alternatively, use Ghostscript to convert you4 PostScript drawing to Encapsulated PostScript, with an appropriate bounding box.

Direct Import into Supporting Applications

Once you have an EPS file containing your drawing, you can include it in many applications.

From the menus select Insert » Picture » From File and browse for your file. Note that Microsoft can only correctly handle the DeviceRGB and DeviceGray color spaces. (Those are the color spaces used in this booklet.)

Word: http://answers.microsoft.com/en-us/office/forum/office_2013_release-word/how-do-i-import-an-eps-file-into-word-2013/701ebda7-7efb-40ac-b719-08b735a1d436

LibreOffice: http://smallbusiness.chron.com/open-eps-file-openoffice-63727.html

Mathematica: can import EPS pictures but has trouble with any textual elements http://stackoverflow.com/questions/18647024/how-can-i-import-eps-in-mathematica-without-losing-the-text Amazingly, Import converts the drawing into the vector Mma graphics language! https://www.wolfram.com/mathematica/new-in-8/import-and-export-formats/import-eps-images.html

LaTeX: use \includegraphics to include your EPS file. You will not be able to view the EPS in your DVI file until you use dvips to process it to PostScript. If you wish, you can then use Ghostscript to convert the entire document to PDF. See http://www.tex.ac.uk/FAQ-impgraph.html for details.

If your workflow is more focused on PDF, you can first use Ghostscript to convert your EPS files into PDF files, and then include these PDF files in your document. That allows use of pdflatex. Alternatively, you can use dvipdf on a .dvi file containing PostScript pictures.

The key command is \includegraphics, but here we use this inside a figure environment. (This is the most common usage.)

\documentclass{article}
\usepackage{graphicx}
\begin{document}
\begin{figure}[hbt]
\begin{center}
\includegraphics{myfile.eps}
\caption{My Picture}
\label{fig:mylabel}
\end{center}
\end{figure}
\end{document}

Standalone Pictures from PyX

That's what we've been creating. But it is it also possible to produce multipage documents.

Standalone Pictures from Tikz

The standalone document class makes it simple to produce cropped images from TikZ code. The crop option is et by default for this class (since version 1). The tikz package is also automatically loaded. So we just need:

\documentclass[tikz]{standalone}
\begin{document}
\begin{tikzpicture}
  % your TikZ code here
\end{tikzpicture}
\end{document}

Additionally, there is a standalone package that allows easy inclusion of your stand-alone pictures into a larger document. It will recompile the the pictures only when needed (effectively, when you change the TikZ code). This can save substantial time in a document with many pictures.

Acquisition and Installation

If you are using an operating other than Windows, you probably already have Ghostscript. If you are using Windows, download and run the installer from http://pages.cs.wisc.edu/~ghost/.

Page Size

Ghostscript display PostScript drawin in an Image Window. This displays one page, at the prescribed page size. By default, the page size is US Letter (8.5 x 11 inches). You may be able to change this to another size by editing the gs_init.ps initialization file. See http://www.ghostscript.com/doc/current/Use.htm#Change_default_size for details. (On some systems, the intialization file is compiled into Ghostscript.) You can also set custom size (w,h) in PostScript points with the Ghostscript commnd options -dDEVICEWIDTHPOINTS=w -dDEVICEHEIGHTPOINTS=h.

PostScript Debugging Hints

=

destructively diplay a text representation of the top item on the stack

==

destructively diplay a syntactic representation of the top item on the stack

clear

clear the stack

count

counts the number of items on the operand stack (and pushes this count to the stack)

print

<string> print` writes string to standard output

pstack

print the stack; (apply == to each item, but leave the stack unchanged)

stack

print the stack (apply = to each item, but leave the stack unchanged)

References

PostScript Utilities

%file: utilities.ps
%You can include these in your drawing program most simply by using ``run``.
%E.g., assuming this files is in your working directory: ``(utilties.ps)run``
%(But if you do this and then batch process your drawing, you will need to
%set the ``-dNOSAFER`` when calling GhostScript.)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  transformation utilites  %%%%%%%%%%%%%%%%%%%%%%%%%%%%

/pageLocation {matrix currentmatrix transform matrix defaultmatrix itransform} bind def

%BEGIN:map
% [num] (num -> num) *map* [num]
/map {
  [           %push mark on stack
  3 1 roll    %move mark before array
  forall      %execute function for each array item
  ]           %create array from new items on stack
} bind def
%END:map

%BEGIN:zip
% [obj] [obj] *zip* [[obj]]
/zip {2 dict begin [/a2 /a1] {exch def}forall
  [
    0 1 a1 length a2 length min 1 sub
    {
      dup               % n n
      a1 exch get       % n a1n
      a2 3 -1 roll get  % a1n a2n
      [ 3 1 roll ]      % [a1n a2n]
    }
  for
  ]
end} bind def
%END:zip

/existsCurrentpoint {
{currentpoint pop pop}stopped not
}def
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  point manipulation utilites  %%%%%%%%%%%%%%%%%%%%%%%%%%%%
% num [num] *a:scale* [num]
% scalar mulitiplication
/s:mul {
  [ 3 1 roll {1 index mul exch}forall pop]
} bind def

% [num] [num] *a:add* [num]
%BEGIN:amath
/a:add {zip {sum}map} def 
/a:sub {zip {aload pop sub}map} def 
/a:mul {zip {aload pop mul}map} def 
/a:div {zip {aload pop div}map} def 
%END:amath

/midpoint {a:add {2 div}map} def

% [num] ... [num] *wadd* [num]
% weighted sum of arrays (weights on top)
/wadd { 3 dict begin
  /wts exch def
  /n wts length def
  /n1 n 1 add def
  wts {n1 -1 roll s:mul}forall
  n 1 sub {a:add}repeat
end} def


% [num] *sum* num
%BEGIN:sum
/sum {0 exch {add} forall} bind def
%END:sum

% proc proc *proccombine* proc
% Combines the actions of two procedures into a single procedure.
% credit: Joshua Ryan (2016)
% stackoverflow.com/questions/38272415/point-free-procedure-composition/38276006
% Stack details: {a} {b}  .  {{a} exec {b} exec}
/proccombine {
  /exec cvx exch     % {a} exec {b}
  /exec cvx          % {a} exec {b} exec
  4 array astore     % [{a} exec {b} exec]
  cvx                % {{a} exec {b} exec}
} def


% start step stop *iRange* [num]
% consumes an array; pushes a new array on ostack
%BEGIN:iRange
/iRange {[ 4 1 roll {}for ]} def
%END:iRange

% [obj] *head* obj
% consumes an array; pushes first element on ostack
%BEGIN:head
/head {0 get} bind def
%END:head

%synonym
/first {head} bind def

% [obj] *tail [obj]
% consumes an array; pushes on ostack a new array
% that contains all but first element
%BEGIN:tail
/tail {              % a0
  dup length 1 sub   % a0 len (len is a1's length)
  1 exch             % a0 1 len
  getinterval        % a1 (the tail of a0)
} bind def
%END:tail

% [obj] *uncons* [obj] obj
%BEGIN:uncons
/uncons {     %arr
  dup         %arr arr
  tail exch   %tail arr
  head        %tail head
} bind def
%END:uncons

/last  {dup length 1 sub get} bind def 
/init  {dup length 1 sub 0 exch getinterval} bind def


%null is a PostScript name
/null? {length 0 eq {true} {false} ifelse} bind def

%concat is a PostScript operator
/concatArrays {[ exch {{} forall} forall ]} bind def

% [obj] obj *lput* [obj]
%equivalent to: /lput {[ exch 3 -1 roll {}forall ]} bind def 
%BEGIN:lput
/lput {             %arr x
  exch dup          %x arr arr
  length 1 add      %x arr n
  array dup         %x arr arrn arrn
  0 5 -1 roll put   %arr arrn
  dup 1             %arr arrn arrn 1
  4 -1 roll         %arrn arrn 1 arr 
  putinterval       %arrn
} bind def
%END:lput



% [obj] *reverse* [obj]
%name ok
/reverse { [ exch {counttomark 1 roll}forall ] } bind def

% [num] (num {...} bool) *findidx* int
%%find fist index where element satisfies predicate
/findIndex {<< /f 3 -1 roll /idx 0 /fidx -1  >> begin
  {f{/fidx idx def exit}{/idx idx 1 add def}ifelse }forall fidx
end} bind def

% [num] (num {...} bool) *selectBy* [num]
%% find items that satisfy predicate
%% (filter is a PostScript operator)
/selectBy {<< /f 3 -1 roll>> begin
  [ exch {dup f{}{pop}ifelse }forall ]
end} bind def

% (int {...} num) int nValues [num]
/nValues {1 sub exch [ 0 1 5 -2 roll for ]} bind def



% [obj] obj *intersperse* [obj]
/intersperse {<< /x 3 -1 roll >> begin [ exch {x}forall pop ] end} bind def
%TODO try another approach?

% [num] num  (num num {...} num) *foldl* num
% Example: [1 2 3] 0 {add} foldl
% credit: http://codereview.stackexchange.com/questions/12249/concatenative-postscript-library/69933#69933
/foldl {3 1 roll exch 3 -1 roll forall} bind def

% [num] (num num {...} num) *foldl1* num
% warning: fails on empty array
/foldl1 {exch uncons 3 -1 roll foldl} bind def

% num1 num2 *max* num
/max {<< /x1 4 2 roll /x2 exch >> begin x1 x2 ge{x1}{x2}ifelse end} bind def

% [num] *maximum* num
% warning: fails on empty array
/maximum {{max} foldl1} bind def

% num1 num2 *min num
/min {<< /x1 4 2 roll /x2 exch >> begin x1 x2 le{x1}{x2}ifelse end} bind def

% [num] *minimum* num
% warning: fails on empty array
/minimum {{min} foldl1} bind def

% [obj] (obj {...} bool) *all?* bool
/all? {{and} proccombine true exch foldl} def

%[bool] *And* bool
/And {{} all?} bind def

% [obj] (obj {...} bool) *any?* bool
/any? {{or} proccombine false exch foldl} def

%[bool] *And* bool
/Or {{} any?} bind def


%%%%%%%%%%%%%%%%%%  string utilities  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% str str *concatstrings* str
%a more efficient concatstrings is already provided by GhostScript
%(but this one is easier to understand)
%https://en.wikibooks.org/wiki/PostScript_FAQ#How_to_concatenate_strings.3F
/concatstrings {3 dict begin [/s2 /s1] {exch def}forall
  /s3 s1 length s2 length add string def
  s3 0 s1 putinterval
  s3 s1 length s2 putinterval
  s3
end} def

% string *centerShow* --
%show string centered on current point
/centerShow {
dup stringwidth pop -2 div 0 rmoveto show
} bind def
%%%%%%%%%%%%%%%%%%  path construction utilities  %%%%%%%%%%%%%%%%%%%%%%%%%%

% Line is deprecated in favor of polyLine
% [[num]] *Line* --
%BEGIN:Line
/Line {
  uncons               %tail head
  aload pop moveto     %tail
    {aload pop lineto} %tail proc
  forall               % --
} bind def
%END:Line

% [[num]] *Line* --
%BEGIN:polyLine
/polyLine {
  uncons               %tail head
  aload pop moveto     %tail
    {aload pop lineto} %tail proc
  forall               % --
} bind def
%END:polyLine


% [[num]] *constructScatter* --
%BEGIN:constructScatter
/constructScatter {
  {aload pop 2 copy moveto lineto} forall
} bind def
%END:Line

/hLine {
  Line
  closepath
} bind def
 
%convert polar coordinates to Cartesian coordinates 
% r theta *fromPolar2D* x y
%BEGIN:fromPolar2D
/fromPolar2D { % r theta 
  2 copy       % r theta r theta
  cos mul      % r theta x
  3 1 roll     % x r theta
  sin mul      % x y
}bind def
%END:fromPolar2D

%%%%%%%%%%%%%%%%%  arrow utilities  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%BEGIN:simpleArrowTo
/simpleArrowTo {12 dict begin
  /y exch def
  /x exch def
  currentpoint
  y sub neg /dy exch def                    %dy along arrow
  x sub neg /dx exch def                    %dx along arrow
  /alen dx dx mul dy dy mul add sqrt def    %total length of arrow
  /heading dy dx atan def                   %heading of arrow
  /theta 60 def                             %angle of arrowhead
  /turn 180 theta 2 div sub def             %turn angle of barb
  /width currentlinewidth def               %line width of arrow
  /blen 8 width mul def                     %barb length
  /mlen width theta 2 div sin div def       %miter length
  /slen alen mlen 2 div sub def             %shaft length
  slen heading fromPolar2D rlineto          %construct the shaft
  currentpoint                              %store pt A (end of shaft)
  blen heading turn add fromPolar2D rmoveto %move to end of one barb
  lineto                                    %construct one barb; consume pt A
  blen heading turn sub fromPolar2D rlineto %construct other barb
  x y moveto                                %move to tip of arrow
end}def
%END:simpleArrowTo

%%%%%%%%%%%%%%%%%  other utilities  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% int *factorial* int
%BEGIN:factorial
/factorial {    % n
  1 1 1         % n 1 1 1
  4 -1 roll     % 1 1 1 n
  {mul}for      % n!
} bind def
%END:factorial

Appendix: Execution Model

The following description is based on Reid (1986). A PostScript program is interpreted as a sequence of lexical tokens. Tokens that are not names are pushed on the ostack. If a token is a name, its value is looked up in the dstack. If the value is executable, it is executed. Otherwise, it is pushed on the ostack.

for token in parse(input):
  lexType := lexicalType(token)
  if isName(lexType):
    push(token)
  else:
    tokenValue := lookup(token)
    tokenType := type(tokenValue)
    if isExecutable(tokenType):
      execute(tokenValue)
    else:
      push(tokenValue)