To date there hasn't been a free software tool to handle both authoring and presentation of large graphs in WWW. IHMC Concept Map tool is ideal for authoring, since it is easy to use and it handles external links, automatic layout as well as multiple output formats. Its HTML output has some limitations, though. Concept map is exported as a single image, which can be inpractical when large graphs are considered. Therefore a different graph presentation is needed.

TouchGraph is an innovative graph browsing component developed by Alex Shapiro. With TouchGraph LinkBrowser it is possible to browse even large graphs because thethe view can be restricted to a local portion of the graph. The graph is browsed in an applet. Links can be opened in a separate frame. TouchGraph LinkBrowser uses a XML-based format for graph presentation which is good for interoperability but rather poor for authoring graphs. LinkBrowser can be used as a basic graph editor, but creating graphs is still rather tedious, especially is you want to include external links or other extra information for nodes.

Xcm2kg tries to solve this authoring vs. browsing problem by supporting concept map authoring with IHMC Concept Map tool and publishing with TouchGraph techology. Moreover, it facilitates TouchGraph's interoperability with other graph drawing applications as well by using GXL (Graph eXchange Language) as intermediate format.

Xcm2kg is a conversion utility that converts concept maps from IHMC Concept Map tools XCM format to KeyGraph, a graph user interface format based on TouchGraph. External resources (ie. pictures, URL links, other concept maps...) eferenced in XCM file are converted to URL links and shown as tooltips in Linkbrowser nodes. Optionally, pictures can be shown directly in tooltip and URL links can be activated directly by doubleclicking LinkBroser node. References to other concept maps (actually, KeyGraph XML files) are passed to a simple PHP-based framework that generates appropriate HTML-page that loads the XML file.

Xcm2kg's purpose is to simplify concept map authoring and web publishing. While being a simple converter, it integrates IHMC Concept Map tools and TouchGraph in a natural way.

Concept map (mind map).  An informal visual representation of knowledge organized in a graph-like form. Concepts maps are developed by J. D. Novak and they are often used as learning tools. As a graph model they are closely related by semantic networks used in AI. See also: J. D. Novak: The Theory Underlying Concept Maps and How To Construct Them.

GXL (Graph eXchange Language) .  XML-based language for representing graphs. Note that only graph structure (not presentation) is defined by GXL (although attributes can be used also for layout information). See also: GXL Home Page.

JGraph.  An open source Java-based graph editor developed by Jgraph.com. JGraphPad component is used in Xcm2kg conversion process. See also: JGraph Home Page.

TouchGraph.  An open source graph-based user interface technology developed by Alex Shapiro. It's based on a graph with clickable and navigable nodes that user can drag around (usually in Java applet). Xcm2kg's output is based on XML format used by TouchGraph LinkBrowser. See also: TouchGraph Development.

Inline resources.  Pictures that are marked as external resources in IHMC Concept Map tool can be shown as tooltips in LinkBrowser nodes. This way seeing the image requires no additional clicking as in other resources. Inline images must have a label with in_-prefix.

Local/external links.  URL links can be local (opened in same browser window, not necessarily in the same frame as LinkBrowser applet) of external (opened in new browser window). External links must have a label with ext_-prefix.

Framework for WWW-publishing.  Xcm2kg features a simple PHP-based framework that eases putting KeyGraph maps on the web. The PHP script searches for all files with kg extension and generates a list based on them. It also generates code for starting a LinkBrowser applet with selected graph.

M:N-relation resolution.  With IHMC Concept Map tools it is possible to design relations that have multiple roles (for example, three nodes connected by a single 'arc'). This is not possible in KeyGraph, so Xcm2kg generates corresponding edges for all possible combinations. (in above example, two edges are generated, their directions depending on how relation was represented in XCM).

Directory listing from the root directory of Xcm2kg shows the following.

bash$ cd /dir/where/you/extracted/xcm2kg
bash$ ls -la
drwxr-xr-x    8 minurmin users        4096 Jan 19 17:45 .
drwxr-xr-x    6 minurmin users        4096 Jan 19 17:46 ..
-rw-rw-rw-    1 minurmin users       26432 Sep  2 21:44 LICENSE
drwxr-xr-x    3 minurmin users        4096 Jan  7 17:53 classes
-rwxr-xr-x    1 minurmin users          73 Jan  5 22:05 convert.bat
-rwxr-xr-x    1 minurmin users         226 Jan 19 17:44 convert.sh
-rwxr-xr-x    1 minurmin users         641 Jan 19 17:36 convert_modules
drwxr-xr-x    4 minurmin users        4096 Jan 19 16:09 doc
drwxr-xr-x    2 minurmin users        4096 Dec 29 18:22 lib
drwxr-xr-x    4 minurmin users        4096 Jan 19 17:45 maps
drwxr-xr-x    2 minurmin users        4096 Jan 19 16:50 src
drwxr-xr-x    2 minurmin users        4096 Jan 19 17:39 tmp
bash$

LICENSE contains software license. Documentation is found from doc/, Java classes from classes/ and external (JGraph) libraries from lib/. convert.bat, convert.sh and convert_modules are example scripts to invoke conversion. maps/ contains php-framework and some example graphs, source code is within src/. tmp/ is optional temporary directory that can be used during conversion process.

Xcm2kg converts concept maps using 2 filters (Xcm2gxl and Gxl2TouchGraph), which can also be used separately. Xcm2kg is just a wrapper. The overall process is shown in Figure 1.

