Drawing graphs with dot
Emden Gansner and Eleftherios Koutsofios and Stephen North
January 26, 2006
Abstract
dot draws directed graphs as hierarchies. It runs as a command line pro-
gram, web visualization service, or with a compatible graphical interface.
Its features include well-tuned layout algorithms for placing nodes and edge
splines, edge labels, “record” shapes with “ports” for drawing data struc-
tures; cluster layouts; and an underlying file language for stream-oriented
graph tools. Below is a reduced module dependency graph of an SML-NJ
compiler that took 0.98 seconds of user time on a 1.4 Ghz AMD Athlon.
ContMap
FreeMap
Expand
CPSprint
Coder
BaseCoder
ErrorMsg
SparcInstr
GlobalFix
CPS
Hoist
SortedList Intset
CPSopt
Contract
Eta
Closure
Profile
List2
SparcAsCode SparcMCEmit
IEEEReal
SparcCM
CG
SparcMCode
ClosureCallee
Sort
SparcAsEmit
Spill
PrintUtil
CPSsize
Prim
SparcMC
CPScomp
Access
RealConst
SparcAC
Convert
CoreInfo Lambda
CPSgen
Strs
Signs
AbstractFct
ApplyFunctor
Overload
PrintType
Unify
Typecheck
PrintAbsyn
Stream
MLLexFun
Vector
Ascii
LrParserJoinWithArg
Join
MLLrValsFun
CoreLang
NewParse
Index
Misc
TyvarSet
Absyn
Types
Normalize
Modules
ConRep
Instantiate
LrTable Backpatch
PrimTypes PolyCont
Initial
Assembly Math Unsafe
Loader
CInterface CleanUp
CoreFunc
InLine
Fastlib
CoreDummy
Overloads MakeMos
Stamps
IntmapPersStamps
Pathnames
Symbol
Bigint
Dynamic
IntStrMap
ArrayExt
UnionfindSiblings
StrgHash
Env
BasicTypes
Tuples
ModuleUtil
EqTypes
Fixity
TypesUtil
Equal
Variables
BareAbsyn PrintBasics
PrintVal
PrintDec
SigMatch
IntSparcD
IntShare BatchRealDebug BogusDebug
UnixPaths Interact ModuleComp
Importer
IntSparcIntNullD
Linkage
Prof
IntNull
Interp
ProcessFile
FreeLvar LambdaOpt
Translate
OptReorder
CompSparc
MCopt
MCprint
Nonrec MC
InlineOps
Unboxed
1
dot User’s Manual, January 26, 2006 2
1 Basic Graph Drawing
dot draws directed graphs. It reads attributed graph text files and writes drawings,
either as graph files or in a graphics format such as GIF, PNG, SVG or PostScript
(which can be converted to PDF).
dot draws a graph in four main phases. Knowing this helps you to understand
what kind of layouts dot makes and how you can control them. The layout proce-
dure used by dot relies on the graph being acyclic. Thus, the first step is to break
any cycles which occur in the input graph by reversing the internal direction of
certain cyclic edges. The next step assigns nodes to discrete ranks or levels. In a
top-to-bottom drawing, ranks determine Y coordinates. Edges that span more than
one rank are broken into chains of “virtual” nodes and unit-length edges. The third
step orders nodes within ranks to avoid crossings. The fourth step sets X coordi-
nates of nodes to keep edges short, and the final step routes edge splines. This is
the same general approach as most hierarchical graph drawing programs, based on
the work of Warfield [War77], Carpano [Car80] and Sugiyama [STT81]. We refer
the reader to [GKNV93] for a thorough explanation of dot’s algorithms.
dot accepts input in the DOT language (cf. Appendix A). This language de-
scribes three kinds of objects: graphs, nodes, and edges. The main (outermost)
graph can be directed (digraph) or undirected graph. Because dot makes lay-
outs of directed graphs, all the following examples use digraph. (A separate
layout utility, neato, draws undirected graphs [Nor92].) Within a main graph, a
subgraph defines a subset of nodes and edges.
Figure 1 is an example graph in the DOT language. Line 1 gives the graph
name and type. The lines that follow create nodes, edges, or subgraphs, and set
attributes. Names of all these objects may be C identifiers, numbers, or quoted C
strings. Quotes protect punctuation and white space.
A node is created when its name first appears in the file. An edge is created
when nodes are joined by the edge operator ->. In the example, line 2 makes
edges from main to parse, and from parse to execute. Running dot on this file (call
it graph1.dot)
$ dot -Tps graph1.dot -o graph1.ps
yields the drawing of Figure 2. The command line option -Tps selects PostScript
(EPSF) output. graph1.ps may be printed, displayed by a PostScript viewer, or
embedded in another document.
It is often useful to adjust the representation or placement of nodes and edges
in the layout. This is done by setting attributes of nodes, edges, or subgraphs in
the input file. Attributes are name-value pairs of character strings. Figures 3 and 4
illustrate some layout attributes. In the listing of Figure 3, line 2 sets the graph’s
dot User’s Manual, January 26, 2006 3
1: digraph G {
2: main -> parse -> execute;
3: main -> init;
4: main -> cleanup;
5: execute -> make_string;
6: execute -> printf
7: init -> make_string;
8: main -> printf;
9: execute -> compare;
10: }
Figure 1: Small graph
main
parse
init
cleanup
printf
execute
make_string compare
Figure 2: Drawing of small graph
dot User’s Manual, January 26, 2006 4
size to 4,4 (in inches). This attribute controls the size of the drawing; if the
drawing is too large, it is scaled as necessary to fit.
Node or edge attributes are set off in square brackets. In line 3, the node main
is assigned shape box. The edge in line 4 is straightened by increasing its weight
(the default is 1). The edge in line 6 is drawn as a dotted line. Line 8 makes edges
from execute to make string and printf. In line 10 the default edge color
is set to red. This affects any edges created after this point in the file. Line 11
makes a bold edge labeled 100 times. In line 12, node make_string is given
a multi-line label. Line 13 changes the default node to be a box filled with a shade
of blue. The node compare inherits these values.
2 Drawing Attributes
The complete list of attributes that affect graph drawing is summarized in Tables 1,
2 and 3.
2.1 Node Shapes
Nodes are drawn, by default, with shape=ellipse, width=.75, height=.5
and labeled by the node name. Other common shapes include box, circle,
record and plaintext. A complete list of node shapes is given in Appendix E.
The node shape plaintext is of particularly interest in that it draws a node with-
out any outline, an important convention in some kinds of diagrams. In cases where
the graph structure is of main concern, and especially when the graph is moderately
large, the point shape reduces nodes to display minimal content. When drawn, a
node’s actual size is the greater of the requested size and the area needed for its text
label, unless fixedsize=true, in which case the width and height values
are enforced.
Node shapes fall into two broad categories: polygon-based and record-based.1
All node shapes except record and Mrecord are considered polygonal, and
are modeled by the number of sides (ellipses and circles being special cases), and
a few other geometric properties. Some of these properties can be specified in
a graph. If regular=true, the node is forced to be regular. The parameter
peripheries sets the number of boundary curves drawn. For example, a dou-
blecircle has peripheries=2. The orientation attribute specifies a clock-
wise rotation of the polygon, measured in degrees.
1There is a way to implement custom node shapes, using shape=epsf and the shapefile
attribute, and relying on PostScript output. The details are beyond the scope of this user’s guide.
Please contact the authors for further information.
dot User’s Manual, January 26, 2006 5
1: digraph G {
2: size ="4,4";
3: main [shape=box]; /* this is a comment */
4: main -> parse [weight=8];
5: parse -> execute;
6: main -> init [style=dotted];
7: main -> cleanup;
8: execute -> { make_string; printf}
9: init -> make_string;
10: edge [color=red]; // so is this
11: main -> printf [style=bold,label="100 times"];
12: make_string [label="make a\nstring"];
13: node [shape=box,style=filled,color=".7 .3 1.0"];
14: execute -> compare;
15: }
Figure 3: Fancy graph
main
parse
init
cleanup
printf
100 times
execute
make a
stringcompare
Figure 4: Drawing of fancy graph
dot User’s Manual, January 26, 2006 6
The shape polygon exposes all the polygonal parameters, and is useful for
creating many shapes that are not predefined. In addition to the parameters regular,
peripheries and orientation, mentioned above, polygons are parameter-
ized by number of sides sides, skew and distortion. skew is a floating
point number (usually between −1.0 and 1.0) that distorts the shape by slanting
it from top-to-bottom, with positive values moving the top of the polygon to the
right. Thus, skew can be used to turn a box into a parallelogram. distortion
shrinks the polygon from top-to-bottom, with negative values causing the bottom
to be larger than the top. distortion turns a box into a trapezoid. A variety of
these polygonal attributes are illustrated in Figures 6 and 5.
Record-based nodes form the other class of node shapes. These include the
shapes record and Mrecord. The two are identical except that the latter has
rounded corners. These nodes represent recursive lists of fields, which are drawn
as alternating horizontal and vertical rows of boxes. The recursive structure is
determined by the node’s label, which has the following schema:
rlabel → field ( ’|’ field )*
field → boxLabel | ’’ rlabel ’’
boxLabel → [ ’<’ string ’>’ ] [ string ]
Literal braces, vertical bars and angle brackets must be escaped. Spaces are
interpreted as separators between tokens, so they must be escaped if they are to
appear literally in the text. The first string in a boxLabel gives a name to the field,
and serves as a port name for the box (cf. Section 3.1). The second string is used
as a label for the field; it may contain the same escape sequences as multi-line
labels (cf. Section 2.2. The example of Figures 7 and 8 illustrates the use and some
properties of records.
2.2 Labels
As mentioned above, the default node label is its name. Edges are unlabeled by
default. Node and edge labels can be set explicitly using the label attribute as
shown in Figure 4.
Though it may be convenient to label nodes by name, at other times labels
must be set explicitly. For example, in drawing a file directory tree, one might have
several directories named src, but each one must have a unique node identifier.
The inode number or full path name are suitable unique identifiers. Then the label
of each node can be set to the file name within its directory.
dot User’s Manual, January 26, 2006 7
1: digraph G {
2: a -> b -> c;
3: b -> d;
4: a [shape=polygon,sides=5,peripheries=3,color=lightblue,style=filled];
5: c [shape=polygon,sides=4,skew=.4,label="hello world"]
6: d [shape=invtriangle];
7: e [shape=polygon,sides=4,distortion=.7];
8: }
Figure 5: Graph with polygonal shapes
a
b
hello world d
e
Figure 6: Drawing of polygonal node shapes
1: digraph structs {
2: node [shape=record];
3: struct1 [shape=record,label=" left| mid\ dle| right"];
4: struct2 [shape=record,label=" one| two"];
5: struct3 [shape=record,label="hello\nworld |{ b |{c| d|e}| f}| g | h"];
6: struct1 -> struct2;
7: struct1 -> struct3;
8: }
Figure 7: Records with nested fields
zp
高亮
zp
文本框
默认形状是椭圆
dot User’s Manual, January 26, 2006 8
Multi-line labels can be created by using the escape sequences \n, \l, \r to
terminate lines that are centered, or left or right justified.2
Graphs and cluster subgraphs may also have labels. Graph labels appear, by
default, centered below the graph. Setting labelloc=t centers the label above
the graph. Cluster labels appear within the enclosing rectangle, in the upper left
corner. The value labelloc=b moves the label to the bottom of the rectangle.
The setting labeljust=r moves the label to the right.
The default font is 14-point Times-Roman, in black. Other font families,
sizes and colors may be selected using the attributes fontname, fontsize and
fontcolor. Font names should be compatible with the target interpreter. It is
best to use only the standard font families Times, Helvetica, Courier or Symbol
as these are guaranteed to work with any target graphics language. For example,
Times-Italic, Times-Bold, and Courier are portable; AvanteGarde-
DemiOblique isn’t.
For bitmap output, such as GIF or JPG, dot relies on having these fonts avail-
able during layout. Most precompiled installations of Graphviz use the fontconfig
library for matching font names to available fontfiles. fontconfig comes with a
set of utilities for showing matches and installing fonts. Please refer to the font-
config documentation, or the external Graphviz FontFAQ or for further details. If
Graphviz is built without fontconfig (which usually means you compiled it from
source code on your own), the fontpath attribute can specify a list of directo-
ries3 which should be searched for the font files. If this is not set, dot will use the
DOTFONTPATH environment variable or, if this is not set, the GDFONTPATH
environment variable. If none of these is set, dot uses a built-in list.
Edge labels are positioned near the center of the edge. Usually, care is taken to
prevent the edge label from overlapping edges and nodes. It can still be difficult,
in a complex graph, to be certain which edge a label belongs to. If the decorate
attribute is set to true, a line is drawn connecting the label to its edge. Sometimes
avoiding collisions among edge labels and edges forces the drawing to be bigger
than desired. If labelfloat=true, dot does not try to prevent such overlaps,
allowing a more compact drawing.
An edge can also specify additional labels, using headlabel and taillabel,
which are be placed near the ends of the edge. The characteristics of these la-
bels are specified using the attributes labelfontname, labelfontsize and
labelfontcolor. These labels are placed near the intersection of the edge and
the node and, as such, may interfere with them. To tune a drawing, the user can set
2The escape sequence \N is an internal symbol for node names.
3For Unix-based systems, this is a concatenated list of pathnames, separated by colons. For
Windows-based systems, the pathnames are separated by semi-colons.
dot User’s Manual, January 26, 2006 9
the labelangle and labeldistance attributes. The former sets the angle,
in degrees, which the label is rotated from the angle the edge makes incident with
the node. The latter sets a multiplicative scaling factor to adjust the distance that
the label is from the node.
2.3 Graphics Styles
Nodes and edges can specify a color attribute, with black the default. This is the
color used to draw the node’s shape or the edge. A color value can be a hue-
saturation-brightness triple (three floating point numbers between 0 and 1, sepa-
rated by commas); one of the colors names listed in Appendix G (borrowed from
some version of the X window system); or a red-green-blue (RGB) triple4 (three
hexadecimal number between 00 and FF, preceded by the character ’#’). Thus, the
values "orchid", "0.8396,0.4862,0.8549" and "#DA70D6" are three
ways to specify the same color. The numerical forms are convenient for scripts or
tools that automatically generate colors. Color name lookup is case-insensitive and
ignores non-alphanumeric characters, so warmgrey and Warm_Grey are equiv-
alent.
We can offer a few hints regarding use of color in graph drawings. First, avoid
using too many bright colors. A “rainbow effect” is confusing. It is better to
choose a narrower range of colors, or to vary saturation along with hue. Sec-
ond, when nodes are filled with dark or very saturated colors, labels seem to be
more readable with fontcolor=white and fontname=Helvetica. (We
also have PostScript functions for dot that create outline fonts from plain fonts.)
Third, in certain output formats, you can define your own color space. For exam-
ple, if using PostScript for output, you can redefine nodecolor, edgecolor,
or graphcolor in a library file. Thus, to use RGB colors, place the following
line in a file lib.ps.
/nodecolor {setrgbcolor} bind def
Use the -l command line option to load this file.
dot -Tps -l lib.ps file.dot -o file.ps
The style attribute controls miscellaneous graphics features of nodes and
edges. This attribute is a comma-separated list of primitives with optional argu-
ment lists. The predefined primitives include solid, dashed, dotted, bold
and invis. The first four control line drawing in node boundaries and edges
4A fourth form, RGBA, is also supported, which has the same format as RGB with an additional
fourth hexadecimal number specifying alpha channel or transparency information.
dot User’s Manual, January 26, 2006 10
Name Default Values
color black node shape color
comment any string (format-dependent)
distortion 0.0 node distortion for shape=polygon
fillcolor lightgrey/black node fill color
fixedsize false label text has no affect on node size
fontcolor black type face color
fontname Times-Roman font family
fontsize 14 point size of label
group name of node’s group
height .5 height in inches
label node name any string
layer overlay range all, id or id:id
orientation 0.0 node rotation angle
peripheries shape-dependent number of node boundaries
regular false force polygon to be regular
shape ellipse node shape; see Section 2.1 and Appendix E
shapefile external EPSF or SVG custom shape file
sides 4 number of sides for shape=polygon
skew 0.0 skewing of node for shape=polygon
style graphics options, e.g. bold, dotted,
filled; cf. Section 2.3
URL URL associated with node (format-dependent)
width .75 width in inches
z 0.0 z coordinate for VRML output
Table 1: Node attributes
dot User’s Manual, January 26, 2006 11
Name Default Values
arrowhead normal style of arrowhead at head end
arrowsize 1.0 scaling factor for arrowheads
arrowtail normal style of arrowhead at tail end
color black edge stroke color
comment any string (format-dependent)
constraint true use edge to affect node ranking
decorate if set, draws a line connecting labels with their edges
dir forward forward, back, both, or none
fontcolor black type face color
fontname Times-Roman font family
fontsize 14 point size of label
headlabel label placed near head of edge
headport n,ne,e,se,s,sw,w,nw
headURL URL attached to head label if output format is ismap
label edge label
labelangle -25.0 angle in degrees which head or tail label is rotated off edge
labeldistance 1.0 scaling factor for distance of head or tail label from node
labelfloat false lessen constraints on edge label placement
labelfontcolor black type face color for head and tail labels
labelfontname Times-Roman font family for head and tail labels
labelfontsize 14 point size for head and tail labels
layer overlay range all, id or id:id
lhead name of cluster to use as head of edge
ltail name of cluster to use as tail of edge
minlen 1 minimum rank distance between head and tail
samehead tag for head node; edge heads with the same tag are
merged onto the same port
sametail tag for tail node; edge tails with the same tag are merged
onto the same port
style graphics options, e.g. bold, dotted, filled; cf.
Section 2.3
taillabel label placed near tail of edge
tailport n,ne,e,se,s,sw,w,nw
tailURL URL attached to tail label if output format is ismap
weight 1 integer cost of stretching an edge
Table 2: Edge attributes
dot User’s Manual, January 26, 2006 12
Name Default Values
bgcolor background color for drawing, plus initial fill color
center false center drawing on page
clusterrank local may be global or none
color black for clusters, outline color, and fill color if fillcolor not defined
comment any string (format-dependent)
compound false allow edges between clusters
concentrate false enables edge concentrators
fillcolor black cluster fill color
fontcolor black type face color
fontname Times-Roman font family
fontpath list of directories to search for fonts
fontsize 14 point s