# IsAViz: Installation Instructions

## 1. Quick Instructions

The following components are required to run IsAViz:

- A Java Virtual Machine version 1.3.0 or later (1.4 strongly recommended - see Known problems)
- A distribution of IsaViz, which contains the following Java JAR archives:
  - IsaViz itself (isaviz.jar)
  - Visual Transformation Machine (vtm.jar)
  - Jena version 1.3 (jena.jar)
  - Xerces-J version 1.4.x (xerces.jar)
- GraphViz from AT&T version 1.7.6 or later

More detailed information is available in the following sections.

## 2. Requirements

### 2.1. Java Virtual Machine (JVM)

IsAViz is written in Java. The GUI is built on VTM, a ZUI toolkit that heavily relies on Java2D. This basically means that you will need a JVM version 1.3.0 or later.

IsAViz has only been tested with Sun's JVM, which can be found at:
http://java.sun.com/j2se/1.4/
http://java.sun.com/j2se/1.3/

A JVM 1.4.0 or later is strongly recommended since Java2D performances have been noticeably improved from 1.3 to 1.4 (read also Known problems). If you want to compile IsAViz, a JDK 1.4.x is required (IsAViz uses the ImageIO API for the PNG export feature).

### 2.2. VTM (Visual Transformation Machine)

Xerox's VTM is the ZUI (Zoomable User Interface) toolkit on which is based IsaViz's GUI. It is included in this distribution (vtm.jar). More information is available at http://www.xrce.xerox.com/competencies/contextual-computing/vtm/

### 2.3. Graphviz/dot

AT&T's GraphViz/dot is a tool for making hierarchical layouts of directed graphs. It is used only to compute the initial layout of imported RDF models and when the user wants IsaViz to suggest a new layout for an existing graph. It is therefore not required in order to run IsaViz, but major features will not be available if you do not install it.

GraphViz is not written in Java, but is available on a wide range of platforms (see Graphviz's web site for an up-to-date list):

- Windows
- Linux
- Solaris (x86 and Sparc)
- DEC Alpha
- HP-UX
- SGI Irix
- Mac OS X

GraphViz is not included in the IsaViz distribution, but is freely available at http://www.research.att.com/sw/tools/graphviz/

You must download version 1.7.6 (with support for SVG) or later. IsaViz only requires the DOT program. I strongly suggest using version 1.8.1 or later as you may have some problems with earlier versions when trying to import some RDF files (see Known problems).

Note: GraphViz can be installed in any location. You will be able to configure it from IsaViz's Preferences window.

### 2.4. Jena Semantic Web Toolkit

HP's Jena is a java API for manipulating RDF models. It is included in this distribution (jena.jar). More information is available at http://www.hpl.hp.com/semweb/jena-top.html

### 2.5. Xerces-J

Apache's Xerces-J is a java XML parser. It is included in this distribution (xerces.jar). More information is available at http://xml.apache.org/xerces-j/index.html

## 3. Installation

The installation procedure should be fairly quick and simple. Unpack IsaViz.zip in any location you want. This will create a directory named IsaViz which will contain the following files and directories, among others:

IsaViz\
|
|
---isaviz.cfg (configuration files where user preferences are saved)
|
|
---export\ (default directory for RDF/N-Triple/SVG and PNG files exported from IsaViz)
|
|
---lib\ (contains all JAR files required by IsaViz)
|
|
---projects\ (default directory for ISV (isaViz project) files)
|
|
---tmp\ (default directory where are stored temporary files used to communicate with GraphViz/dot)

The top-level directory also contains launch scripts for Windows (run.bat) and POSIX systems (run.sh) that should be working immediately provided that java is in your PATH.

Note: IsaViz uses Jena and Xerces-J (included in the distribution). You might want to use versions of these other than the ones included. The requirements are:

- for Jena, version 1.2 or 1.3 (version included in this package: 1.3)
- for Xerces-Java 1, version 1.4.x (version included in this package: 1.4.4)

Note: GraphViz can be installed in any location. You will be able to configure it from IsaViz's Preferences window.

## 4. Running IsaViz for the first time

Once you have the following installed:

- a JVM 1.3.0 or later (1.4 (even beta or candidate release) strongly recommended: Known problems)
- GraphViz 1.7.6 or later (only the dot program is required)
- IsaViz

you should be able to run IsaViz by either:

- using one of the available scripts (run.bat) or (run.sh)
- entering the following command line from the IsaViz directory
  Windows: java -classpath lib\isaviz.jar;lib\vtm.jar;lib\jena.jar;lib\xerces.jar org.w3c.IsaViz.Editor
  POSIX: java -classpath lib/isaviz.jar:lib/vtm.jar:lib/jena.jar:lib/xerces.jar org.w3c.IsaViz.Editor

The main class is org.w3c.IsaViz.Editor

The last step consists in configuring some directories. Launch IsaViz, go to Edit->Preferences, choose the "Directories" tab.

You have to choose a valid directory for temporary files (e.g. IsaViz/tmp or C:\Temp).
Then you have to tell IsaViz where to find GraphViz/dot: browse to the location of the dot executable file
(e.g. C:\Program Files\ATT\GraphViz\bin\dot.exe
or /usr/local/graphviz/bin/dot).

The other directories are optional. You can set the font directory to GraphViz's main directory
(e.g. C:\Program Files\ATT\GraphViz - this does not seem to really matter actually).

By default, IsaViz is configured for GraphViz 1.7.6. If you are using a later version, select the other option (the SVG output format changed between both versions and IsaViz needs to know which version of GraphViz/dot it deals with).

Note: if you want to add IsaViz to your CLASSPATH, you need the following entries:

- lib\isaviz.jar
- lib\vtm.jar
- lib\jena.jar
- lib\xerces.jar

## Sample files

In order to test your installation, you can try to import sample RDF files located in the export directory. There is also a sample ISV project in the projects directory.