GraphViz(3) User Contributed Perl Documentation GraphViz(3)NAMEGraphViz - Interface to AT&T's GraphViz. Deprecated. See GraphViz2
SYNOPSIS
use GraphViz;
my $g = GraphViz->new();
$g->add_node('London');
$g->add_node('Paris', label => 'City of\nlurve');
$g->add_node('New York');
$g->add_edge('London' => 'Paris');
$g->add_edge('London' => 'New York', label => 'Far');
$g->add_edge('Paris' => 'London');
print $g->as_png;
DESCRIPTION
This module provides an interface to layout and image generation of
directed and undirected graphs in a variety of formats (PostScript,
PNG, etc.) using the "dot", "neato", "twopi", "circo" and "fdp"
programs from the GraphViz project (http://www.graphviz.org/ or
http://www.research.att.com/sw/tools/graphviz/).
GraphViz is deprecated in favour of GraphViz2.
Modules in this distro
o GraphViz
o GraphViz::No
o GraphViz::Small
o GraphViz::Regex
o GraphViz::XML
o GraphViz::Data::Grapher
o GraphViz::Parse::RecDescent
o GraphViz::Parse::Yacc
o GraphViz::Parse::Yapp
What is a graph?
A (undirected) graph is a collection of nodes linked together with
edges.
A directed graph is the same as a graph, but the edges have a
direction.
What is GraphViz?
This module is an interface to the GraphViz toolset
(http://www.graphviz.org/). The GraphViz tools provide automatic graph
layout and drawing. This module simplifies the creation of graphs and
hides some of the complexity of the GraphViz module.
Laying out graphs in an aesthetically-pleasing way is a hard problem -
there may be multiple ways to lay out the same graph, each with their
own quirks. GraphViz luckily takes part of this hard problem and does a
pretty good job in a couple of seconds for most graphs.
Why should I use this module?
Observation aids comprehension. That is a fancy way of expressing that
popular faux-Chinese proverb: "a picture is worth a thousand words".
Text is not always the best way to represent anything and everything to
do with a computer programs. Pictures and images are easier to
assimilate than text. The ability to show a particular thing
graphically can aid a great deal in comprehending what that thing
really represents.
Diagrams are computationally efficient, because information can be
indexed by location; they group related information in the same area.
They also allow relations to be expressed between elements without
labeling the elements.
A friend of mine used this to his advantage when trying to remember
important dates in computer history. Instead of sitting down and trying
to remember everything, he printed over a hundred posters (each with a
date and event) and plastered these throughout his house. His spatial
memory is still so good that asked last week (more than a year since
the experiment) when Lisp was invented, he replied that it was
upstairs, around the corner from the toilet, so must have been around
1958.
Spreadsheets are also a wonderfully simple graphical representation of
computational models.
Applications
Bundled with this module are several modules to help graph data
structures (GraphViz::Data::Dumper), XML (GraphViz::XML), and
Parse::RecDescent, Parse::Yapp, and yacc grammars
(GraphViz::Parse::RecDescent, GraphViz::Parse::Yapp, and
GraphViz::Parse::Yacc).
Note that Marcel Grunauer has released some modules on CPAN to graph
various other structures. See GraphViz::DBI and GraphViz::ISA for
example.
brian d foy has written an article about Devel::GraphVizProf for Dr.
Dobb's Journal:
http://www.ddj.com/columns/perl/2001/0104pl002/0104pl002.htm
Award winning!
I presented a paper and talk on "Graphing Perl" using GraphViz at the
3rd German Perl Workshop and received the "Best Knowledge Transfer"
prize.
Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf
Slides: http://www.astray.com/graphing_perl/
METHODS
new
This is the constructor. It accepts several attributes.
my $g = GraphViz->new();
my $g = GraphViz->new(directed => 0);
my $g = GraphViz->new(layout => 'neato', ratio => 'compress');
my $g = GraphViz->new(rankdir => 'BT');
my $g = GraphViz->new(width => 8.5, height => 11);
my $g = GraphViz->new(width => 30, height => 20,
pagewidth => 8.5, pageheight => 11);
The most two important attributes are 'layout' and 'directed'.
layout
The 'layout' attribute determines which layout algorithm
GraphViz.pm will use. Possible values are:
dot The default GraphViz layout for directed graph layouts
neato
For undirected graph layouts - spring model
twopi
For undirected graph layouts - radial
circo
For undirected graph layouts - circular
fdp For undirected graph layouts - force directed spring model
directed
The 'directed' attribute, which defaults to 1 (true) specifies
directed (edges have arrows) graphs. Setting this to zero produces
undirected graphs (edges do not have arrows).
rankdir
Another attribute 'rankdir' controls the direction in which the
nodes are linked together. The default is 'TB' (arrows from top to
bottom). Other legal values are 'BT' (bottom->top), 'LR'
(left->right) and 'RL' (right->left).
width, height
The 'width' and 'height' attributes control the size of the
bounding box of the drawing in inches. This is more useful for
PostScript output as for raster graphic (such as PNG) the pixel
dimensions can not be set, although there are generally 96 pixels
per inch.
pagewidth, pageheight
The 'pagewidth' and 'pageheight' attributes set the PostScript
pagination size in inches. That is, if the image is larger than the
page then the resulting PostScript image is a sequence of pages
that can be tiled or assembled into a mosaic of the full image.
(This only works for PostScript output).
concentrate
The 'concentrate' attribute controls enables an edge merging
technique to reduce clutter in dense layouts of directed graphs.
The default is not to merge edges.
orientation
This option controls the angle, in degrees, used to rotate polygon
node shapes.
random_start
For undirected graphs, the 'random_start' attribute requests an
initial random placement for the graph, which may give a better
result. The default is not random.
epsilon
For undirected graphs, the 'epsilon' attribute decides how long the
graph solver tries before finding a graph layout. Lower numbers
allow the solver to fun longer and potentially give a better
layout. Larger values can decrease the running time but with a
reduction in layout quality. The default is 0.1.
overlap
The 'overlap' option allows you to set layout behavior for graph
nodes that overlap. (From GraphViz documentation:)
Determines if and how node overlaps should be removed.
true
(the default) overlaps are retained.
scale
overlaps are removed by uniformly scaling in x and y.
false
If the value converts to "false", node overlaps are removed by
a Voronoi-based technique.
scalexy
x and y are separately scaled to remove overlaps.
orthoxy, orthxy
If the value is "orthoxy" or "orthoyx", overlaps are moved by
optimizing two constraint problems, one for the x axis and one
for the y. The suffix indicates which axis is processed first.
NOTE: The methods related to "orthoxy" and "orthoyx" are still
evolving. The semantics of these may change, or these methods
may disappear altogether.
compress
If the value is "compress", the layout will be scaled down as
much as possible without introducing any overlaps.
Except for the Voronoi method, all of these transforms preserve the
orthogonal ordering of the original layout. That is, if the x
coordinates of two nodes are originally the same, they will remain
the same, and if the x coordinate of one node is originally less
than the x coordinate of another, this relation will still hold in
the transformed layout. The similar properties hold for the y
coordinates.
no_overlap
The 'no_overlap' overlap option, if set, tells the graph solver to
not overlap the nodes. Deprecated, Use 'overlap' => 'false'.
ratio
The 'ratio' option sets the aspect ratio (drawing height/drawing
width) for the drawing. Note that this is adjusted before the size
attribute constraints are enforced. Default value is "fill".
numeric
If ratio is numeric, it is taken as the desired aspect ratio.
Then, if the actual aspect ratio is less than the desired
ratio, the drawing height is scaled up to achieve the desired
ratio; if the actual ratio is greater than that desired ratio,
the drawing width is scaled up.
fill
If ratio = "fill" and the size attribute is set, node positions
are scaled, separately in both x and y, so that the final
drawing exactly fills the specified size.
compress
If ratio = "compress" and the size attribute is set, dot
attempts to compress the initial layout to fit in the given
size. This achieves a tighter packing of nodes but reduces the
balance and symmetry. This feature only works in dot.
expand
If ratio = "expand" the size attribute is set, and both the
width and the height of the graph are less than the value in
size, node positions are scaled uniformly until at least one
dimension fits size exactly. Note that this is distinct from
using size as the desired size, as here the drawing is expanded
before edges are generated and all node and text sizes remain
unchanged.
auto
If ratio = "auto" the page attribute is set and the graph
cannot be drawn on a single page, then size is set to an
``ideal'' value. In particular, the size in a given dimension
will be the smallest integral multiple of the page size in that
dimension which is at least half the current size. The two
dimensions are then scaled independently to the new size. This
feature only works in dot.
bgcolor
The 'bgcolor' option sets the background colour. A colour value may
be "h,s,v" (hue, saturation, brightness) floating point numbers
between 0 and 1, or an X11 color name such as 'white', 'black',
'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or
'burlywood'.
name
The 'name' option sets name of the graph. This option is useful in
few situations, like client side image map generation, see cmapx.
By default 'test' is used.
node,edge,graph
The 'node', 'edge' and 'graph' attributes allow you to specify
global node, edge and graph attributes (in addition to those
controlled by the special attributes described above). The value
should be a hash reference containing the corresponding key-value
pairs. For example, to make all nodes box-shaped (unless explicity
given another shape):
my $g = GraphViz->new(node => {shape => 'box'});
add_node
A graph consists of at least one node. All nodes have a name attached
which uniquely represents that node.
The add_node method creates a new node and optionally assigns it
attributes.
The simplest form is used when no attributes are required, in which the
string represents the name of the node:
$g->add_node('Paris');
Various attributes are possible: "label" provides a label for the node
(the label defaults to the name if none is specified). The label can
contain embedded newlines with '\n', as well as '\c', '\l', '\r' for
center, left, and right justified lines:
$g->add_node('Paris', label => 'City of\nlurve');
Attributes need not all be specified in the one line: successive
declarations of the same node have a cumulative effect, in that any
later attributes are just added to the existing ones. For example, the
following two lines are equivalent to the one above:
$g->add_node('Paris');
$g->add_node('Paris', label => 'City of\nlurve');
Note that multiple attributes can be specified. Other attributes
include:
height, width
sets the minimum height or width
shape
sets the node shape. This can be one of: 'record', 'plaintext',
'ellipse', 'circle', 'egg', 'triangle', 'box', 'diamond',
'trapezium', 'parallelogram', 'house', 'hexagon', 'octagon'
fontsize
sets the label size in points
fontname
sets the label font family name
color
sets the outline colour, and the default fill colour if the 'style'
is 'filled' and 'fillcolor' is not specified
A colour value may be "h,s,v" (hue, saturation, brightness)
floating point numbers between 0 and 1, or an X11 color name such
as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
'cyan', or 'burlywood'
fillcolor
sets the fill colour when the style is 'filled'. If not specified,
the 'fillcolor' when the 'style' is 'filled' defaults to be the
same as the outline color
style
sets the style of the node. Can be one of: 'filled', 'solid',
'dashed', 'dotted', 'bold', 'invis'
URL sets the url for the node in image map and PostScript files. The
string '\N' value will be replaced by the node name. In PostScript
files, URL information is embedded in such a way that Acrobat
Distiller creates PDF files with active hyperlinks
If you wish to add an anonymous node, that is a node for which you do
not wish to generate a name, you may use the following form, where the
GraphViz module generates a name and returns it for you. You may then
use this name later on to refer to this node:
my $nodename = $g->add_node('label' => 'Roman city');
Nodes can be clustered together with the "cluster" attribute, which is
drawn by having a labelled rectangle around all the nodes in a cluster.
An empty string means not clustered.
$g->add_node('London', cluster => 'Europe');
$g->add_node('Amsterdam', cluster => 'Europe');
Clusters can also take a hashref so that you can set attributes:
my $eurocluster = {
name =>'Europe',
style =>'filled',
fillcolor =>'lightgray',
fontname =>'arial',
fontsize =>'12',
};
$g->add_node('London', cluster => $eurocluster, @default_attrs);
Nodes can be located in the same rank (that is, at the same level in
the graph) with the "rank" attribute. Nodes with the same rank value
are ranked together.
$g->add_node('Paris', rank => 'top');
$g->add_node('Boston', rank => 'top');
Also, nodes can consist of multiple parts (known as ports). This is
implemented by passing an array reference as the label, and the parts
are displayed as a label. GraphViz has a much more complete port
system, this is just a simple interface to it. See the 'from_port' and
'to_port' attributes of add_edge:
$g->add_node('London', label => ['Heathrow', 'Gatwick']);
add_edge
Edges are directed (or undirected) links between nodes. This method
creates a new edge between two nodes and optionally assigns it
attributes.
The simplest form is when now attributes are required, in which case
the nodes from and to which the edge should be are specified. This
works well visually in the program code:
$g->add_edge('London' => 'Paris');
Attributes such as 'label' can also be used. This specifies a label for
the edge. The label can contain embedded newlines with '\n', as well
as '\c', '\l', '\r' for center, left, and right justified lines.
$g->add_edge('London' => 'New York', label => 'Far');
Note that multiple attributes can be specified. Other attributes
include:
minlen
sets an integer factor that applies to the edge length (ranks for
normal edges, or minimum node separation for flat edges)
weight
sets the integer cost of the edge. Values greater than 1 tend to
shorten the edge. Weight 0 flat edges are ignored for ordering
nodes
fontsize
sets the label type size in points
fontname
sets the label font family name
fontcolor
sets the label text colour
color
sets the line colour for the edge
A colour value may be "h,s,v" (hue, saturation, brightness)
floating point numbers between 0 and 1, or an X11 color name such
as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta',
'cyan', or 'burlywood'
style
sets the style of the node. Can be one of: 'filled', 'solid',
'dashed', 'dotted', 'bold', 'invis'
dir sets the arrow direction. Can be one of: 'forward', 'back', 'both',
'none'
tailclip, headclip
when set to false disables endpoint shape clipping
arrowhead, arrowtail
sets the type for the arrow head or tail. Can be one of: 'none',
'normal', 'inv', 'dot', 'odot', 'invdot', 'invodot.'
arrowsize
sets the arrow size: (norm_length=10,norm_width=5,
inv_length=6,inv_width=7,dot_radius=2)
headlabel, taillabel
sets the text for port labels. Note that labelfontcolor,
labelfontname, labelfontsize are also allowed
labeldistance, port_label_distance
sets the distance from the edge / port to the label. Also
labelangle
decorateP
if set, draws a line from the edge to the label
samehead, sametail
if set aim edges having the same value to the same port, using the
average landing point
constraint
if set to false causes an edge to be ignored for rank assignment
Additionally, adding edges between ports of a node is done via the
'from_port' and 'to_port' parameters, which currently takes in the
offset of the port (ie 0, 1, 2...).
$g->add_edge('London' => 'Paris', from_port => 0);
as_canon, as_text, as_gif etc. methods
There are a number of methods which generate input for dot / neato /
twopi / circo / fdp or output the graph in a variety of formats.
Note that if you pass a filename, the data is written to that filename.
If you pass a filehandle, the data will be streamed to the filehandle.
If you pass a scalar reference, then the data will be stored in that
scalar. If you pass it a code reference, then it is called with the
data (note that the coderef may be called multiple times if the image
is large). Otherwise, the data is returned:
Win32 Note: you will probably want to binmode any filehandles you write
the output to if you want your application to be portable to Win32.
my $png_image = $g->as_png;
# or
$g->as_png("pretty.png"); # save image
# or
$g->as_png(\*STDOUT); # stream image to a filehandle
# or
#g->as_png(\$text); # save data in a scalar
# or
$g->as_png(sub { $png_image .= shift });
as_debug
The as_debug method returns the dot file which we pass to GraphViz.
It does not lay out the graph. This is mostly useful for debugging.
print $g->as_debug;
as_canon
The as_canon method returns the canonical dot / neato / twopi /
circo / fdp file which corresponds to the graph. It does not
layout the graph - every other as_* method does.
print $g->as_canon;
# prints out something like:
digraph test {
node [ label = "\N" ];
London [label=London];
Paris [label="City of\nlurve"];
New_York [label="New York"];
London -> Paris;
London -> New_York [label=Far];
Paris -> London;
}
as_text
The as_text method returns text which is a layed-out dot / neato /
twopi / circo / fdp format file.
print $g->as_text;
# prints out something like:
digraph test {
node [ label = "\N" ];
graph [bb= "0,0,162,134"];
London [label=London, pos="33,116", width="0.89", height="0.50"];
Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
}
as_ps
Returns a string which contains a layed-out PostScript-format file.
print $g->as_ps;
as_hpgl
Returns a string which contains a layed-out HP pen plotter-format
file.
print $g->as_hpgl;
as_pcl
Returns a string which contains a layed-out Laserjet printer-format
file.
print $g->as_pcl;
as_mif
Returns a string which contains a layed-out FrameMaker graphics-
format file.
print $g->as_mif;
as_pic
Returns a string which contains a layed-out PIC-format file.
print $g->as_pic;
as_gd
Returns a string which contains a layed-out GD-format file.
print $g->as_gd;
as_gd2
Returns a string which contains a layed-out GD2-format file.
print $g->as_gd2;
as_gif
Returns a string which contains a layed-out GIF-format file.
print $g->as_gif;
as_jpeg
Returns a string which contains a layed-out JPEG-format file.
print $g->as_jpeg;
as_png
Returns a string which contains a layed-out PNG-format file.
print $g->as_png;
$g->as_png("pretty.png"); # save image
as_wbmp
Returns a string which contains a layed-out Windows BMP-format
file.
print $g->as_wbmp;
as_cmap (deprecated)
Returns a string which contains a layed-out HTML client-side image
map format file. Use as_cmapx instead.
print $g->as_cmap;
as_cmapx
Returns a string which contains a layed-out HTML HTML/X client-side
image map format file. Name and id attributes of map element are
set to name of the graph.
print $g->as_cmapx;
as_ismap (deprecated)
Returns a string which contains a layed-out old-style server-side
image map format file. Use as_imap instead.
print $g->as_ismap;
as_imap
Returns a string which contains a layed-out HTML new-style server-
side image map format file.
print $g->as_imap;
as_vdx
Returns a string which contains a VDX-format (Microsoft Visio)
file.
print $g->as_vdx;
as_vrml
Returns a string which contains a layed-out VRML-format file.
print $g->as_vrml;
as_vtx
Returns a string which contains a layed-out VTX (Visual Thought)
format file.
print $g->as_vtx;
as_mp
Returns a string which contains a layed-out MetaPost-format file.
print $g->as_mp;
as_fig
Returns a string which contains a layed-out FIG-format file.
print $g->as_fig;
as_svg
Returns a string which contains a layed-out SVG-format file.
print $g->as_svg;
as_svgz
Returns a string which contains a layed-out SVG-format file that is
compressed.
print $g->as_svgz;
as_plain
Returns a string which contains a layed-out simple-format file.
print $g->as_plain;
FAQ
Why do I get error messages like the following?
Error: <stdin>:1: syntax error near line 1
context: digraph >>> Graph <<< {
Graphviz reserves some words as keywords, meaning they can't be used as
an ID, e.g. for the name of the graph. So, don't do this:
strict graph graph{...}
strict graph Graph{...}
strict graph strict{...}
etc...
Likewise for non-strict graphs, and digraphs. You can however add
double-quotes around such reserved words:
strict graph "graph"{...}
Even better, use a more meaningful name for your graph...
The keywords are: node, edge, graph, digraph, subgraph and strict.
Compass points are not keywords.
See keywords <http://www.graphviz.org/content/dot-language> in the
discussion of the syntax of DOT for details.
NOTES
Older versions of GraphViz used a slightly different syntax for node
and edge adding (with hash references). The new format is slightly
clearer, although for the moment we support both. Use the new, clear
syntax, please.
SEE ALSOGraphViz is deprecated in favour of GraphViz2.
Machine-Readable Change Log
The file CHANGES was converted into Changelog.ini by
Module::Metadata::Changes.
AUTHOR
Leon Brocard: <acme@astray.com>.
Current maintainer: Ron Savage <ron@savage.net.au>.
COPYRIGHT
Copyright (C) 2000-4, Leon Brocard
LICENSE
This module is free software; you can redistribute it or modify it
under the same terms as Perl itself.
perl v5.14.3 2012-11-09 GraphViz(3)
