3D Graphiti - User Guide

SourceForge.net Logo

Menu image

User Guide

This manual is intended to guide you through the process of setting up 3D Graphiti on a website and getting the most out of the application; contact details can be found on this website if you have any unanswered questions. This applet has been designed to be as flexible and easy to use as possible but there are also plenty of options to play around with.

1. Overview

3D Graphiti has a single core component required to run on a website which contains the program code. It is available for download from the website and is named graphiti.jar. This file does not need to be modified (unless you wish to extend its functionality; see section 4 for this) and is included on an HTML page using convention tags. Modification of the graph is achieved through modifying the parameters that are applied to the graph with up to 30 values supported on the model at once; a full list of parameters to alter described in section 3. The system works by using the Java plug-in which is installed on the majority of computers to display the visualisation. Users who do not have this plug-in installed will be presented with a message informing them where they may download it from.

2. Getting Started

To get started, the first thing to do is to download the latest release of the application. Go to the download page, find the file graphiti.jar and save it to your computer in the same location as the web page you’d like to include it on. Make sure that you are saving the file as a jar archive: Internet Explorer may try to rename the file as a zip archive. If you are including the file on an existing page, open the HTML source code and find the position where you would like the applet to be placed; otherwise, create a new HTML document and find the body of the document. Paste the following code in the relevant position to include the applet:

<applet code="graphiti.class" archive="graphiti.jar" name="graphiti" width="300" height="300" alt="3D Graphiti Java Applet displaying a 3D graph">

To view 3D Graphiti, you must have a recent version of Java installed on your machine, please click <a href="http://www.java.com/getjava">here</a> to download it.

<param name="label1" value="3D" />
<param name="value1" value="1" />
<param name="label2" value="HI" />
<param name="value2" value="0.5" />
<param name="label3" value="TI" />
<param name="value3" value="0.7" />
<param name="label4" value="GR" />
<param name="value4" value="0.6" />
<param name="label5" value="AP" />
<param name="value5" value="0.3" />
<param name="bgcolor" value="FFFFFF" />
<param name="showvalues" value="0" />
<param name="showdecimals" value="0" />
<param name="fontface" value="Arial" />
<param name="fontantialias" value="1" />
<param name="fontbold" value="1" />
<param name="fontitalic" value="0" />
<param name="fontsize" value="40" />
<param name="colorlines" value="1" />
<param name="colortext" value="1" />
<param name="showcenter" value="1" />

</applet>

This will include the applet on the page with some test settings. To check that it is operating correctly, save the document and load it in your browser. Check the troubleshooting guide in section 5 if there are any problems. To alter the size of the applet, modify the height and width attributes of the <applet> tag. You may also wish to change the default message that appears for users who do not have the correct version of Java installed to view the applet. This is possible by changing the text message which is enclosed within the <applet> tags. The alt attribute of the opening <applet> tag also contains a brief description to help users with disabilities.
The next step is to modify the appearance to suit your needs. This is achieved by altering the <param> tags that are enclosed within the <applet> tags. These tags take the form of having a name and a value attribute. The name describes the parameter setting that is being modified and the value is the setting that is being applied. For example, to change the font from Arial to Verdana, it would be necessary to modify the line:

<param name="fontface" value="Arial" />

To read:

<param name="fontface" value="Verdana" />

With this knowledge of how to modify parameters, it is possible to alter the data passed to the graph and its appearance. The following section lists all the parameters that can be modified in the system.

3. Parameters

The following table lists all of the parameters that are available to change, the expected types of data and the default values they use.

Parameter Name

Type

Default

Example

Description

valueX *

float

0

22

The values that are being plotted on the graph

labelX *

String

""

"Hello World!"

The text description of the relevant value

colorX *

String

""

"990000"

The colour of the relevant line and associated label if colortext is on

showvalues

int

1

1

Display the values automatically as part of the label

showdecimals

int

0

1

Display decimal points for values being shown

fontface

String

"Arial"

 

The name of the font to display text with

fontsize

int

Relative to applet size

25

The font size to use in points

fontcolor

String

"000000"

"0000CC"

Hex code representing the font colour

fontbold

int

0

1

Make the text bold

fontitalic

int

0

1

Make the text italicized

fontantialias

int

1

1

Make the text anti-aliased

showcenter

int

1

0

Show the central sphere

bgcolor

String

"FFFFFF"

"999999"

Hex code representing the background colour

colorline

int

0

1

Randomly colour lines instead of using the same colour for each one

colortext

int

0

1

Colour the text the same as the relevant line

origin

float

0

15

The value represented by the central sphere

* The X represents a number as these parameters will be numbered representing an array of data. For example, the first value to be used would be named value1, the second value2 etc.

All of the modifications that can be made to the graph are encompassed by this table. The best way to learn how to use it is to play around with the parameters and take note of the changes that occur in the visualisation after modifying the parameters. To assist you in learning how these parameters affect the system, there is a graph generator example on the website which takes the parameters from a form and reflects the applet from the settings applied. It also includes the parameter code that is required to display the graph so that it can be copy and pasted to your own website. To use this, navigate to the examples section of the website and click on the link to the graph generator.
Bear in mind that lines are added to the graph according to the number of consecutive value parameters that are present. This means that value6 would not display if any of the previous 5 value parameters were missing. Also, a label will not be included without an appropriate value of the same number (e.g. label5 requires value5 to exist to be displayed).

4. Java Source

If you are interested in looking at the source code for the project, it is possible to download it yourself. The code is available from the download section of the website under the filename graphiti.java. It will also be necessary to download the Render package used for providing the 3D functionality in the application. This package was written by Ken Perlin and is available for academic use for free from the following link: http://mrl.nyu.edu/~perlin/experiments/render. The files that constitute the render package should be placed in a folder called render which is on the same directory level as the Java file. For example, if the graphiti.java file was stored in C:\Work\Graphiti, the Java files for the Render package should be placed in C:\Work\Graphiti\render. Follow the instructions on the Render website to compile the package. Compiling graphiti.java can be carried out using the standard method; for reference the command that was used to ensure compatibility with Java 1.1 was:

javac graphiti.java -target 1.1 -source 1.3

Using the applet on a website would require that the code is packaged again into a JAR archive. To achieve this, the following command may be used:

jar cvf graphiti.jar graphiti.class render/*.class

The Application Programmers Interface is located in the documentation section of the website.

5. Troubleshooting

Problem: The applet does not display at all.

Possible Solutions:

  • Ensure that the JAR file has the correct file extension; occasionally Internet Explorer attempts to rename the file as a zip archive.
  • Check that the file graphiti.jar is in the same folder as the HTML file that includes the visualisation. If it must be located in another folder, it is necessary to alter the archive attribute of the <applet> tag accordingly.
  • Check that the tags are well formed and valid HTML as specified in section 2. If you have modified the parameters, verify that the applet works when using the default settings specified above.
  • Ensure that you are using a Java compatible browser with the latest version of Java to view the page.
  • Internet Explorer may restrict the applet from displaying without your permission, especially on local computers. Ensure that the information bar is displayed at the top of the web page. If it is, click on it and select 'Allow blocked content...', clicking 'Yes' when prompted for confirmation.
  • For a website that is hosted online, check with your service provider that there are no restrictions on the use of JAR files.

Problem: I am trying to change a parameter but it does not appear to have any effect when I make the modification.

Possible Solutions:

  • Make sure that you have not misspelt any part of the tag, including both the tag name and the attribute names.
  • Check that the value of the parameter is of the correct type specified in section 3.
  • Ensure that there is not a duplicate copy of the same parameter.
  • Make sure that you have saved the HTML file before trying to preview the changes.

6. Examples of Use

There are several interesting applications of the system located on the website in the examples section. It may be useful to find the most similar system to your own needs, copy its parameter settings and modify it to display your own data. Alternative, the graph generator example allows you to enter the settings you would like to use into a form and displays the results they produce. This is a useful tool for being able to preview your graph while customising it.

7. Uninstalling

Simply remove the code from the HTML file and delete graphiti.jar from your server to uninstall the application.

Valid XHTML 1.0 Transitional