Extensions to PTViewer: PTCompass, PTObject, PTMovies, PTMedia, PTZoom
and more
Helmut Dersch
der@fh-furtwangen.de
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>
<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">
</APPLET>

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}

                               {frame=frames/frame#.jpg}
                               {px=533}
                               {py=165}
                               {fps=25}
                               {loop=2}">
</APPLET>

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

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:

compass - Name of image to be used as rotating pan-indicator; see file Controls.html for an example.
compass_map - Identical to tag 'compass' above, but image turns in opposite direction. Use this tag if the compass image is put onto a floorplan or map.
compass_pan - Pan angle corresponding to compass image (default 0)
compass_x - x-coordinate of upper left corner of compass image (default 0)
compass_y - y-coordinate of upper left corner of compass image (default 0)
tilt - set this option to 'true' to indicate tilt angles rather than pan angles.

PTMovies

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:

frame - the filename of the frame images. These should be numbered starting at 0. The number has to appear somewhere in the file name. The position of the number should be marked using the sign '#'. See the example above ('frames/frame#.jpg' loads the files frames/frame0.jpg, frames/frame1.jpg etc). There should be no leading zeros in the number.
PTViewer - the name of the ptviewer applet, defaults to "ptviewer".
warp - true (default) or false; determines how images are inserted; see description above.
px - the x-pixel coordinate of the insertion point in the panoramic image (upper left point, default 0). If warp is false, px is the viewer pixel coordinate.
py - the y-pixel coordinate of the insertion point in the panoramic image (upper left point, default 0).If warp is false, py is the viewer pixel coordinate.
fps - maximum number of frames per second, may be fractional, defaults to 20.
loop - 0 - don't loop, 1 - restart at beginning, 2 - reverse (default 1).

See the sources of ptmovies.java for more details.

PTObject

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:

PTViewer - the name of the ptviewer applet (defaults to "ptviewer").
file - the name of the image files. These should be numbered starting with 0. The number has to appear somewhere in the file name. The position of the number should be marked using the sign '#'. See the example above ('frames/frame#.jpg' loads the files frames/frame0.jpg, frames/frame1.jpg etc). There should be no leading zeros in the number.
mask - the name of the mask images (optional). Same convention for numbering as tag 'file' above.
nhor - number of images in horizontal direction.
nver - number of images in vertical direction
vx - x -pixelcoordinate of inserted image in viewer window (defaults to 0).
vy - y- pixelcoordinate of inserted image in viewer window (defaults to 0).
showSHS - number of static hotspot in PTViewer. This static hotspots image (i-tag) is displayed after the file-images are downloaded. This feature can be used as download indicator.

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

PTMedia

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

PTViewer - the name of the ptviewer applet (defaults to "ptviewer").
file - the name of the media file.
vx - The x coordinate of the uppler left point of the display window (default 0, only for visual media)
vy - The y coordinate of the uppler left point of the display window (default 0, only for visual media)

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

PTZoom

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

PTViewer - the name of the ptviewer applet (defaults to "ptviewer").
file - the name of the image file. JPEG and GIF images are supported.
mask - An optional mask for the image above. This mask should be a b/w image of the same size as the file-image, white marking opaque regions, and black marking transparent parts.
fov - horizontal field of view in degrees (double)
pan - pan-angle of image center relative to background panorama (double).
tilt - tilt-angle of image center relative to background panorama (double).
rot - rotation angle of image relative to background panorama (double).
showSHS - number of static hotspot in PTViewer. This static hotspots image (i-tag) is displayed after the file-images are downloaded. This feature can be used as download indicator.
progress - set to true if the standard PTViewer download feedback (progress bar or progress message) is to be displayed during download of the file.
antialias - set this option to 'true' to turn on antialiasing (default: off). See this example for details.
oversampling - this floating point parameter determines the maximum ratio of source resolution (pixel/degree) to screen resolution (pixel/degree). It is treated differently depending on whether antialias is turned on or off. If it is turned off, the oversampling parameter determines whether the image is displayed at all (oversampling smaller than maximum oversampling), or turned off. The default value is 8 in this case. If antialiasing is turned on, the image is always displayed, and the multiple source images are switched whenever the oversampling parameter is exceeded. In this case, the default is 1.5.

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} 
                                       {file=Insert2.jpg}
                                       {pan=-28.358}
                                       {tilt=1.144}
                                       {rot=-0.3}
                                       {fov=6.786}">
<param name=applet1             value="{code= ptzoom.class} 

                                       {file=Insert.jpg}
                                       {pan=-13.96}
                                       {tilt=-1.4}
                                       {rot=1.6}
                                       {fov=57}">
<param name=inits            value="ptviewer:startApplet(1);startApplet(0)'">
</applet>

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'.
Example:

        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 ){            
            try{
                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:

    pv.startCommunicating(this);

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

    pv.stopCommunicating(this);

Alternatively, the call

     pv.startCommunicating(null);

cuts connections to all applets.
See the sources for the example and the ptviewer API for details.