circo(1)

1DOT(1)                      General Commands Manual                     DOT(1)
2
3
4

NAME

6       dot - filter for drawing directed graphs
7       neato - filter for drawing undirected graphs
8       twopi - filter for radial layouts of graphs
9       circo - filter for circular layout of graphs
10       fdp - filter for drawing undirected graphs
11

SYNOPSIS

13       dot  [-(G|N|E)name=value]  [-Tlang] [-l libfile] [-o outfile] [-v] [-V]
14       [files]
15       neato [-(G|N|E)name=value] [-Tlang] [-l libfile] [-n[1|2]] [-o outfile]
16       [-v] [-V] [files]
17       twopi [-(G|N|E)name=value] [-Tlang] [-l libfile] [-o outfile] [-v] [-V]
18       [files]
19       circo [-(G|N|E)name=value] [-Tlang] [-l libfile] [-o outfile] [-v] [-V]
20       [files]
21       fdp  [-(G|N|E)name=value]  [-Tlang] [-l libfile] [-o outfile] [-v] [-V]
22       [files]
23

DESCRIPTION

25       dot draws directed graphs.  It works well on DAGs and other graphs that
26       can  be  drawn  as  hierarchies.   It  reads attributed graph files and
27       writes drawings.  By default, the output format dot is the  input  file
28       with layout coordinates appended.
29
30       neato  draws  undirected graphs using ``spring'' models (see Kamada and
31       Kawai, Information Processing Letters 31:1, April 1989).   Input  files
32       must  be  formatted  in the dot attributed graph language.  By default,
33       the output  of  neato  is  the  input  graph  with  layout  coordinates
34       appended.
35
36       twopi  draws  graphs  using a radial layout (see G. Wills, Symposium on
37       Graph Drawing GD'97, September, 1997).  Basically, one node  is  chosen
38       as the center and put at the origin.  The remaining nodes are placed on
39       a sequence of concentric circles centered  about  the  origin,  each  a
40       fixed  radial  distance from the previous circle.  All nodes distance 1
41       from the center are placed on the first circle; all  nodes  distance  1
42       from a node on the first circle are placed on the second circle; and so
43       forth.
44
45       circo draws graphs using a circular layout (see Six and Tollis, GD  '99
46       and  ALENEX  '99, and Kaufmann and Wiese, GD '02.)  The tool identifies
47       biconnected components and draws the nodes of the component on  a  cir‐
48       cle.  The block-cutpoint tree is then laid out using a recursive radial
49       algorithm. Edge crossings within a circle are minimized by  placing  as
50       many  edges  on  the circle's perimeter as possible.  In particular, if
51       the component is outerplanar, the component will have a planar layout.
52
53       If a node belongs to multiple non-trivial biconnected  components,  the
54       layout puts the node in one of them. By default, this is the first non-
55       trivial component found in the search from the root component.
56
57       fdp draws undirected graphs using a ``spring'' model. It  relies  on  a
58       force-directed  approach in the spirit of Fruchterman and Reingold (cf.
59       Software-Practice & Experience 21(11), 1991, pp. 1129-1164).
60

OUTPUT FORMATS

62       Dot uses an extensible plugin mechanism for its output renderers, so to
63       see  what  output formats your installation of dot supports you can use
64       ``dot -Txxx'' (where xxx is an unlikely format) and check  the  warning
65       message.   Also, The plugin mechanism supports multiple implementations
66       of the output formats.  To see what variants are  available,  use,  for
67       example:  ``dot  -Tpng:''  and  to force a particular variant, use, for
68       example: ``dot -Tpng:gd''
69
70       Traditionally, dot supports the  following:  -Tps  (PostScript),  -Tsvg
71       -Tsvgz  (Structured  Vector  Graphics),  -Tfig  (XFIG  graphics), -Tmif
72       (FrameMaker graphics), -Thpgl (HP pen plotters),  and  -Tpcl  (Laserjet
73       printers),  -Tpng  -Tgif  (bitmap graphics), -Timap (imagemap files for
74       httpd servers for  each  node  or  edge  that  has  a  non-null  "href"
75       attribute.),  -Tcmapx (client-side imagemap for use in html and xhtml).
76       Additional less common or more special-purpose output  formats  can  be
77       found at http://www.graphviz.org/cvs/doc/info/output.html.)
78

GRAPH FILE LANGUAGE

80       Here  is a synopsis of the graph file language, traditionally using the
81       extension .dot, for graphs:
82
83       [strict] (graph|digraph) name { statement-list }
84       Is the top level graph. If the graph is strict then multiple edges  are
85       not  allowed  between  the  same  pairs  of nodes.  If it is a directed
86       graph, indicated by digraph, then the edgeop must be "->". If it is  an
87       undirected graph then the edgeop must be "--".  Statements may be:
88
89       name=val;
90       node [name=val];
91       edge [name=val];
92       Set  default graph, node, or edge attribute name to val.  Any subgraph,
93       node, or edge appearing after this inherits the new default attributes.
94
95       n0 [name0=val0,name1=val1,...]; Creates node n0 (if it does not already
96       exist) and sets its attributes according to the optional list.
97
98       n0 edgeop n1 edgeop ... edgeop nn [name0=val0,name1=val1,...];
99       Creates  edges  between nodes n0, n1, ..., nn and sets their attributes
100       according to the optional list.  Creates nodes as necessary.
101
102       [subgraph name] { statement-list }
103       Creates a subgraph.  Subgraphs may be used in place of n0, ...,  nn  in
104       the  above statements to create edges.  [subgraph name] is optional; if
105       missing, the subgraph is assigned an internal name.
106
107       Comments may be /*C-like*/ or //C++-like.
108
109
110       Attribute names and values are ordinary (C-style) strings.  The follow‐
111       ing sections describe attributes that control graph layout.
112
113

GRAPH ATTRIBUTES

115       size="x,y" sets bounding box of drawing in inches.
116
117       page="x,y" sets the PostScript pagination unit.
118
119       ratio=f  sets  the aspect ratio to f which may be a floating point num‐
120       ber, or one of the keywords fill, compress, or auto.
121
122       margin=f sets the page margin (included in the page size).
123
124       nodesep=f sets the minimum separation between nodes.
125
126       ranksep=f sets the minimum separation between ranks.
127
128       ordering=out constrains order of out-edges in a subgraph  according  to
129       their file sequence.
130
131       rankdir=LR|RL|BT requests a left-to-right, right-to-left, or bottom-to-
132       top, drawing.
133
134       pagedir=[TBLR][TBLR] sets the major and minor order of pagination.
135
136       rank=same (or min or max) in a subgraph constrains the rank  assignment
137       of  its nodes.   If a subgraph's name has the prefix cluster, its nodes
138       are drawn in a distinct rectangle  of  the  layout.   Clusters  may  be
139       nested.
140
141       rotate=90  sets landscape mode.  (orientation=land is backward compati‐
142       ble but obsolete.)
143
144       center=n a non-zero value centers the drawing on the page.
145
146       nslimit=f or mclimit=f adjusts the bound on the number of network  sim‐
147       plex   or  mincross  iterations  by  the  given  ratio.   For  example,
148       mclimit=2.0 runs twice as long.
149
150       layers="id:id:id:id" is a sequence of  layer  identifiers  for  overlay
151       diagrams.  The PostScript array variable layercolorseq sets the assign‐
152       ment of colors to layers. The least index is 1 and each element must be
153       a 3-element array to be interpreted as a color coordinate.
154
155       color=colorvalue sets foreground color (bgcolor for background).
156
157       href="url"  the  default  url for image map files; in PostScript files,
158       the base URL for all relative URLs, as recognized by Acrobat  Distiller
159       3.0 and up.
160
161       URL="url" ("URL" is a synonym for "href".)
162
163       stylesheet="file.css" includes a reference to a stylesheet in -Tsvg and
164       -Tsvgz outputs.  Ignored by other formats.
165
166
167       (neato-specific attributes)
168       start=val.  Requests random initial placement and seeds the random num‐
169       ber  generator.   If  val  is not an integer, the process ID or current
170       time is used as the seed.
171
172       epsilon=n.  Sets the cutoff for the solver.  The default is 0.1.
173
174       splines=boolean. Setting this to true  causes  edges  to  be  drawn  as
175       splines if nodes don't overlap. The default is false.
176
177
178       (twopi-specific attributes)
179       root=ctr.  This specifies the node to be used as the center of the lay‐
180       out. If not specified, twopi will randomly pick one of the  nodes  that
181       are furthest from a leaf node, where a leaf node is a node of degree 1.
182       If no leaf nodes exists, an arbitrary node is picked as center.
183
184       ranksep=val. Specifies  the  radial  distance  in  inches  between  the
185       sequence of rings. The default is 0.75.
186
187       overlap=mode. This specifies what twopi should do if any nodes overlap.
188       If mode is "false", the program uses Voronoi  diagrams  to  adjust  the
189       nodes  to  eliminate  overlaps.  If mode is "scale", the layout is uni‐
190       formly scaled up, preserving node sizes, until nodes no longer overlap.
191       The  latter  technique  removes  overlaps while preserving symmetry and
192       structure,  while  the  former  removes  overlaps  more  compactly  but
193       destroys symmetries.  If mode is "true" (the default), no repositioning
194       is done.
195
196       splines=true/false. If set to true, twopi will use  the  graphviz  path
197       planning library to draw edges as splines avoiding nodes.  If the value
198       is false, or some nodes overlap, edges are drawn as straight line  seg‐
199       ments connecting nodes.  This is also the default style.
200
201
202       (circo-specific attributes)
203       root=nodename.  Specifies  the  name  of  a  node occurring in the root
204       block. If the graph is disconnected, the root  node  attribute  can  be
205       used to specify additional root blocks.
206
207       mindist=value.  Sets  the  minimum separation between all nodes. If not
208       specified then circo uses a default value of 1.0.
209
210       splines=true/false. If set to true, circo will use  the  graphviz  path
211       planning library to draw edges as splines avoiding nodes.  If the value
212       is false, or some nodes overlap, edges are drawn as straight line  seg‐
213       ments connecting nodes.  This is also the default style.
214
215
216       (fdp-specific attributes)
217       K=val. Sets the default ideal node separation in the layout.
218
219       maxiter=val.  Sets  the maximum number of iterations used to layout the
220       graph.
221
222       start=val. Adjusts the random initial placement of nodes with no speci‐
223       fied position.  If val is is an integer, it is used as the seed for the
224       random number generator.  If val is not an integer,  a  random  system-
225       generated  integer,  such as the process ID or current time, is used as
226       the seed.
227
228       splines=val. If val is "true", edges are  drawn  as  splines  to  avoid
229       nodes. By default, edges are draw as line segments.
230

NODE ATTRIBUTES

232       height=d  or  width=d  sets  minimum  height  or  width.  Adding fixed‐
233       size=true forces these to be the actual size (text labels are ignored).
234
235       shape=record polygon epsf builtin_polygon
236       builtin_polygon is one of: plaintext ellipse oval circle  egg  triangle
237       box  diamond  trapezium parallelogram house hexagon octagon.  (Polygons
238       are defined or modified by  the  following  node  attributes:  regular,
239       peripheries,  sides,  orientation, distortion and skew.)  epsf uses the
240       node's shapefile attribute as the path name of an external EPSF file to
241       be automatically loaded for the node shape.
242
243       label=text  where  text  may include escaped newlines \n, \l, or \r for
244       center, left, and right justified lines.  The string '\N' value will be
245       replaced  by  the  node  name.  Record labels may contain recursive box
246       lists delimited by { | }.  Port identifiers in labels are  set  off  by
247       angle   brackets  <  >.   In  the  graph  file,  use  colon  (such  as,
248       node0:port28).
249
250       fontsize=n sets the label type size to n points.
251
252       fontname=name sets the label font family name.
253
254       color=colorvalue sets the outline color, and the default fill color  if
255       style=filled and fillcolor is not specified.
256
257       fillcolor=colorvalue  sets  the  fill  color when style=filled.  If not
258       specified, the fillcolor when style=filled defaults to be the  same  as
259       the outline color.
260
261       fontcolor=colorvalue sets the label text color.
262
263       A  colorvalue  may  be  "h,s,v"  (hue, saturation, brightness) floating
264       point numbers between 0 and 1, or an X11 color name such as white black
265       red  green  blue yellow magenta cyan or burlywood, or a "#rrggbb" (red,
266       green, blue, 2 hex characters each) value.
267
268       style=filled solid dashed dotted bold invis or any Postscript code.
269
270       layer=id or id:id or "all" sets the node's active  layers.   The  empty
271       string means no layers (invisible).
272
273       The following attributes apply only to polygon shape nodes:
274
275       regular=n  if n is non-zero then the polygon is made regular, i.e. sym‐
276       metric about the x and y axis,  otherwise  the  polygon  takes  on  the
277       aspect ratio of the label.  builtin_polygons that are not already regu‐
278       lar are made regular by  this  attribute.   builtin_polygons  that  are
279       already  regular  are  not affected (i.e.  they cannot be made asymmet‐
280       ric).
281
282       peripheries=n sets the number of periphery lines drawn around the poly‐
283       gon.    This   value  supersedes  the  number  of  periphery  lines  of
284       builtin_polygons.
285
286       sides=n sets the number of sides to the  polygon.  n<3  results  in  an
287       ellipse.  This attribute is ignored by builtin_polygons.
288
289       orientation=f  sets  the  orientation  of the first apex of the polygon
290       counterclockwise from the vertical, in degrees.  f may  be  a  floating
291       point  number.   The  orientation  of  labels  is  not affected by this
292       attribute.  This attribute is  added  to  the  initial  orientation  of
293       builtin_polygons.
294
295       distortion=f  sets the amount of broadening of the top and narrowing of
296       the bottom of the polygon  (relative  to  its  orientation).   Floating
297       point  values  between  -1  and  +1  are  suggested.  This attribute is
298       ignored by builtin_polygons.
299
300       skew=f sets the amount of right-displacement of the top  and  left-dis‐
301       placement  of  the bottom of the polygon (relative to its orientation).
302       Floating point values between -1 and +1 are suggested.  This  attribute
303       is ignored by builtin_polygons.
304
305       href="url"  sets  the  url for the node in imagemap, PostScript and SVG
306       files.  The substring '\N' is substituted in the same manner as for the
307       node label attribute.
308
309       URL="url" ("URL" is a synonym for "href".)
310
311       target="target"  is  a target string for client-side imagemaps and SVG,
312       effective when nodes have a URL.  The target string is used  to  deter‐
313       mine  which  window  of the browser is used for the URL.  Setting it to
314       "_graphviz" will open a new window if it doesn't already exist, or  re‐
315       use it if it does.  If the target string is empty, the default, then no
316       target attribute is included in the output.  The substring '\N' is sub‐
317       stituted in the same manner as for the node label attribute.
318
319       tooltip="tooltip"  is  a  tooltip  string for client-side imagemaps and
320       SVG, effective when nodes have a URL.  The tooltip string  defaults  to
321       be the same as the label string, but this attribute permits nodes with‐
322       out labels to still have tooltips thus permitting denser  graphs.   The
323       substring  '\N' is substituted in the same manner as for the node label
324       attribute.
325
326
327       (circo-specific attributes)
328       root=true/false. This specifies that the  block  containing  the  given
329       node be treated as the root of the spanning tree in the layout.
330
331
332       (fdp-specific attributes)
333       pin=val.  If  val  is "true", the node will remain at its initial posi‐
334       tion.
335
336

EDGE ATTRIBUTES

338       minlen=n where n is an integer factor that applies to the  edge  length
339       (ranks for normal edges, or minimum node separation for flat edges).
340
341       weight=n  where n is the integer cost of the edge.  Values greater than
342       1 tend to shorten the edge.  Weight 0 flat edges are ignored for order‐
343       ing nodes.
344
345       label=text  where  text  may include escaped newlines \n, \l, or \r for
346       centered, left, or right justified lines.  If  the  substring  '\T'  is
347       found  in  a  label  it will be replaced by the tail_node name.  If the
348       substring '\H' is found in a label it will be replaced by the head_node
349       name.   If  the  substring  '\E'  value  is found in a label it will be
350       replaced      by:      tail_node_name->head_node_name      or       by:
351       tail_node_name--head_node_name for undirected graphs.
352
353       fontsize=n sets the label type size to n points.
354
355       fontname=name sets the label font family name.
356
357       fontcolor=colorvalue sets the label text color.
358
359       style=solid dashed dotted bold invis
360
361       color=colorvalue sets the line color for edges.
362
363       color=colorvaluelist  a ':' separated list of colorvalue creates paral‐
364       lel edges, one edge for each color.
365
366       dir=forward back both none controls arrow direction.
367
368       tailclip,headclip=false disables endpoint shape clipping.
369
370       href="url" sets the url for the node in imagemap,  PostScript  and  SVG
371       files.  The substrings '\T', '\H', and '\E' are substituted in the same
372       manner as for the edge label attribute.
373
374       URL="url" ("URL" is a synonym for "href".)
375
376       target="target" is a target string for client-side imagemaps  and  SVG,
377       effective  when  edges  have a URL.  If the target string is empty, the
378       default, then no target attribute is included in the output.  The  sub‐
379       strings  '\T', '\H', and '\E' are substituted in the same manner as for
380       the edge label attribute.
381
382       tooltip="tooltip" is a tooltip string for client-side imagemaps  effec‐
383       tive when edges have a URL.  The tooltip string defaults to be the same
384       as the edge label string.  The substrings '\T', '\H', and '\E' are sub‐
385       stituted in the same manner as for the edge label attribute.
386
387       arrowhead,arrowtail=none, normal, inv, dot, odot, invdot, invodot, tee,
388       empty, invempty, open, halfopen, diamond, odiamond, box, obox, crow.
389
390       arrowsize                                 (norm_length=10,norm_width=5,
391       inv_length=6,inv_width=7,dot_radius=2)
392
393       headlabel,taillabel=string  for port labels.  labelfontcolor,labelfont‐
394       name,labelfontsize for head and  tail  labels.   The  substrings  '\T',
395       '\H', and '\E' are substituted in the same manner as for the edge label
396       attribute.
397
398       headhref="url" sets the url for the head port in  imagemap,  PostScript
399       and  SVG files.  The substrings '\T', '\H', and '\E' are substituted in
400       the same manner as for the edge label attribute.
401
402       headURL="url" ("headURL" is a synonym for "headhref".)
403
404       headtarget="headtarget" is a target string  for  client-side  imagemaps
405       and  SVG,  effective when edge heads have a URL.  The headtarget string
406       is used to determine which window of the browser is used for  the  URL.
407       If  the  headtarget  string  is  empty,  the  default,  then headtarget
408       defaults to the same value as target  for  the  edge.   The  substrings
409       '\T', '\H', and '\E' are substituted in the same manner as for the edge
410       label attribute.
411
412       headtooltip="tooltip" is a tooltip  string  for  client-side  imagemaps
413       effective  when  head ports have a URL.  The tooltip string defaults to
414       be the same as the headlabel string.  The substrings  '\T',  '\H',  and
415       '\E'  are  substituted  in  the  same  manner  as  for  the  edge label
416       attribute.
417
418       tailhref="url" sets the url for the tail port in  imagemap,  PostScript
419       and  SVG files.  The substrings '\T', '\H', and '\E' are substituted in
420       the same manner as for the edge label attribute.
421
422       tailURL="url" ("tailURL" is a synonym for "tailhref".)
423
424       tailtarget="tailtarget" is a target string  for  client-side  imagemaps
425       and  SVG,  effective when edge tails have a URL.  The tailtarget string
426       is used to determine which window of the browser is used for  the  URL.
427       If  the  tailtarget  string  is  empty,  the  default,  then tailtarget
428       defaults to the same value as target  for  the  edge.   The  substrings
429       '\T', '\H', and '\E' are substituted in the same manner as for the edge
430       label attribute.
431
432       tailtooltip="tooltip" is a tooltip  string  for  client-side  imagemaps
433       effective  when  tail ports have a URL.  The tooltip string defaults to
434       be the same as the taillabel string.  The substrings  '\T',  '\H',  and
435       '\E'  are  substituted  in  the  same  manner  as  for  the  edge label
436       attribute.
437
438       labeldistance and port_label_distance set distance; also labelangle (in
439       degrees CCW)
440
441       decorate draws line from edge to label.
442
443       samehead,sametail  aim  edges  having  the same value to the same port,
444       using the average landing point.
445
446       constraint=false causes an edge to be ignored for rank assignment.
447
448       layer=id or id:id or "all" sets the edgess active  layers.   The  empty
449       string means no layers (invisible).
450
451
452       (neato-specific attributes)
453       w=f  sets the weight (spring constant) of an edge to the given floating
454       point value.  The default is 1.0; greater values  make  the  edge  tend
455       more toward its optimal length.
456
457       len=f sets the optimal length of an edge.  The default is 1.0.
458
459       (fdp-specific attributes)
460       weight=f  sets the weight of an edge to the given floating point value.
461       The default is 1.0; greater values make the edge tend more  toward  its
462       optimal length.
463

COMMAND LINE OPTIONS

465       -G sets a default graph attribute.
466       -N sets a default node attribute.
467       -E  sets  a  default edge attribute.  Example: -Gsize="7,8" -Nshape=box
468       -Efontsize=8
469
470       -lfile loads custom PostScript library  files.   Usually  these  define
471       custom  shapes  or  styles.   If  -l  is  given by itself, the standard
472       library is omitted.
473
474       -Tlang sets the output language as described above.
475
476
477       -n[1|2] (no-op) If set, neato assumes nodes  have  already  been  posi‐
478       tioned  and  all  nodes  have a pos attribute giving the positions.  It
479       then performs an  optional  adjustment  to  remove  node-node  overlap,
480       depending on the value of the overlap attribute, computes the edge lay‐
481       outs, depending on the value of the splines attribute,  and  emits  the
482       graph  in  the  appropriate  format.  If num is supplied, the following
483       actions occur:
484           num = 1
485       Equivalent to -n.
486           num > 1
487       Use node positions as specified, with no adjustment to remove node-node
488       overlaps,  and  use  any  edge  layouts  already  specified  by the pos
489       attribute.  neato computes an edge layout for any edge  that  does  not
490       have  a  pos attribute.  As usual, edge layout is guided by the splines
491       attribute.
492
493       -v (verbose) prints delta energy every 100th iteration.
494
495       -V (version) prints version information and exits.
496
497       -? prints the usage and exits.
498

EXAMPLES

500       digraph test123 {
501               a -> b -> c;
502               a -> {x y};
503               b [shape=box];
504               c [label="hello\nworld",color=blue,fontsize=24,
505                    fontname="Palatino-Italic",fontcolor=red,style=filled];
506               a -> z [label="hi", weight=100];
507               x -> z [label="multi-line\nlabel"];
508               edge [style=dashed,color=red];
509               b -> x;
510               {rank=same; b x}
511       }
512
513       graph test123 {
514               a -- b -- c;
515               a -- {x y};
516               x -- c [w=10.0];
517               x -- y [w=5.0,len=3];
518       }
519

CAVEATS

521       Edge splines can overlap unintentionally.
522
523       Flat edge labels are slightly broken.   Intercluster  edge  labels  are
524       totally broken.
525
526       Because unconstrained optimization is employed, node boxes can possibly
527       overlap or touch unrelated edges.  All existing spring  embedders  seem
528       to have this limitation.
529
530       Apparently  reasonable attempts to pin nodes or adjust edge lengths and
531       weights can cause instability.
532

AUTHORS

534       Stephen C. North <north@research.att.com>
535       Emden R. Gansner <erg@research.att.com>
536       John C. Ellson <ellson@research.att.com>
537
538       The  bitmap   driver   (PNG,   GIF   etc)   is   by   Thomas   Boutell,
539       <http://www.boutell.com/gd>
540
541       The  Truetype font renderer is from the Freetype Project (David Turner,
542       Robert Wilhelm, and Werner Lemberg) (who can be contacted at  freetype-
543       devel@lists.lrz-muenchen.de).
544