1GraphViz(3) User Contributed Perl Documentation GraphViz(3)
2
6 GraphViz - Interface to the GraphViz graphing tool
7
9 use GraphViz;
10 my $g = GraphViz->new();
12 $g->add_node('London');
14 $g->add_node('Paris', label => 'City of\nlurve');
15 $g->add_node('New York');
16 $g->add_edge('London' => 'Paris');
18 $g->add_edge('London' => 'New York', label => 'Far');
19 $g->add_edge('Paris' => 'London');
20 print $g->as_png;
22
24 This module provides an interface to layout and image generation of
25 directed and undirected graphs in a variety of formats (PostScript,
26 PNG, etc.) using the "dot", "neato", "twopi", "circo" and "fdp" pro‐
27 grams from the GraphViz project (http://www.graphviz.org/ or
28 http://www.research.att.com/sw/tools/graphviz/).
29 What is a graph?
31 A (undirected) graph is a collection of nodes linked together with
33 edges.
34 A directed graph is the same as a graph, but the edges have a direc‐
36 tion.
37 What is GraphViz?
39 This module is an interface to the GraphViz toolset
41 (http://www.graphviz.org/). The GraphViz tools provide automatic graph
42 layout and drawing. This module simplifies the creation of graphs and
43 hides some of the complexity of the GraphViz module.
44 Laying out graphs in an aesthetically-pleasing way is a hard problem -
46 there may be multiple ways to lay out the same graph, each with their
47 own quirks. GraphViz luckily takes part of this hard problem and does a
48 pretty good job in a couple of seconds for most graphs.
49 Why should I use this module?
51 Observation aids comprehension. That is a fancy way of expressing that
53 popular faux-Chinese proverb: "a picture is worth a thousand words".
54 Text is not always the best way to represent anything and everything to
56 do with a computer programs. Pictures and images are easier to assimi‐
57 late than text. The ability to show a particular thing graphically can
58 aid a great deal in comprehending what that thing really represents.
59 Diagrams are computationally efficient, because information can be
61 indexed by location; they group related information in the same area.
62 They also allow relations to be expressed between elements without
63 labeling the elements.
64 A friend of mine used this to his advantage when trying to remember
66 important dates in computer history. Instead of sitting down and trying
67 to remember everything, he printed over a hundred posters (each with a
68 date and event) and plastered these throughout his house. His spatial
69 memory is still so good that asked last week (more than a year since
70 the experiment) when Lisp was invented, he replied that it was
71 upstairs, around the corner from the toilet, so must have been around
72 1958.
73 Spreadsheets are also a wonderfully simple graphical representation of
75 computational models.
76 Applications
78 Bundled with this module are several modules to help graph data struc‐
80 tures (GraphViz::Data::Dumper), XML (GraphViz::XML), and Parse::RecDes‐
81 cent, Parse::Yapp, and yacc grammars (GraphViz::Parse::RecDescent,
82 GraphViz::Parse::Yapp, and GraphViz::Parse::Yacc).
83 Note that Marcel Grunauer has released some modules on CPAN to graph
85 various other structures. See GraphViz::DBI and GraphViz::ISA for exam‐
86 ple.
87 brian d foy has written an article about Devel::GraphVizProf for Dr.
89 Dobb's Journal: http://www.ddj.com/col‐
90 umns/perl/2001/0104pl002/0104pl002.htm
91 Award winning!
93 I presented a paper and talk on "Graphing Perl" using GraphViz at the
95 3rd German Perl Workshop and received the "Best Knowledge Transfer"
96 prize.
97 Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf
99 Slides: http://www.astray.com/graphing_perl/
100
102 new
103 This is the constructor. It accepts several attributes.
105 my $g = GraphViz->new();
107 my $g = GraphViz->new(directed => 0);
108 my $g = GraphViz->new(layout => 'neato', ratio => 'compress');
109 my $g = GraphViz->new(rankdir => 1);
110 my $g = GraphViz->new(width => 8.5, height => 11);
111 my $g = GraphViz->new(width => 30, height => 20,
112 pagewidth => 8.5, pageheight => 11);
113 The most two important attributes are 'layout' and 'directed'.
115 layout
117 The 'layout' attribute determines which layout algorithm
118 GraphViz.pm will use. Possible values are:
119 dot The default GraphViz layout for directed graph layouts
121 neato
123 For undirected graph layouts - spring model
124 twopi
126 For undirected graph layouts - radial
127 circo
129 For undirected graph layouts - circular
130 fdp For undirected graph layouts - force directed spring model
132 directed
134 The 'directed' attribute, which defaults to 1 (true) specifies
135 directed (edges have arrows) graphs. Setting this to zero produces
136 undirected graphs (edges do not have arrows).
137 rankdir
139 Another attribute 'rankdir' controls the direction the nodes are
140 linked together. If true it will do left->right linking rather than
141 the default up-down linking.
142 width, height
144 The 'width' and 'height' attributes control the size of the bound‐
145 ing box of the drawing in inches. This is more useful for Post‐
146 Script output as for raster graphic (such as PNG) the pixel dimen‐
147 sions can not be set, although there are generally 96 pixels per
148 inch.
149 pagewidth, pageheight
151 The 'pagewidth' and 'pageheight' attributes set the PostScript pag‐
152 ination size in inches. That is, if the image is larger than the
153 page then the resulting PostScript image is a sequence of pages
154 that can be tiled or assembled into a mosaic of the full image.
155 (This only works for PostScript output).
156 concentrate
158 The 'concentrate' attribute controls enables an edge merging tech‐
159 nique to reduce clutter in dense layouts of directed graphs. The
160 default is not to merge edges.
161 random_start
163 For undirected graphs, the 'random_start' attribute requests an
164 initial random placement for the graph, which may give a better
165 result. The default is not random.
166 epsilon
168 For undirected graphs, the 'epsilon' attribute decides how long the
169 graph solver tries before finding a graph layout. Lower numbers
170 allow the solver to fun longer and potentially give a better lay‐
171 out. Larger values can decrease the running time but with a reduc‐
172 tion in layout quality. The default is 0.1.
173 overlap
175 The 'overlap' option allows you to set layout behavior for graph
176 nodes that overlap. (From GraphViz documentation:)
177 Determines if and how node overlaps should be removed.
179 true
181 (the default) overlaps are retained.
182 scale
184 overlaps are removed by uniformly scaling in x and y.
185 false
187 If the value converts to "false", node overlaps are removed by
188 a Voronoi-based technique.
189 scalexy
191 x and y are separately scaled to remove overlaps.
192 orthoxy, orthxy
194 If the value is "orthoxy" or "orthoyx", overlaps are moved by
195 optimizing two constraint problems, one for the x axis and one
196 for the y. The suffix indicates which axis is processed first.
197 NOTE: The methods related to "orthoxy" and "orthoyx" are still
199 evolving. The semantics of these may change, or these methods
200 may disappear altogether.
201 compress
203 If the value is "compress", the layout will be scaled down as
204 much as possible without introducing any overlaps.
205 Except for the Voronoi method, all of these transforms preserve the
207 orthogonal ordering of the original layout. That is, if the x coor‐
208 dinates of two nodes are originally the same, they will remain the
209 same, and if the x coordinate of one node is originally less than
210 the x coordinate of another, this relation will still hold in the
211 transformed layout. The similar properties hold for the y coordi‐
212 nates.
213 no_overlap
215 The 'no_overlap' overlap option, if set, tells the graph solver to
216 not overlap the nodes. Deprecated, Use 'overlap' => 'false'.
217 ratio
219 The 'ratio' option sets the aspect ratio (drawing height/drawing
220 width) for the drawing. Note that this is adjusted before the size
221 attribute constraints are enforced. Default value is "fill".
222 numeric
224 If ratio is numeric, it is taken as the desired aspect ratio.
225 Then, if the actual aspect ratio is less than the desired
226 ratio, the drawing height is scaled up to achieve the desired
227 ratio; if the actual ratio is greater than that desired ratio,
228 the drawing width is scaled up.
229 fill
231 If ratio = "fill" and the size attribute is set, node positions
232 are scaled, separately in both x and y, so that the final draw‐
233 ing exactly fills the specified size.
234 compress
236 If ratio = "compress" and the size attribute is set, dot
237 attempts to compress the initial layout to fit in the given
238 size. This achieves a tighter packing of nodes but reduces the
239 balance and symmetry. This feature only works in dot.
240 expand
242 If ratio = "expand" the size attribute is set, and both the
243 width and the height of the graph are less than the value in
244 size, node positions are scaled uniformly until at least one
245 dimension fits size exactly. Note that this is distinct from
246 using size as the desired size, as here the drawing is expanded
247 before edges are generated and all node and text sizes remain
248 unchanged.
249 auto
251 If ratio = "auto" the page attribute is set and the graph can‐
252 not be drawn on a single page, then size is set to an ``ideal''
253 value. In particular, the size in a given dimension will be the
254 smallest integral multiple of the page size in that dimension
255 which is at least half the current size. The two dimensions are
256 then scaled independently to the new size. This feature only
257 works in dot.
258 bgcolor
260 The 'bgcolor' option sets the background colour. A colour value may
261 be "h,s,v" (hue, saturation, brightness) floating point numbers
262 between 0 and 1, or an X11 color name such as 'white', 'black',
263 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or 'burly‐
264 wood'.
265 node,edge,graph
267 The 'node', 'edge' and 'graph' attributes allow you to specify
268 global node, edge and graph attributes (in addition to those con‐
269 trolled by the special attributes described above). The value
270 should be a hash reference containing the corresponding key-value
271 pairs. For example, to make all nodes box-shaped (unless explicity
272 given another shape):
273 my $g = GraphViz->new(node => {shape => 'box'});
275 add_node
277 A graph consists of at least one node. All nodes have a name attached
279 which uniquely represents that node.
280 The add_node method creates a new node and optionally assigns it
282 attributes.
283 The simplest form is used when no attributes are required, in which the
285 string represents the name of the node:
286 $g->add_node('Paris');
288 Various attributes are possible: "label" provides a label for the node
290 (the label defaults to the name if none is specified). The label can
291 contain embedded newlines with '\n', as well as '\c', '\l', '\r' for
292 center, left, and right justified lines:
293 $g->add_node('Paris', label => 'City of\nlurve');
295 Attributes need not all be specified in the one line: successive decla‐
297 rations of the same node have a cumulative effect, in that any later
298 attributes are just added to the existing ones. For example, the fol‐
299 lowing two lines are equivalent to the one above:
300 $g->add_node('Paris');
302 $g->add_node('Paris', label => 'City of\nlurve');
303 Note that multiple attributes can be specified. Other attributes
305 include:
306 height, width
308 sets the minimum height or width
309 shape
311 sets the node shape. This can be one of: 'record', 'plaintext',
312 'ellipse', 'circle', 'egg', 'triangle', 'box', 'diamond', 'trapez‐
313 ium', 'parallelogram', 'house', 'hexagon', 'octagon'
314 fontsize
316 sets the label size in points
317 fontname
319 sets the label font family name
320 color
322 sets the outline colour, and the default fill colour if the 'style'
323 is 'filled' and 'fillcolor' is not specified
324 A colour value may be "h,s,v" (hue, saturation, brightness) float‐
326 ing point numbers between 0 and 1, or an X11 color name such as
327 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
328 'cyan', or 'burlywood'
329 fillcolor
331 sets the fill colour when the style is 'filled'. If not specified,
332 the 'fillcolor' when the 'style' is 'filled' defaults to be the
333 same as the outline color
334 style
336 sets the style of the node. Can be one of: 'filled', 'solid',
337 'dashed', 'dotted', 'bold', 'invis'
338 URL sets the url for the node in image map and PostScript files. The
340 string '\N' value will be replaced by the node name. In PostScript
341 files, URL information is embedded in such a way that Acrobat Dis‐
342 tiller creates PDF files with active hyperlinks
343 If you wish to add an anonymous node, that is a node for which you do
345 not wish to generate a name, you may use the following form, where the
346 GraphViz module generates a name and returns it for you. You may then
347 use this name later on to refer to this node:
348 my $nodename = $g->add_node('label' => 'Roman city');
350 Nodes can be clustered together with the "cluster" attribute, which is
352 drawn by having a labelled rectangle around all the nodes in a cluster.
353 An empty string means not clustered.
354 $g->add_node('London', cluster => 'Europe');
356 $g->add_node('Amsterdam', cluster => 'Europe');
357 Clusters can also take a hashref so that you can set attributes:
359 my $eurocluster = {
361 name =>'Europe',
362 style =>'filled',
363 fillcolor =>'lightgray',
364 fontname =>'arial',
365 fontsize =>'12',
366 };
367 $g->add_node('London', cluster => $eurocluster, @default_attrs);
368 Nodes can be located in the same rank (that is, at the same level in
370 the graph) with the "rank" attribute. Nodes with the same rank value
371 are ranked together.
372 $g->add_node('Paris', rank => 'top');
374 $g->add_node('Boston', rank => 'top');
375 Also, nodes can consist of multiple parts (known as ports). This is
377 implemented by passing an array reference as the label, and the parts
378 are displayed as a label. GraphViz has a much more complete port sys‐
379 tem, this is just a simple interface to it. See the 'from_port' and
380 'to_port' attributes of add_edge:
381 $g->add_node('London', label => ['Heathrow', 'Gatwick']);
383 add_edge
385 Edges are directed (or undirected) links between nodes. This method
387 creates a new edge between two nodes and optionally assigns it
388 attributes.
389 The simplest form is when now attributes are required, in which case
391 the nodes from and to which the edge should be are specified. This
392 works well visually in the program code:
393 $g->add_edge('London' => 'Paris');
395 Attributes such as 'label' can also be used. This specifies a label for
397 the edge. The label can contain embedded newlines with '\n', as well
398 as '\c', '\l', '\r' for center, left, and right justified lines.
399 $g->add_edge('London' => 'New York', label => 'Far');
401 Note that multiple attributes can be specified. Other attributes
403 include:
404 minlen
406 sets an integer factor that applies to the edge length (ranks for
407 normal edges, or minimum node separation for flat edges)
408 weight
410 sets the integer cost of the edge. Values greater than 1 tend to
411 shorten the edge. Weight 0 flat edges are ignored for ordering
412 nodes
413 fontsize
415 sets the label type size in points
416 fontname
418 sets the label font family name
419 fontcolor
421 sets the label text colour
422 color
424 sets the line colour for the edge
425 A colour value may be "h,s,v" (hue, saturation, brightness) float‐
427 ing point numbers between 0 and 1, or an X11 color name such as
428 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
429 'cyan', or 'burlywood'
430 style
432 sets the style of the node. Can be one of: 'filled', 'solid',
433 'dashed', 'dotted', 'bold', 'invis'
434 dir sets the arrow direction. Can be one of: 'forward', 'back', 'both',
436 'none'
437 tailclip, headclip
439 when set to false disables endpoint shape clipping
440 arrowhead, arrowtail
442 sets the type for the arrow head or tail. Can be one of: 'none',
443 'normal', 'inv', 'dot', 'odot', 'invdot', 'invodot.'
444 arrowsize
446 sets the arrow size: (norm_length=10,norm_width=5,
447 inv_length=6,inv_width=7,dot_radius=2)
448 headlabel, taillabel
450 sets the text for port labels. Note that labelfontcolor, labelfont‐
451 name, labelfontsize are also allowed
452 labeldistance, port_label_distance
454 sets the distance from the edge / port to the label. Also labelan‐
455 gle
456 decorateP
458 if set, draws a line from the edge to the label
459 samehead, sametail
461 if set aim edges having the same value to the same port, using the
462 average landing point
463 constraint
465 if set to false causes an edge to be ignored for rank assignment
466 Additionally, adding edges between ports of a node is done via the
468 'from_port' and 'to_port' parameters, which currently takes in the off‐
469 set of the port (ie 0, 1, 2...).
470 $g->add_edge('London' => 'Paris', from_port => 0);
472 as_canon, as_text, as_gif etc. methods
474 There are a number of methods which generate input for dot / neato /
476 twopi / circo / fdp or output the graph in a variety of formats.
477 Note that if you pass a filename, the data is written to that filename.
479 If you pass a filehandle, the data will be streamed to the filehandle.
480 If you pass a scalar reference, then the data will be stored in that
481 scalar. If you pass it a code reference, then it is called with the
482 data (note that the coderef may be called multiple times if the image
483 is large). Otherwise, the data is returned:
484 Win32 Note: you will probably want to binmode any filehandles you write
486 the output to if you want your application to be portable to Win32.
487 my $png_image = $g->as_png;
489 # or
490 $g->as_png("pretty.png"); # save image
491 # or
492 $g->as_png(\*STDOUT); # stream image to a filehandle
493 # or
494 #g->as_png(\$text); # save data in a scalar
495 # or
496 $g->as_png(sub { $png_image .= shift });
497 as_debug
499 The as_debug method returns the dot file which we pass to GraphViz.
500 It does not lay out the graph. This is mostly useful for debugging.
501 print $g->as_debug;
503 as_canon
505 The as_canon method returns the canonical dot / neato / twopi /
506 circo / fdp file which corresponds to the graph. It does not lay‐
507 out the graph - every other as_* method does.
508 print $g->as_canon;
510 # prints out something like:
512 digraph test {
513 node [ label = "\N" ];
514 London [label=London];
515 Paris [label="City of\nlurve"];
516 New_York [label="New York"];
517 London -> Paris;
518 London -> New_York [label=Far];
519 Paris -> London;
520 }
521 as_text
523 The as_text method returns text which is a layed-out dot / neato /
524 twopi / circo / fdp format file.
525 print $g->as_text;
527 # prints out something like:
529 digraph test {
530 node [ label = "\N" ];
531 graph [bb= "0,0,162,134"];
532 London [label=London, pos="33,116", width="0.89", height="0.50"];
533 Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
534 New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
535 London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
536 London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
537 Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
538 }
539 as_ps
541 Returns a string which contains a layed-out PostScript-format file.
542 print $g->as_ps;
544 as_hpgl
546 Returns a string which contains a layed-out HP pen plotter-format
547 file.
548 print $g->as_hpgl;
550 as_pcl
552 Returns a string which contains a layed-out Laserjet printer-format
553 file.
554 print $g->as_pcl;
556 as_mif
558 Returns a string which contains a layed-out FrameMaker graphics-
559 format file.
560 print $g->as_mif;
562 as_pic
564 Returns a string which contains a layed-out PIC-format file.
565 print $g->as_pic;
567 as_gd
569 Returns a string which contains a layed-out GD-format file.
570 print $g->as_gd;
572 as_gd2
574 Returns a string which contains a layed-out GD2-format file.
575 print $g->as_gd2;
577 as_gif
579 Returns a string which contains a layed-out GIF-format file.
580 print $g->as_gif;
582 as_jpeg
584 Returns a string which contains a layed-out JPEG-format file.
585 print $g->as_jpeg;
587 as_png
589 Returns a string which contains a layed-out PNG-format file.
590 print $g->as_png;
592 $g->as_png("pretty.png"); # save image
593 as_wbmp
595 Returns a string which contains a layed-out Windows BMP-format
596 file.
597 print $g->as_wbmp;
599 as_cmap (deprecated)
601 Returns a string which contains a layed-out HTML client-side image
602 map format file. Use as_cmpax instead.
603 print $g->as_cmap;
605 as_cmapx
607 Returns a string which contains a layed-out HTML HTML/X client-side
608 image map format file.
609 print $g->as_cmapx;
611 as_ismap (deprecated)
613 Returns a string which contains a layed-out old-style server-side
614 image map format file. Use as_imap instead.
615 print $g->as_ismap;
617 as_imap
619 Returns a string which contains a layed-out HTML new-style server-
620 side image map format file.
621 print $g->as_imap;
623 as_vrml
625 Returns a string which contains a layed-out VRML-format file.
626 print $g->as_vrml;
628 as_vtx
630 Returns a string which contains a layed-out VTX (Visual Thought)
631 format file.
632 print $g->as_vtx;
634 as_mp
636 Returns a string which contains a layed-out MetaPost-format file.
637 print $g->as_mp;
639 as_fig
641 Returns a string which contains a layed-out FIG-format file.
642 print $g->as_fig;
644 as_svg
646 Returns a string which contains a layed-out SVG-format file.
647 print $g->as_svg;
649 as_svgz
651 Returns a string which contains a layed-out SVG-format file that is
652 compressed.
653 print $g->as_svgz;
655 as_plain
657 Returns a string which contains a layed-out simple-format file.
658 print $g->as_plain;
660
662 Older versions of GraphViz used a slightly different syntax for node
663 and edge adding (with hash references). The new format is slightly
664 clearer, although for the moment we support both. Use the new, clear
665 syntax, please.
666
668 GraphViz::XML, GraphViz::Regex
669
671 Leon Brocard <acme@astray.com>
672
674 Copyright (C) 2000-4, Leon Brocard
675 This module is free software; you can redistribute it or modify it
677 under the same terms as Perl itself.
678perl v5.8.8 2004-12-02 GraphViz(3)