@@ -1,659 +1,49 @@
-NAME
- GraphViz - Interface to the GraphViz graphing tool
+README file for GraphViz.
-SYNOPSIS
- use GraphViz;
+See also: CHANGES and Changelog.ini.
- my $g = GraphViz->new();
+Warning: WinZip 8.1 and 9.0 both contain an 'accidental' bug which stops
+them recognizing POSIX-style directory structures in valid tar files.
+You are better off using a reliable tool such as InfoZip:
+ftp://ftp.info-zip.org/pub/infozip/
- $g->add_node('London');
- $g->add_node('Paris', label => 'City of\nlurve');
- $g->add_node('New York');
+1 Installing from a Unix-like distro
+------------------------------------
+shell>gunzip GraphViz-2.15.tgz
+shell>tar mxvf GraphViz-2.15.tar
- $g->add_edge('London' => 'Paris');
- $g->add_edge('London' => 'New York', label => 'Far');
- $g->add_edge('Paris' => 'London');
+On Unix-like systems, assuming you have installed Module::Build V 0.25+:
- print $g->as_png;
+shell>perl Build.PL
+shell>./Build
+shell>./Build test
+shell>./Build install
-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/).
+On MS Windows-like systems, assuming you have installed Module::Build V 0.25+:
- What is a graph?
- A (undirected) graph is a collection of nodes linked together with
- edges.
+shell>perl Build.PL
+shell>perl Build
+shell>perl Build test
+shell>perl Build install
- A directed graph is the same as a graph, but the edges have a direction.
+Alternately, without Module::Build, you do this:
- 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.
+Note: 'make' on MS Windows-like systems may be called 'nmake' or 'dmake'.
- 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.
+shell>perl Makefile.PL
+shell>make
+shell>make test
+shell>su (for Unix-like systems)
+shell>make install
+shell>exit (for Unix-like systems)
- 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".
+On all systems:
- 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.
-
- 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'.
-
- 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_cmpax instead.
-
- print $g->as_cmap;
-
- as_cmapx
- Returns a string which contains a layed-out HTML HTML/X client-side
- image map format file.
-
- 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_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;
-
-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 ALSO
- GraphViz::XML, GraphViz::Regex
-
-AUTHOR
- Leon Brocard <acme@astray.com>
-
-COPYRIGHT
- Copyright (C) 2000-4, Leon Brocard
-
- This module is free software; you can redistribute it or modify it under
- the same terms as Perl itself.
+Run GraphViz.pm through your favourite pod2html translator.
+2 Installing from an ActiveState distro
+---------------------------------------
+shell>unzip GraphViz-2.15.zip
+shell>ppm install --location=. GraphViz
+shell>del GraphViz-2.15.ppd
+shell>del PPM-GraphViz-2.15.tar.gz