Extensions to PTViewer: PTCompass, PTObject, PTMovies, PTMedia, PTZoom
and more
Helmut Dersch
updated October 18, 2001

Using Extensions

Extensions are applets that interact with PTViewer and  add functionality. PTViewer provides several mechanisms to interface with other applets. These applets may either be embedded in a html page, or directly into PTViewer. Embedding into the html-page requires the definition of two applet tags, one for PTViewer and one for the extension. This is an example for PTMovies:

<APPLET archive=ptviewer.jar  code=ptviewer.class width=320 height=200 name=ptviewer>
<PARAM name=file                value="Image.jpg">
<APPLET  archive=ptviewer.jar   code=ptmovies.class width=0 height=0>

<PARAM name=frame               value="frames/frame#.jpg">
<PARAM name=px                  value="533">
<PARAM name=py                  value="165">
<PARAM name=fps                 value="25">
<PARAM name=loop                value="2">
The code for both applets is included in the same jar file of the distribution (big applet). It is recommended to nevertheless include the class files in the same directory of the server since some browsers can not read jar files. The browser then starts both applets, and the helper applet tries to contact ptviewer. It is important that the ptviewer applet has a 'name' tag, in this case 'name=ptviewer', otherwise the ptmovies applet can not find it. If you choose a different name, then you have to notify the ptmovies applet about that. Also, set width and height of ptmovies to 0, otherwise you get an additional empty window. For the available commands in ptmovies, see the separate chapter below.

This method works quite well in all browsers that support interaction among applets. This is the case for Netscape on all platforms, and Internet Explorer on Windows. Unfortunately, many other java installations don't support this interaction, eg Internet Explorer on Macintosh, iCab, Appletviewer and the standalone program versions of PTViewer. To be able to use extensions, a second method of loading applets has been implemented. It uses the 'applet0/1/2' parameter tag in the ptviewer properties list. The same example as above then becomes:

<APPLET archive=ptviewer.jar  code=ptviewer.class width=320 height=200 name=ptviewer>
<PARAM name=file        value="Image.jpg">
<PARAM name=inits       value="ptviewer:startApplet(0)">
<PARAM name=applet0     value="{code=ptmovies.class}

The same parameter names are used as above, but this time listed as {name=value} pairs in the applet0 tag. It is important that the code=ptmovies.class pair appears. The extension must be 'class' (lowercase!). Note that an 'inits' tag has been added, which supplies an initialization command. This command starts the applet after the main panorama is loaded. This method requires just one html-applet tag, and can be displayed in any java installation.

How to Bundle Extensions

Extensions may be combined with the basic panorama viewer into single 'jar' files. The distribution includes the necessary 'class' files, and two example jar-files. One contains just the basic ptviewer.class, and one includes all classes. The free 'jar' utility is required to build these files. It can be downloaded from www.javasoft.com as part of the Java Development Kit. The basic viewer can then be created by executing the following command inside the 'files' folder of the distribution:

Jar cf ptviewer.jar ptviewer.class
The full featured viewer combines all class files. It is created using this command
Jar cfm ptviewer.jar MainClass ptviewer.class ptmovies.class ptobject.class ptstub.class ptcontext.class
     ptvjapp.class  ptvjapp$1.class ptvjapp$2.class  ptmedia.class ptcompass.class ptflat.class
If only some of the extensions are required, and if bandwidth is very limited, other combinations can be created. The file  MainClass is only needed for standalone viewers, not for applets. If it is not included, remove the 'm' option in the Jar command. Then include ptviewer.class, ptstub.class, ptcontext.class, the 3 ptvjapp.class files and the extensions you want to include. Example: To build a customized applet that includes the ptcompass extension, execute the command
Jar cf ptviewer.jar ptviewer.class ptstub.class ptcontext.class
     ptvjapp.class  ptvjapp$1.class ptvjapp$2.class  ptcompass.class



PTCompass inserts a user defined image which rotates synchronized with the pan-angle. It may be used as navigation and orientation aid. The image may be placed anywhere in the appletwindow, and it can rotate in both directions: like a real compass, or opposite.

List of parameters:


PTMovies inserts a set of images into the panoramic image or the viewer window, depending on the warp-parameter. If warp is true (default) the images are inserted into the panorama and they have to be warped to the panoramic projection. They are displayed perspectively corrected in PTViewer and appear like natural elements of the VR-scene. For an example that displays an animation on the screen of a movie theater, see here.If warp is false, the images are inserted unchanged into the foreground viewer window.

List of parameters:

See the sources of ptmovies.java for more details.


PTObjects displays 3D-objects using a set of images similar to the Apple QTVR-viewer. The images are organized in horizontal stripes, and may cover several rows. Below is an example row using 20 images. Also shown is an optional mask image, that can be supplied to make portions of the original image transparent (non-white regions).

The middle row is loaded and displayed first. See this example of a 10 row object movie, which covers a full spherical view (360°*180°).

