WilmaScope API Reference

Extending WilmaScope

See:
Description

Packages

org.wilmascope.centernode
org.wilmascope.columnlayout
org.wilmascope.control
org.wilmascope.dotlayout
org.wilmascope.dotparser
org.wilmascope.fastlayout
org.wilmascope.file
org.wilmascope.forcelayout
org.wilmascope.global
org.wilmascope.gmlparser
org.wilmascope.graph
org.wilmascope.graphgen
org.wilmascope.graphgen.plugin
org.wilmascope.gui
org.wilmascope.highdimensionlayout
org.wilmascope.images
org.wilmascope.layoutregistry
org.wilmascope.light
org.wilmascope.multiscalelayout
org.wilmascope.patterns
org.wilmascope.rotation
org.wilmascope.view
org.wilmascope.viewplugin
plugin

Extending WilmaScope

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

Tim Dwyer – 14th October 2004

Accurate for WilmaScope Version 3.0.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

This document is intended as a rough guide for people who wish to use WilmaScope beyond simply interacting with the Graphical User Interface (GUI). There are a number of ways that Wilma can be used by the adventurous, for example:

• 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

Term	Description
WILMA_HOME	The directory in which WilmaScope has been installed, eg: "c:/Program Files/Wilma"
WILMA_CONSTANTS.properties	The global properties file that WilmaScope loads at runtime. Resides in WILMA_HOME/lib directory

Architecture

Wilma is a typical example of a Model-View-Controller (MVC) architecture (see Figure 1).

Figure 1: MVC Architecture

That is to say, an effort has been made to separate:

• 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.

A more detailed idea of how WilmaScope uses the MVC architecture is conveyed by Figure 2.

Figure 2a: WilmaScope MVC Architecture

These three conceptual components are realised in the WilmaScope architecture as follows:

• 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

The entities indicated within the controller component indicate some of the ways a user might interact with WilmaScope, or that a programmer might write extensions to construct or maintain a graph. These are (see Figure 2b):

• 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

Conceptually, the graph model includes definitions of what we call Layout Engines. A layout engine is an implementation of a layout algorithm. That is, an automated system for finding positions for the elements of a graph in 3D space. In practice the details of layout engines are completely separated from the graph data structures so that new layout engines can easily be created. A more detailed view of WilmaScope’s internal architecture is shown in Figure 3.

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

The classes in the forcelayout package are an example of an implementation of the LayoutEngine interface. Several other layout engines have been implemented already and efforts have been made to simplify the task of creating new layout engines. Classes implementing different graphical representations of graph elements (glyphs) must extend the relevant abstract class from the view package. When such classes are placed in the viewplugin directory and added to the “Plugins” list in the WILMA_CONSTANTS.properties file they will be loaded at run-time.

Graph Model

The basic elements of a WilmaScope graph are nodes and edges. The Node and Edge classes both implement the GraphElement interface which defines some general properties for how such elements are arranged or visualised. WilmaScope supports recursive definitions for graphs: that is, clustered graphs. This is realised in an object oriented design by making Cluster a subclass of node. This means that clusters can be added or removed from a graph model in the same way as nodes. The difference being that a cluster is itself a collection of nodes and edges. An important thing to note is that the top-level graph is a cluster.

GraphControl Bridge

Knowledge of the details of the classes in the graph package is not generally required for programmers to implement applications using or extending WilmaScope. Instead, the API methods for creating or updating a graph are provided by the GraphControl class. GraphControl defines facades (or simplified classes) as inner classes: ie, GraphControl.Node, GraphControl.Edge and GraphControl.Cluster. When a GraphControl object is instantiated a root cluster is created upon which a graph may be built. As a basic example consider the following code fragment:

import org.wilmascope.control.GraphControl.Cluster;
import org.wilmascope.control.GraphControl.Node;
import org.wilmascope.control.GraphControl.Edge;
...
// add elements to an existing instance of graphControl
Cluster root = graphControl.getRootCluster();
Node a = root.addNode();
Node b = root.addNode();
root.addEdge(a,b);

We give more detailed examples of use of the API provided by the GraphControl class later.

Plug-ins for Generating Graphs

Wilma comes with a number of graph generators which create random or regular graphs for testing purposes. Creating a new graph generator is probably the easiest way to begin experimenting with the WilmaScope API. In this section we describe how the WilmaScope graph generator framework is designed and outline how to use it to create your own graph generator.

User Interface

The various graph generators are accessed by the user from the “Graph Generator Window” which is accessed by the user from the “File->Create Test Graph...” menu option as shown in Figure 4.

