Xcm2kg
Miika Nurminen
Distance-learning designer
University of Jyva:skyla:, Department of mathematics and statistics
Xcm2kg is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 2.1 of the License, or (at your
option) any later version.
$ Date: 2004/1/28 $
Abstract
Converts concept maps from IHMC Concept Map tools 3 to KeyGraph (modified
TouchGraph format).
----------------------------------------------------------------------
Table of Contents
1. Introduction
1.1. Motivation
1.2. Purpose
1.3. Terminology
1.4. Features
2. Structure
2.1. Files and directories
2.2. Conversion process
3. Setting up Xcm2kg
3.1. Requirements
3.2. Installation
3.3. Configuration
4. Using Xcm2kg
4.1. Command-line parameters
4.2. IHMC Concept Map tool considerations
4.3. TouchGraph considerations
5. Development ideas
A. License agreement
1. Introduction
Xcm2kg is a conversion utility that converts concept maps from IHMC
Concept Map tools to KeyGraph, a graph user interface format based on
TouchGraph.
This manual is structured as follows: this section provides a brief
introduction to Xcm2kg, Section 2 describes program structure and
conversion process in more detail. Section 3 covers installation and
Section 4 covers utilization of the application. Finally, some development
ideas are discussed in Section 5.
1.1. Motivation
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.
1.2. Purpose
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.
1.3. Terminology
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.
1.4. Features
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).
2. Structure
Program structure and conversion process is described in this section.
2.1. Files and directories
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.
2.2. 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
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:
relativeURL=file:/./meta/foo.gif;name=foo;desc=Desc
some label
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.
3. Setting up Xcm2kg
System requirements and setup is described in this section.
3.1. Requirements
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.
3.2. Installation
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
3.3. Configuration
Currently Xcm2kg has no configuration files. Everything (not very much...)
can be configured with command-line parameters.
4. Using Xcm2kg
The simplest way to use Xcm2kg is by using convert-scripts. They call the
Xcm2kg-wrapper that handles everything quietly and hides details from
user. If you are interested in details of the conversion process, you
might want to look at convert_modules-script that does roughly the same
job as Xcm2kg-wrapper but calls each module explicitly.
The scripts may need adaptation on different systems. They should be easy
to modify if you know how to call Java programs and have a general idea of
how to use pipes and filters and standard I/O.
4.1. 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).
4.2. IHMC Concept Map tool considerations
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 a:, o: 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.
4.3. TouchGraph considerations
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:
If you have a file called meta.html and you don't use PHP, you could
change the link as follows:
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.
5. Development ideas
o Better support for direct GXL-KeyGraph -conversion. This would require
some standard way to represent style in GXL files. Some approaches are
implemented in GXLGraphPad and proposed in Mark Minas: Using GXL and
SVG for Describing Graphs with Layout.
o Developing map.php-framework, especially making it more configurable.
o Better IHMC Concept Map tool style support.
o More? Mail the author at or implement it
yourself. :-)
A. License agreement
Xcm2kg is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 2.1 of the License, or (at your
option) any later version.
Xcm2kg is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.
You should have received a copy of the GNU Lesser General Public License
along with Xcm2kg; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA