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 an image of a directed graph. The directed graph is described using a simple text markup called "The DOT Language". This markup is written between

<dot> ... </dot>

<dot>

By default, this version of the plugin uses the TWik API to manipulate the attached graphs. The first user to view a topic containing a directed graph will be denied access if they do not have update permission. If defaults or DOT parameters have changed, viewing the topic may modify attachments, which will require update permission.

Caution The plugin will also update attached files during Preview. if the edit is subsequently canceled, the attachments will be regenerated again.

A MD5 hash is calculated for each dot command input and the results saved in the TWiki work_area directory. The hash file is named with the Web name, the Topic name, and the string -filehash The location of the workarea has changed in recent TWiki releases. 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.

Default behavior is to leave any previously generated attachments even if the <dot> tags are removed from the file. If the configuration setting DELETEATTACHMENTS is enabled, then the plugin will remove any old attachments that are not needed. However if the final <dot> tag is removed, the plugin is not invoked, and the attachments will not be deleted.

Caution! If a topic has not previously been processed by this version of the plugin, attachments named using the original "Graph[32 character hex checksum].jpg will all be deleted from the topic when this parameter is enabled! Once the new -filehash file has been created, old style attachments will not be deleted. If you want to go back and clean up the old atachment filenames, you can remove the Web_Topic-filehash file from the workare directory.

In TWiki 4.2.0 and later, if a topic is renamed, the -filehash file in the TWiki workarea directory will be renamed as well and regeneration of attachment files will be avoided. In previous versions, there is no afterRenameHandler. The hash file will be orphaned, and the graphics attachments will be regenerated when the page is displayed.

Caution <dot> syntax is not currently compatible with the WYSIWYG editor. Raw editing is recommended, or use <sticky> tags to protect the dot tags.

Also note that after changes that modify the order of generated image names, it may be necessary to refresh the browser cache with shift-reload.

Visit the Graphviz gallery to see some examples on what can be achieved 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. This is the default engine.
• 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

Changes to the settings marked will cause changes to the file hash. This will result in the attached graphcs being regenerated on the next view.

• 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

• Set the format for inline attachment files.
  • Set INLINEATTACHMENT = png

• Include links for other attachment types if specified.
  • Set LINKATTACHMENTS = on

• If enabled, the plugin will delete any remaining attachments when a <dot> is removed or modified.
  • Set DELETEATTACHMENTS = off

• If enabled, the plugin will ignore the "configure" settings of attachPath and attachUrlPath. Forcing use of the attachment API can be used to create topics that are portable across TWiki installations. (for example, the HowtoDirectedGraphs topic) It can be also used to get standard attachment revision history handling on the generated attachments. [This parameter is ignored and the TWiki attachment API always used if the configure settings attachPath and attachUrlPath are not supplied.
  • Set FORCEATTACHAPI = off

• 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 defaults to PNG, others are attached. Options are ps and svg (space separated). Any output format supported by GraphViz can be specified. 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.
• [Optional] Set the attachPath and attachUrlPath. These can be set to match the TWiki pubUrlPath and pubDir settings, or set to a web-readable directory outside of TWiki.
  • If not set, the standard TWiki "attach" API will be used by the plugin. View users will require "update" permission if the plugin needs to regenerate the attached files.
  • If the attachPath is set, standard TWiki attachment handling will be bypassed and files will be written directly to this path. Attachments will not be subject to revision controls.
  • If the attachPath is not the TWiki pub directory, then the attachUrlPath must be configured for the plugin to generate correct URLs.
  • The plugin does not attempt to manage attachments across changes between direct file I/O and the TWiki API. Attachments can be orphaned when these parameters are changed.

• For TWiki 4.0.1, the configure interface does not set plugin variables. Manually insert the following lines into the lib/TWiki.cfg file
  • $TWiki::cfg{DirectedGraphPlugin}{enginePath} = '/usr/bin/';
  • $TWiki::cfg{DirectedGraphPlugin}{magickPath} = '/usr/bin/';
  • $TWiki::cfg{DirectedGraphPlugin}{toolsPath} = '[complete path of twiki/tools/ directory]';
  • $TWiki::cfg{DirectedGraphPlugin}{perlCmd} = '/usr/bin/perl';
  • $TWiki::cfg{DirectedGraphPlugin}{attachPath} = ''; [optional]
  • $TWiki::cfg{DirectedGraphPlugin}{attachUrlPath} = ''; [optional]

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