Figure 4: Accessing the graph generator window.

The main features of the Graph Generator Window (as shown in Figure 5) are:

• 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

Base classes associated with the graph generator framework are found in the org.wilmascope.graphgen package.

GraphGenerator

The abstract GraphGenerator class is a boilerplate for building new graph generators. It provides miscellaneous methods for generating graphs but also provides a set of abstract methods which must be implemented so that your graph generator can be loaded by WilmaScope. The abstract methods which a new graph generator must implement are as follows:

• 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

The GeneratorManager class maintains a list of available graph generators. If you create a new class based on GraphGenerator then add an entry for the fully qualified path name to the WILMA_HOME/lib/WILMA_CONSTANTS.properties file for the GeneratorPlugins property. Your new class will then be loaded (assuming the directory where it resides is in the classpath) when you run Wilma.

Example – Random Graph Generator

As an example of an implementation of GraphGenerator look at the RandomGraphGenerator class. Key things to note are:

• 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

Often it is useful to procedurally modify the structure of an existing graph or cluster. Plug-ins for effecting this functionality are made possible by the GraphModifier framework. A GraphModifier plug-in extends the org.wilmascope.graphmodifier.GraphModifier abstract class and must implement three methods:

• 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.

The user can invoke one of these plugins either:

• 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

The easiest way to visualise graphs from other data sources is to convert them into a file format that WilmaScope understands and then simply to load them up using the File->Load menu option. Here we describe supported file formats.

XML Wilma Graph (XWG) File Format

The most flexible way to load graphs into WilmaScope is to use Wilma's own internal file format, the XML Wilma Graph (XWG) file format. Based on XML, XWG files are easily parsed and generated by XML libraries and tools. As the Wilma internal format, it should support any of Wilma's functionality, including specifications for layout engines and view plugins.

XWG is based on a fairly straightforward DTD which can be found in the Wilma/data/WilmaGraph.dtd file, shown in Figure 7. Note that this file should be present in any directory from which you wish to load XWG files into Wilma.

Figure 7: The WilmaGraph.dtd XWG definition

Note that the XWG format mirrors the structure of the Wilma graph model shown in Figure 3. That is, clustered graphs are recursively defined where a graph is itself a cluster which may contain nodes, edges or other clusters. Figure 8 shows an example of a very simple XWG file and Figure 9 shows how it looks loaded into Wilma.

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

Property Key	Values	Description
Position	Three floats separated by spaces	X Y Z position. Values between 0 and 1 are a good start.
LevelConstraint	integer	constrains the z position to a plane specified by the integer when used with certain layout engines
FixedPosition	[True|null]	If this property is present with any string then the node's position will be fixed... ie, not affected by the layout

Edge Properties

Property Key	Values	Description
Weight	Float	Affects layout when used with certain layout engines.

Available ViewTypes

A ViewType entry requires a name. This specifies the View plugin that will be loaded. Some ViewPlugins that have been implemented are as follows (when entering the value for name in an XWG file spaces must appear exactly as below):

Nodes:

ViewPlugin name	Description
DefaultNodeView	Spherical node view. Labels appear as floating banners. For improved performance the number of faces shown are dependant on the distance from the camera.
Oriented Box Node	A box that always faces the viewer. Labels are texture mapped onto the face.
LineNode	Use with LineEdge... the node itself is invisible but this node type ensures that the line edge colours are set according to the node colour
LabelOnly	Only the label is shown as a banner
Box Node	A box shaped node. Labels are texture mapped onto the face.
SquareTube	A tube with square cross section and specified bottom and top dimensions
A tubular node	A tube with round cross section and specified bottom and top dimensions

Edges:

ViewPlugin name	Description
Plain Edge	Cylindrical edge. For improved performance the number of faces shown are dependant on the distance from the camera.
Arrow	Arrow made out of a cylinder and a cone
LineEdge	Uses OpenGL (or DirectX) line segment primitive for super-fast rendering. Lines colouring is smoothly graded from start node colour to end node colour if used with LineNode.
Directed Edge	Shows a directed edge with a little cone next to the edge. Alternative to arrow. Originally intended as a 3D analog for UML directed edges.
Attenuated Edge	An attenuated edge is tube that's fat at the ends and thin in the middle. If my sloppy calculations are correct then the radius should match the radius of spherical nodes at either end. Colour should also be graded from the start node colour to end node colour.
Inheritance	A 3D analogue for a UML inheritance edge. Basically an arrow with a blue cylinder and a green cone at the start node.
Aggregation	A 3D analogue of the UML aggregation edge style. Blue cylinder with red diamond on top.

