Daniel@0:
Daniel@0: Daniel@0: Note: Daniel@0: This is not a tutorial; to understand the following, you should Daniel@0: know how to use the basic features of the tools and Daniel@0: languages involved. Please see the Daniel@0: Daniel@0: user guides and documentation for further information or the Daniel@0: resources page Daniel@0: for a partial list of compatible tools and packages. Daniel@0: Daniel@0:
Daniel@0: See Daniel@0: Graph Attributes. There is also information on Daniel@0: Daniel@0: command-line usage and Daniel@0: Daniel@0: output formats. Daniel@0:
Daniel@0: Daniel@0: Daniel@0: Q2. Where can I discuss Graphviz? Daniel@0: Daniel@0:
Daniel@0: We run a mailing list. Daniel@0:
Daniel@0: To subscribe or unsubscribe, visit the Daniel@0: graphviz-interest mailman control page. See also the general Daniel@0: Daniel@0: instructions for mailman. Daniel@0:
Daniel@0: You can also see the Daniel@0: Daniel@0: archive. Daniel@0:
Daniel@0: You may wish to use a Yahoo or Hotmail account if you're concerned Daniel@0: about spam. We also run anti-spam filters, and rewrite @ Daniel@0: as at to keep verbatim addresses out of the archive. Daniel@0:
Daniel@0: Please, please, please, do not torment the mailing list with beginner's Daniel@0: questions. First, check this FAQ and the Daniel@0: Daniel@0: message archive carefully. Daniel@0: If you are desperate, or better yet, if you have constructive advice, Daniel@0: please send a message to the graphviz-devel mailing list. Daniel@0:
Daniel@0: Also, if a program crashes or you get an abort or something strange occurs Daniel@0: and you are fairly comfortable using the tools: Daniel@0:
Daniel@0: Daniel@0: Q3. I'm trying to make a layout larger. How? Daniel@0: Daniel@0:
Daniel@0: There are various ways to increase the size of a layout. In doing this, Daniel@0: one has to decide if the sizes of the nodes and text should be Daniel@0: increased as well. Daniel@0:
Daniel@0: One approach is to adjust individual Daniel@0: parameters such as fontsize, nodesep and ranksep. Daniel@0: For example, Daniel@0:
Daniel@0: digraph G {
Daniel@0: graph [fontsize=24];
Daniel@0: edge [fontsize=24];
Daniel@0: node [fontsize=24];
Daniel@0: ranksep = 1.5;
Daniel@0: nodesep = .25;
Daniel@0: edge [style="setlinewidth(3)"];
Daniel@0: a -> b -> c;
Daniel@0: }
Daniel@0:
Daniel@0: If you do this, make sure you are not fighting a conflicting graph
Daniel@0: size setting, like size="6,6", which will then scale
Daniel@0: everything back down.
Daniel@0: Daniel@0: If you are using fdp or neato, increasing the edge len will tend to Daniel@0: expand the layout. Daniel@0:
Daniel@0: graph G {
Daniel@0: edge [len=3]
Daniel@0: a -- { b c d }
Daniel@0: }
Daniel@0:
Daniel@0: For twopi and circo, there are other parameters such as
Daniel@0: ranksep which can be used. See the
Daniel@0:
Daniel@0: graph attributes.
Daniel@0: Daniel@0: You can also use the ratio attribute. If you set the size Daniel@0: attribute to the desired drawing size, and then set ratio=fill, node Daniel@0: positions are scaled separately in x and y until the drawing fills the Daniel@0: specified size. Note that node sizes stay the same. If, instead, Daniel@0: you set ratio=expand, the layout is uniformly scaled up in x and y Daniel@0: until at least one dimension fits size. Daniel@0:
Daniel@0: If you specify the size attribute but end it with an exclamation Daniel@0: mark (!), the final drawing will be scaled up uniformly in x and y Daniel@0: until at least one dimension fits size. Note that everything is Daniel@0: scaled up, including text and node sizes. Daniel@0:
Daniel@0: If you're using Postscript, you can just scale up the output by Daniel@0: manually adding a command such as 2 2 scale where the Daniel@0: Postscript environment is set up. Make sure to adjust the Daniel@0: BoundingBox too if your tools look at this header. Daniel@0:
Daniel@0: Daniel@0: Q4. How can I join or merge certain edge routes in dot? Daniel@0: Daniel@0:
Daniel@0: You can try running dot -Gconcentrate=true or you can Daniel@0: introduce your own virtual nodes drawn as tiny circles where Daniel@0: you want to split or join edges: Daniel@0: Daniel@0:
Daniel@0: digraph G {
Daniel@0: yourvirtualnode [shape=circle,width=.01,height=.01,label=""];
Daniel@0: a -> yourvirtualnode [arrowhead=none]
Daniel@0: yourvirtualnode -> {b;c}
Daniel@0: }
Daniel@0:
Daniel@0:
Daniel@0: Daniel@0: Daniel@0: Q. How can I generate graph layouts in PDF? Daniel@0: Daniel@0:
Daniel@0: Recent versions of graphviz with the CairoPango based drivers Daniel@0: can generate PDF directly with the -Tpdf command line option. Daniel@0: This this first. Daniel@0:
Daniel@0: Otherwise, create Postscript output, then use an external converter from
Daniel@0: Postscript to PDF.
Daniel@0: For example,
Daniel@0: dot -Tps | epsf2pdf -o file.pdf
Daniel@0: Note that URL tags are respected, to allow clickable PDF objects.
Daniel@0:
Daniel@0: If your intention is to use the figure as PDF in some document preparation Daniel@0: system, such as pdflatex, it is very important to use -Tps2 rather than Daniel@0: -Tps. In general, if you really want PDF output, that is, you would like Daniel@0: to have a -Tpdf flag, use -Tps2 before converting to PDF. Daniel@0:
Daniel@0: In the diagram below, the shaded nodes will contain bad output.
Daniel@0:
Daniel@0:
Daniel@0: Daniel@0: Q. How can I make duplicate nodes? Daniel@0: Daniel@0:
Daniel@0: Make unique nodes with duplicate labels. Daniel@0:
Daniel@0: digraph G {
Daniel@0: node001 [label = "A"];
Daniel@0: node002 [label = "A"];
Daniel@0: node001 -> node002;
Daniel@0: }
Daniel@0:
Daniel@0: Daniel@0: Daniel@0: Q. How can I set a graph or cluster label without its propagating to all sub-clusters? Daniel@0: Daniel@0:
Daniel@0: Set the label at the end of the graph (before the closing brace), after all Daniel@0: its contents have been defined. (We admit it seems desirable to define some Daniel@0: special syntax for non-inherited attribute settings.) Daniel@0:
Daniel@0: Daniel@0: Q5. How can I draw multiple parallel edges in neato? Daniel@0: Daniel@0:
Daniel@0: This is possible when the splines attribute is false, which Daniel@0: is the default. When splines=true, we have no good answer but Daniel@0: we are working on it. One trick which is sometimes sufficient is to Daniel@0: specify multiple colors for the edge. This will a produce set of tightly Daniel@0: parallel splines, each in its specified color. Read about the Daniel@0: color Daniel@0: attribute for more information. Daniel@0: Daniel@0:
Daniel@0: This only works in Graphviz version 1.7 and higher. Daniel@0: To make edges between clusters, first set the Daniel@0: graph attribute compound=true. Daniel@0: Then, you can specify a cluster by name as Daniel@0: a logical head or tail to an edge. This will Daniel@0: cause the edge joining the two nodes to be Daniel@0: clipped to the exterior of the box around the Daniel@0: given cluster. Daniel@0:
Daniel@0: For example, Daniel@0: Daniel@0:
Daniel@0: digraph G {
Daniel@0: compound=true;
Daniel@0: nodesep=1.0;
Daniel@0: subgraph cluster_A {
Daniel@0: a -> b;
Daniel@0: a -> c;
Daniel@0: }
Daniel@0: subgraph cluster_B {
Daniel@0: d -> e;
Daniel@0: f -> e;
Daniel@0: }
Daniel@0: a -> e [ ltail=cluster_A,
Daniel@0: lhead=cluster_B ];
Daniel@0: }
Daniel@0:
Daniel@0:
Daniel@0: has an edge going from cluster_A to
Daniel@0: cluster_B. If, instead, you say
Daniel@0:
Daniel@0: Daniel@0: a -> e [ltail=cluster_A]; Daniel@0:Daniel@0: Daniel@0: this gives you an edge from cluster_A to node Daniel@0: e. Or you could just specify Daniel@0: an lhead attribute. Daniel@0: Daniel@0: The program warns if a cluster specified as a Daniel@0: logical node is not defined. Daniel@0: Also, if a cluster is specified as a logical Daniel@0: head for an edge, the real Daniel@0: head must be contained in the cluster, and Daniel@0: the real tail must not be. Daniel@0: A similar check is done for logical tails. In Daniel@0: these cases, the edge Daniel@0: is drawn between the real nodes as usual. Daniel@0:
Daniel@0: Daniel@0: Q6. Clusters are hard to see. Daniel@0: Daniel@0:
Daniel@0: Set bgcolor=grey Daniel@0: (or some other color) Daniel@0: in the cluster. Daniel@0:
Daniel@0: Daniel@0: Q7. How can I symmetrize (balance) tree layouts? Daniel@0: Daniel@0:
Daniel@0: When a tree node has an even number of children, it isn't necessarily Daniel@0: centered above the two middle ones. If you know the order of the children, Daniel@0: a simple hack is to introduce new, invisible middle nodes to re-balance Daniel@0: the layout. The connecting edges should also be invisible. For example: Daniel@0:
Daniel@0: digraph G {
Daniel@0: a -> b0;
Daniel@0: xb [label="",width=.1,style=invis]
Daniel@0: a -> xb [style=invis];
Daniel@0: a -> b1;
Daniel@0: {rank=same b0 -> xb -> b1 [style=invis]}
Daniel@0: b0 -> c0;
Daniel@0: xc [label="",width=.1,style=invis]
Daniel@0: b0 -> xc [style=invis];
Daniel@0: b0 -> c1;
Daniel@0: {rank=same c0 -> xc -> c1 [style=invis]}
Daniel@0: }
Daniel@0:
Daniel@0: This trick really ought to be build into our solver (and made
Daniel@0: independent of the order of the children, and available for
Daniel@0: layouts other than trees, too).
Daniel@0:
Daniel@0: Daniel@0: The easiest thing may be to make the layout in Postscript (option -Tps), Daniel@0: then run through Ghostview with Daniel@0: antialiasing enabled. The important command line options are Daniel@0: -dTextAlphaBits=4 -dGraphicsAlphaBits=4 Daniel@0: (4 is the highest level of antialiasing allowed - see the Daniel@0: Ghostview documentation). Daniel@0: The full command line to render a raster could be something like: Daniel@0:
Daniel@0: gs -q -dNOPAUSE -dBATCH -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -sDEVICE=png16m -sOutputFile=file.png file.ps Daniel@0:Daniel@0:
Daniel@0: On Mac OS X, the pixelglow port Daniel@0: uses Apple's Quartz renderer, which enables antialiasing. It also provides a beautiful document container for its user interface. (One downside is Daniel@0: that you can't run Pixelglow Graphviz as a web server or other background Daniel@0: process if your Mac has 3D graphics, because Quartz wants to get this resource Daniel@0: to accelerate rendering. Another problem is that as of this writing, Daniel@0: Pixelglow Graphviz hasn't been updated in a long time, maybe mid 2004.) Daniel@0:
Daniel@0: On the Linux bleeding edge, Graphviz has an optional plugin to use Daniel@0: the cairo back end, Daniel@0: which has antialiased, path-based graphics. If you want this, Daniel@0: you must install cairo, which is not part of Graphviz. Cairo is Daniel@0: available in recent versions of Fedora linux, or it can be built Daniel@0: from source. Daniel@0:
Daniel@0: Daniel@0: Q9. I can only get 11x17 output. Daniel@0: Daniel@0:
Daniel@0: It's not us! It's probably your printer setup. If you don't Daniel@0: believe this, run dot -Tps and look at the Daniel@0: BoundingBox header. The coords are in 1/72ths of an inch. Daniel@0: Daniel@0:
Daniel@0: Daniel@0: Q10. How do I create special symbols and accents in labels? Daniel@0: Daniel@0:
Daniel@0: The following solution only works with the Daniel@0: raster drivers that load Truetype or Type1 Daniel@0: fonts! (That means, -Tgif, -Tpng, -Tjpeg, and possibly Daniel@0: -Tbmp or -Txbm if enabled). Daniel@0: Daniel@0: Use UTF8 coding, e.g. ¥ for the Yen currency symbol ¥. Daniel@0: Example: Daniel@0: Daniel@0:
Daniel@0: graph G {
Daniel@0: yen [label="¥"]
Daniel@0: }
Daniel@0:
Daniel@0: Daniel@0: You can look up other examples in this handy Daniel@0: Daniel@0: character set reference. Daniel@0:
Daniel@0: Daniel@0: Q. More generally, how do I use non-ASCII character sets? Daniel@0: Daniel@0:
Daniel@0: The following applies to Graphviz 2.8 and later. (In older versions Daniel@0: of Graphviz, you can sometimes get away with simply putting Daniel@0: Latin-1 or other UTF-8 characters in the input stream, but the Daniel@0: results are not always correct.) Daniel@0:
Daniel@0: Input: the general idea is to find the Daniel@0: Unicode Daniel@0: value for the glyph you want, and enter it within a text Daniel@0: string "...." or HTML-like label <...>. Daniel@0:
Daniel@0: For example, the mathematical
Daniel@0: We also accept the HTML symbolic names for Latin-1 characters as suggested Daniel@0: above. Daniel@0: (Go to http://www.research.att.com/~john/docs/html/index.htm and click Daniel@0: on Special symbols and Entities) For example, the cent sign (unicode Daniel@0: and Latin-1 value decimal 162 can be inserted as Daniel@0:
Daniel@0: ¢ Daniel@0:Daniel@0:
Daniel@0: Note that the graph file must always be a plain text document Daniel@0: not a Word or other rich format file. Any characters not enclosed in "..." Daniel@0: or <...> must be ordinary ASCII characters. In particular, all of the DOT Daniel@0: keywords such as digraph or subgraph must be ASCII. Daniel@0:
Daniel@0: Because we cannot always guess the encoding, you should set the graph Daniel@0: attribute charset to Daniel@0: UTF-8, Daniel@0: Latin1 Daniel@0: (alias ISO-8859-1 or ISO-IR-100) Daniel@0: or Daniel@0: Big-5 for Daniel@0: Traditional Chinese. This can be done in the graph file or on the command line. Daniel@0: For example charset=Latin1. Daniel@0:
Daniel@0: Output: It is essential that a font which has the glyphs for your Daniel@0: specified characters is available at final rendering time. Daniel@0: The choice of this font depends on the target code generator. Daniel@0: For the gd-based raster generators (PNG, GIF, etc.) you need a Daniel@0: TrueType or Type-1 font file on the machine running the Graphviz program. Daniel@0: If Graphviz is built with the fontconfig Daniel@0: library, it will be used to find the specified font. Otherwise, Graphviz will Daniel@0: look in various default directories for the font. The directories to be Daniel@0: searched include those specified by the fontpath attribute, Daniel@0: related environment or shell variables Daniel@0: (see the fontpath entry), Daniel@0: and known system font directories. Daniel@0: The table Daniel@0: Daniel@0: http://www.graphviz.org/doc/char.html Daniel@0: points out that these glyphs are from the times.ttf font. Daniel@0: With fontconfig, it's hard to specify this font. Times usually gets Daniel@0: resolved to Adobe Type1 times, which doesn't have all the glyphs seen on that page.) Daniel@0: Daniel@0:
Daniel@0: For Postscript, the input must be either the ASCII subset of UTF-8 Daniel@0: or Latin-1. (We have looked for more general solutions, but it Daniel@0: appears that UTF-8 and Unicode are handled differently for every Daniel@0: kind of font type in Postscript, and we don't have time to hack Daniel@0: this case-by-case. If someone wants to volunteer to work on this, let us know.) Daniel@0:
Daniel@0: For SVG output, we just pass the raw UTF-8 (or other encoding) Daniel@0: straight through to the generated code. Daniel@0:
Daniel@0: Non-ASCII characters probably won't ever work in Grappa Daniel@0: or dotty, which have their own back end rendering. Daniel@0: (Though, Java supports UTF-8, so there's a chance Daniel@0: Grappa also handles raw UTF-8 strings.) Daniel@0:
Daniel@0: As you can see, this is a sad state of affairs. Daniel@0: Our plan is to eventually migrate Graphviz to the Daniel@0: pango text formatting Daniel@0: library, to ameliorate the worst of these complications. Daniel@0:
Daniel@0: Daniel@0: Q. How do I get font and color changes in record labels or other labels? Daniel@0: Daniel@0:
Daniel@0: This is not possible in record shapes. However, you can do this using Daniel@0: Daniel@0: HTML-like labels. The granularity of changes is still at the cell level, Daniel@0: but by playing with cell spacing and padding, you can get pretty much Daniel@0: the effect you want. The intention is to support arbitrary font changes Daniel@0: within running text in the not-too-distant future. Daniel@0: Daniel@0:
Daniel@0: Daniel@0: Q12. In plain format, splines do not touch the nodes (arrowheads are missing). Daniel@0: Daniel@0:
Daniel@0: Edges are specified as the main spline and, if necessary, arrowheads Daniel@0: which actually abut the node. If the arrowheads are not given, drawing Daniel@0: the edge spline will leave a gap between the edge and the node. Daniel@0: This is a bug which has now solidified into a feature. Daniel@0: A workaround is to set Daniel@0: Daniel@0:
Daniel@0: edge [dir=none] Daniel@0:Daniel@0: Since the edges have no arrowheads, the spline specification will go Daniel@0: all the way to both nodes. Daniel@0:
Daniel@0: Daniel@0: Q13. Record nodes are drawn differently in dot and neato when rankdir=LR. Daniel@0: Daniel@0:
Daniel@0: It's true. dot -Grankdir=LR rotates record nodes so that their top level Daniel@0: fields are still listed across levels. rankdir=LR has no effect in neato. Daniel@0: One workaround is Daniel@0: Daniel@0: HTML-like records (they don't rotate; the downside is that Daniel@0: you have to write in XML). Another workaround is to enclose Daniel@0: record labels in { } to rotate/unrotate the record contents. See also, Daniel@0: How To Avoid Foolish Consistency Daniel@0: by Scott Berkun (Microsoft Corp.) Daniel@0:
Daniel@0: Daniel@0: Q14. How can I print a big graph on multiple pages? Daniel@0: Daniel@0:
Daniel@0: The page attribute, if set, tells Graphviz to print the Daniel@0: graph as an array of pages of the given size. Thus, the graph Daniel@0:
Daniel@0: digraph G {
Daniel@0: page="8.5,11";
Daniel@0: ...
Daniel@0: }
Daniel@0:
Daniel@0: will be emitted as 8.5 by 11 inch pages. When printed, the
Daniel@0: pages can be tiled to make a drawing of the entire graph.
Daniel@0: At present, the feature only works with PostScript output.
Daniel@0: Daniel@0: Alternatively, there are various tools and viewers which will take Daniel@0: a large picture and allow you to extract page-size pieces, which can Daniel@0: then be printed. Daniel@0:
Daniel@0: Daniel@0: Q. When I have a red edge it shows up as a Daniel@0: solid red in PNG and GIF formats, but has a Daniel@0: black border when rendered to JPEG. Daniel@0: Daniel@0:
Daniel@0: This is an artifact of JPEG's lossy Daniel@0: compression algorithm. JPEG isn't very good Daniel@0: for line drawings. PNG is bitmap format of Daniel@0: choice. John Ellson wants to deprecate and Daniel@0: eventually remove the JPEG driver, but North Daniel@0: is reluctant to change anything that people Daniel@0: might already rely on. Daniel@0:
Daniel@0: Daniel@0: Q16. How can I get custom shapes or images in my graph? Daniel@0: Daniel@0:
Daniel@0: Please see the Daniel@0: Daniel@0: Shape HowTo for some approaches. There is no easy way to create Daniel@0: custom shapes that work with dot/neato, dotty Daniel@0: (Unix or MS-Windows) and Grappa (the Java Daniel@0: front end), because they don't share any universal back end structure. Daniel@0: We're thinking about it. Daniel@0:
Daniel@0: Daniel@0: Q. Sometimes in dotty, right mouse click shows the global menu Daniel@0: but none of the items can be selected. Daniel@0: Daniel@0:
Daniel@0: Check that the NUMLOCK key is off. It's a Daniel@0: Daniel@0: known bug. Daniel@0:
Daniel@0: Daniel@0: Q18. Why does dotty report a syntax error on a legal dot file? Daniel@0: Daniel@0:
Daniel@0: Typically this error is reported as: Daniel@0:
Daniel@0: >> graph parser: syntax error near line 14
Daniel@0: >> context: >>> <<< digraph G {
Daniel@0: >> dotty.lefty: giving up on dot
Daniel@0: >> dotty.lefty: graph that causes dot
Daniel@0: >> dotty.lefty: to fail has been saved in file dottybug.dot
Daniel@0:
Daniel@0: Probably there is a command in your shell environment (such as
Daniel@0: .alias or .profile) that does output even for non-interactive shells.
Daniel@0: When this occurs, those characters go in the pipe to the dot parser
Daniel@0: and cause this problem. An easy check is whether other users have
Daniel@0: the same problem.
Daniel@0: Daniel@0: Daniel@0: Q. How can I get some display feature (such Daniel@0: as bold lines) in dotty? Daniel@0: Daniel@0:
Daniel@0: Dotty has not really changed for many years. Therefore, there are Daniel@0: myriad features available in Graphviz which it cannot handle. Daniel@0: In some cases, you can use Daniel@0: Grappa Daniel@0: or webdot Daniel@0: for display instead of dotty. Daniel@0: For example, Grappa has generalized polygons Daniel@0: (node [shape=polygon]) that dotty lacks. Daniel@0: There are additional interactive viewers available. For example, see Daniel@0: Graphical Interfaces Daniel@0: and Viewers. If you Daniel@0: are using Mac OS X, the Mac Daniel@0: version of Graphviz has a highly recommended GUI. Daniel@0:
Daniel@0: If the display attribute that you need isn't there already, in dotty, Daniel@0: there's probably no easy way to do it except by rolling up Daniel@0: your sleeves and hacking the dotty code (a lefty script) that Daniel@0: interprets and renders graphical attributes. This is problematic Daniel@0: for the same reason as above: there's no universal low-level driver Daniel@0: layer shared across all the Graphviz tools. We recently added an Daniel@0: intermediate rendering language to the layout tools, but the Daniel@0: various front ends don't use it yet. This would be a good project Daniel@0: for someone who wants to get involved here (along with porting Daniel@0: dotty to GTK.) Daniel@0:
Daniel@0: Daniel@0: Q. How can I get rid of the little circles on Daniel@0: edges ("edge handles") in dotty? Daniel@0: Daniel@0:
Daniel@0: Edit the file dotty.lefty and change the Daniel@0: line that says: 'edgehandles' = 1; to 'edgehandles' = 0; Daniel@0: it's around line 110. Daniel@0:
Daniel@0: Daniel@0: Q. I already have all the coordinates for the Daniel@0: nodes and edges of my graph and just want to Daniel@0: use dot, neato, or dotty to render it. How? Daniel@0: Daniel@0:
Daniel@0: Put the graph with layout attributes into a dot Daniel@0: file. Daniel@0: Daniel@0: Then run neato -s -n2. For example: Daniel@0:
Daniel@0: neato -s -n2 -Tgif file.dot -o file.gif Daniel@0:Daniel@0: Note that if an edge does not have a pos attribute Daniel@0: defined, neato will perform whatever edge routing it would Daniel@0: normally do. All of the usual backend attributes (size, Daniel@0: overlap, page, etc.) are available. Daniel@0:
Daniel@0: Daniel@0: Q. I already have all the coordinates for the Daniel@0: nodes, and I want dot or neato to route the edges. Daniel@0: Daniel@0:
Daniel@0: It's not really too convenient to use dot for this. Daniel@0: It is possible to use neato for this, Daniel@0: running neato -s -n For example: Daniel@0:
Daniel@0: neato -s -n -Tgif file.dot -o file.gif Daniel@0:Daniel@0: neato will use the node positions, but use its technique Daniel@0: for routing the edges. There are several things to note. First, Daniel@0: the neato edge router is different from dot's. Without the built-in Daniel@0: top-down bias, it doesn't do as good a job of avoiding edge overlaps Daniel@0: and, at present, it doesn't handle spline multi-edges at all. Second, by Daniel@0: default, neato uses straight lines as edges. To get spline routing, Daniel@0: you have to specify -Gsplines=true. And this will only work if none of Daniel@0: the nodes overlap. Since the input graph supplies fixed node positions, Daniel@0: it is the user's task to insure this. Daniel@0:
Daniel@0: Daniel@0: Q. I already have all the coordinates for the Daniel@0: nodes and edges of my graph and just want to Daniel@0: use dotty to render it. How? Daniel@0: Daniel@0:
Daniel@0: Just run dotty on it. Dotty will use the given pos attributes. Daniel@0:
Daniel@0: Daniel@0: Q25. Same as above, but I have only node coords, not edges. Daniel@0: Daniel@0:
Daniel@0: neato -n is some help, but neato doesn't handle Daniel@0: spline-based parallel edges. Daniel@0:
Daniel@0: Daniel@0: Q26. How can I make client-side image maps? Daniel@0: Daniel@0:
Daniel@0: Use the -Tcmap command line option (only version 1.8.9 and beyond!) Daniel@0:
Daniel@0: Daniel@0: Q27. Why aren't my server-side maps being recognized? I've checked the HTML! Daniel@0: Daniel@0:
Daniel@0: Make sure that your server has map files enabled. For example, if running Daniel@0: apache, check that httpd.conf has a line like the following: Daniel@0:
Daniel@0: AddHandler imap-file map Daniel@0:Daniel@0: and that it is not commented out! Daniel@0:
Daniel@0: Daniel@0: Q. I've installed Debian Graphviz and it works just fine on the command line, Daniel@0: but when I execute a Perl/CGI script through Apache, no output is generated. Daniel@0: For example, the code Daniel@0: Daniel@0: system("/usr/local/bin/dot -Tpng /tmp/tree.dot -o /tmp/tree.png"); Daniel@0: Daniel@0: produces no file /tmp/tree.png. Daniel@0:
Daniel@0: As best as we can tell, dot dies with no stdout or stderr messages on Debian Daniel@0: systems when run from an Apache cgi program Daniel@0: with no HOME set. The workaround is to provide a HOME directory in the Daniel@0: Apache userid's environment. Daniel@0:
Daniel@0: Someone has also suggested using the Daniel@0: Daniel@0: Perl module for Graphviz. Daniel@0:
Daniel@0: Daniel@0: Q29. How can I get 3D output? Daniel@0: Daniel@0:
Daniel@0: The Graphviz authors have qualms about the gratuitous use of 3D. Daniel@0:
Daniel@0: Nonetheless, dot -Tvrml generates VRML files. There's no Z coordinate Daniel@0: layout - you specify Z coords yourself in the z attribute of nodes, Daniel@0: and the Z coordinates of edges are interpolated. If someone Daniel@0: contributes a driver for a newer, more useful format (OpenGL Performer Daniel@0: scene graphs? Open Scene Graphs? Java3D programs?) we'd like to try it. Daniel@0:
Daniel@0: neato internally supports layouts in higher dimensions through the dim Daniel@0: attribute, e.g. neato -Gdim=7 but there's no way to get the output Daniel@0: unless you invoke neato as a library and inspect ND_pos(n)[i] Daniel@0: where n is a pointer to the relevant node. Daniel@0: This would need some (minor) driver work and a good 7-dimensional viewer. Well, Daniel@0: dim=3 ought to be possible. Daniel@0: Daniel@0:
Daniel@0: Use the graph attribute overlap. Daniel@0:
Daniel@0: Daniel@0: Q31. How can I avoid node-edge overlaps in neato? Daniel@0: Daniel@0:
Daniel@0: Use the overlap attribute to leave room among the nodes, then Daniel@0: use -Gsplines=true. Daniel@0:
Daniel@0: neato -Goverlap=... -Gsplines=true -Gsep=.1 Daniel@0:Daniel@0:
Daniel@0: The sep argument is the node-edge separation as Daniel@0: a ratio of a node's bounding box. That is, sep=.1 means Daniel@0: each node is treated as though it is 1.1 times larger than it is. Daniel@0: The actual value may require some tinkering. Daniel@0: (Don't ask why this isn't just a constant!) Note that this option really Daniel@0: slows down neato, so should be used sparingly and only Daniel@0: with modest-sized graphs. Daniel@0:
Daniel@0: Daniel@0: Q32. Neato runs forever on a certain example. Daniel@0: Daniel@0:
Daniel@0: First, how big is your graph? Neato is a quadratic algorithm, roughly Daniel@0: equivalent to statistical multidimensional scaling. If you Daniel@0: feed it a graph with thousands of nodes and edges, it can easily take Daniel@0: hours or days. The first thing to check is to run neato -v to Daniel@0: get a trace of the output. If the numbers you see are generally Daniel@0: getting smaller, the layout is just taking a long time. You can set Daniel@0: certain parameters, such as epsilon or maxiter to Daniel@0: shorten the layout time, at the expense of layout quality. But if your Daniel@0: graph is big, who's going to notice? Daniel@0:
Daniel@0: If you see Daniel@0: the numbers repeating, or fluctuating up and down, then neato is Daniel@0: cycling, especially if your graph is small. Daniel@0: This should never happen by default for versions later than 1.13. If it Daniel@0: does, please report it as a bug. Daniel@0:
Daniel@0: If you are using an earlier version of neato, or you used mode=KK, Daniel@0: cycling is indeed possible. This cycling is very sensitive to the Daniel@0: initial layout. By using the start attribute, for example, Daniel@0:
Daniel@0: neato -Gstart=3 Daniel@0: neato -Gstart=rand Daniel@0:Daniel@0: the cycling will most likely disappear. Or you can employ the parameters used Daniel@0: for large graphs to stop the layout earlier: Daniel@0:
Daniel@0: neato -Gepsilon=.01 Daniel@0: neato -Gmaxiter=500 Daniel@0:Daniel@0:
Daniel@0: Note that, if you have a large graph, the generation of edges as splines Daniel@0: is a cubic algorithm, so you would do well to avoid using splines=true. Daniel@0: (This commment applies to circo, fdp and twopi as well.) Daniel@0:
Daniel@0: Daniel@0: Q33. Edge label placement in neato is bad. Daniel@0: Daniel@0:
Daniel@0: Difficult problem. We're working on it. Daniel@0: If anyone has some general Daniel@0: label placement code (e.g. a simulated annealer based on the Marks et al. Daniel@0: technique in Graphics Gems IV), please get in touch. Daniel@0:
Daniel@0: Daniel@0: Q34. Dot runs forever on a certain example. Daniel@0: Daniel@0:
Daniel@0: Try dot -v to observe its progress. Daniel@0:
Daniel@0: Note that it's possible to make graphs whose layout or even parsing Daniel@0: is quadratic in the input size. For example, in dot, Daniel@0: Daniel@0:
Daniel@0: digraph G {
Daniel@0: a -> b -> c -> .... -> x -> y -> z
Daniel@0: a -> z
Daniel@0: b -> z
Daniel@0: c -> z
Daniel@0: /* and so on... */
Daniel@0: x -> z
Daniel@0: }
Daniel@0:
Daniel@0:
Daniel@0: The total edge length (therefore the layout time) of
Daniel@0: this as a ranked graph is quadratic in the number of nodes.
Daniel@0:
Daniel@0:
Daniel@0: You probably won't encounter the following, but it is also possible
Daniel@0: to construct graphs whose parsing takes quadratic time in the number
Daniel@0: of attributes, by appending attributes to nodes and edges after the
Daniel@0: graph has been loaded. For example:
Daniel@0:
Daniel@0:
Daniel@0: digraph G {
Daniel@0: /* really big graph goes here...with N+1 nodes */
Daniel@0: n0 -> n1 -> ... -> nN;
Daniel@0:
Daniel@0: n0 [attr0="whatever",
Daniel@0: attr1="something else",
Daniel@0: /* and so on with many more attributes */
Daniel@0: attrM="something again"]
Daniel@0: }
Daniel@0:
Daniel@0: When an attribute first appears, each object is visited with possible cost
Daniel@0: proportional to the number of previously declared attributes. Thus,
Daniel@0: the running time for the above would be cN O(M)
Daniel@0: for some constant c. If there is any concern about this, the
Daniel@0: graph should specify the attributes first before declaring nodes or
Daniel@0: edges. In practice, this problem is neglible.
Daniel@0: Daniel@0: Daniel@0: Q. Twopi runs forever on a certain example. Daniel@0: Daniel@0:
Daniel@0: Is your graph is large (many thousands of edges), Daniel@0: and did you set
splines=true? It takes Daniel@0: a lot of cycles to fit all those splines! Daniel@0:
Daniel@0: Daniel@0: Q. Neato has unnecessary edge crossings, or has missed an Daniel@0: obvious chance to make a much nicer layout. Daniel@0: Daniel@0:
Daniel@0: Neato and all similar virtual physical model algorithms rely Daniel@0: on heuristic solutions of optimization problems. The better Daniel@0: the solution, the longer it takes to find. Unfortunately, it Daniel@0: is also possible for these heuristics to get stuck in local Daniel@0: minima. Also, it is heavily influenced by the initial position Daniel@0: of the nodes. It is quite possible that if you run neato again, Daniel@0: but with a different random seed value, Daniel@0: or more iterations, you'll get a better layout. For example: Daniel@0:
Daniel@0: neato -Gstart=5 file.dot -Tps -o file.ps Daniel@0: neato -Gepsilon=.0000001 file.dot -Tps -o file.ps Daniel@0:Daniel@0:
Daniel@0: In particular, note that there are no guarantees that neato will produce Daniel@0: a planar layout of a planar graph, or expose all or most of a graph's Daniel@0: symmetries. Daniel@0:
Daniel@0: Daniel@0: Q36. Webdot doesn't work. Daniel@0: Daniel@0:
Daniel@0: We assume you're using Apache and have TCL installed. Daniel@0: If you don't, it's probably better to just use the Daniel@0: Daniel@0: webdot perl script. Daniel@0:
Daniel@0: To debug webdot, first test whether tclsh can load the Daniel@0: Tcldot shared library. Try: Daniel@0:
Daniel@0: $ tclsh Daniel@0: % load $prefix/lib/graphviz/libtcldot.so.0 Daniel@0: % Daniel@0:Daniel@0: where $prefix is the installation prefix for graphviz; usually /usr Daniel@0: or /usr/local. Daniel@0:
Daniel@0: Then test whether webdot runs from a shell command. (With webdot we provide Daniel@0: a helper script scaffold.tcl or scaffold.sh that sets up an environment Daniel@0: like the one Apache provides.) For example Daniel@0:
Daniel@0: $ scaffold.tcl >out.gif Daniel@0: can't read "LIBTCLDOT": no such variable Daniel@0: while executing Daniel@0: "file mtime $LIBTCLDOT" Daniel@0: invoked from within Daniel@0: "set t1 [file mtime $LIBTCLDOT]" Daniel@0: (file "cgi-bin/webdot" line 67) Daniel@0: invoked from within Daniel@0: "source cgi-bin/webdot Daniel@0: " Daniel@0: (file "scaffold.tcl" line 22) Daniel@0:Daniel@0: The above is a strong clue that webdot is not configured properly. Daniel@0:
Daniel@0: Finally, test whether webdot runs as a cgi-bin program. Daniel@0: It may help to examine the cgi-bin environment using a Daniel@0: simple cgi-bin tcl script like: Daniel@0:
Daniel@0: #!/bin/env tclsh
Daniel@0: puts "Content-type: text/plain"
Daniel@0: puts ""
Daniel@0: foreach e [lsort [array names env]] {puts "$e: $env($e)"}
Daniel@0:
Daniel@0: Save this script as .../cgi-bin/test.tcl, make it executable, then
Daniel@0: look at: http://localhost/cgi-bin/test.tcl
Daniel@0: Daniel@0: Also, if you see something like: Daniel@0:
Daniel@0: WebDot Error: Daniel@0: Daniel@0: Response Code = 403 Daniel@0:Daniel@0: This usually means that webdot ran succesfully, but was not able Daniel@0: to fetch the remote graph from the URL you gave as an argument. Daniel@0: The reason is probably that your server is behind a firewall that Daniel@0: blocks the webdot server, so it cannot get the graph file. Daniel@0: You can either change firewall permissions, put the graph on a Daniel@0: different server, or install webdot locally so you don't need a Daniel@0: remote server to fetch your graph data. Daniel@0:
Daniel@0: It would be nice if someone hacked webdot to take the contents Daniel@0: of a graph as a cgi-bin argument, so it wouldn't need Daniel@0: permission to fetch a graph remotely. Daniel@0: This is left as an exercise for the Open Source Community. Daniel@0:
Daniel@0: Daniel@0: Q37. I have "Font not found" errors, or text labels missing in webdot. Daniel@0: Daniel@0:
Daniel@0: Firstly, recent versions of graphviz will use fontconfig if it is available Daniel@0: on your platform. With fontconfig, this error should not occur, so you Daniel@0: may want to see if an upgrade to graphviz is available, or if a rebuild Daniel@0: will add fontconfig support. Daniel@0:
Daniel@0: If fontconfig is not available then graphviz tries to resolve fontnames Daniel@0: to fontpaths itself, and uses DOTFONTPATH (or GDFONTPATH) to indicate where it should look. Daniel@0:
Daniel@0: For copyright reasons, Graphviz doesn't come with its own fonts. Daniel@0: On a Windows machine, it knows to search in C:\Windows\Fonts. Daniel@0: On a Unix machine, you need to set up a directory that contains Daniel@0: Truetype fonts. You can get a copy of some fonts Daniel@0: here. Daniel@0:
Daniel@0: The default DOTFONTPATH is: Daniel@0:
Daniel@0: #define DEFAULT_FONTPATH "/usr/X11R6/lib/X11/fonts/TrueType:/usr/X11R6/lib/X11/fonts/truetype:/usr/X11R6/lib/X11/fonts/TTF:/usr/share/fonts/TrueType:/usr/share/fonts/truetype:/usr/openwin/lib/X11/fonts/TrueType:/usr/X11R6/lib/X11/fonts/Type1" Daniel@0:Daniel@0: If your fonts are somewhere else, then you must set that directory in Daniel@0: the webdot script, or recompile Graphviz with the correct DEFAULT_FONTPATH Daniel@0: (or set fontpath="/your/font/directory" in every graph you lay out, Daniel@0: but that's pretty clumsy.) Daniel@0:
Daniel@0: Daniel@0: Q38. My browser doesn't recognize SVG. Daniel@0: Daniel@0:
Daniel@0: The correct MIME type for svg images is: image/svg+xml (note "+" not "-"). Daniel@0:
Daniel@0: SVG is not built into all browsers; you can get Daniel@0: plugins Daniel@0: from Adobe for Windows, Linux and some other operating systems. Daniel@0: Daniel@0: Firefox 1.5 has a large subset of SVG and renders graphviz -Tsvg output Daniel@0: though until graphviz 2.8, the fonts may be too large (thanks for Daniel@0: Phil Colbourne at the RailCorp of New South Wales for this advice). Daniel@0:
Daniel@0: For help with embedding SVG in HTML pages, see Daniel@0: here. Daniel@0:
Daniel@0: There are several good standalone viewers and editors for SVG. Daniel@0: We like inkscape. Daniel@0: evince Daniel@0: is the standard Gnome document viewer that handles SVG, at least Daniel@0: since version 0.5 (though Phil C. reports output is blurred) Daniel@0: (see also eog (Eye of Gnome)). Daniel@0: Commercial tools like Adobe Illustrator and Microsoft Visio Daniel@0: can import SVG (the better to deal with your content, my dear!) Daniel@0: If you are using an older (less bloated) Unix system, you Daniel@0: may find tools like Batik Daniel@0: (an SVG renderer in Java) or sodipodi Daniel@0: useful, though it seems they are no longer very actively maintained. Daniel@0: sodipodi is faster but both make sharp images - isn't that the Daniel@0: beauty of path-based graphics? Daniel@0:
Daniel@0: Daniel@0: Q39. libexpat is reported as containing a virus or as a security hole. Daniel@0: Is this a real problem? Daniel@0: Daniel@0:
Daniel@0: No, this is a false positive reported by various security software. Daniel@0: See http://www.pcreview.co.uk/forums/thread-1689630.php or Daniel@0: http://spywareblog.com/index.php/2004/11/24/is_libexpat_dll_spyware. Daniel@0:
Daniel@0: Daniel@0: Q40. What is the coordinate transformation between the graph bb and a .png image? Daniel@0:
Daniel@0: At the renderer api, plugins have a choice of coordinate representation: Daniel@0:
Daniel@0: Daniel@0: Q41. File associations are broken in Mac OSX. Clicking on a dot file doesn't open Graphviz. Daniel@0:
Daniel@0: The immediate fix is to rebuild the Launch Services database like this: Daniel@0:
Daniel@0: 1. Trash all other versions of Graphviz.app on your system, except for the just installed one. You can use either of these command lines to find it: Daniel@0:
Daniel@0:
locate Graphviz.appDaniel@0:
Daniel@0: or Daniel@0:
Daniel@0:
find / -name "Graphviz.app"Daniel@0:
Daniel@0: 2. Run the following command line: Daniel@0:
Daniel@0:
/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r /Daniel@0:
Daniel@0: or Daniel@0:
Daniel@0:
/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r /ApplicationsDaniel@0:
Daniel@0: which deletes the Launch Services database and rebuilds it from existing apps. You may need to sudo to do this. Daniel@0:
Daniel@0: 3. Verify that the Graphviz.app can now open .dot files and Microsoft Word can still open its own .dot files. Daniel@0:
Daniel@0: One artifact of this will be that Microsoft .dot files may appear with the Graphviz document icon. Unfortunately there doesn't seem any a priori way of getting the system to determine whether an arbitrary .dot file belongs to Word or Graphviz -- you can choose which application to open with by right-clicking or control-clicking on the document icon and choosing the app. Daniel@0:
Daniel@0: As for why the Launch Services database doesn't automatically register Graphviz, Daniel@0: we're not entirely sure but suspect this only happens if both conditions Daniel@0: hold true: Daniel@0:
Daniel@0: A. The user had installed Microsoft Word.
Daniel@0: B. There is also another version of Graphviz.app present in the system. (Possibly the previous version 1.13 released by Pixelglow Software)
Daniel@0: Q41. What do all these plugin libraries do?
Daniel@0:
Daniel@0:
| Daniel@0: | UTF8 | Daniel@0:hyperlinks | Daniel@0:human readable PostScript | Daniel@0:
|---|---|---|---|
| -Tps:core | no | yes | ++ | Daniel@0:
| -Tps:lasi | yes | yes | + | Daniel@0:
| -Tps:cairo | yes | no | -- | Daniel@0: