1GraphViz(3) User Contributed Perl Documentation GraphViz(3)
2
6 GraphViz - Interface to AT&T's GraphViz. Deprecated. See GraphViz2
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 GraphViz is deprecated in favour of GraphViz2.
31
33 Of course you need to install AT&T's Graphviz before using this module.
34 See <http://www.graphviz.org/Download.php>.
35 You are strongly advised to download the stable version of Graphviz,
37 because the development snapshots (click on 'Source code'), are
38 sometimes non-functional.
39 Install GraphViz as you would for any "Perl" module:
41 Run:
43 cpanm GraphViz
45 Note: cpanm ships in App::cpanminus. See also App::perlbrew.
47 or run:
49 sudo cpan GraphViz
51 or unpack the distro, and then either:
53 perl Build.PL
55 ./Build
56 ./Build test
57 sudo ./Build install
58 or:
60 perl Makefile.PL
62 make (or dmake or nmake)
63 make test
64 make install
65
67 Modules in this distro
68 o GraphViz
69 o GraphViz::No
70 o GraphViz::Small
71 o GraphViz::Regex
72 o GraphViz::XML
73 o GraphViz::Data::Grapher
74 o GraphViz::Parse::RecDescent
75 o GraphViz::Parse::Yacc
76 o GraphViz::Parse::Yapp
77 What is a graph?
79 A (undirected) graph is a collection of nodes linked together with
80 edges.
81 A directed graph is the same as a graph, but the edges have a
83 direction.
84 What is GraphViz?
86 This module is an interface to the GraphViz toolset
87 (http://www.graphviz.org/). The GraphViz tools provide automatic graph
88 layout and drawing. This module simplifies the creation of graphs and
89 hides some of the complexity of the GraphViz module.
90 Laying out graphs in an aesthetically-pleasing way is a hard problem -
92 there may be multiple ways to lay out the same graph, each with their
93 own quirks. GraphViz luckily takes part of this hard problem and does a
94 pretty good job in a couple of seconds for most graphs.
95 Why should I use this module?
97 Observation aids comprehension. That is a fancy way of expressing that
98 popular faux-Chinese proverb: "a picture is worth a thousand words".
99 Text is not always the best way to represent anything and everything to
101 do with a computer programs. Pictures and images are easier to
102 assimilate than text. The ability to show a particular thing
103 graphically can aid a great deal in comprehending what that thing
104 really represents.
105 Diagrams are computationally efficient, because information can be
107 indexed by location; they group related information in the same area.
108 They also allow relations to be expressed between elements without
109 labeling the elements.
110 A friend of mine used this to his advantage when trying to remember
112 important dates in computer history. Instead of sitting down and trying
113 to remember everything, he printed over a hundred posters (each with a
114 date and event) and plastered these throughout his house. His spatial
115 memory is still so good that asked last week (more than a year since
116 the experiment) when Lisp was invented, he replied that it was
117 upstairs, around the corner from the toilet, so must have been around
118 1958.
119 Spreadsheets are also a wonderfully simple graphical representation of
121 computational models.
122 Applications
124 Bundled with this module are several modules to help graph data
125 structures (GraphViz::Data::Dumper), XML (GraphViz::XML), and
126 Parse::RecDescent, Parse::Yapp, and yacc grammars
127 (GraphViz::Parse::RecDescent, GraphViz::Parse::Yapp, and
128 GraphViz::Parse::Yacc).
129 Note that Marcel Grunauer has released some modules on CPAN to graph
131 various other structures. See GraphViz::DBI and GraphViz::ISA for
132 example.
133 brian d foy has written an article about Devel::GraphVizProf for Dr.
135 Dobb's Journal:
136 http://www.ddj.com/columns/perl/2001/0104pl002/0104pl002.htm
137 Award winning!
139 I presented a paper and talk on "Graphing Perl" using GraphViz at the
140 3rd German Perl Workshop and received the "Best Knowledge Transfer"
141 prize.
142 Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf
144 Slides: http://www.astray.com/graphing_perl/
145
147 new
148 This is the constructor. It accepts several attributes.
149 my $g = GraphViz->new();
151 my $g = GraphViz->new(directed => 0);
152 my $g = GraphViz->new(layout => 'neato', ratio => 'compress');
153 my $g = GraphViz->new(rankdir => 'BT');
154 my $g = GraphViz->new(width => 8.5, height => 11);
155 my $g = GraphViz->new(width => 30, height => 20,
156 pagewidth => 8.5, pageheight => 11);
157 The most two important attributes are 'layout' and 'directed'.
159 layout
161 The 'layout' attribute determines which layout algorithm
162 GraphViz.pm will use. Possible values are:
163 dot The default GraphViz layout for directed graph layouts
165 neato
167 For undirected graph layouts - spring model
168 twopi
170 For undirected graph layouts - radial
171 circo
173 For undirected graph layouts - circular
174 fdp For undirected graph layouts - force directed spring model
176 directed
178 The 'directed' attribute, which defaults to 1 (true) specifies
179 directed (edges have arrows) graphs. Setting this to zero produces
180 undirected graphs (edges do not have arrows).
181 rankdir
183 Another attribute 'rankdir' controls the direction in which the
184 nodes are linked together. The default is 'TB' (arrows from top to
185 bottom). Other legal values are 'BT' (bottom->top), 'LR'
186 (left->right) and 'RL' (right->left).
187 width, height
189 The 'width' and 'height' attributes control the size of the
190 bounding box of the drawing in inches. This is more useful for
191 PostScript output as for raster graphic (such as PNG) the pixel
192 dimensions can not be set, although there are generally 96 pixels
193 per inch.
194 pagewidth, pageheight
196 The 'pagewidth' and 'pageheight' attributes set the PostScript
197 pagination size in inches. That is, if the image is larger than the
198 page then the resulting PostScript image is a sequence of pages
199 that can be tiled or assembled into a mosaic of the full image.
200 (This only works for PostScript output).
201 concentrate
203 The 'concentrate' attribute controls enables an edge merging
204 technique to reduce clutter in dense layouts of directed graphs.
205 The default is not to merge edges.
206 orientation
208 This option controls the angle, in degrees, used to rotate polygon
209 node shapes.
210 random_start
212 For undirected graphs, the 'random_start' attribute requests an
213 initial random placement for the graph, which may give a better
214 result. The default is not random.
215 epsilon
217 For undirected graphs, the 'epsilon' attribute decides how long the
218 graph solver tries before finding a graph layout. Lower numbers
219 allow the solver to fun longer and potentially give a better
220 layout. Larger values can decrease the running time but with a
221 reduction in layout quality. The default is 0.1.
222 overlap
224 The 'overlap' option allows you to set layout behavior for graph
225 nodes that overlap. (From GraphViz documentation:)
226 Determines if and how node overlaps should be removed.
228 true
230 (the default) overlaps are retained.
231 scale
233 overlaps are removed by uniformly scaling in x and y.
234 false
236 If the value converts to "false", node overlaps are removed by
237 a Voronoi-based technique.
238 scalexy
240 x and y are separately scaled to remove overlaps.
241 orthoxy, orthxy
243 If the value is "orthoxy" or "orthoyx", overlaps are moved by
244 optimizing two constraint problems, one for the x axis and one
245 for the y. The suffix indicates which axis is processed first.
246 NOTE: The methods related to "orthoxy" and "orthoyx" are still
248 evolving. The semantics of these may change, or these methods
249 may disappear altogether.
250 compress
252 If the value is "compress", the layout will be scaled down as
253 much as possible without introducing any overlaps.
254 Except for the Voronoi method, all of these transforms preserve the
256 orthogonal ordering of the original layout. That is, if the x
257 coordinates of two nodes are originally the same, they will remain
258 the same, and if the x coordinate of one node is originally less
259 than the x coordinate of another, this relation will still hold in
260 the transformed layout. The similar properties hold for the y
261 coordinates.
262 no_overlap
264 The 'no_overlap' overlap option, if set, tells the graph solver to
265 not overlap the nodes. Deprecated, Use 'overlap' => 'false'.
266 ratio
268 The 'ratio' option sets the aspect ratio (drawing height/drawing
269 width) for the drawing. Note that this is adjusted before the size
270 attribute constraints are enforced. Default value is "fill".
271 numeric
273 If ratio is numeric, it is taken as the desired aspect ratio.
274 Then, if the actual aspect ratio is less than the desired
275 ratio, the drawing height is scaled up to achieve the desired
276 ratio; if the actual ratio is greater than that desired ratio,
277 the drawing width is scaled up.
278 fill
280 If ratio = "fill" and the size attribute is set, node positions
281 are scaled, separately in both x and y, so that the final
282 drawing exactly fills the specified size.
283 compress
285 If ratio = "compress" and the size attribute is set, dot
286 attempts to compress the initial layout to fit in the given
287 size. This achieves a tighter packing of nodes but reduces the
288 balance and symmetry. This feature only works in dot.
289 expand
291 If ratio = "expand" the size attribute is set, and both the
292 width and the height of the graph are less than the value in
293 size, node positions are scaled uniformly until at least one
294 dimension fits size exactly. Note that this is distinct from
295 using size as the desired size, as here the drawing is expanded
296 before edges are generated and all node and text sizes remain
297 unchanged.
298 auto
300 If ratio = "auto" the page attribute is set and the graph
301 cannot be drawn on a single page, then size is set to an
302 ``ideal'' value. In particular, the size in a given dimension
303 will be the smallest integral multiple of the page size in that
304 dimension which is at least half the current size. The two
305 dimensions are then scaled independently to the new size. This
306 feature only works in dot.
307 bgcolor
309 The 'bgcolor' option sets the background colour. A colour value may
310 be "h,s,v" (hue, saturation, brightness) floating point numbers
311 between 0 and 1, or an X11 color name such as 'white', 'black',
312 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or
313 'burlywood'.
314 name
316 The 'name' option sets name of the graph. This option is useful in
317 few situations, like client side image map generation, see cmapx.
318 By default 'test' is used.
319 node,edge,graph
321 The 'node', 'edge' and 'graph' attributes allow you to specify
322 global node, edge and graph attributes (in addition to those
323 controlled by the special attributes described above). The value
324 should be a hash reference containing the corresponding key-value
325 pairs. For example, to make all nodes box-shaped (unless explicitly
326 given another shape):
327 my $g = GraphViz->new(node => {shape => 'box'});
329 add_node
331 A graph consists of at least one node. All nodes have a name attached
332 which uniquely represents that node.
333 The add_node method creates a new node and optionally assigns it
335 attributes.
336 The simplest form is used when no attributes are required, in which the
338 string represents the name of the node:
339 $g->add_node('Paris');
341 Various attributes are possible: "label" provides a label for the node
343 (the label defaults to the name if none is specified). The label can
344 contain embedded newlines with '\n', as well as '\c', '\l', '\r' for
345 center, left, and right justified lines:
346 $g->add_node('Paris', label => 'City of\nlurve');
348 Attributes need not all be specified in the one line: successive
350 declarations of the same node have a cumulative effect, in that any
351 later attributes are just added to the existing ones. For example, the
352 following two lines are equivalent to the one above:
353 $g->add_node('Paris');
355 $g->add_node('Paris', label => 'City of\nlurve');
356 Note that multiple attributes can be specified. Other attributes
358 include:
359 height, width
361 sets the minimum height or width
362 shape
364 sets the node shape. This can be one of: 'record', 'plaintext',
365 'ellipse', 'circle', 'egg', 'triangle', 'box', 'diamond',
366 'trapezium', 'parallelogram', 'house', 'hexagon', 'octagon'
367 fontsize
369 sets the label size in points
370 fontname
372 sets the label font family name
373 color
375 sets the outline colour, and the default fill colour if the 'style'
376 is 'filled' and 'fillcolor' is not specified
377 A colour value may be "h,s,v" (hue, saturation, brightness)
379 floating point numbers between 0 and 1, or an X11 color name such
380 as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
381 'cyan', or 'burlywood'
382 fillcolor
384 sets the fill colour when the style is 'filled'. If not specified,
385 the 'fillcolor' when the 'style' is 'filled' defaults to be the
386 same as the outline color
387 style
389 sets the style of the node. Can be one of: 'filled', 'solid',
390 'dashed', 'dotted', 'bold', 'invis'
391 URL sets the url for the node in image map and PostScript files. The
393 string '\N' value will be replaced by the node name. In PostScript
394 files, URL information is embedded in such a way that Acrobat
395 Distiller creates PDF files with active hyperlinks
396 If you wish to add an anonymous node, that is a node for which you do
398 not wish to generate a name, you may use the following form, where the
399 GraphViz module generates a name and returns it for you. You may then
400 use this name later on to refer to this node:
401 my $nodename = $g->add_node('label' => 'Roman city');
403 Nodes can be clustered together with the "cluster" attribute, which is
405 drawn by having a labelled rectangle around all the nodes in a cluster.
406 An empty string means not clustered.
407 $g->add_node('London', cluster => 'Europe');
409 $g->add_node('Amsterdam', cluster => 'Europe');
410 Clusters can also take a hashref so that you can set attributes:
412 my $eurocluster = {
414 name =>'Europe',
415 style =>'filled',
416 fillcolor =>'lightgray',
417 fontname =>'arial',
418 fontsize =>'12',
419 };
420 $g->add_node('London', cluster => $eurocluster, @default_attrs);
421 Nodes can be located in the same rank (that is, at the same level in
423 the graph) with the "rank" attribute. Nodes with the same rank value
424 are ranked together.
425 $g->add_node('Paris', rank => 'top');
427 $g->add_node('Boston', rank => 'top');
428 Also, nodes can consist of multiple parts (known as ports). This is
430 implemented by passing an array reference as the label, and the parts
431 are displayed as a label. GraphViz has a much more complete port
432 system, this is just a simple interface to it. See the 'from_port' and
433 'to_port' attributes of add_edge:
434 $g->add_node('London', label => ['Heathrow', 'Gatwick']);
436 add_edge
438 Edges are directed (or undirected) links between nodes. This method
439 creates a new edge between two nodes and optionally assigns it
440 attributes.
441 The simplest form is when now attributes are required, in which case
443 the nodes from and to which the edge should be are specified. This
444 works well visually in the program code:
445 $g->add_edge('London' => 'Paris');
447 Attributes such as 'label' can also be used. This specifies a label for
449 the edge. The label can contain embedded newlines with '\n', as well
450 as '\c', '\l', '\r' for center, left, and right justified lines.
451 $g->add_edge('London' => 'New York', label => 'Far');
453 Note that multiple attributes can be specified. Other attributes
455 include:
456 minlen
458 sets an integer factor that applies to the edge length (ranks for
459 normal edges, or minimum node separation for flat edges)
460 weight
462 sets the integer cost of the edge. Values greater than 1 tend to
463 shorten the edge. Weight 0 flat edges are ignored for ordering
464 nodes
465 fontsize
467 sets the label type size in points
468 fontname
470 sets the label font family name
471 fontcolor
473 sets the label text colour
474 color
476 sets the line colour for the edge
477 A colour value may be "h,s,v" (hue, saturation, brightness)
479 floating point numbers between 0 and 1, or an X11 color name such
480 as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
481 'cyan', or 'burlywood'
482 style
484 sets the style of the node. Can be one of: 'filled', 'solid',
485 'dashed', 'dotted', 'bold', 'invis'
486 dir sets the arrow direction. Can be one of: 'forward', 'back', 'both',
488 'none'
489 tailclip, headclip
491 when set to false disables endpoint shape clipping
492 arrowhead, arrowtail
494 sets the type for the arrow head or tail. Can be one of: 'none',
495 'normal', 'inv', 'dot', 'odot', 'invdot', 'invodot.'
496 arrowsize
498 sets the arrow size: (norm_length=10,norm_width=5,
499 inv_length=6,inv_width=7,dot_radius=2)
500 headlabel, taillabel
502 sets the text for port labels. Note that labelfontcolor,
503 labelfontname, labelfontsize are also allowed
504 labeldistance, port_label_distance
506 sets the distance from the edge / port to the label. Also
507 labelangle
508 decorate
510 if set, draws a line from the edge to the label
511 samehead, sametail
513 if set aim edges having the same value to the same port, using the
514 average landing point
515 constraint
517 if set to false causes an edge to be ignored for rank assignment
518 Additionally, adding edges between ports of a node is done via the
520 'from_port' and 'to_port' parameters, which currently takes in the
521 offset of the port (ie 0, 1, 2...).
522 $g->add_edge('London' => 'Paris', from_port => 0);
524 as_canon, as_text, as_gif etc. methods
526 There are a number of methods which generate input for dot / neato /
527 twopi / circo / fdp or output the graph in a variety of formats.
528 Note that if you pass a filename, the data is written to that filename.
530 If you pass a filehandle, the data will be streamed to the filehandle.
531 If you pass a scalar reference, then the data will be stored in that
532 scalar. If you pass it a code reference, then it is called with the
533 data (note that the coderef may be called multiple times if the image
534 is large). Otherwise, the data is returned:
535 Win32 Note: you will probably want to binmode any filehandles you write
537 the output to if you want your application to be portable to Win32.
538 my $png_image = $g->as_png;
540 # or
541 $g->as_png("pretty.png"); # save image
542 # or
543 $g->as_png(\*STDOUT); # stream image to a filehandle
544 # or
545 #g->as_png(\$text); # save data in a scalar
546 # or
547 $g->as_png(sub { $png_image .= shift });
548 as_debug
550 The as_debug method returns the dot file which we pass to GraphViz.
551 It does not lay out the graph. This is mostly useful for debugging.
552 print $g->as_debug;
554 as_canon
556 The as_canon method returns the canonical dot / neato / twopi /
557 circo / fdp file which corresponds to the graph. It does not
558 layout the graph - every other as_* method does.
559 print $g->as_canon;
561 # prints out something like:
564 digraph test {
565 node [ label = "\N" ];
566 London [label=London];
567 Paris [label="City of\nlurve"];
568 New_York [label="New York"];
569 London -> Paris;
570 London -> New_York [label=Far];
571 Paris -> London;
572 }
573 as_text
575 The as_text method returns text which is a layed-out dot / neato /
576 twopi / circo / fdp format file.
577 print $g->as_text;
579 # prints out something like:
581 digraph test {
582 node [ label = "\N" ];
583 graph [bb= "0,0,162,134"];
584 London [label=London, pos="33,116", width="0.89", height="0.50"];
585 Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
586 New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
587 London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
588 London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
589 Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
590 }
591 as_ps
593 Returns a string which contains a layed-out PostScript-format file.
594 print $g->as_ps;
596 as_hpgl
598 Returns a string which contains a layed-out HP pen plotter-format
599 file.
600 print $g->as_hpgl;
602 as_pcl
604 Returns a string which contains a layed-out Laserjet printer-format
605 file.
606 print $g->as_pcl;
608 as_mif
610 Returns a string which contains a layed-out FrameMaker graphics-
611 format file.
612 print $g->as_mif;
614 as_pic
616 Returns a string which contains a layed-out PIC-format file.
617 print $g->as_pic;
619 as_gd
621 Returns a string which contains a layed-out GD-format file.
622 print $g->as_gd;
624 as_gd2
626 Returns a string which contains a layed-out GD2-format file.
627 print $g->as_gd2;
629 as_gif
631 Returns a string which contains a layed-out GIF-format file.
632 print $g->as_gif;
634 as_jpeg
636 Returns a string which contains a layed-out JPEG-format file.
637 print $g->as_jpeg;
639 as_png
641 Returns a string which contains a layed-out PNG-format file.
642 print $g->as_png;
644 $g->as_png("pretty.png"); # save image
645 as_wbmp
647 Returns a string which contains a layed-out Windows BMP-format
648 file.
649 print $g->as_wbmp;
651 as_cmap (deprecated)
653 Returns a string which contains a layed-out HTML client-side image
654 map format file. Use as_cmapx instead.
655 print $g->as_cmap;
657 as_cmapx
659 Returns a string which contains a layed-out HTML HTML/X client-side
660 image map format file. Name and id attributes of map element are
661 set to name of the graph.
662 print $g->as_cmapx;
664 as_ismap (deprecated)
666 Returns a string which contains a layed-out old-style server-side
667 image map format file. Use as_imap instead.
668 print $g->as_ismap;
670 as_imap
672 Returns a string which contains a layed-out HTML new-style server-
673 side image map format file.
674 print $g->as_imap;
676 as_vdx
678 Returns a string which contains a VDX-format (Microsoft Visio)
679 file.
680 print $g->as_vdx;
682 as_vrml
684 Returns a string which contains a layed-out VRML-format file.
685 print $g->as_vrml;
687 as_vtx
689 Returns a string which contains a layed-out VTX (Visual Thought)
690 format file.
691 print $g->as_vtx;
693 as_mp
695 Returns a string which contains a layed-out MetaPost-format file.
696 print $g->as_mp;
698 as_fig
700 Returns a string which contains a layed-out FIG-format file.
701 print $g->as_fig;
703 as_svg
705 Returns a string which contains a layed-out SVG-format file.
706 print $g->as_svg;
708 as_svgz
710 Returns a string which contains a layed-out SVG-format file that is
711 compressed.
712 print $g->as_svgz;
714 as_plain
716 Returns a string which contains a layed-out simple-format file.
717 print $g->as_plain;
719
721 Why do I get error messages like the following?
722 Error: <stdin>:1: syntax error near line 1
723 context: digraph >>> Graph <<< {
724 Graphviz reserves some words as keywords, meaning they can't be used as
726 an ID, e.g. for the name of the graph. So, don't do this:
727 strict graph graph{...}
729 strict graph Graph{...}
730 strict graph strict{...}
731 etc...
732 Likewise for non-strict graphs, and digraphs. You can however add
734 double-quotes around such reserved words:
735 strict graph "graph"{...}
737 Even better, use a more meaningful name for your graph...
739 The keywords are: node, edge, graph, digraph, subgraph and strict.
741 Compass points are not keywords.
742 See keywords <http://www.graphviz.org/content/dot-language> in the
744 discussion of the syntax of DOT for details.
745 How do you handle XXE within XML?
747 Due to security risks with XXE in XML, Graphviz does not support XML
748 that contains XXE. Thus it automatically prevents external entities
749 being parsed by using the no_xxe option in XML::Twig when calling
750 XML::Twig -> new(). And for this reason also the pre-reqs in
751 Makefile.PL specify XML::Twig V 3.52.
752 See
754 <https://metacpan.org/pod/release/MIROD/XML-Twig-3.52/Twig.pm#no_xxe>
755
757 Older versions of GraphViz used a slightly different syntax for node
758 and edge adding (with hash references). The new format is slightly
759 clearer, although for the moment we support both. Use the new, clear
760 syntax, please.
761
763 GraphViz is deprecated in favour of GraphViz2.
764
766 The file Changes was converted into Changelog.ini by
767 Module::Metadata::Changes.
768
770 <https://github.com/ronsavage/GraphViz>
771
773 Leon Brocard: <acme@astray.com>.
774 Current maintainer: Ron Savage <ron@savage.net.au>.
776 My homepage: <http://savage.net.au/>.
778
780 Copyright (C) 2000-4, Leon Brocard
781
783 This module is free software; you can redistribute it or modify it
784 under the Perl License, a copy of which is available at
785 <http://dev.perl.org/licenses/>.
786perl v5.30.1 2020-01-30 GraphViz(3)