Figure 1. Xcm2kg-process

Actually, before applying Xcm2gxl and Gxl2TouchGraph, concept map is passed to simple filter (DisposeUTF) that merely fixes the XML declaration of XCM file from UTF-8 to ISO-8859-1. This is done because of a minor bug in IHMC Concept Map tools, see Section 4.2.

Xcm2gxl converts XCM file from IHMC Concept Map tools to a generic graph interchange format, GXL. The converter doesn't do anything to external resources. References and node/edge labels are preserved as attributes. Layout information is presented as nonstandard node attribute style. For example:

<node id="1059035_286" style="left=394px;top=141px;width=85px;height=20px;">
  <attr name="resource_1">
    <string>relativeURL=file:/./meta/foo.gif;name=foo;desc=Desc</string>
  </attr>
  <attr name="label">
    <string>some label</string>
  </attr>
</node>

Gxl2TouchGraph converts GXL-file to KeyGraph format. KeyGraph is similar to format used in TouchGraph LinkBrowser 1.20 apart edge labels and a few additional parameters (see KeyGraph relase notes for additional information). During conversion, URL-links are embedded directly in kg-file, references to other concept maps are resolved and inline pictures are handled.

Xcm2kg requires Java Runtime Environment 1.4 (or J2SDK 1.4 if you want to compile it). The converter has been tested in Linux and Windows 98/2000/XP, but theoretically it should run with any OS that has Java 1.4 available. Xcm2gxl-filter requires JGraph 3.0 and JGraphPad 3.0 -packages (jgraph.jar and jgraphpad.jar) and they are included in default distribution.

PHP-framework requires a PHP-enabled website, but you can also use plain HTML if you wish. On HTML alternative see Section 4.3.

Xcm2kg can be obtained from http://www.maths.jyu.fi/~minurmin/.

Extract the distribution package on a place where you keep your local program files.

Note that directory maps contains PHP-files that should be run within scope of a PHP-enabled Web server. It is recommended that you copy the directory and your converted kg-files with resources to your web site and adapt the PHP/HTML-files as you see fit.

If you have GNU tar, extracting goes with command.

bash$ tar --extract --ungzip --file=xcm2kg.tar.gz

Currently Xcm2kg has no configuration files. Everything (not very much...) can be configured with command-line parameters.

All classes in Xcm2kg packet accept parameter -h that prints a short help text about current class.

All submodules DisposeUtf, Xcm2gxl, Gxl2TouchGraph can be used as filters. That is, standard input and standard output can be used. For example (Linux):

bash$ cat workpath/input.xcm | java -cp classes Xcm2gxl > workpath/output.gxl

You can also use switches -i and -o. They can be used instead of standard I/O as follows:

bash$ java -cp classes Xcm2gxl -i workpath/input.xcm -o workpath/output.gxl

Note that the wrapper class Xcm2kg accepts only parameter -i (no standard I/O) and converts file automatically in same directory as input, extension kg.

Xcm2gxl accepts additional switch -nowindow (used in convert scripts). If the switch is not used, a JGraph window is opened so user can check the conversion result.

Gxl2TouchGraph has additional parameter -dir that can be used to specify the base directory for XCM resource files. This is the same directory as the location of the original XCM file (not the actual directory where the resources are located - this is read from the XCM files).

Currently, Xcm2kg does not preserve any font, color or other style information about the graph except relative node positions. All such info is stored in the XCM file, so basically some of it could be used in conversion as well.

There are some minor bugs in IHMC Concept Map tools v3.0 considering the XCM export. In the XML file declaration it is claimed that character encoding is set to UTF-8. However, it appears that file content is similar to ISO-8859-1 after all (at least if scandinavian characters ä, ö etc are concerned). This declaration problem is fixed by simple DisposeUTF-filter that corrects the declaration.

Another, somewhat more serious problem is related to resource file names. When concept map is exported to XCM, resource file names are not preserved. The names are converted similar to their description strings that are shown in the Concept map. This can lead to name collisions if different resources are described with same names. IHMC has been notified about the bug but it has has not been fixed at the time of writing this manual.

Xml2kg uses some special resource naming conventions that are not directly supported by IHMC Concept Map tools. They are described in Section 1.4.

The output format Xcm2kg uses is compatible with format used by TouchGraph LinkBrowser 1.20. However, Xcm2kg features some minor extensions that are implemented in KeyGraph package. The most notable addition is using edge labels. That is, using KeyGraph you can see edge labels that TG LinkBrowser does not recognize.

If you don't have PHP in your website, you must put references to concept maps and code to start the KeyGraph applet in your HTML pages. An example HTML-file Jaollisuus_new.html is in maps/-directory. Also, if your concept maps refer to other concept maps you must change the link target in kg-file. For example, the Xcm2kg-generated link in kg-file might look like this:

<NODE_HINT hint="&lt;a target=&quot;_blank&quot;
               href=&quot;map.php?map=meta&quot;&gt;Meta&lt;/a&gt;" 
               width="250" 
               height="-1" 
               isHTML="true"/>

If you have a file called meta.html and you don't use PHP, you could change the link as follows:

<NODE_HINT hint="&lt;a target=&quot;_blank&quot;
               href=&quot;meta.html&quot;&gt;Meta&lt;/a&gt;" 
               width="250" 
               height="-1" 
               isHTML="true"/>

It would be easy to adapt the converter such that links to local graphs are directed to on-the-fly-generated HTML files, but it hasn't been implemented at this relatively early state of development.