MetaCombine Organization Visualizer

                                 version .3.1a

                                  2005-05-10

                                Stephen Ingram
                               Emory University


Overview
========

This software allows users to visualize Organization hierarchies.
Organizations are XML documents specifying a taxonomy of documents.  The
sofware provides the ability to rapidly observe the relationships between
document categories.  It does this by performing a prinicpal components
analysis of the centroid of each collection of categories in the organization
and then plotting the categories according to these new coordinates.  The
software also functions as a browsing interface to an organization by allowing
the user to view item listings of each category and view detailed metadata
information for any item.

This software is part of the MetaCombine project, which seeks to  more
meaningfully bring together digital library resources, helping to build more
coherent services on top of them.  

See http://www.metacombine.org/ for more on MetaCombine.


Dependencies
============

You must first ensure that java of a version that is at least 1.4.2_05 is
properly installed on your system.  You must also have the java plug-in
configured with your browser. If you are running Windows, you will need some
method, to zip/unzip files.  WinZip is a popular program for this purpose.

You will also need to download and build the prefuse libraries.  These are a
set of libraries for java that aid in information visualization.  You can find
these here:

 http://prefuse.sourceforge.net/index.html

Finally, you will have to have the Colt distribution of Open Source Libraries
for High Performance Scientific and Technical Computing in Java.  It can be
found here: 

 http://hoschek.home.cern.ch/hoschek/colt/


Running
=======

Decompress the scheme_viz.tar.gz file. It should create a directory called
scheme_viz.  Copy your colt.jar file from your Colt distribution (see
Dependencies section) to this directory.  Also copy the prefuse.jar and
prefusex.jar files from your prefuse build directory to this directory.

Before an organization can be visualized, you must preprocess the organization
XML.  In the scheme_viz directory there are (among other things) two different
scripts that preprocess the XML, one for Windows (preprocess.bat) and one for
Unix (preprocess.sh).

IN WINDOWS: You run the preprocessor by moving to the newly created scheme_viz
directory from the command line and type "scheme_preproc.bat organization
basename" where organization is the name of your organization xml file and
basename is the basename of your metadata map files.  This will generate a file
organization.dat.  Zip this file into a file named organization.zip

IN UNIX: move to the newly created scheme_viz directory and execute the script
"./scheme_prepoc.sh organization basename" where organization is the name of
your organization xml file and basename is the basename of your metadata map
files. This will generate a file called organization.zip

Now that you have the file called organization.zip in the scheme_viz directory.  
Load the file scheme_viz.html in your browser and the visualization should
begin.  If the applet has a red x on it, then your plug-in is not the correct
version (though the applet should inform you if this happens).  

If you want to name your file something other than organization.zip, check the
scripts and the applet parameters in the html for the filename and change them
accordingly.


Instructions
============

The scheme_viz.html file contains proper instructions for operating the 
visualization.


Building
========

Ensure the colt.jar, prefuse.jar,and prefusex.jar are in the decompressed
root directory.

IN WINDOWS: from the command line move to the decompressed root directory.
Then type "build.bat".

IN UNIX: move to the decompressed root directory and type "make".


License
=======

BSD.  See included "LICENSE" file.

Contact
=======

If you want to make a bug report, open the Java Console window and check if
there is a stack trace printed out.  Attach or include the text in an email to
me.  

I can be contacted at singram@emory.edu.

Permanent contact: mhalber@emory.edu.

Stephen Ingram
Emory University
General Libraries

The MetaCombine Project