Extending WilmaScope

A developer’s guide to extending the WilmaScope 3D graph visualisation system

Tim Dwyer – 26th November 2004

Accurate for WilmaScope Version 3.1

Contents

• Introduction
• Nomenclature
• Architecture
• Graph Model
• GraphControl Bridge
• Generating Graphs
  
• User Interface
• The Graph Generator Framework
• GraphGenerator
• GeneratorManager
• Example – Random Graph Generator
• Plug-ins for Modifying Graphs or Clusters
  
• Plug-ins for Performing Graph/Cluster Analysis
• File Formats
• XML Wilma Graph (XWG)
• GML File Format
• LEDA File Format
• Creating New Graph Element Glyphs
• Creating New Layout Engines
• Getting the WilmaScope Source Code
• Code Conventions

Introduction

• by creating WilmaScope XML Graph (XWG) files which can be loaded to visualise graphs.
• by extending the WilmaScope GraphGenerator framework to automatically generate graphs based on simple algorithms.
• by implementing new layout algorithms based on the WilmaScope LayoutEngine framework.
• by adding new graphical representations for graph elements (glyphs).
• by creating stand-alone applications which use the WilmaScope GraphCanvas in a custom GUI.

Nomenclature

Architecture

Figure 1: MVC Architecture

• classes in which the underlying graph model (data structure) is maintained.
• classes which provide a centralised bridge for modifying this model.
• classes which define how the model is displayed graphically.

Figure 2a: WilmaScope MVC Architecture

• model—classes in the graph package.
• view—classes extending one of the abstract classes found in the view package.
• controller—the GraphController class provides a centralised bridge for updating the graph model

• WilmaScope XML Graph (.xwg) files can be created by another program, converted from other XML formats using XSTL, or constructed in text or XML editor, and loaded into the standard WilmaScope frontend.
• A user can use the Graph Generator menus to automatically create a generic graph, or a programmer can implement a new plugin based procedure for constructing a graph by implementing the GraphGenerator framework (see Creating Test Graphs).
• Similarly, modifier and analysis plug-ins can be created, respectively for modifying the structure of a graph or for mapping graph analysis methods to visual properties.
  
• New layout algorithms can also be added as plugins by extending the WilmaScope LayoutEngine framework<>. Such layout algorithms can use the WilmaScope graph data structures or they can use external graph datastructure libraries such as Leda or yFiles. They can also potentially use other programs such as DOT (see Section 4). Developers can add plugins for new graphical representations for graph elements (glyphs).
  
• Developers can create standalone applications which use the WilmaScope GraphCanvas and API in a custom GUI (see Creating Applications Based on GraphCanvas and also the WilmaScope Javadoc).
• A user can interact with the WilmaScope GUI to add or edit graph components (see the user help documentation).

Figure 2b: Different ways to use Wilma for custom applications

Figure 3: graph and view packages and example packages in which the various interfaces are implemented.

Graph Model

GraphControl Bridge

Plug-ins for Generating Graphs

User Interface

Figure 4: Accessing the graph generator window.

• The drop down menu box at the top: this allows users to select from the available graph generators.
• The “Graph Rendering Mode” radio buttons: the user can select the visual elements of the resulting graph.  These can be either simple line primitives (for faster rendering), or fancy 3D primitives.
• The “Generate Graph” button: this initiates graph generation
• The control panel with sliders and so on at the bottom.  The controls that appear here are dependant on the generator chosen from the menu.

Figure 5: The Graph Generator window

The Graph Generator Framework

GraphGenerator

• getName - you should simply return a string constant that is a unique identifier.  This string will appear in the Graph Generator Window list so give it a capital letter and spaces where necessary.
• generate – this method will do the work of actually creating the graph.
• getControls – the best way to use this is to create a JPanel with controls for setting parameters for your graph generator in your constructor and ensure that this method returns a reference to it.

GeneratorManager

Example – Random Graph Generator

• The constructor creates a JPanel with controls for setting parameters for the random graph generator (see Figure 5)
• getControls returns the JPanel set up in the constructor
• getName returns the string constant: “Random”
• The generate method does all the actual work, specifically:
• The root cluster is extracted from the GraphControl instance passed in using the getRootClusterMethod
• The root cluster’s deleteAll method is called to remove any existing graph (you would not do this if you wanted to add to or modify an existing graph)
• graph elements are added to the root cluster using the addNode and addEdge methods.  By default nodes are created at the origin... here we assigned random positions using the GraphControl.NodeFacade.setPosition method
• Finally we call the root cluster’s draw method to draw the nodes at the random positions assigned above.   Alternately we could trigger automatic layout using the root cluster’s unfreeze method which would also handle the redraw.

Plug-ins for Modifying Existing Graphs and Clusters

• getName - you should simply return a string constant that is a unique identifier.  This string will appear in the Graph Modifier Window list so give it a capital letter and spaces where necessary.
• modify – this method will do the work of actually modifying the specified cluster.
  
