The Ontopia Vizigator

User's Guide

Published by:Ontopia


This document introduces the reader to Vizigator. It provides guidance on the use of Vizigator to:

Reading this document assumes some basic knowledge about topic maps. If you are not familiar with topic maps, try reading one of the simple introductions, such as The TAO of Topic Maps, available from the Ontopia web site. If you are technically minded, you might also want to look at the XTM Specification or the latest drafts of the new version of ISO 13250, especially the Data Model.

We welcome any suggestions you might have on ways of improving this User Guide. Please send them to the mailing list.

Happy Vizigating!

Table of contents

1. Introduction

The Topic Maps model describes the knowledge structures inherent in an underlying body of information. This model, which reflects the associative mode typical of the way humans think, can then be intuitively perused in different ways.

One possibility is a text-based interface. The Ontopia Omnigator (the name is a contraction of "omnivorous navigator") uses a form-based navigation paradigm that is commonly known and used by most of us every day when using the web.

However, often a picture or graphic can be easier to grasp than a wordy description. The Ontopia Vizigator ("vi[z]ual navigator") uses a graphical interface to provide an additional method of topic map navigation. Although Vizigator can be used on its own, it is also well-suited to complement a text-based interface.

1.1. Components

Vizigator consists of three components which are related/dependent on each other.

Vizigator uses TouchGraph, an open source toolkit for graph visualization, which is maintained as a Sourceforge project. For further information, please see the Sourceforge project homepage and the TouchGraph homepage with other example applications.

1.2. Scope of Use

Vizigator is designed for graphically browsing and navigating topic maps. It supports all aspects of ISO 13250 with the exception of merging and some aspects of scope. It accepts topic maps in a variety of serialization syntaxes.

Vizigator is used to visualize a topic map, not an ontology. That is, Vizigator is designed to help users understand, navigate, and browse a populated topic map via a graphical interface.


It is possible to visualize an ontology using Vizigator; however, it requires modifications to the topic map. One way to accomplish this is to create a topic type, such as 'ontology_topic' and make all typing topics an instance of that type.

Creating and editing topic maps via Vizigator is not supported at this time.

1.3. Localization Support

Vizigator has internationalization support for translating the user interface into any language. The following table lists the currently supported languages and the codes that should be used to designate their use (see section 2.1 and section 3.2). Additional languages will be added over time.

Table 1.1. Interface localizations

LanguageCodeTranslation Acknowledgements
JapanesejaThank you to Motomu Naito, CEO of partner Knowledge Synergy, Inc., Japan
GermandeThank you to Ingo Schönfeld, Knowledge Engineer at ATLAS Elektronik GmbH, Germany

Users interested in translating the interface to an unsupported language should contact the Ontopia project mailing list.

2. VizDesktop - Getting started with Vizigator

VizDesktop provides:


The VizDesktop application is developed using the GUI toolkit (Java Foundation Classes(JFC)/Swing) provided with Java platform 2 standard edition (J2SE). The general look and feel of the user interface is according to the Java Swing controls in order to run on both Windows and Unix/Linux clients.

2.1. Starting VizDesktop

Prerequisites: VizDesktop is a Java application and requires the Java Developer Kit (JDK), Standard Edition Version 1.3 (or higher).

Starting VizDesktop:

  1. On Windows execute the vizdesktop.bat file in ${ONTOPIA_HOME}\bin.

  2. On UNIX/Linux execute the file in ${ONTOPIA_HOME}/bin.

To set the language used in the VizDesktop interface, you can edit the command line in the .bat or .sh file with the parameter --lang=<lang> where <lang> is a two-character designation of the language to be used. (See section 1.3 for the list of supported languages.) Alternatively, you can add the parameter when invoking the batch files:

  1. On Windows: vizdesktop --lang=<lang>

  2. On UNIX/Linux: --lang=<lang>

Please send all comments to Bugs can be reported in the bug database.

2.2. The user interface

2.2.1. Primary graphical conventions

Conventions for visualization of topic map constructs are as follows:

