|
|
| |
GraphViz(3) |
User Contributed Perl Documentation |
GraphViz(3) |
GraphViz - Interface to AT&T's GraphViz. Deprecated. See GraphViz2
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", "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.
Of course you need to install AT&T's Graphviz before using this module. See
<http://www.graphviz.org/Download.php>.
You are strongly advised to download the stable version of
Graphviz, because the development snapshots (click on 'Source code'), are
sometimes non-functional.
Install GraphViz as you would for any
"Perl" module:
Run:
cpanm GraphViz
Note: cpanm ships in App::cpanminus. See also App::perlbrew.
or run:
sudo cpan GraphViz
or unpack the distro, and then either:
perl Build.PL
./Build
./Build test
sudo ./Build install
or:
perl Makefile.PL
make (or dmake or nmake)
make test
make install
- 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
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.
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 explicitly 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');
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']);
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
- decorate
- 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 / 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;
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.
Due to security risks with XXE in XML, Graphviz does not support XML that
contains XXE. Thus it automatically prevents external entities being parsed by
using the no_xxe option in XML::Twig when calling XML::Twig ->
new(). And for this reason also the pre-reqs in Makefile.PL specify
XML::Twig V 3.52.
See
<https://metacpan.org/pod/release/MIROD/XML-Twig-3.52/Twig.pm#no_xxe>
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.
GraphViz is deprecated in favour of GraphViz2.
The file Changes was converted into Changelog.ini by Module::Metadata::Changes.
<https://github.com/ronsavage/GraphViz>
Leon Brocard: <acme@astray.com>.
Current maintainer: Ron Savage
<ron@savage.net.au>.
My homepage: <http://savage.net.au/>.
Copyright (C) 2000-4, Leon Brocard
This module is free software; you can redistribute it or modify it under the
Perl License, a copy of which is available at
<http://dev.perl.org/licenses/>.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |