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. png images are always created and attached inline, any other requested formats are saved as attachments. The graph is described in a simple text markup called "the DOT language". A MD5 hash is calculated for the dot command input and the results saved in the TWiki work_area directory. If the calculated hash matches on subsequent page visits, the attached graphics files are used without rerunning Graphviz. If the hash doesn't match, the attachments are regenerated.

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 <dot> ... </dot> tags.

You can use the following parameters in the dot tag to control the rendering of your graph (All parameters are optional):

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 unless the dothash option is set to off.

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) 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"; }

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) 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; }

You get: (simulated, antialiasing on)

You get: (if installed, antialiasing on) 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; }

Usecase description / state diagram

View source of this page to see graph description.

You get: (simulated)

You get: (if installed) digraph G { size="7,7"; graph [rankdir="TB" label="1st Time Use/Phone Registration" fontsize=12 bgcolor="#eeeeff"]; node [shape=box fontsize=9]; edge [color=blue fontsize=8 font="Arial"]; cell_number_entry [label="Cell Number Entry"]; welcome [label="Welcome Page"]; member_name_creation [label="Member Name Creation"]; password_creation [label="Password Creation"]; member_name_unavailable [label="Member Name Unavailable"]; email_entry [label="Email Entry"]; zip_code_entry [label="Zip Code Entry"]; tos [label="TOS"]; decline_confirmation [label="Decline Confirmation"]; registration_confirmation [label="Registration Confirmation"]; member_name_entry [label="Member Name Entry"]; password_entry [label="Password Entry"]; confirm_phone_number [label="Confirm Phone Number"]; unsuccessfull_sign_in [label="Unsuccessfull Sign In"]; email_confirmation [label="Email Confirmation"]; main_menu [label="Main Menu"]; initial_screen [label="Initial Screen"]; exit_application [label="Exit the Application"]; welcome -> initial_screen [label="First Time"] initial_screen -> member_name_creation [label="Register"]; initial_screen -> member_name_entry [label="Sign In"]; member_name_creation -> password_creation [label="Valid Member Name" dir="both"]; member_name_creation -> member_name_unavailable [label="Invalid Member Name" dir="both"]; welcome -> password_creation; password_creation -> cell_number_entry [dir="both"]; member_name_entry -> password_entry [dir="both"]; cell_number_entry -> email_entry [dir="both"]; password_entry -> confirm_phone_number [label="Auth. Successful" dir="both"]; password_entry -> unsuccessfull_sign_in [label="Auth. Unsuccessful"]; email_entry -> zip_code_entry [dir="both"]; zip_code_entry -> tos [dir="both"]; confirm_phone_number -> main_menu; unsuccessfull_sign_in -> member_name_entry [label="Try Again" constraint="false"]; unsuccessfull_sign_in -> email_confirmation; tos -> decline_confirmation [label="Decline" dir="both"]; tos -> registration_confirmation [label="Accept"]; decline_confirmation -> exit_application [label="Yes"]; registration_confirmation -> main_menu [label="10 Sec/NEXT"]; }

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) digraph G { graph [rankdir=LR, size="9.5,2.5"] subgraph cluster_0 { graph [label=User] edge [style=dashed] browser [label="WWW\nbrowser" URL="http://www.mozilla.org/"] svgplugin [label="SVG Plugin" URL="http://www.adobe.com/svg/viewer/install/old.html"] pdfplugin [label="PDF Plugin" URL="http://www.adobe.com/support/downloads/product.jsp?product=10&platform=unix"] svgplugin -> browser svgplugin -> browser [dir=back] pdfplugin -> browser pdfplugin -> browser [dir=back] { graph [rank=same] pngpage [label=PNG shape=box URL="/cgi-bin/webdot/webdot/demo.dot.dot.png"] svgpage [label=SVGZ shape=box URL="/cgi-bin/webdot/webdot/demo.dot.dot.svgz"] pdfpage [label=PDF shape=box URL="/cgi-bin/webdot/webdot/demo.dot.dot.pdf"] } pngpage -> browser [dir=none style=dotted] svgpage -> svgplugin [dir=none style=dotted] pdfpage -> pdfplugin [dir=none style=dotted] } subgraph cluster_1 { graph [label="Server 1"] httpd1 [label=httpd URL="http://httpd.apache.org/"] webdot [label="/cgi-bin/webdot" style=filled fillcolor=yellow color=black URL="/webdot/"] } subgraph cluster_2 { graph [label="Server 2"] httpd2 [label=httpd URL="http://httpd.apache.org/"] "demo.dot" [shape=box URL="/webdot/demo.dot"] httpd2 -> "demo.dot" [dir=none style=dotted] } browser -> httpd1 -> webdot -> httpd2 browser -> httpd1 -> webdot -> httpd2 [dir=back] }

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) digraph G { size="2,3!"; dpi="100"; edge [arrowhead=none color=blue]; node [fontcolor=blue color=white]; Workstation [shapefile="Sun_Workstation.png"]; Printer [shapefile="Printer.png"]; Internet [shapefile="Cloud-Filled.png"]; Router [shapefile="Wireless_Router.png"]; Switch [shapefile="Workgroup_Switch.png"]; Laptop [shapefile="Laptop.png"]; Workstation -> Switch; Printer -> Switch; Switch -> Router; Router -> Internet; Laptop -> Router [style=dotted]; }

You get: (if installed, antialiased) digraph G { size="2,3!"; dpi="100"; edge [arrowhead=none color=blue]; node [fontcolor=blue color=white]; Workstation [shapefile="Sun_Workstation.png"]; Printer [shapefile="Printer.png"]; Internet [shapefile="Cloud-Filled.png"]; Router [shapefile="Wireless_Router.png"]; Switch [shapefile="Workgroup_Switch.png"]; Laptop [shapefile="Laptop.png"]; Workstation -> Switch; Printer -> Switch; Switch -> Router; Router -> Internet; Laptop -> Router [style=dotted]; }

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 antialiasing off, rendering size is controlled by dot (can be effected by an eventual size parameter in the digraph description), with antialiasing 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 = off

• 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

• Set whether or not attached files should be automatically hidden in the attachments table.
  • Set HIDEATTACHMENTS = on

• 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
• On Linux install cairo and the graphviz-cairo plugin if desired
• 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.
• Using the TWiki configure interface, set the paths to the graphviz dot and ImageMagick convert commands, along with perl, and the TWiki tools directory.

Plugin zip content:

Dependencies:

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

Notes on antialiasing

There are two ways to accomplish antialiased output. The older method is to:

• generate the graph output in postscript format (.ps)
• convert to png format using ImageMagick (convert) command

This method is not compatible with client side image maps unless the imagesize rendered by graphviz is the same as the final output from ImageMagick? . For example, the following parameters will result in compatible maps.

dot parameters passed to convert

antialias="1" size="300x300" density="100" library="TWiki.DirectedGraphPlugin"

• Size the image size in dots, density is dots per inch.

graph parameters used by dot

digraph G { size="2,3!"; dpi="100";

• Size is the image size in inches, ! = scale to fill one dimension.

(The graphviz site suggests using ghostscript to do the antialiasing however ImageMagick also does this by default and is more widely installed. ImageMagick is used by this plugin, not ghostscript.)

The other method is to directly render the graph with graphviz using the cairo backend, "which has antialiased, path-based graphics".

As documented on the graphviz FAQ on the "Linux bleeding edge", install the cairo graphics backend library, along with the graphviz-cairo plugin. (It appears that the current graphviz includes cairo support without the plugin.)

You can determine what rendering engine is used for any specified file type by running the dot command from the command shell. If the rendering is done with cairo, you already have antialiased output.

dot -v -Tpng -V
Activated plugin library: libgvplugin_pango.so.5
Using textlayout: textlayout:cairo
Activated plugin library: libgvplugin_dot_layout.so.5
Using layout: dot:dot_layout
Using render: cairo:cairo
Using device: png:cairo:cairo
dot - Graphviz version 2.16.1 (Sat Dec 22 18:29:59 UTC 2007)

Details on how to install cairo, graphviz and imagemagick are beyond the scope of this document.

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.ColeBeck - 01 Jul 2004