If no predefined configuration is associated with a topic map, each type of topic and each type of association is automatically and randomly assigned a color each time the topic map is opened. These colors can be changed and saved in a configuration for the specific topic map.

2.2.2. Viewing principles

For the purposes of this section, we will ignore the fact that the graph in Vizigator represents a topic map, and instead focus on the graph and what happens to it. This means that in general, a node is considered to be just a node, regardless of whether it represents a topic or an association.

The graph available through Vizigator is best seen as divided into three sets:

The complete graph

This is the entire, unfiltered graph where every topic and association in the topic map have corresponding nodes and edges.

The filtered graph

This is the graph as filtered by the type and scope filter settings.

The visible graph

This is the graph that is actually shown in the Vizigator screen (including parts that may be scrolled off outside the rectangle currently being shown).

The visible graph is always a subset of the filtered graph (though not necessarily a true subset), and the filtered graph is always a subset of the complete graph (though again not necessarily a true subset). The filter settings determine what's in the filtered graph, but determining what is in the visible graph is more complex. There are two views or modes of operation for the visible graph:

Map View

In Map View the visible graph is the filtered graph, minus nodes and edges explicitly hidden by the user.

Topic View

In Topic View, that is, when there is a Focus Node, the visible graph is the fragment of the filtered graph within X steps of the Focus Node. However, the user can modify the visible graph by both adding and removing nodes and edges.

When initially loading a topic map, dialog boxes allow the user to choose a Focus Node, to proceed with modelling a Map View, or to cancel the loading. From a Topic View, Map View can be can be restored via the View\Map View menu item.

VizLet (and VizPlugin) and VizDesktop behave the same way, with the exception that VizLet always operates in topic view.

2.2.3. Screen Layout

The VizDesktop window includes a main menu bar, three scroll bars, a number control, and a search box:

Figure 1. VizDesktop user interface

To hide/display the scrollbars, zoom bar, search box, and locality factor, right click on the background and select "Toggle Controls". Alternatively, only the search box can be removed from the display through use of the check box.

2.2.4. Menus

The main menu bar consists of the following menu items:


If a menu item has been assigned a keyboard short cut, it is shown to the right of the item's name.

2.2.5. Loading a topic map

Vizigator recognizes all files with the extensions .xtm,.hytm, .ltm, .tmx, .rdf, or .n3.

What to expect when loading a topic map will differ depending on whether or not a configuration has been saved for the topic map.

Hints for achieving a sensible display of a very large topic map:

2.2.6. Navigating the graph

The following section gives a short introduction and overview of the default actions available using the mouse:


For changing the default mouse actions, see section 2.4.4

2.2.7. Summary of operations

This section summarizes the effects of the various operations. Since the effects of operations are different in the two views, each view is described separately. Topic View

Topic View is the view where there is a Focus Node, and the visible graph (at least initially) contains only the nodes within a specified distance (the locality) of the Focus Node. Distance is computed with no regard to whether nodes represent topics or associations. The Focus Node is always in the visible graph.

Hide node

If hiding the node disconnects part of the visible graph that part is removed.

Hide edge

If hiding the edge disconnects part of the visible graph that part is removed.

Expand node

All nodes in the filtered graph that are neighbours of the expanded node become visible together with the edges connecting them to the expanded node and any edges between the newly visible nodes.

Collapse node

All nodes which only have edges to the collapsed node and between each other are removed from the visible graph.

Set Focus Node

Whether done by double-clicking a node or setting the Start Topic, recomputes the visible graph from the new Focus Node with the existing locality setting.

Change locality

