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"
27 programs 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
32 edges.
33 A directed graph is the same as a graph, but the edges have a
35 direction.
36 What is GraphViz?
38 This module is an interface to the GraphViz toolset
39 (http://www.graphviz.org/). The GraphViz tools provide automatic graph
40 layout and drawing. This module simplifies the creation of graphs and
41 hides some of the complexity of the GraphViz module.
42 Laying out graphs in an aesthetically-pleasing way is a hard problem -
44 there may be multiple ways to lay out the same graph, each with their
45 own quirks. GraphViz luckily takes part of this hard problem and does a
46 pretty good job in a couple of seconds for most graphs.
47 Why should I use this module?
49 Observation aids comprehension. That is a fancy way of expressing that
50 popular faux-Chinese proverb: "a picture is worth a thousand words".
51 Text is not always the best way to represent anything and everything to
53 do with a computer programs. Pictures and images are easier to
54 assimilate than text. The ability to show a particular thing
55 graphically can aid a great deal in comprehending what that thing
56 really represents.
57 Diagrams are computationally efficient, because information can be
59 indexed by location; they group related information in the same area.
60 They also allow relations to be expressed between elements without
61 labeling the elements.
62 A friend of mine used this to his advantage when trying to remember
64 important dates in computer history. Instead of sitting down and trying
65 to remember everything, he printed over a hundred posters (each with a
66 date and event) and plastered these throughout his house. His spatial
67 memory is still so good that asked last week (more than a year since
68 the experiment) when Lisp was invented, he replied that it was
69 upstairs, around the corner from the toilet, so must have been around
70 1958.
71 Spreadsheets are also a wonderfully simple graphical representation of
73 computational models.
74 Applications
76 Bundled with this module are several modules to help graph data
77 structures (GraphViz::Data::Dumper), XML (GraphViz::XML), and
78 Parse::RecDescent, Parse::Yapp, and yacc grammars
79 (GraphViz::Parse::RecDescent, GraphViz::Parse::Yapp, and
80 GraphViz::Parse::Yacc).
81 Note that Marcel Grunauer has released some modules on CPAN to graph
83 various other structures. See GraphViz::DBI and GraphViz::ISA for
84 example.
85 brian d foy has written an article about Devel::GraphVizProf for Dr.
87 Dobb's Journal:
88 http://www.ddj.com/columns/perl/2001/0104pl002/0104pl002.htm
89 Award winning!
91 I presented a paper and talk on "Graphing Perl" using GraphViz at the
92 3rd German Perl Workshop and received the "Best Knowledge Transfer"
93 prize.
94 Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf
96 Slides: http://www.astray.com/graphing_perl/
97
99 new
100 This is the constructor. It accepts several attributes.
101 my $g = GraphViz->new();
103 my $g = GraphViz->new(directed => 0);
104 my $g = GraphViz->new(layout => 'neato', ratio => 'compress');
105 my $g = GraphViz->new(rankdir => 1);
106 my $g = GraphViz->new(width => 8.5, height => 11);
107 my $g = GraphViz->new(width => 30, height => 20,
108 pagewidth => 8.5, pageheight => 11);
109 The most two important attributes are 'layout' and 'directed'.
111 layout
113 The 'layout' attribute determines which layout algorithm
114 GraphViz.pm will use. Possible values are:
115 dot The default GraphViz layout for directed graph layouts
117 neato
119 For undirected graph layouts - spring model
120 twopi
122 For undirected graph layouts - radial
123 circo
125 For undirected graph layouts - circular
126 fdp For undirected graph layouts - force directed spring model
128 directed
130 The 'directed' attribute, which defaults to 1 (true) specifies
131 directed (edges have arrows) graphs. Setting this to zero produces
132 undirected graphs (edges do not have arrows).
133 rankdir
135 Another attribute 'rankdir' controls the direction the nodes are
136 linked together. If true it will do left->right linking rather than
137 the default up-down linking.
138 width, height
140 The 'width' and 'height' attributes control the size of the
141 bounding box of the drawing in inches. This is more useful for
142 PostScript output as for raster graphic (such as PNG) the pixel
143 dimensions can not be set, although there are generally 96 pixels
144 per inch.
145 pagewidth, pageheight
147 The 'pagewidth' and 'pageheight' attributes set the PostScript
148 pagination size in inches. That is, if the image is larger than the
149 page then the resulting PostScript image is a sequence of pages
150 that can be tiled or assembled into a mosaic of the full image.
151 (This only works for PostScript output).
152 concentrate
154 The 'concentrate' attribute controls enables an edge merging
155 technique to reduce clutter in dense layouts of directed graphs.
156 The default is not to merge edges.
157 random_start
159 For undirected graphs, the 'random_start' attribute requests an
160 initial random placement for the graph, which may give a better
161 result. The default is not random.
162 epsilon
164 For undirected graphs, the 'epsilon' attribute decides how long the
165 graph solver tries before finding a graph layout. Lower numbers
166 allow the solver to fun longer and potentially give a better
167 layout. Larger values can decrease the running time but with a
168 reduction in layout quality. The default is 0.1.
169 overlap
171 The 'overlap' option allows you to set layout behavior for graph
172 nodes that overlap. (From GraphViz documentation:)
173 Determines if and how node overlaps should be removed.
175 true
177 (the default) overlaps are retained.
178 scale
180 overlaps are removed by uniformly scaling in x and y.
181 false
183 If the value converts to "false", node overlaps are removed by
184 a Voronoi-based technique.
185 scalexy
187 x and y are separately scaled to remove overlaps.
188 orthoxy, orthxy
190 If the value is "orthoxy" or "orthoyx", overlaps are moved by
191 optimizing two constraint problems, one for the x axis and one
192 for the y. The suffix indicates which axis is processed first.
193 NOTE: The methods related to "orthoxy" and "orthoyx" are still
195 evolving. The semantics of these may change, or these methods
196 may disappear altogether.
197 compress
199 If the value is "compress", the layout will be scaled down as
200 much as possible without introducing any overlaps.
201 Except for the Voronoi method, all of these transforms preserve the
203 orthogonal ordering of the original layout. That is, if the x
204 coordinates of two nodes are originally the same, they will remain
205 the same, and if the x coordinate of one node is originally less
206 than the x coordinate of another, this relation will still hold in
207 the transformed layout. The similar properties hold for the y
208 coordinates.
209 no_overlap
211 The 'no_overlap' overlap option, if set, tells the graph solver to
212 not overlap the nodes. Deprecated, Use 'overlap' => 'false'.
213 ratio
215 The 'ratio' option sets the aspect ratio (drawing height/drawing
216 width) for the drawing. Note that this is adjusted before the size
217 attribute constraints are enforced. Default value is "fill".
218 numeric
220 If ratio is numeric, it is taken as the desired aspect ratio.
221 Then, if the actual aspect ratio is less than the desired
222 ratio, the drawing height is scaled up to achieve the desired
223 ratio; if the actual ratio is greater than that desired ratio,
224 the drawing width is scaled up.
225 fill
227 If ratio = "fill" and the size attribute is set, node positions
228 are scaled, separately in both x and y, so that the final
229 drawing exactly fills the specified size.
230 compress
232 If ratio = "compress" and the size attribute is set, dot
233 attempts to compress the initial layout to fit in the given
234 size. This achieves a tighter packing of nodes but reduces the
235 balance and symmetry. This feature only works in dot.
236 expand
238 If ratio = "expand" the size attribute is set, and both the
239 width and the height of the graph are less than the value in
240 size, node positions are scaled uniformly until at least one
241 dimension fits size exactly. Note that this is distinct from
242 using size as the desired size, as here the drawing is expanded
243 before edges are generated and all node and text sizes remain
244 unchanged.
245 auto
247 If ratio = "auto" the page attribute is set and the graph
248 cannot be drawn on a single page, then size is set to an
249 ``ideal'' value. In particular, the size in a given dimension
250 will be the smallest integral multiple of the page size in that
251 dimension which is at least half the current size. The two
252 dimensions are then scaled independently to the new size. This
253 feature only works in dot.
254 bgcolor
256 The 'bgcolor' option sets the background colour. A colour value may
257 be "h,s,v" (hue, saturation, brightness) floating point numbers
258 between 0 and 1, or an X11 color name such as 'white', 'black',
259 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or
260 'burlywood'.
261 name
263 The 'name' option sets name of the graph. This option is useful in
264 few situations, like client side image map generation, see cmapx.
265 By default 'test' is used.
266 node,edge,graph
268 The 'node', 'edge' and 'graph' attributes allow you to specify
269 global node, edge and graph attributes (in addition to those
270 controlled by the special attributes described above). The value
271 should be a hash reference containing the corresponding key-value
272 pairs. For example, to make all nodes box-shaped (unless explicity
273 given another shape):
274 my $g = GraphViz->new(node => {shape => 'box'});
276 add_node
278 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
297 declarations of the same node have a cumulative effect, in that any
298 later attributes are just added to the existing ones. For example, the
299 following 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',
313 'trapezium', '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)
326 floating point numbers between 0 and 1, or an X11 color name such
327 as '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
342 Distiller 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
379 system, 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
386 creates a new edge between two nodes and optionally assigns it
387 attributes.
388 The simplest form is when now attributes are required, in which case
390 the nodes from and to which the edge should be are specified. This
391 works well visually in the program code:
392 $g->add_edge('London' => 'Paris');
394 Attributes such as 'label' can also be used. This specifies a label for
396 the edge. The label can contain embedded newlines with '\n', as well
397 as '\c', '\l', '\r' for center, left, and right justified lines.
398 $g->add_edge('London' => 'New York', label => 'Far');
400 Note that multiple attributes can be specified. Other attributes
402 include:
403 minlen
405 sets an integer factor that applies to the edge length (ranks for
406 normal edges, or minimum node separation for flat edges)
407 weight
409 sets the integer cost of the edge. Values greater than 1 tend to
410 shorten the edge. Weight 0 flat edges are ignored for ordering
411 nodes
412 fontsize
414 sets the label type size in points
415 fontname
417 sets the label font family name
418 fontcolor
420 sets the label text colour
421 color
423 sets the line colour for the edge
424 A colour value may be "h,s,v" (hue, saturation, brightness)
426 floating point numbers between 0 and 1, or an X11 color name such
427 as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
428 'cyan', or 'burlywood'
429 style
431 sets the style of the node. Can be one of: 'filled', 'solid',
432 'dashed', 'dotted', 'bold', 'invis'
433 dir sets the arrow direction. Can be one of: 'forward', 'back', 'both',
435 'none'
436 tailclip, headclip
438 when set to false disables endpoint shape clipping
439 arrowhead, arrowtail
441 sets the type for the arrow head or tail. Can be one of: 'none',
442 'normal', 'inv', 'dot', 'odot', 'invdot', 'invodot.'
443 arrowsize
445 sets the arrow size: (norm_length=10,norm_width=5,
446 inv_length=6,inv_width=7,dot_radius=2)
447 headlabel, taillabel
449 sets the text for port labels. Note that labelfontcolor,
450 labelfontname, labelfontsize are also allowed
451 labeldistance, port_label_distance
453 sets the distance from the edge / port to the label. Also
454 labelangle
455 decorateP
457 if set, draws a line from the edge to the label
458 samehead, sametail
460 if set aim edges having the same value to the same port, using the
461 average landing point
462 constraint
464 if set to false causes an edge to be ignored for rank assignment
465 Additionally, adding edges between ports of a node is done via the
467 'from_port' and 'to_port' parameters, which currently takes in the
468 offset of the port (ie 0, 1, 2...).
469 $g->add_edge('London' => 'Paris', from_port => 0);
471 as_canon, as_text, as_gif etc. methods
473 There are a number of methods which generate input for dot / neato /
474 twopi / circo / fdp or output the graph in a variety of formats.
475 Note that if you pass a filename, the data is written to that filename.
477 If you pass a filehandle, the data will be streamed to the filehandle.
478 If you pass a scalar reference, then the data will be stored in that
479 scalar. If you pass it a code reference, then it is called with the
480 data (note that the coderef may be called multiple times if the image
481 is large). Otherwise, the data is returned:
482 Win32 Note: you will probably want to binmode any filehandles you write
484 the output to if you want your application to be portable to Win32.
485 my $png_image = $g->as_png;
487 # or
488 $g->as_png("pretty.png"); # save image
489 # or
490 $g->as_png(\*STDOUT); # stream image to a filehandle
491 # or
492 #g->as_png(\$text); # save data in a scalar
493 # or
494 $g->as_png(sub { $png_image .= shift });
495 as_debug
497 The as_debug method returns the dot file which we pass to GraphViz.
498 It does not lay out the graph. This is mostly useful for debugging.
499 print $g->as_debug;
501 as_canon
503 The as_canon method returns the canonical dot / neato / twopi /
504 circo / fdp file which corresponds to the graph. It does not
505 layout the graph - every other as_* method does.
506 print $g->as_canon;
508 # prints out something like:
511 digraph test {
512 node [ label = "\N" ];
513 London [label=London];
514 Paris [label="City of\nlurve"];
515 New_York [label="New York"];
516 London -> Paris;
517 London -> New_York [label=Far];
518 Paris -> London;
519 }
520 as_text
522 The as_text method returns text which is a layed-out dot / neato /
523 twopi / circo / fdp format file.
524 print $g->as_text;
526 # prints out something like:
528 digraph test {
529 node [ label = "\N" ];
530 graph [bb= "0,0,162,134"];
531 London [label=London, pos="33,116", width="0.89", height="0.50"];
532 Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
533 New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
534 London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
535 London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
536 Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
537 }
538 as_ps
540 Returns a string which contains a layed-out PostScript-format file.
541 print $g->as_ps;
543 as_hpgl
545 Returns a string which contains a layed-out HP pen plotter-format
546 file.
547 print $g->as_hpgl;
549 as_pcl
551 Returns a string which contains a layed-out Laserjet printer-format
552 file.
553 print $g->as_pcl;
555 as_mif
557 Returns a string which contains a layed-out FrameMaker graphics-
558 format file.
559 print $g->as_mif;
561 as_pic
563 Returns a string which contains a layed-out PIC-format file.
564 print $g->as_pic;
566 as_gd
568 Returns a string which contains a layed-out GD-format file.
569 print $g->as_gd;
571 as_gd2
573 Returns a string which contains a layed-out GD2-format file.
574 print $g->as_gd2;
576 as_gif
578 Returns a string which contains a layed-out GIF-format file.
579 print $g->as_gif;
581 as_jpeg
583 Returns a string which contains a layed-out JPEG-format file.
584 print $g->as_jpeg;
586 as_png
588 Returns a string which contains a layed-out PNG-format file.
589 print $g->as_png;
591 $g->as_png("pretty.png"); # save image
592 as_wbmp
594 Returns a string which contains a layed-out Windows BMP-format
595 file.
596 print $g->as_wbmp;
598 as_cmap (deprecated)
600 Returns a string which contains a layed-out HTML client-side image
601 map format file. Use as_cmapx instead.
602 print $g->as_cmap;
604 as_cmapx
606 Returns a string which contains a layed-out HTML HTML/X client-side
607 image map format file. Name and id attributes of map element are
608 set to name of the graph.
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
677 This module is free software; you can redistribute it or modify it
678 under the same terms as Perl itself.
679perl v5.12.0 2008-12-12 GraphViz(3)