List of parameters:

Pan and tilt angles and limits are taken from PTViewer's parameter list.


Many more media formats are available if JMF is installed on the host computer. These include avi-video, linear quicktime video, flash 2,  mpeg1/2/3, many soundformats etc. See www.javasoft.com for supported media types.

List of parameters

Visual JMFMedia are displayed in their natural size. JMF-media are silently ignored if JMF is not installed.


High resolution zoomable images can be inserted using this extension. These images are seamlessly integrated in the viewer window, and automatically show up when the user pans and zooms into the respective feature. PTZoom uses rectilinear images from any normal or telephoto lens. Suitable pan/tilt/rotation angles can be determined using the optimizer of the Panorama Tools plug-in or PTPicker (yaw/pitch/roll).

List of parameters

An example which uses two stacked high resolution images uses these applet tags:
<applet name="ptviewer" archive=ptviewer.jar  code=ptviewer.class width=320 height=200>
<param name=file                value="Monument.jpg">
<param name=fovmin              value=1.0>

<param name=applet0             value="{code= ptzoom.class} 
<param name=applet1             value="{code= ptzoom.class} 

<param name=inits            value="ptviewer:startApplet(1);startApplet(0)'">
It is possible to display a complete panorama solely using PTZoom images. The following example displays 6 cubic face images and converts PTViewer to a cubic viewer:
<applet name="ptviewer" archive=ptviewer.jar  code=ptviewer.class width=320 height=200>
<param name=pwidth     value=1000>
<param name=applet0    value="{code= ptzoom.class}{file=GC_f.jpg}{pan=0}{tilt=0}{rot=0}{fov=90.4}">
<param name=applet1    value="{code= ptzoom.class}{file=GC_l.jpg}{pan=-90}{tilt=0}{rot=0}{fov=90.4}">
<param name=applet2    value="{code= ptzoom.class}{file=GC_r.jpg}{pan=90}{tilt=0}{rot=0}{fov=90.4}">
<param name=applet3    value="{code= ptzoom.class}{file=GC_b.jpg}{pan=180}{tilt=0}{rot=0}{fov=90.4}">

<param name=applet4    value="{code= ptzoom.class}{file=GC_u.jpg}{pan=0}{tilt=90}{rot=0}{fov=90.4}">
<param name=applet5    value="{code= ptzoom.class}{file=GC_d.jpg}{pan=0}{tilt=-90}{rot=0}{fov=90.4}">
<param name=inits      value="ptviewer:startApplet(0);startApplet(1);startApplet(2);startApplet(3);startApplet(4);startApplet(5)'">

Note that the fov-parameter is chosen slightly larger than 90° to ensure some overlap at the cubic edges.

Using other Applets

Any non-graphical applet, that can be controlled via the standard init()/ start()/ stop() methods may be used as extension. The following example demonstrates the use of the GSMStreamer applet to playback and stream GSM-decoded sound in PTViewer.

Download and decompress the GSMStreamer files, which consist of the following JAVA classes:
GSMStreamer.class, GSMDecoder.class, GSMStream.class. The following code can be used to load it inside PTViewer:

<PARAM name=applet0   value="{code=GSMStreamer.class}{url=mysound.gsm}">
The sound file 'mysound.gsm' is then played using the startApplet(0) call either via Javascript, or via ptviewer: command. It can be stopped using the stopApplet(0) method.

The GSM class files must be placed together with the PTViewer class files. They may all be packed into a single 'Jar'-file.

Writing Extensions

An applet to be used for interaction with PTViewer should contain the following elements:

There need to be two constructors, one without parameters for use within html-pages, and one with two parameters for use inside PTViewer. The parameters supply the reference to ptviewer, which should be saved locally, and the list of properties, which is tranfered to the class 'ptstub'.

        ptviewer pv;
        String PTViewer = "ptviewer";
        public ptmovies(){}

        public ptmovies( ptviewer p, String properties ){
                pv = p;
                setStub(new ptstub(pv, properties ));
If the helper applet is started from the html-page, it needs to find ptviewer. The following code does that and should be executed before calling ptviewer functions:
        while( pv == null ){            
                pv = (ptviewer) getAppletContext().getApplet(PTViewer);
            }catch(Exception e){
                 try{ Thread.sleep( 2000 );}                             
                 catch (InterruptedException ie) {return;}
The helper application can now execute any ptviewer command, see the API documentation. Especially useful is the callback functionality which is used by PTFlat and PTObject. This is enabled by calling the function startCommunicating() with the applet as parameter:
After this call, the paint() method of the helper applet is called by ptviewer's paint() method. Finally, cut the connection when the applet gets stopped or destroyed using the call
Alternatively, the call
cuts connections to all applets.
See the sources for the example and the ptviewer API for details.

Copyright © 2000 Helmut Dersch der@fh-furtwangen.de