Recomputes the visible graph from the existing Focus Node with the new locality setting. (This ignores the user's expanding/collapsing/hiding modifications, but is a consistent behaviour, matches the current code, and is the simplest option.)

Filter out

Any nodes and edges filtered out of the visible graph are removed, and any parts of the graph disconnected from the Focus Node by this are also removed.

Filter in

The topic view is recomputed, but without hiding already visible nodes/edges outside the topic view. Map view
Hide node

The node and all its edges are removed from the visible graph.

Hide edge

The edge is removed from the visible graph.

Expand node

Any of the node's edges which are in the filtered graph but not in the visible graph are added, together with the nodes on the other side and any edges between those nodes in the filtered graph but not in the visible graph.

Collapse node

All nodes which only have edges to the collapsed node and between each other are removed from the visible graph.

Set Focus Node

Whether done by double-clicking a node or setting the Start Topic, moves into topic view.

Change locality

No effect.

Filter out

Any nodes and edges filtered out of the visible graph are removed.

Filter in

New nodes and edges are added to the visible graph.

2.2.8. The Properties box

The Properties box is accessed via a topic's context menu (right mouse click). Where applicable, it contains:

Figure 2. Properties Box

The Properties box remains open until specifically closed. Its contents are updated each time a different topic's properties are requested.

2.3. Searching in VizDesktop

The search box provides an alternative way to find topics. Enter all or part of a topic name in the search box. Vizigator will search the topic names that appear in the topic shapes. The hits will blink and the visible part of the topic map will be repositioned to center the hit with the highest relevance (i.e., closest matches).

If more than one hit is displayed, the topic type can be determined by right clicking on a blinking topic to a ccess its Properties box. Once the appropriate topic has been found, right clicking to set it as the Start Topic will localize a Topic View around the chosen topic.

Using the Clear button will clear the search box, stop all topics from blinking, and reset the cursor within the search box.

2.4. Configuration

2.4.1. Components of a configuration

A configuration is defined by the current state of each of the items under the following menus:

Optionally, if a Start Topic is specified, it will be saved as part of the configuration.


The locality factor is not saved as part of a configuration. If a topic map is opened in Topic View, it will conform to the current setting of the locality factor.

2.4.2. Filtering Topics and Associations

The Filtering Topics and Filtering Associations menus provide checklists for including or excluding topic and association types to be displayed. Unchecking the box of a particular topic type will remove all of the topics of that type from the visualization, as well as any associations by which they are linked to other topics. Conversely, unchecking the box of a particular association type will remove all of the associations of that type and any topics that are only in the visualization because of that association.

For example, assume that a topic map has both born-in and died-in associations, each expressing relationships between a person and either a city or a country.

Unchecking the topic type city will remove not only all of the topics of type city, but also all born-in and died-in associations in which a city plays the place role, but not in which a country plays that role. Unchecking the born-in association will remove all such associations and topics of type either city or country that play the place role in each instance of that association (and which do not play any other roles in that view).

Note that if the checkbox is shown in gray this means that the topic or association type has no setting, and that the setting used is that of the default topic or association type. Checkboxes shown in green or red are set specifically for the given topic/association type. The menu will contain an item for "Default type" which can be used to change the default setting.

2.4.3. Styling Topics and Associations

The Styling menu consists of two items to change the randomly pre-assigned shapes, colors, and fonts used to designate topic and association types.

The Styling\Styling Associations and Styling\Styling Topics menu items each bring up similar dialog boxes for choosing the Shape (geometric shape, weight) , color, and font to be used for topics or associations of a particular type. The Icon portion of the Shape tab can be used to stipulate an icon to appear to the left of each topic of that type. Clicking Clear will clear the field and remove the icons for the designated type.

Note that a type can either have a specified setting, or it can use the setting for the default type. The default type appears in the list and its settings can be changed just like those of real types. There is also a button for each type that can be used to remove all settings so that it reverts to getting its settings from the default type.

2.4.4. Determining General Options

The Options\General menu item brings up the multi-tabbed General Options dialog box, which is used to set more general parameters:

2.4.5. Topic Type Precedence

The Options\Topic Type Precedence menu item brings up a simple dialog box that can be used to specify the precedence order of topic types. This is used to determine how to render topics which have more than one type. Topics which have more than one type will then be rendered according to the configuration for the topic which is comes first in the precedence order.

2.4.6. Name Scoping

The Name Scoping menu offers a choice of scoping topics available in the topic map (if any) to be applied to the Topic Names of all topics. Choosing a scoping topic makes that scope active. The active scope will be saved with a configuration.

2.4.7. Association Scoping

The Association Scoping menu offers a choice of scoping topics available in the topic map (if any) to be applied to the Association Types of all topics.

The menu is divided into two sections. The top section has three options:

The lower section contains one item for every topic that occurs in the scope of an association in the topic map, sorted alphabetically. If the scoping topics are instances of more than one type (say, if some are instances of "language" and others of "country"), the menu will have an additional level.

Choosing a scoping topic makes that scope active. The active scope will be saved with a configuration.

2.4.8. Saving and using the configuration

The current state of the configuration settings can be saved using the 'File menu'.

When a topic map (e.g., foo.xtm) is loaded into VizDesktop, if a configuration file (e.g., foo.xtm.viz) exists in the same directory, it will be automatically loaded at the same time.

Otherwise, a topic map is loaded without a defined configuration, that is, all topics and associations are visible and VizDesktop uses default shapes and fonts, and randomly assigned colors for topic and association type displays.


In order for configuration files to properly do their job, they have to be able to reference topics in a topic map. There are a number of ways in which this can be done, some more robust than others.

The most robust method is through a subject identifier, which Vizigator will use if available. Where no subject identifier has been specified by the author of the topic map, the fallback solution is for Vizigator to use the item identifier, which involves pointing back into the source topic map file itself. What this means is that if the file is moved to another location, the references may break. The moral of this story is always use subject identifiers, especially for typing topics.

3. VizLet - Vizigating in web applications

VizLet is an applet that provides the same visualization functionality as VizDesktop, except that the menu bar (and all the functionality available through it), is unavailable. VizLet is intended to be used to add visualization functionality to web applications and can be embedded in any web application.

3.1. Comparing VizLet to VizDesktop

The following restrictions apply to VizLet compared to VizDesktop:

The following differences apply to VizLet compared to VizDesktop:

3.2. Using VizLet in a web application

VizLet can be added to a web page by adding the following HTML to the page:

  <applet width="800" height="800" alt="Ontopia vizlet" 
    <param name="baseuri"  value="omnigator/plugins/viz/"/>
    <param name="tmid"     value="opera.ltm"/>
    <param name="idtype"   value="indicator"/>
    <param name="idvalue"  value=""/>

The applet parameters are as follows:

This is the URL on the server where the TMRAP servlet can be found. (More about how to set these up below.) The URL is resolved relative to the code base of the applet.
This is the URL on the server where the configuration topic map in XTM syntax can be found. VizLet will load it directly from this URL. The URL is resolved relative to the code base of the applet. If this parameter is omitted, VizLet will work without a configuration.
This is the ID of the topic map in the topic map registry.
This is the identifying value used to look up the Focus Node to be loaded in VizLet. This is always a URI.
This tells VizLet what kind of identifier is contained in the idvalue parameter. The alternatives are "source" (meaning item identifier), "indicator" (meaning subject identifier), and "subject" (meaning subject locator).
The name of the HTML frame in which Vizlet should open topic pages when the user selects the "Go to Topic Page" menu item in Vizlet. Defaults to the current frame if not set.
The name of the HTML frame in which Vizlet should open URLs when the user selects a URL in the Properties box. Defaults to _blank (meaning new frame every time) if not set.
The identifying value used to look up the topic used for name scoping, identified by URI. A value set here will override a value saved in the Vizigator configuration.
This tells VizLet what kind of identifier is contained in the scopevalue parameter. The alternatives are the same as for idtype.
A boolean value of 'true' or 'false' that specifies whether the control panel should be visible or not. The default is 'true'.
Specifies the language that is to be used in the user interface. The default is 'en' (English). See section 1.2 for the currently supported languages.
Specifies the location of a file which describes which menu items in popup menus are to be enabled or disabled. The value is a URI relative to the URI the applet was loaded from. For more detail, see section 3.2.1.
The locality setting VizLet starts with on loading. The default is 1.
The largest locality value which VizLet will accept. The default is 5.
A URL pointing to an image to be used as a wallpaper background in the Vizlet. If no URL is provided, no background will be shown.

In order for this to work, a number of things need to be set up on the server side, and we will walk through them one by one. One example of how this can be done can be found in VizPlugin for Omnigator; looking at its source code may be instructive.

The first step is to make the ${ONTOPIA_HOME}/extras/ontopia-vizlet.jar file available on the server side. Put it anywhere you want, then make the applet element refer to it. Use the Java console of your web browser to check whether you have succeeded or not. For more information consult the HTML 4.01 Recommendation.

The next step is to set up the TMRAP (topic map remote access protocol) servlet used by the applet to download topic map fragments for the visualization. This is done by adding the following to the web.xml file of the web application:



The url-pattern parameter must match what is given in the tmrap parameter to the applet, so that the servlet is made available where the applet expects to find it. Also, the uri parameter to the servlet must be a URI template where once the topic map ID and topic ID are filled in, the main page for the topic can be found. VizLet will go to this URI when the "Go to Topic Page" option is selected in VizLet.

The final part is to place the configuration XTM file somewhere on the server so that VizLet can download it. This must be in the location that the config parameter refers to. VizPlugin uses a JSP file to do this, because it needs to be able to support multiple configurations, but if you only have a single configuration file you can just refer to it directly and store it on the server as a normal file.

If you experience unexpected results with VizLet, please do the following:

3.2.1. The menufile parameter

As stated above, this parameter specifies the location of a file which describes which menu items in popup menus should be visible. The menu file is a normal text file, of which an example can be seen below:

properties=off       # users never use this, anyway
set.start.topic=on # we don't have topic pages

Menu items that are not mentioned in the file will be displayed (and if the parameter is not given all items are displayed). The list of menu choice names is:

expand.nodeExpand node
collapse.nodeCollapse node
hide.nodeHide node
hide.edgeHide edge
set.start.topicSet start topic
copy.nameCopy name to topic page search bar
toggle.controlsToggle controls
set.all.nodes.stickySet all nodes sticky
set.all.nodes.unstickySet all nodes unsticky
stop.moving.nodesStop moving nodes
enable.motion.killerStart/stop motion reduction
enable.neighbour.circleEnable neighbour circle
topic.stylesTopic type configuration
association.stylesAssociation type configuration

3.3. The "Copy name" operation

In VizDesktop the popup menu on topic nodes contains a "Copy name" choice, which copies the name of the node to the system clipboard. This menu choice is by default not present in VizLet because for security reasons applets do not have access to the clipboard. (Otherwise, web pages would be able to spy on your clipboard, or spam it with unwelcome content.)

To solve this, there is another version of the VizLet in the ${ONTOPIA_HOME}/extras/signed-vizlet.jar file, which is cryptographically signed. This gives the VizLet access to the clipboard, provided users accept the certificate with which it was signed. In order to avoid bothering users with certificates the VizPlugin (see section 4) does not use the signed applet.

Using the signed applet is not in itself enough to enable the "Copy name" menu item. To do this, use the menufile parameter to VizLet as described in section 3.2.1.

4. VizPlugin - Vizigating in Omnigator

VizPlugin is an Omnigator plug-in that adds support for graphic visual navigation of topic maps. It uses VizLet (described in section 3) to support visualization directly in the browser. Like the other plug-ins, it appears as a button (Vizigate) in the row of links at the top of Omnigator topic pages.

All of the restrictions and differences that apply to VizLet, when compared to VizDesktop, also apply to VizPlugin.

4.1. Using VizPlugin

To use VizPlugin, click on the Vizigate link, and the current topic will be loaded into VizLet and displayed. To return to the Omnigator view, right click on the topic to be viewed in Omnigator and choose the additional menu item available , Go to Topic Page.


For this to work, support for Java applets must be turned on in your browser, and it must also support Swing applets.

Figure 3. VizPlugin is VizLet as used in the Omnigator

VizPlugin will work for any topic map, regardless of whether a configuration has been created for it or not, but results are more likely to be more consistent if a configuration exists.