Directed Graph Plugin

Introduction

Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. Automatic graph drawing has many important applications in software engineering, database and web design, networking, and in visual interfaces for many other domains.

This plugin uses Graphviz's applications to create a png image of a directed graph. The graph is described in a simple text markup called "the DOT language".

Visit the Graphviz gallery to see some examples on what can be achived with this plugin and Graphviz. Full documentation is available at http://graphviz.org/Documentation.php.

DirectedGraphPlugin supports the following engines:

• dot - makes "hierarchical" or layered drawings of directed graphs. The layout algorithm aims edges in the same direction (top to bottom, or left to right) and then attempts to avoid edge crossings and reduce edge length.
• neato and fdp - make "spring model" layouts. neato uses the Kamada-Kawai algorithm, which is equivalent to statistical multi-dimensional scaling. fdp implements the Fruchterman-Reingold heuristic including a multigrid solver that handles larger graphs and clustered undirected graphs.
• twopi - radial layout, after Graham Wills 97.
• circo - circular layout, after Six and Tollis 99, Kauffman and Wiese 02. Suitable for certain diagrams of multiple cyclic structures.

Syntax Rules

Enclose the description for your directed graph within DirectedGraph Error (1): Problem executing dot command

*DirectedGraphPlugin error:* 
Error: /dev/shm/DirectedGraphPlugin9380:0: syntax error near line 0
01: context:  >>> </span> <<<  ... <span>

You can use the following parameters in the dot tag to control the rendering of your graph:

Sitewide default settings are set in this topic and can be overwritten for each graph. When you change a setting the graph will be re-generated.

Howto

HowtoDirectedGraphs has a basic howto on creating directed graphs using dot.

Examples

Cole's example

You type:

<dot>
digraph G {
    subgraph cluster_c0 {a0 -> a1 -> a2 -> a3}
    subgraph cluster_c1 {
        b0 -> b1 -> b2 -> b3;
        label="Group B";
    }
    x -> a0 [style=dotted];
    x -> b0;
    a1 -> a3 [style=bold, label="a1 to a3"];
    a3 -> a0;
    a0 [shape=box, fontname=Courier, fontsize=11];
    a1 [color=red];
    a3 [label="Label\nfor a3"];
    label="Cole's Example";
}
</dot> 

You get: (simulated)

You get: (if installed)

Clientside imagemap (clickable nodes and edges)

You type:

<dot map=1>
digraph G {
    URL="http://www.twiki.org";
    Plugins [URL="http://twiki.org/cgi-bin/view/Plugins/PluginPackage"];
    DirectedGraphPlugin [URL="http://twiki.org/cgi-bin/view/Plugins/DirectedGraphPlugin"];
    Plugins -> DirectedGraphPlugin;
}
</dot>

You get: (simulated)

You get: (if installed)

You get: (simulated, antialising on)

You get: (if installed, antialising on)

Usecase description / state diagram

View source of this page to see graph description.

You get: (simulated)

You get: (if installed)

Component architecture

This is a typical example of a component architecture drawing (This kind of graph is also easy to do in TWiki:Plugins.TWikiDrawPlugin if you like the look but you prefer to draw it manually using your mouse).

View source of this page for graph description.

You get: (simulated)

You get: (if installed)

Simple LAN setup (custom icons / shapefiles)

This type of graph can also easily be extended, for instance making network nodes clickable, pointing to asset databases or similar.

View source of this page for graph description.

You get: (simulated)

You get: (if installed) DirectedGraph Error: library parameter should point to topic with attachments to use: Web.TopicName (was: Sandbox/TestDot3)

DirectedGraphPlugin Global Settings

• One line description, shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Embed directed graphs in TWiki topics (using the Graphviz package)

• Layout engine to use per default. Can be one of dot, neato, twopi, circo, fdp
  • Set ENGINE = dot

• Antialias option. If set to on the plugin will use the convert binary from the imagemagick package to pretty print graphs. This option should not be used with clientside maps as pixel dimensions are usually altered in this process and therefore the "hot spot" locations will not match the generated image. With antialising off, rendering size is controlled by dot (can be effected by an eventual size parameter in the digraph description), with antialising on you set the final image size in pixels explicitly with the size parameter. (If you must use an image map with this option, take care manually that the two generated pixel sizes match).
  • Set ANTIALIAS = on

• Default density (dpi) for antialias option. 300 dpi should be sufficient for most purposes (if your graphs look blurred at large image sizes try using a higher value).
  • Set DENSITY = 300

• Default image size (pixels, widthxheight) for antialias option (keeps aspect ratio; enlarges until max of one of the dimensions is reached).
  • Set SIZE = 800x600

• Additional vector formats to create per default. Displayed version is always PNG, others are attached. Options are ps and svg (comma separated). The ps format is useful to have handy if you are later converting your document to LaTeX? or other typesetting / publication utility. The svg format has inline clickable map if used.
  • Set VECTORFORMATS = none

• Default topic to read library icons (shapefiles) from
  • Set LIBRARY = DirectedGraphPlugin

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Plugin Installation Instructions

Note: The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

• Install the Graphviz package
• Install required web fonts
  • Install the ImageMagick? package
• Install the Perl module Digest::MD5
• Download the ZIP file from the Plugin web (see below)
• Unzip DirectedGraphPlugin.zip in your twiki installation directory.

Plugin zip content:

Dependencies:

• Customize paths to executables to your environment (in DirectedGraphPlugin.pm set $enginePath, $dotHelperPath, $execCmd, $antialiasCmd to correct paths for your environment)
• (Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

To install the web fonts, download this rpm and run the command rpm --install webfonts-1.0-5.noarch.rpm (Red Hat only).

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.ColeBeck - 01 Jul 2004