Clusters:

ViewPlugin name	Description
Spherical Cluster	A semitransparent spherical bubble around the constituent nodes. For improved performance the number of faces shown are dependant on the distance from the camera.
Box Cluster	Semitransparent box around constituent nodes.

Common ViewType properties

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

Property Key	Values	Description
Label	String	Text that will appear texture mapped onto or in a banner above the graph element
Visible	[True|False]	The graph element will not be rendered... eg, hidden edges can be useful
Colour	Three space separated floats between 0 and 1	Red, Green and Blue colour values

Common to all Nodes

Property Key	Values	Description
Radius	Float	Radius... 0.1 is good for spherical nodes.

Common to all Edges

Property Key	Values	Description
Radius	Float	Radius of edge cylinders. 0.02 works well with the DefaultEdgeView.

GML File Format

WilmaScope currently supports a very limited subset of the GML file format. Better support is planned.

Leda Graph File Format

WilmaScope currently supports a very limited subset of the LEDA Graph File Format file format. Better support is planned.

Creating New Graph Element Glyphs

Creating New Layout Engines

To create a new layout engine plugin, a developer must extend the LayoutEngine abstract class, and also extend the NodeLayout and EdgeLayout abstract classes which are used to store any layout specific properties for nodes and edges. For example, here is the code for the RandomLayout class:

package org.wilmascope.randomlayout;

import javax.swing.JPanel;

import org.wilmascope.global.RandomGenerator;
import org.wilmascope.graph.Edge;
import org.wilmascope.graph.EdgeLayout;
import org.wilmascope.graph.LayoutEngine;
import org.wilmascope.graph.Node;
import org.wilmascope.graph.NodeLayout;

/**
* Assigns random positions to nodes. This is the simplest possible layout
* algorithm I can think of. Use this as a starting point for creating your own
* layout engines.
*
* @author dwyer
*/
public class RandomLayout extends LayoutEngine<RandomNode, RandomEdge> {

/*
* This method always returns true because this layout can be completed in one
* step. An iterative algorithm could return false until complete.
*
* @see org.wilmascope.graph.LayoutEngine#applyLayout()
*/
public boolean applyLayout() {
for (Node n : getRoot().getNodes()) {
n.setPosition(RandomGenerator.getPoint3f());
}
return true;
}

/*
* Name to appear in the layout menu.
*
* @see org.wilmascope.graph.LayoutEngine#getName()
*/
public String getName() {
return "Random";
}

/*
* called by super.init when layout instantiated
*
* @see org.wilmascope.graph.LayoutEngine#createNodeLayout(org.wilmascope.graph.Node)
*/
public RandomNode createNodeLayout(Node n) {
return new RandomNode();
}

/*
* called by super.init when layout instantiated
*
* @see org.wilmascope.graph.LayoutEngine#createEdgeLayout(org.wilmascope.graph.Edge)
*/
public RandomEdge createEdgeLayout(Edge e) {
return new RandomEdge();
}

/*
* Potentially we could create a control panel in the constructor to be
* returned here. Such a control panel would allow the user to set various
* layout properties.
*
* @see org.wilmascope.graph.LayoutEngine#getControls()
*/
public JPanel getControls() {
return new JPanel();
}

}
/**
* When the layout engine is instatiated, instances of this classes are assigned
* to all nodes in the root cluster. You can store node data specific to your
* layout in here.
*/
class RandomNode extends NodeLayout {
}

/**
* When the layout engine is instatiated, instances of the following class are
* assigned to all edges in the root cluster. You can store edge data specific
* to your layout here.
*/
class RandomEdge extends EdgeLayout {
}


Once these classes have been defined and compiled you should add the fully qualified path for your LayoutEngine class to the WILMA_CONSTANTS.properties file, and optionally set it as the default layout, eg:

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

DefaultLayout=Random

Then, run WilmaScope, ensuring the path to your new classes and your copy of the WILMA_CONSTANTS.properties file are added to the classpath, eg:

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

As discussed throughout this document, modifying the Wilma source code is not usually necessary to extend the system with plugins or to use it inside another application. However, it may be useful to look at the source to find out how something works or to fix a bug that you can't wait for us to fix (if you do so, please send as details of the fix!).

As of Version 3.0 the WilmaScope binary distribution includes source code in the WILMA_HOME/src directory. However, it is recommended that you obtain the most recent source version by accessing the CVS repository. The easiest way to do this is with the Eclipse IDE as follows:

• 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