• getControls – the best way to use this is to create a JPanel with controls for setting parameters for your graph generator in your constructor and ensure that the getControls method returns a reference to it.

• for the graph (root cluster) - by selecting "Modify Graph" from the tools menu; or
• for a particular cluster - by right clicking the cluster and selecting "Modify Cluster" from the resultant cluster options menu

As of writing this document WilmaScope includes the following graph modifier plug-ins (found in org.wilmascope.graphmodifier.plugin):

• ChangeViews - replace the GraphElementViews of nodes and/or edges with the current default settings from the toolbar.
• CopyCluster - copy either the root graph or a particular cluster
• DirectedCycleRemoval - reverse the direction of edges such that the graph is acyclic.
• InsertDummyNodes - if LevelConstraints are defined, this inserts dummy nodes into edges that span multiple levels
• KMeansClustering - creates clusters around nodes that are close together in the current layout
• LongestPathLayering - assigns nodes to LevelConstraints such that edges are monotonically directed (uses DirectedCycleRemoval).
  

Plug-ins for Performing Graph/Cluster Analysis

The GraphAnalysis plug-in framework works in a similar way to GraphModifier plugins, but GraphAnalysis plug-ins are not expected to modify the structure or attributes of a graph directly.  Rather, they should set a property in nodes and edges corresponding to the name of the plugin (the string returned by the getName method) with a floating point value that can be mapped by other classes to visual attributes (for example, the VisualMapping classes defined in the org.wilmascope.graphanalysis package).

A graph analysis plug-in must extend the org.wilmascope.graphanalysis.GraphAnalysis class, implementing the getName and analyse methods.  As with GraphModifier getName simply returns a descriptive string.  The analyse method takes no argument.  Rather, you must use getCluster() to operate on the cluster in the analyse method.  For example:

/**
 * Calculate degree centrality for each node, ie for node v in V:
 * degreecentrality(v) = degree(v)/max(degree(w)|w in V)
 * 
 * @author dwyer
 */
public class DegreeCentrality extends GraphAnalysis {

  public String getName() {
    return "Degree Centrality";
  }
  
  /*
   * @see org.wilmascope.graphanalysis.GraphAnalysis#analyse(org.wilmascope.control.GraphControl.Cluster)
   */
  public void analyse() {
    int maxDegree = 0;
    for (Node n : getCluster().getNodes()) {
      int degree = n.getDegree();
      if (degree > maxDegree) {
        maxDegree = degree;
      }
    }
    if (maxDegree > 0) {
      for (Node n : getCluster().getNodes()) {
        float degreeCentrality = (float) n.getDegree() / (float) maxDegree;
        n.getProperties().setProperty(getName(), "" + degreeCentrality);
      }
    }
  }
}

There is no need for a getControls method in GraphAnalysis plug-ins.  By default an instance of AnalysisPanel is created by the super class.  AnalysisPanel allows a user to choose visual mappings for the results of the analysis, and appears in the Graph Analysis window, shown below with a number of mappings defined for various analysis plugins:

File Formats

XML Wilma Graph (XWG) File Format

Figure 7: The WilmaGraph.dtd XWG definition

Figure 8: A very simple XWG file.

Figure 9: The XWG file from Figure 8 loaded into Wilma.

The file shown in Figure 8 was created by hand.  When we save it back out to a file from WilmaScope more detail is recorded (for example, detail about the layout engine used and the view parameters for nodes and edges):

Figure 10: The same graph but with more details specified.

Node Properties

Edge Properties

Available ViewTypes

Nodes:

Edges:

Clusters:

Common ViewType properties

Common to all graph elements (Nodes, Edges and Clusters)

Common to all Nodes

Common to all Edges

GML File Format

Leda Graph File Format

Creating New Graph Element Glyphs

Creating New Layout Engines

LayoutPlugins=org.wilmascope.forcelayout.ForceLayout,....,org.wilmascope.randomlayout.RandomLayout

DefaultLayout=Random

java -cp %PATH_TO_YOUR_COPY_OF_WILMA_CONSTANTS_FILE%;%PATH_TO_YOUR_LAYOUT_CLASS% 
     -jar %WILMA_HOME%/lib/wilma.jar

Getting the WilmaScope Source Code

• Download and install version 3.1 or higher of Eclipse from www.eclipse.org
• Switch to the  CVS Repository Exploring perspective (You may have to first  open this perspective).
• Create a new repository location (Right click within the  CVS Repositories View, New >  Repository Location) with these settings:
• Host: cvs.sourceforge.net
• Repository Path: /cvsroot/wilma
• User: anonymous
• Connection type: pserver
• Navigate into :pserver:anonymous@cvs.sourceforge.net:/cvsroot/wilma > HEAD and check out the "Wilma" module (Select "Wilma" and right click > Check Out as Project).
• To compile: set the compiler compliance settings to 5.0, ensure that all jars in the %WILMA_HOME%/lib dir are included in the class path
• To run: ensure that lib dir and all jars in lib dir are in class path.
  

Code Conventions