GraphViz 1.4
Perl
module
-
Part of CPAN
distribution
GraphViz 1.4.
GraphViz - Interface to the GraphViz graphing tool
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;
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" and "neato" programs from the GraphViz
project (http://www.graphviz.org/).
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.
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.
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.
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
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/
This is the constructor. It accepts several attributes.
The most important attribute is named 'directed', which defaults to 1
(true) - this specifies directed (tree-like) graphs. Setting this to
zero produces undirected graphs, which are layed out differently.
Another attribute 'rankdir' controls the direction the nodes are linked
together. If true it will do left->right linking rather than the
default up-down linking.
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.
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).
my $g = GraphViz->new();
my $g = GraphViz->new(directed => 0);
my $g = GraphViz->new(rankdir => 1);
my $g = GraphViz->new(width => 8.5, height => 11);
my $g = GraphViz->new(width => 30, height => 20,
pagewidth => 8.5, pageheight => 11);
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.
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.
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.
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'});
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');
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']);
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);
There are a number of methods which generate input for dot / neato 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. Otherwise, the data is returned:
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_canon
-
The as_canon method returns the canonical dotneato 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-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_ismap
-
Returns a string which contains a layed-out HTML client-side image map
format file.
print $g->as_ismap;
- as_imap
-
Returns a string which contains a layed-out HTML server-side image map
format file.
print $g->as_imap;
- 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_plain
-
Returns a string which contains a layed-out simple-format file.
print $g->as_plain;
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.
Leon Brocard <acme@astray.com>
Copyright (C) 2000-1, Leon Brocard
This module is free software; you can redistribute it or modify it
under the same terms as Perl itself.
|
