Using Royère

QuickStart Guide

To run Royere:

Make sure that your machine has JDK1.3 or better.

Running Royere is simplest with the use of the scripts provided in the scripts directory:


More Information

For more information on how to use Royere, see the help menu or press F1. Sample graph files can be found in the Graphs directory.

More information on the design of Royere can be found in separate files in the Docs directory. The Javadoc documentation is also there. (<- these links only available in the distribution.)

If you plan to develop with Royere, please send a message to Scott Marshall. Please also see An object-oriented design for graph visualization (published in Software - Practice & Experience)

Please send feedback and questions to (remove the SPAM bomb first):

Installation Overview

Royere is built on the Java 2 platform, and has been tested with JDK1.3. For speed reasons we advise you to use JDK1.3.

The current directory structure is as follows:

In some situations, you will want to adapt the file to your local configuration, primarily the entries for the online help and the DTD file. The current setting uses relative paths but if you want to run from another directory you will need to change them to absolute paths. The file must be in the directory where java is invoked to run the application.

Royere can be started by "java royere.cwi.appl.Royere" with an optional file name for a graph file. The input can be in GML or in GraphXML formats (the Newick format for consensus trees is also supported). The GraphXML format is preferred and Royere demonstrates many of its features.

The GraphXMLDocs directory contains:

Note to Developers: External Packages

There are a few scripts that can be used to automate package builds: makeclean, makeall, makedocs, and makejar. They are all runnable from bash (you can get bash for windows at the Cygwin Project. There is also a build.bat for DOS-style builds.

We have removed support for magician and two extra parsers from Sun and IBM because of the complexity that they added. Java2D is fast enough at drawing as long as you have the latest JDK and the Xerces parser is sufficient.

We are currently using a test framework for Java called JUnit that you might want to download. For examples look in the source/test directory.

Royere includes an on-line help facility, which is implemented using Sun's JavaHelp sytem (see the javasoft pages for further details). Also, the generation of jpg, png, or bmp format images is made possible through Sun's JIMI package (see again the javasoft pages for further details). These facilities are not strictly necessary to run Royère, and the application will recognize if the packages are not available; however, they are handy. We have added the necessary (minimal) jar files to the JarFiles directory, although you should probably license those with Sun if you want to develop any serious products based on those.

Extending Royere

It is possible to add new layout, metric, clustering, and metric colouring classes to Royere by only compiling one file and editing

To avoid confusion, we would prefer new packages and classes to be added in separate packages in the class hierarchy instead of being added to the current ones. At present, there is a royere and a cwi folder on the top. Forget about the top-level (cwi), this is for packages developed at CWI but which are not exclusively for Royère. Under royere there is a directory cwi which contains the various packages of Royere. If you want to add new packages, please make a new directory at the same level as cwi, labri, bath, and use the same structure as what can be found under cwi (structure, layout, view, etc., whichever you use). By doing so, we can keep our code compartmentalized.

The extension mechanism in Royère is based, internally, on a factory mechanism and, externally, on user property control. The factory mechanism means that there exists a LayoutFactory, MetricFactory, MetricVisualsFactory, and a ClusteringFactory object to generate new Metric, Layout, Clustering, MetricVisuals, and PanelEntry object instances. These factory objects, when properly initialized, build up an internal table containing the appropriate references (essentially the Class information) of all available classes.

Initilization of the factories is done by the application, making use of user properties. The properties would list the full classnames of the layout, metric, etc, objects which should replace and/or supplement the classes which are part of Royere by default. Because the Class objects are found and created dynamically at run-time, the average user does not have to recompile Royere to include a new layout object, for example, just to modify the property value.

Here are some more details:

How to extend Royere...

A new Parser:
Implement the class as a subclass of royere.cwi.input.Input. Do not forget to:

A new Metric:
Implement the class as a subclass of royere.cwi.structure.Metric. Do not forget to:

A new metric colouring class:
Implement the class as a subclass of royere.cwi.view.metrics.MetricVisuals. Do not forget to:
A new Layout:
Implement the class as a subclass of royere.cwi.layout.Layout. Do not forget to:

Common Steps to extend Royere with a new Metric, Layout, Clustering:

1) Implement a subclass of the new type:

  • Define a final static String Name.
  • Add the getName() method to give a meaningful name to the colouring in the menu. This method should return Name.
  • If your object depends on other objects, add them to dependentEntries.

    For example, if a particular metric instance is used, the system might require access to another metric class, too. To force the factory initialization to include those metrics as available metrics, you can override the dependentEntries method:

        public String  dependentEntries() {
          return "royere.cwi.structure.NeighborValueMetric:royere.cwi.structure.EdgeCountMetric";
    instructs the factory to load the two additional metric classes when loading the current one. Note, however, that those classes will not appear in the application menu, unless they are listed in the properties (see below) on their own right.
  • Implement the setRequirements() method, using other metrics, layouts, or clusterings as an example (StrahlerMetric, EdgeCountMetric, etc. See the javadoc documentation). These are usually graph-theoretic properties that are required by this algorithm.

2) Add the full classname to the property file as a possible value to the AdditionalOBJECTs key

(Replace OBJECT with one of: Layout, Metric, Clustering, or MetricVisual.)

If this is the only additional class, then the property file will include the line:

if you have several additional objects, then
note that you can use a shorthand by defining the possible class names separately:
See the file for examples.

Scott Marshall