Introduction
This is a guide to generating diagrams using Pikchr (pronounced "Picture"). This guide is designed to teach you to use Pikchr. It is not a reference for the Pikchr language (that is a separate document) nor is it an explanation of why you might want to use Pikchr. The goal here is to provide a practical and accessible tutorial on using Pikchr.
Running Pikchr Scripts
The design goal of Pikchr is to enable embedded line diagrams in Markdown or other simple markup languages. The details on how to embedded Pikchr in Markdown is covered separately. For the purpose of this tutorial, we will only write pure Pikchr scripts without the surrounding markup. To experiment with Pikchr, visit the /pikchrshow page on the website hosting this document (preferably in a separate window). Type in the following script and press the Preview button:
line; box "Hello," "World!"; arrow
If you do this right, the output should appear as:
line; box "Hello," "World!"; arrow
So there you go: you've created and rendered your first diagram using Pikchr! You will do well to keep that /pikchrshow screen handy, in a separate browser window, so that you can try out scripts as you proceed through this tutorial.
Viewing Pikchr Script Source Code For This Document
For this particular document, you can click on any of the diagrams rendered by Pikchr and the display will convert to showing you the original Pikchr source text. Click again to go back to seeing the rendered diagram.
The click-to-change-view behavior is a property of this one particular document and is not a general capability of Pikchr. On other documents containing Pikchr diagrams that are generated using Fossil you can use ctrl-click (alt-click on Macs) to toggle the view. That is, click on the diagram while holding down the Ctrl key or the Alt key. This is not possible if you are on a tablet or phone, since you don't have a Ctrl or Alt key to hold down there. Other systems might not implement the view-swapping behavior at all. This is a platform-depending feature that is one layer above Pikchr itself.
About Pikchr Scripts
Pikchr is designed to be simple. A Pikchr script is just a sequence of Pikchr statements, separated by either new-lines or semicolons. The "Hello, world!" example above used three statements, a "line", a "box", and an "arrow", each separated by semicolons.
Whitespace (other than newlines) and comments are ignored. Comments in
pikchr can be in the style of TCL, C, or C++. That is to say, comments
consist of a "#" or "//" and include all characters up to but
not including the next new-line, or all text
in between "/*" and the first following "*/".
The example script above could be rewritten with each statement on
a separate line, and with comments describing what each statement is
doing:
# The first component of the drawing is a line
line
// The second component is a box with text "Hello, World!"
box "Hello," "World!"
/* Finally an arrow */
arrow
Remember that new-lines separate statements. If you have a long statement that needs to be split into multiple lines, escape the newline with a backslash character and the new-line will be treated as any other space:
line
box \
"Hello," \
"World!"
arrow
So, a Pikchr script is just a list of statements, but what is a statement?
Pikchr Statements
Most statements are descriptions of a single graphic object that becomes part of the diagram. The first token of the statement is the object class-name. The following classes are currently supported:
box "box" circle "circle" at 1 right of previous ellipse "ellipse" at 1 right of previous oval "oval" at .8 below first box cylinder "cylinder" at 1 right of previous file "file" at 1 right of previous line "line" above from .8 below last oval.w arrow "arrow" above from 1 right of previous spline from previous+(1.8cm,-.2cm) \ go right .15 then .3 heading 30 then .5 heading 160 then .4 heading 20 \ then right .15 "spline" at 3rd vertex of previous dot at .6 below last line text "dot" with .s at .2cm above previous.n arc from 1 right of previous dot text "arc" at (previous.start, previous.end) text "text" at 1.3 right of start of previous arc
A statement can be only the class-name and nothing else, but the class-name is usually followed by one or more "attributes". Attributes are used to modify the appearance of the object, or to position the object relative to prior objects.
So to revisit the "Hello, World" demonstration script above, we see that that script contains three object descriptions:
- A "line" object with no attributes (meaning that the line is shown with no changes to its default appearance).
- A "box" object with two string literal attributes. The string literal attributes cause the corresponding strings to be drawn inside the box.
- An "arrow" object with no attributes.
Layout
By default, objects are stacked beside each other from left to right. The Pikchr layout engine keeps track of the "layout direction", which can be one of "right", "down", "left", or "up". The layout direction defaults to "right", but you can change it using a statement which consists of just the name of the new direction. So, if we insert the "down" statement in front of our test script, like this:
down
line
box "Hello," "World!"
arrow
Then the objects are stacked moving downward:
down
line
box "Hello," "World!"
arrow
Or, you can change the layout direction to "left":
left
line
box "Hello," "World!"
arrow
Or to "up":
up
line
box "Hello," "World!"
arrow
It is common to stack line objects (lines, arrows, splines) against block objects (boxes, circles, ovals, etc.), but this is not required. You can stack a bunch of block objects together. For example:
box; circle; cylinder
Yields:
box; circle; cylinder
More often, you want to put space in between the block objects. The special "move" object exists for that purpose. Consider:
box; move; circle; move; cylinder
This script creates the same three block objects but with whitespace in between them:
box; move; circle; move; cylinder
Implementation note: A "move" is really just an invisible "line". So the following script generates the same output as the previous. (Try it!)
box; line invisible; circle; line invisible; cylinder
Controlling Layout Using Attributes
The automatic stacking of objects is convenient in many cases, but most diagrams will want some objects placed somewhere other than immediately adjacent to their predecessor. For that reason, layout attributes are provided that allow precise placement of objects.
To see how this works, consider the previous example of a box, circle, and cylinder separated by some space. Suppose we want to draw an arrow that goes downward out of the box, then right, then up into the cylinder. The complete script might look something like this:
box; move; circle; move; cylinder
arrow from first box.s \
down 1cm \
then right until even with first cylinder \
then to first cylinder.s
This script results in the following diagram:
box; move; circle; move; cylinder
arrow from first box.s \
down 1cm \
then right until even with first cylinder \
then to first cylinder.s
That is indeed the image we want, but there are a lot of words on that "arrow" statement! Don't panic, though. It's actually pretty simple. We'll take it apart and explain it piece by piece.
First note that the "arrow" statement is broken up into four separate
lines of text, with a "\" at the end of the first three lines to
prevent the subsequent new-line from prematurely closing the statement.
Splitting up the arrow into separate lines this way is purely for
human readability. If you are more comfortable putting the whole
statement on one line, that is fine too. Pikchr doesn't care. Just
be sure to remember the backslashes if you do split lines!
The attributes on the "arrow" statement describe the path taken by
the arrow. The first attribute is "from first box.s". This "from"
attribute specifies where the arrow starts. In this case, it starts
at the "s" (or "south") anchor point of the "first box". The "first box"
part is probably self explanatory. (You can also write it as
"1st box" instead of "first box", and in fact legacy-PIC requires
the use of "1st" instead of "first".) But what is the ".s" part?
Every block object has eight anchor points on its perimeter that are named for compass points, like this:
A: box dot color red at A.nw ".nw " rjust above dot same at A.w ".w " rjust dot same at A.sw ".sw " rjust below dot same at A.s ".s" below dot same at A.se " .se" ljust below dot same at A.e " .e" ljust dot same at A.ne " .ne" ljust above dot same at A.n ".n" above dot same at A.c " .c" ljust A: circle at 1.5 right of A dot color red at A.nw ".nw " rjust above dot same at A.w ".w " rjust dot same at A.sw ".sw " rjust below dot same at A.s ".s" below dot same at A.se " .se" ljust below dot same at A.e " .e" ljust dot same at A.ne " .ne" ljust above dot same at A.n ".n" above dot same at A.c " .c" ljust A: cylinder at 1.5 right of A dot color red at A.nw ".nw " rjust above dot same at A.w ".w " rjust dot same at A.sw ".sw " rjust below dot same at A.s ".s" below dot same at A.se " .se" ljust below dot same at A.e " .e" ljust dot same at A.ne " .ne" ljust above dot same at A.n ".n" above dot same at A.c " .c" ljust
As you can see, there is also a ninth point in the middle called ".c". Every block object has these anchor points; you can refer to them when positioning the object itself, or when positioning other objects relative to the block object. In this case, we are starting the arrow at the ".s" anchor of the box.
The next phrase on the "arrow" statement is "down 1cm". As you
might guess, this phrase causes the arrow to move downward from its
previous position (its starting point) by 1 centimeter. This phrase
highlights a key enhancement of Pikchr over PIC, which did
everything in inches only. No units were allowed. Pikchr allows
you to attach units to measurements, as in this case where it is
"1cm". Internally, Pikchr still keeps track of everything in inches
for compatibility with PIC, so the "1cm" token is really just an
alternative spelling for the numeric constant "0.39370078740157480316",
which is the inch-equivalent of 1 centimeter. Surely you agree that
"1cm" is much easier to read and write! Other units recognized by Pikchr
are "px" for pixels, "pt" for points, "pc" for picas, "mm" for millimeters,
and of course "in" for inches. Inches are assumed if no units are
specified.
Back to our arrow: we have now established a path for the arrow
down 1 centimeter from the ".s" anchor of the box. The next phrase
is: "then right until even with first cylinder".
You can perhaps guess that this means that the arrow should continue
to the right until it is lined up below the first cylinder. You,
the diagram designer, don't know (and don't really want to know)
how far apart the box and the cylinder are, so you can't tell it
exactly how far to go. This phrase is a convenient way of telling
Pikchr to "make the line long enough".
Note that the "first cylinder" part of the "until even with"
phrase is actually an abbreviation for "first cylinder.c" - the
center of the cylinder. This is what we want. You could also
write "first cylinder.s" if you want.
The "until even with" phrase is not found in the original version of PIC. In that
system, you would have to do some extra math to figure out the
distance for yourself, something like
"then right (1st cylinder.s.x - 1st box.s.x)". We think the
"until even with" phrase is easier to use and understand.
The final phrase in the "arrow" statement is
"then to first cylinder.s". This phrase tells the arrow to go
from wherever it is at the moment directly to the ".s" anchor
of the cylinder.
The Advantage Of Relative Layout
Notice that our sample diagram contains no coordinates and only one hard-coded distance, the "down 1cm" bit in the "arrow" statement. The script is written in such a way that the script-writer does not have to do a lot of distance calculation. The layout compensates automatically.
For example, suppose you come back to this script later and decide you need to insert an ellipse in between the circle and the cylinder. This is easily accomplished:
box; move; circle; move; ellipse; move; cylinder
arrow from first box.s \
down 1cm \
then right until even with first cylinder \
then to first cylinder.s
We simply add the ellipse (and an extra "move") on the first line. Even though the coordinate positions of the objects have adjusted, the description of the arrow that connects the box to the cylinder is not based on coordinates or absolute distances, so it does not have to change at all. Pikchr compensates automatically:
box; move; circle; move; ellipse; move; cylinder
arrow from first box.s \
down 1cm \
then right until even with first cylinder \
then to first cylinder.s
Both PIC and Pikchr allow you to specify hard-coded coordinates and distances when laying out your diagram, but you are encouraged to avoid that approach. Instead, place each new object you create relative to the position of prior objects. Pikchr provides many mechanisms for specifying the location of each object in terms of the locations of its predecessors. With a little study of the syntax options available to you (and discussed further below) you will be generating complex diagrams using Pikchr in no time.
Single-Pass Design
Both Pikchr and PIC operate on a single-pass design. Objects
can refer to other objects that occur before them in the script, but not
to objects that occur later in the script. Any computations that go
into placing an object occur as the object definition is parsed. As soon
as the newline or semicolon that terminates the object definition is
reached, the size, location, and characteristics of the object are
fixed and cannot subsequently be altered. (One exception: sub-objects that
are part of a []-container (discussed later) are placed relative to the
origin of the container. Their shape and locations relative to each
other are fixed, but their final absolute position is not fixed until
the []-container itself is fixed.)
The single-pass approach contributes to the conceptual simplicity of Pikchr (and PIC). There is no "solver" that has to work through forward and backward layout constraints to find a solution. This simplicity of design helps to keep Pikchr scripts easy to write and easy to understand.
Labeling Objects
The previous example used the phrases like "first box" and "first cylinder"
to refer to particular objects. There are many variations on this naming
scheme:
- "
previous" ← the previous object regardless of its class - "
last circle" ← the most recently created circle object - "
3rd last oval" ← the antipenultimate oval object - "
17th ellipse" ← the seventeenth ellipse object - ... and so forth
These relative and ordinal references work, but they can be fragile. If you go back later and insert a new object in the stream, you can mess up the counting. Or, for that matter, you might just miscount.
In a complex diagram, it often works better to assign symbolic names to objects, which we call “labels” in Pikchr. A label begins with a capital letter followed by some number of regular ASCII letters, digits or underscores, followed by a colon. This must come immediately before an object, without an intervening newline. Afterwards, the object can be referred to by that label.
Consider how this simplifies our previous example:
B1: box; move;
circle; move;
ellipse; move;
C1: cylinder
arrow from B1.s \
down 1cm \
then right until even with C1 \
then to C1.s
By giving symbolic names to the box (B1) and cylinder (C1), the arrow path description is simplified. Furthermore, if the ellipse gets changed into another cylinder, the arrow still refers to the correct cylinder.
The indentation of the lines following each symbolic name above is syntactically unimportant: it serves only to improve human readability. Nevertheless, this is typical coding style for Pikchr and PIC before it.
Layout Of Block Objects
For lines (and arrows and splines), you have to specify a path that the line follows, a path that might involve multiple bends and turns. Defining the location of block objects is easier: you just provide a single location to place the object. Ideally, you should place the object relative to some other object, of course.
Let's say you have box, and you want to position a circle 2 centimeters to the
right of that box. You simply use an "at" attribute on the circle to tell it
to position itself 2 cm to the right of the box:
B1: box
circle at 2cm right of B1
The resulting diagram is:
B1: box
circle at 2cm right of B1
X1: line thin color gray down 50% from 2mm south of B1.s
X2: line same from (last circle.s,X1.start)
arrow <-> thin from 3/4<X1.start,X1.end> right until even with X2 \
"2cm" above color gray
assert( last arrow.width == 2cm )
(We’ve added gray dimension lines purely for illustration. Click the diagram per the instructions above to see that they do not change the example, only add to it.)
The circle is positioned so that its center is 2 centimeters to the right of the center of the box. If what you really wanted is that the left (or west) side of the circle is 2 cm to the right (or east) of the box, then just say so:
B1: box C1: circle with .w at 2cm right of B1.e
Normally an "at" clause will set the center of an object, but if
you add a "with" prefix you can specify any other anchor
point of the object to be the reference for positioning. The Pikchr
script above is saying "make the C1.w point be 2 cm right of B1.e".
And we have:
B1: box
C1: circle with .w at 2cm right of B1.e
X1: line thin color gray down 50% from 2mm south of B1.se
X2: line same from (C1.w,X1.start)
arrow <-> thin from 3/4<X1.start,X1.end> right until even with X2 \
"2cm" above color gray
assert( last arrow.width == 2cm )
That's the whole story behind positioning block objects on a diagram. You just add an attribute of the form:
with reference-point at position
And Pikchr will place the specified reference-point of the object at
position. If you omit the "with" clause, the center of the
object (".c") is used as the reference-point. The power of Pikchr
comes from the fact that "position" can be a rather complex expression.
The previous example used a relatively simple position
of "2cm right of B1.e". That was sufficient for our simple diagram.
More complex diagrams can have more complex position phrases.
Automatic Layout Of Block Objects
If you omit the "at" attribute from a block object, the object is positioned
as if you had used the following:
with .start at previous.end
Except, the very first object in the script has no "previous" and so it is positioned using:
with .c at (0,0)
Let's talk little more about the usual case:
"with .start at previous.end". The "previous" keyword means the
previous object in the script. (You can also use the keyword "last"
for this purpose.) So we are positioning the current object relative
to the previous object. But what about the ".start" and ".end"?
Remember that every object has 8 anchor points whose names correspond to compass directions: ".n", ".ne", ".e", ".se", ".s", ".sw", ".w", and ".nw", plus the ninth anchor, the center point ".c". Every object also has ".start" and ".end" anchor points, but their position varies depending on the layout direction that is current when the object is created.
Layout Direction .start .end right .w .e down .n .s left .e .w up .s .n
Recall the earlier example that consisted of three objects stacked together:
right; box; circle; cylinder
(I added a "right" at the beginning to make the layout direction
clear, but as "right" is the default layout direction, so it doesn't change
anything.)
Armed with our new knowledge of how "at"-less block objects are
positioned, we can better understand what is going on. The box is
the first object. It gets positioned with its center at (0,0), which
we can show by putting a red dot at (0,0):
right; box; circle; cylinder
dot color red at (0,0)
right; box; circle; cylinder
dot color red at (0,0)
Because the layout direction is "right", the start and end of the box are the .w and .e anchor points. Prove this by putting more colored dots at those points and rendering the result:
right; box; circle; cylinder
dot color green at 1st box.start
dot color blue at 1st box.end
right; box; circle; cylinder
dot color green at 1st box.start
dot color blue at 1st box.end
Similarly, we can show that the .start and .end of the circle are its .w and .e anchor points. (Add new color dots to prove this to yourself, if you like.) And clearly, the .start of the circle is directly on top of the .end of the box.
Now consider what happens if we change the layout direction after the circle is created but before the cylinder is created:
right; box; circle; down; cylinder
This script works a little differently on Pikchr than it does on PIC. The change in behavior is deliberate, because we feel that the Pikchr approach is better. On PIC, the diagram above would be rendered like this:
right; box; circle; cylinder with .n at previous.e
But on Pikchr the placement of the cylinder is different:
right; box; circle; cylinder with .n at previous.s
Let's take apart what is happening here. In both systems, after the "circle" object has been parsed and positioned, the .end of the circle is the same as .e, because the layout direction is "right". If we omit the "down" and "cylinder" and draw a dot at the ".end" of circle to show where it is, we can see this:
right; box; circle
dot color red at last circle.end
The next statement is "down". The "down" statement changes the layout direction to "down" in both systems. In legacy PIC the .end of the circle remains at the .e anchor. Then when the "cylinder" is positioned, its ".start" is at .n because the layout direction is now "down", so the .n point of the cylinder is aligned to the .e point of the circle.
Pikchr works like PIC with one important change: when the "down" statement is evaluated, Pikchr also moves the ".end" of the previous object to a new location that is appropriate for the new direction. In other words, the down command moves the .end of the circle from .e to .s. You can see this by setting a red dot at the .end of the circle after the "down" command:
right; box; circle; down
dot color red at first circle.end
Or, we can "print" the coordinates of the .end of the circle before
and after the "down" command to see that they shift:
after: 0.625 , -0.25
right; box; C1: circle
print "before: ", C1.end.x, ", ", C1.end.y
down
print "after: ", C1.end.x, ", ", C1.end.y
Adjusting The Size Of Block Objects
The size of every block object is controlled by three parameters:
width(often abbreviated aswid)height(orht)radius(orrad)
There is also a fourth convenience parameter:
diameter
The diameter is always twice the radius. Setting the diameter automatically
changes the radius and setting the radius automatically changes the
diameter.
Usually the meanings of these parameters are obvious.
A: box thick line thin color gray left 70% from 2mm left of A.nw line same from 2mm left of A.sw text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below A.sw X2: line thin color gray down 50% from 2mm below A.se text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 ->
The radius parameter, however, sometimes has non-obvious meanings.
For example, on a box, the radius determines the rounding of corners:
A: box thick rad 0.3*boxht line thin color gray left 70% from 2mm left of (A.w,A.n) line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below (A.w,A.s) X2: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 -> X3: line thin color gray right 70% from 2mm right of (A.e,A.s) X4: line thin color gray right 70% from A.rad above start of X3 text "radius" at (6/8<X4.start,X4.end>,1/2<X3,X4>) line thin color gray from (previous,X3) down 30% <- line thin color gray from (previous text,X4) up 30% <-
For a cylinder object the radius determines the
thickness of the end caps:
A: cylinder thick rad 150% line thin color gray left 70% from 2mm left of (A.w,A.n) line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below (A.w,A.s) X2: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 -> X3: line thin color gray right 70% from 2mm right of (A.e,A.ne) X4: line thin color gray right 70% from A.rad below start of X3 text "radius" at (6/8<X4.start,X4.end>,1/2<X3,X4>) line thin color gray from (previous,X4) down 30% <- line thin color gray from (previous text,X3) up 30% <-
For a file object the radius determines the size of
the page fold-over in the upper-right corner:
A: file thick rad 100% line thin color gray left 70% from 2mm left of (A.w,A.n) line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below (A.w,A.s) X2: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 -> X3: line thin color gray right 70% from 2mm right of (A.e,A.n) X4: line thin color gray right 70% from A.rad below start of X3 text "radius" at (6/8<X4.start,X4.end>,1/2<X3,X4>) line thin color gray from (previous,X4) down 30% <- line thin color gray from (previous text,X3) up 30% <-
For a circle object, the width, height, and diameter are always the same, and the radius is always half the diameter. Changing any parameter automatically adjusts the other three.
A: circle thick rad 120% line thin color gray left 70% from 2mm left of (A.w,A.n) line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below (A.w,A.s) X2: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 -> X3: line thin color gray right 70% from 2mm right of (A.e,A.s) X4: line thin color gray right 70% from A.rad above start of X3 text "radius" at (6/8<X4.start,X4.end>,1/2<X3,X4>) line thin color gray from (previous,X3) down 30% <- line thin color gray from (previous text,X4) up 30% <- line thin color gray <-> from A.sw to A.ne line thin color gray from A.ne go 0.5*A.rad ne then 0.25*A.rad east text " diameter" ljust at end of previous line
Even though they are curvy objects, the radius (and hence diameter)
has no effect on ellipse and oval objects.
The size of those objects is determined purely by their width and height:
A: ellipse thick line thin color gray left 70% from 2mm left of (A.w,A.n) line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>) line thin color gray from previous text.n up until even with 1st line -> line thin color gray from previous text.s down until even with 2nd line -> X1: line thin color gray down 50% from 2mm below (A.w,A.s) X2: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>) line thin color gray from previous text.w left until even with X1 -> line thin color gray from previous text.e right until even with X2 ->
A: oval thick X0: line thin color gray left 70% from 2mm left of (A.w,A.n) X1: line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<X0,X1>) line thin color gray from previous text.n up until even with X0 -> line thin color gray from previous text.s down until even with X1 -> X2: line thin color gray down 50% from 2mm below (A.w,A.s) X3: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" at (1/2<X2,X3>,6/8<X2.start,X2.end>) line thin color gray from previous text.w left until even with X2 -> line thin color gray from previous text.e right until even with X3 -> A: oval thick wid A.ht ht A.wid at 2.0*A.wid right of A X0: line thin color gray left 70% from 2mm left of (A.w,A.n) X1: line same from 2mm left of (A.w,A.s) text "height" at (7/8<previous.start,previous.end>,1/2<X0,X1>) line thin color gray from previous text.n up until even with X0 -> line thin color gray from previous text.s down until even with X1 -> X2: line thin color gray down 50% from 2mm below (A.w,A.s) X3: line thin color gray down 50% from 2mm below (A.e,A.s) text "width" small at (1/2<X2,X3>,6/8<X2.start,X2.end>) line thin color gray from previous text.w left until even with X2 -> line thin color gray from previous text.e right until even with X3 ->
Notice that with an oval object, the semicircular end-cap is always on the narrow end of the object. In the default configuration where the height is less than the width, the semicircular end-caps are on the left and right, but if the width and height are modified so that the width is less than the height, then semicircles appear on the top and bottom instead.
Default Sizes
Block objects have default sizes, which are determined by variables.
For example, the width of a box is initialized with the value of the boxwid
variable, which defaults to 0.75in.
It is common for Pikchr scripts to change these default at or near the beginning of a script in order to adjust the default sizes of objects defined within that script.
Setting Sizes Using Attributes
Use the "width" (or "wid") attribute to change the width of an object.
The argument to this attribute can be an expression — such as "1cm" or
"0.75*boxwid" — or it can be a percentage of the prior value,
such as "75%". This also works for "height",
"radius", and "diameter".
Automatic Sizing To Fit Text Annotations
If a block object contains text annotations, the "fit" attribute causes
the width and height to be adjusted so that the object neatly encloses that
text. The "fit" attribute only considers text that is previously defined
for the object, or in other words text annotations that occur to the left
of the "fit" keyword. The width and height can be adjusted further after
the "fit" keyword, for example to provide a larger margin around the
text. Click on the following script to see the difference that the
"width 125%" at the end of the second box definition makes.
down
box "Auto-fit text annotation" "as is" fit
move 50%
box "Auto-fix text annotation" "with 125% width" fit width 125%
If at the end of a block object definition, either the width or height of the object is less than or equal to zero, then that dimension is increased so as to enclose all text annotations on the object. Thus, for example, you can make all of the boxes in your diagram auto-fit around their text annotations by prefacing your script with something like:
boxwid = 0; boxht = 0;
box "Hello";
move
box "A longer label" "with multiple lines" "of label text"
For all of these auto-fit features, Pikchr needs to know the dimensions of the
text annotations after rendering. Unfortunately, that information is not
readily available, as Pikchr runs long before the generated SVG reaches the
web-browser in which it will be displayed. Hence, Pikchr has to guess at the
text size. Usually it does a good job of this, but it can be a little off,
especially for unusual (read: "non-ASCII") characters or if the CSS for
the rendering environment sets a non-standard font face or font size. To
compensate, the "charwid" and "charht" variables can be adjusted or
extra spaces can be added at the beginning or end of text strings.
These auto-fit features are a new innovation for Pikchr and are not available in other PIC family interpreters, as far as we are aware.
Attributes For Stroke Width And Drawing Colors
Various attributes can be added to both block and line objects to influence how the objects are drawn.
thicknessdimensionthickthininvisible(orinvis)colorcolorfillcolor
The "thickness", "thick", "thin", and "invisible" attributes control
the stroke width of the lines that construct an object. The default stroke width
for all objects is determined by the "thickness" variable, which defaults
to "0.015in". The "thick" and "thin" attributes increase or decrease
the stroke width by fixed percentages. These attributes can be repeated
to make the stroke width ever thicker or thinner, up to the limit of the object’s
dimensions where the stroke fills the entire object. The "invisble" attribute
simply sets the stroke width to 0.
boxwid = 0 boxht = 0 right box "normal" move box "thin" thin move box "thick" thick move box "thick thick thick" thick thick thick move box "invisible" invisible
Notice that “invisible” refers only to the object outline, not to the whole object. You therefore cancel the “invisible” attribute with “solid”, not “visible”:
boxwid = 0 boxht = 0 box "fully visible" box invisible color gray "outline invisible" box same solid "outline visible again" fit
The "color" and "fill" attributes change the foreground and background
colors of an object. Colors can be expressed using any of the 148 standard
CSS color names such as "Bisque" or "AliceBlue" or "LightGray". Color
names are not case sensitive, so "bisque", "BISQUE", and "Bisque" all mean
the same thing. Color names can also be expressed as an integer which is
interpreted as a 24-bit RGB value. It is convenient to express numeric
color values using hexadecimal notation. "Bisque" is the same as "0xffe4c4",
which is the same as "16770244".
box "Color: CadetBlue" "Fill: Bisque" fill Bisque color CadetBlue fit move oval "Color: White" "Fill: RoyalBlue" color White fill ROYALBLUE fit
Setting the "fill" to a negative number, to "None", or to "Off" makes the
background transparent. That is the default.
The default foreground color is black.
Filled Polygons
The "fill" attribute does not affect the rendering of lines unless the
route of the line is terminated by the "close" attribute. The "close"
keyword converts the line into a polygon:
line go 3cm heading 150 then 3cm west close \
/* ^^^^^ nota bene! */ \
fill 0x006000 color White "green" below "triangle" below
Polygons are not required to have a fill color. With the default fill of “none,”
you can use the "close"
keyword to convert a polygon into a line and leave the background transparent,
but using "fill color" together with "close" is a common idiom.
Text Annotations
Every object can have up to five lines of text annotation. Each annotation is a string literal attribute on the object definition. By default, the annotations are displayed around the center of the object, from top to bottom, in the order that they appear in the input script.
box "box containing" "three lines" "of text" fit move arrow "Labeled" "line" wid 200%
Text Attributes
The layout and font style of the annotations can be modified using keywords that appear after each string literal. The following modifiers are supported:
- above
- aligned
- below
- big
- bold
- center
- italic
- ljust
- rjust
- small
Position Text Above Or Below The Center Of The Object
The "above" and "below" keywords control the location of the
text above or below the center point of the object with which
the text is associated. If there is just one text on the object
and the "above" and "below" keywords are omitted, the text is
placed directly over the center of the object. This causes
the text to appear in the middle of lines:
line "on the line" wid 150%
So, if there is just a single text label on a line, you probably
want to include either the "above" or "below" keyword.
line "above" above; move; line "below" below
If there are two texts on the object, they straddle the center point
above and below, even without the use of the "above" and "below"
keywords:
line wid 300% "text without \"above\"" "text without \"below\""
The "above" and "below" attributes do not stack or accumulate. Each "above"
or "below" overrides any previous "above" or "below" for the same text.
If there are multiple texts and all are marked "above" or "below", then
all are placed above or below the center point, in order of appearance.
line width 200% "first above" above "second above" above move line same "first below" below "second below" below
Justify Text Left Or Right
As the "above" and "below" keywords control up and down positioning of
the text, so the "ljust" and "rjust" keywords control left and right
positioning.
For a line, the "ljust" means that the left side of the text is flush
against the center point of the line, and "rjust" means that the right
side of the text is flush against the center point of the line.
(In the following diagram, the red dot is at the center of the line.)
line wid 200% "ljust" ljust above "rjust" rjust below dot color red at previous.c
For a block object, "ljust" shifts the text to be left justified
against the left edge of the block (with a small margin) and
"rjust" puts the text against the right side of the object (with
the same margin).
box "ljust" ljust "longer line" ljust "even longer line" ljust fit move box "rjust" rjust "longer line" rjust "even longer line" rjust fit
The behavior of "ljust" and "rjust" for block objects in Pikchr differs
from legacy PIC.
In PIC, text is always justified around the center point, as in lines,
but this means there is no easy way to left justify multiple lines of
text within a "box" or "file", so the behavior was changed for
Pikchr.
Pikchr allows five separate text objects inside another object by combining
"ljust", "rjust", and the default text centering:
box wid 300% \
"above-ljust" above ljust \
"above-rjust" above rjust \
"centered" center \
"below-ljust" below ljust \
"below-rjust" below rjust
Text Attribute "center"
The "center" attribute cancels all prior "above", "below", "ljust", and
"rjust" attributes for the current text object.
Bold And Italic Font Styles
The "bold" and "italic" attributes cause the text object to use a bold or
italic font. Fonts can be both bold and italic at the same time:
box "bold" bold "italic" italic "bold-italic" bold italic fit
Aligned Text
The "aligned" attribute causes text associated with a straight line
to be rotated to align with that line:
arrow go 150% heading 30 "aligned" aligned above move to 1cm east of previous.end arrow go 150% heading 170 "aligned" aligned above move to 1cm east of previous.end arrow go 150% north "aligned" aligned above
To display rotated text not associated with a line, attach the
text to a line that is marked "invisible"
box ht 200% wid 50% line invis from previous.s to previous.n "rotated text" aligned
Note that the direction of aligned text is the same as the direction of the line itself, so if you draw a line from right to left, the aligned text will appear upside down:
circle "C1" fit circle "C0" at C1+(2.5cm,-0.3cm) fit arrow from C0 to C1 "aligned" aligned above chop
If you need aligned text on an arrow that goes from right to left,
and you do not want the text to be rendered upside-down, draw
the arrow from left to right and include the "<-" attribute
so that the arrowhead is at the beginning rather than at the end:
circle "C1" fit circle "C0" at C1+(2.5cm,-0.3cm) fit arrow from C1 to C0 "aligned" aligned above <- chop
Adjusting The Font Size
The "big" and "small" attributes cause the text to be a little larger
or a little smaller, respectively. Two "big" attributes cause the
text to be larger still, as do two "small" attributes. Text
size does not increase or decrease beyond two "big" or "small" keywords.
box "small small" small small "small" small \
"(normal)" italic \
"big" big "big big" big big ht 200%
A "big" keyword cancels any prior "small" keywords on the same text,
and a "small" keyword cancels any prior "big" keywords.
Text Is Positioned Around The Center Of The Object
The anchor point for text annotations is usually the center of the bounding box for the whole object. This is intuitive for block objects and straight lines. But for multi-segment lines, the text might not be near the line itself. For example, in the following four-segment arrow, the red box is the bounding box and the red dot shows the center of the bounding box. The text label is aligned relative to the center of the bounding box, which is not close to any part of the actual line.
arrow up 1.5cm right 1.5cm then down .5cm right 1cm then up .5cm right .3cm \ then down 2.5cm right 1cm "text" box color red thin thin width previous.wid height previous.ht \ with .c at previous.c dot at last arrow.c color red behind last arrow
If you need to position text beside one specific segment of a multi-segment
line, consider creating a separate "invis" line over top of that line
segment and attaching the text to the "invis" line instead. Here is the
same arrow as before, but with the text attached to a separate "invis" line
that overlays the second segment of the arrow:
arrow up 1.5cm right 1.5cm then down .5cm right 1cm then up .5cm right .3cm \ then down 2.5cm right 1cm box color red thin thin width previous.wid height previous.ht \ with .c at previous.c dot at last arrow.c color red behind last arrow line invis from 2nd vertex of last arrow to 3rd vertex of last arrow \ "text" below aligned
The anchor point for text is usually the center of the object, but in some cases, the anchor point might be fudged a little. This happens, for example for cylinder objects:
C1: cylinder "text in a" "cylinder" rad 120%
dot color red at C1.c
dot color blue at 0.75*C1.rad below C1.c
The red dot is on the center of the cylinder and the blue dot shows the anchor point for the text. The text is a little lower for cylinders because that looks better. With out this adjustment of the text center point, the cylinder text would look goofy:
C1: cylinder rad 120%
text "text in a" "cylinder" at C1.c
Containers
A "container" is a list of one or more objects contained within "[...]".
A container is a collection of one or more objects that looks like a single
object to the remainder of the script.
For example:
A: [
oval "Hello"
arrow
box "World" radius 4px
]
Border: box thin width A.width+0.5in height A.height+0.5in at A.center
The "A" container is composed of an oval, and arrow, and a box with rounded corners. But to the subsequent "Border" box, the "A" container appears to be a single object. The Border box can reference the overall width and height and the center point of the A container in order to size and position itself to enclose the container with a 0.25in border:
A: [
oval "Hello"
arrow
box "World" radius 4px
]
Border: box thin width A.width+0.5in height A.height+0.5in at A.center
A container is mostly useful for adding a border around a collection of objects, as shown above, or adding a caption to a diagram. The following diagram shows what a caption might look like. (Click to see the Pikchr source text.)
A: [
oval "Hello"
arrow
box "World" radius 4px
]
Caption: text "Diagram Caption" italic with .n at 0.1in below A.s
In legacy PIC, layout direction changes (the "up", "down", "left", and "right" commands) and variable definitions within a container only affect subsequent statements within the same container. Once the container closes, the prior direction and variable values are restored. Pikchr does not work this way. In Pikchr, layout direction changes and variable definitions that occur within a container continue to be in effect after the container.
Summary And Conclusion
Though based on the decades-old PIC language, Pikchr itself is a relatively new system. However it has already proven itself to be amazingly useful for helping to illustrate concepts in technical documentation written using Markdown.
This document has provided an overview of how Pikchr works. For more details and other perspectives, see the following resources: