Creating Packed VR-Tours using PTViewer and Jar Helmut Dersch der@fh-furtwangen.de University of Furtwangen June 29, 2000 This document describes how to bundle all files belonging to a VR-tour (images, sounds, text files) into one package which can be displayed either within any java-enabled html browser (Internet Explorer, Netscape, iCab, etc) or Suns's Appletviewer. Alternatively, self-displaying tours requiring no external program but just the Java Runtime Environment (JRE) can be created. The same packed archive can be used for broswers and JRE.

Requirements:
The following packages are needed:

PTVJ from this site containing all java classes and support files.
The JDK kit containing the Jar application. This kit is free and can be downloaded from Sun for the Windows and many other platforms. A Macintosh version is available from Apple.
The PTVJ examples from this site are optional if you do not have your own images to experiment with.

1. Packaging tours for Java Browsers:
The procedure is similar for all platforms. Set up all files for the tour inside one directory. Do not use subdirectories. Place the ptviewer.class file (not the ptviewer.jar file) inside this directory. Load the html-file into your browser and test your setup.

The final package contains all files except the html file which has to be kept separate. Once your tour works you can invoke the Jar application to combine the files. On a command line system the Jar application should be called with the following options:

jar c0f  ptviewer.jar ptviewer.class file1 file2 file3 file4 file5

file1, file2, etc should be your images and resources for the VR-tour. Instead of ptviewer.jar, you may choose any other output name with extension .jar. Just make sure you adjust the 'codebase' tag in the html file to the proper jar file.

If you invoke jar inside a development environment or use the MRJ standalone program, be sure to disable 'use compression'. Due to a bug in Java 1.1, compressed jar files can not be read on these systems. A specific manifest file is not required for this package and you can leave the default settings for this item.

To display the tour place the html file and the ptviewer.jar file into the same directory, and open the html-file in your browser. On most systems you can just double-click the html-file. For an example download this file which is a packed version of the PTVJ-example 'Controls.html'.

2. Packaging tours as self-displaying Archives:
The procedure is slightly different for Macintoshs and the rest of the world. In any case you have to first create a jar-file containing all files of the tour. The jar file is independent of the system you used for creation, so a Macintosh created jar-file executes without problems on Windows. This time, you should also include the html-file which has to be renamed to 'default.html' (No quotes). In addition to the ptviewer.class, you have to provide all classes from the application (6 files). Finally, the manifest file 'MainClass' has to be included which makes the archive self-executing on Java 1.2 installations. On a command line system the Jar application should be called with the following options:

Jar c0fm ptvjapp.jar MainClass ptcontext.class ptviewer.class ptstub.class 
         ptvjapp.class ptvjapp$1.class ptvjapp$2.class default.html file1 file2 file3 file4

This should be one command line containing all support files. As above, you have to disable compression (option 0). This time a manifest file must be included as requested by option 'm'. If you use the MRJ-version, set the appropriate options in the dialog.

On Windows or other non-Macintosh systems you are finished now, and can double-click the jar-file to view the tour provided you have the Java 1.2 Runtime installed (Download from Sun). Please note that earlier versions of java do not work this way but may be able to display the tour if it is executed on the Java commandline. For a finished example, download this file.

On the Macintosh, you have to add a wrapper application for the jar-file. Apple provides two solutions which are both included in the MRJ package: JBindery and MRJAppBuilder. Both can be used, and the following method uses the newer MRJAppBuilder: Drop the Jar file onto MRJAppBuilder's icon, select the Properties file 'ptproperties' included in the PTVJ package, and set an arbitrary output file name. Then execute MRJAppBuilder. Alternatively, you can use the MPW tool version of the program with the options

MRJAppBuilder -mergeJarIntoVFS ptvjapp.jar -config ptproperties -o ptvjapp

For an example download this file.

The self-displaying jar-archive may be used for browsers as well since it contains all files necessary to run the applet. Again, you have to properly set the codebase tag in the separate html file. The 'default.html' file in the archive is ignored by the applet. Disadvantage is the somewhat larger filesize since more java classes have to be included.

Problems:
In principle, any platform is supported, but practically a couple of limitations exist:

Not all files can be read from jar-archives. JMF-Media don't work. Sound files can not be read by Netscape 4.04 (both PC and Mac).
Some older systems can't read jar-archives at all, eg Netscape 4.03 can read the java classes, but nothing else, not even images.
Some limitations exist for Java applications vs Java applets: Applications on pre 1.2 systems can't process sound.