Panorado Applet 2.2

- Technical Reference

 

This documentation requires some basic knowledge of HTML and JavaScript. You may skip the technical part and look at the sample pages first. If you like, you can copy some of the sample code and insert it into your own project.

Panorado Applet Overview    

Recommendations

Place a short advisory notice close to the applet explaining how to use the mouse for interactive control!

For panoramic images, try these initial settings:
Spherical projection <param name="projection" value="spherical"> .
Width of the applet: Not more than about 800 pixels.
Width of the source image: For a 360° image about the applet width * 3, or less if the horizontal angle is smaller.
Initial scale: 100% (Default).

For images with a small field of view, we recommend flat projection (which is the default).
Start with a reduced size, fitting the image into the applet frame: <param name="startscale" value="0">.
Encourage the visitor to zoom into the image.

Please notice that large images may need some time to be downloaded over the Internet, and require much more system memory than the file size might suggest.

 

The <applet> element and its attributes

Within a document's HTML source code, the panorado applet is represented by a <applet> element. This element can virtually be placed anywhere within the document's <body> section.

These are the attributes of the <applet> element:

name This name can be used to dynamically access the applet object (recommended).
code Name of the applet class: "Panorado.class".
archive Name of the archive file containig the applet's code: Panorado.jar.
codebase The applet's folder if it is not in the same folder as the HTML document (optional).
width The applet's width (in HTML-style size units; mandatory).
height The applet's height (in HTML-style size units; mandatory).


This is an example of a very basic configuration:

<html>
<body>

<applet name="Viewer" code="Panorado.class" archive="Panorado.jar"
width="600px" height="400px">
   <param name="img" value="YourPano.jpg">
   <!--... more parameters... -->
</applet>

</body>
</html>

Remarks about the example:

The <applet> element's archive attribute refers to the file where the applet itself is to be loaded from. Here: Panorado.jar.

If this file is not in the same folder as the refering HTML document, you have to specify a relative or absolute path to it using a codebase attribute.

width and height attributes are mandatory. They describe the applet's display area. Instead of pixel units you could use percent units. This allows you to change the applet's size on runtime by resizing the browser window! (Restrictions)

The <param> element within the <applet> element refers to the image file to be loaded.

 

<param> elements

The <applet> element can contain multiple <param> child elements which are intended to describe the viewer's behaviour. <param> elemets have name and value attributes.

The panorado applet interprets these parameters, using a <param name="ParamName" value="ParamValue"> syntax:

img Image source file path, relative to the document's folder. File format: JPEG, GIF, or PNG.
For security reasons, the image file can only be loaded from the calling document's server or from the applet's server.
You can omit this parameter, thus launching the applet without an image.
JavaScript can use the setImage metho to dynamically load an image.
title User-friendly image description. This is displayed while loading the image.
The text can be retrieved from JavaScript by calling the getTitle() method.
projection Projection mode: "fast", "flat", or "spherical"; default: "fast".
  • fast - for fast movementes even on large area applets; low memory requirements
  • flat - with anti-aliasing and soft fading; not quite as fast
  • spherical - with 3-D rendering
JavaScript can retrieve the projection mode by calling the getProjection() method.
horzangle Total width of the source image, in degrees.
0 .. 360. Default: 360 (360: seamless). The height angle is calculated based on this value and the image aspect. JavaScript can retrieve the field of view by calling the getHorzFov() or getVertFov() method.
startpan Initial horizontal angle (in degrees).
0 .. 360. Default: like horzangle.
starttilt Initial vertical angle (in degrees).
-90 .. +90. Default: 0
startpanspeed Initial horizontal speed, in degrees/second.
> 0 means "clockwise". Default: 3.
starttiltspeed Initial vertical speed, in degrees/second.
> 0 means "up". Default: 0
startscale Initial zoom scale (1.0 = 100%; 0 = adjust to fit).
minscale..maxscale. Default: 1.0
compass Show compass scale at the bottom margin.
'yes' | 'no'. Default: 'no'
compassnorth Compass north reference, relative to the (left) margin of the source image.
0 ..360. Default: 0
minscale Smallest zoom scale allowed (1.0 = 100%).
0.125 .. 8.0. Default: 0.125
maxscale Largest zoom scale allowed (1.0 = 100%).
0.125 .. 8.0. Default: 8.0
enabled Mouse & keyboard interaction enabling.
'yes' or 'no'. Default: 'yes'
mousemodes Click & drag moves viewport (pan) or image (grab).
If 2 modes are available Panorado starts with the first one.
'pan grab', 'grab pan', 'pan', or 'grab'. Default: 'pan grab'
mousewheel Zoom direction when rotating the mouse wheel down.
'in' | 'out'; default: 'out'
softpan Use the SoftPan feature for smooth image movements.
'yes' | 'no'. Default: 'yes'
softzoom Use the SoftZoom feature for smooth zooming movements.
'yes' | 'no'. Default: 'yes'
tracks Defines if track scripting is to be used, and if the track is to be repeated. If 'once' or 'repeat' is set, the image parameters described above (including 'img') are ignored, and image parameters are taken from the track<nn> enumeration described below.
'no' | 'once' | 'repeat'. Default: 'no'
track<nn> Definition of a single track step.
<nn> is an ascending index between 01 and 99.
The parameters are in URL parameter syntax; the order is not significant: par1=val1&par2=val2...
 
  • type=... Either 'img', 'line', or 'curve'.
    track01 starts with type=img.
if type=img is set, the remaining parameters describe a new image which is to be loaded:
  • img=... Image source file path, relative to the document's folder. See description of the img parameter.
  • title=... User-friendly image description; optional.
  • projection=... Projection mode: "fast", "flat", or "spherical"; default: "fast".
  • horzangle=... Total width of the source image, in degrees.
    0 .. 360. Default: 360.
  • startpan=... Initial horizontal angle (in degrees). Default: 0°
  • starttilt=... Initial vertical angle (in degrees). Default: 0°
  • compassnorth=... Compass north reference, relative to the (left) margin of the source image. Default: -1 (=none).
if type=line or type=curve is set, the remaining parameters describe a part of the motion path:
  • time=... Time for executing this step (in milliseconds).
  • pan=... The horizontal viewing angle at the end of this step
    (in degrees).
  • tilt=... The vertical viewing angle at the end of this step
    (in degrees).
  • scale=... The scale of the image at the end of the step.
hotspotsvisible Initial visiblity of hotspots.
'yes' | 'no'. Default: 'no'
hotspotinfoimg Path of a custom image for all informative hotspots, relative to the document path.
See 'img' parameter for restrictions.
Default: built-in image. Can be overridden for single hotspots.
hotspotlinkimg Path of a custom image for all hotspots with links associated, relative to the document path.
See 'img' parameter for restrictions.
Default: built-in image. Can be overridden for single hotspots.
hotspot<nn> Definition of a single hotspot.
<nn> is an ascending index between 01 and 99.
The parameters are in URL parameter syntax; the order is not significant: par1=val1&par2=val2...
  • pan=... Horizontal angle (in degrees).
  • tilt=... Vertical angle (in degrees).
  • img=... Path of an individual custom image. Default: build-in or globally defined image.
  • description=... User-friendly description to be displayed when the mouse cursor is above the hotspot.
  • url=... URL to be loaded when clicking the hotspot. This can be JavaScript code; this requires that the applet has the mayscript attribute.
  • target=... Name of the target window. It's possible to specify HTML names like '_self', '_blank', or '_top'. Note that opening a new window can be suppressed by a popup blocker.

backgroundcolor

Background color around the image.
HTML syntax; e. g. '#222233'. Default: '#000000' (black)

splashimg

Splash image file path, relative to the document path.
See 'img' parameter for restrictions.

splashtext

'Loading' text (in the image + in the window's status bar).
'$' will be replaced by percent value.
Default: '$% loaded...'

splashtextposition

Position (left, top) of 'Loading' text (pixels).
Default: 10, 20

splashtextfont

Font name, font size (point) of 'Loading' text,
e. g. 'SansSerif, 15'.
Font names: SansSerif, Serif, Monospaced, etc.
Default: System font

splashtextcolor

'Loading' text color.
Default: '#ffffff' (white)

licenseurl

URL of the website where the applet is licensed.
Only required for use on commercial websites.

licensekey

License registration key.
Only required for use on commercial websites.
onloadimage Name of a JavaScript event handler function which is called as soon as the image has been loaded completely (optional).
This JavaScript function could be used to display image properties retrieved from the viewer.
onclick Name of a JavaScript event handler function which is called when the left mouse button is clicked on the viewer surface. (optional).
A JavaScript handler function for mouse events could, for example, retrieve the current mouse coordinates from the viewer and evaluate them.
ondoubleclick Name of a JavaScript event handler function which is called when the left mouse button is double-clicked on the viewer surface. (optional).
onmousemove Name of a JavaScript event handler function which is called when the mouse pointer is moved above the viewer surface with no mouse button pressed (optional).
onmousedrag Name of a JavaScript event handler function which is called when the mouse pointer is moved above the viewer surface while the left mouse button is pressed (optional).
onimagemove Name of a JavaScript event handler function which is called when the image viewing angle or scale changes (optional).

 

The applet's methods

HTML pages can contain JavaScript code which refers to elements on this page. Thus, JavaScript can address an applet by its name and call the applet's methods.

Example:

<applet name="Viewer" ...>...</applet>
<a href="#" onclick="alert(Viewer.getAppletInfo());">Show Info</a>
<a href="#" onclick="Viewer.setScale(2.0);">Scale: 200%</a>

Remarks about the example:

The applet's name is "Viewer".
When the first link is clicked, an info text will be displayed which has been retrieved from the viewer.
When the second link is clicked, the viewer's scale is set to 200%.

These applet methods are provided for JavaScript calls:

String getAppletInfo()

Returns version, licensing and environment information.

String[][] getParameterInfo()

Returns a 2-dimensional text array with parameter informations. This is only supported by Mozilla browsers and some HTML generators.

void info()

Opens the panorado.com website in a new window.

boolean setImage(String strFileName, String strTitle, String strProjection, double horzFov, double startPan, double startTilt, double startPanSpeed, double startTiltSpeed, double startScale, double compassNorth)

Loads a new source image.
Parameters:
strFileNameimage filename, relative to the document's folder. File format: JPEG, GIF, or PNG.
For security reasons, the image file can only be loaded from the calling document's server or from the applet's server.
strTitle User-friendly image description. The text can be retrieved by calling getTitle().
strProjection Projection mode: "fast", "flat", or "spherical". Can be retrieved by calling getProjection().
horzFov Total width of the source image, in degrees.
startPan Initial horizontal angle (in degrees).
startTilt Initial vertical angle (in degrees).
startPanSpeed Initial horizontal speed, in degrees/second. > 0 means "clockwise".
startTiltSpeed Initial vertical speed, in degrees/second. > 0 means "up".
startScale Initial zoom scale (1.0 = 100%; 0 = adjust to fit).
compassNorth Compass north reference, relative to the (left) margin of the source image (-1 = no compass).

boolean setImage(String strParams)

Loads a new source image.
This is an alternative syntax to the above setImage method, concatenating up to 10 parameters into one parameter string in URL parameter syntax:
A question mark (?), followed by a list of parameters which are separated from each other by ampersand (&) marks.
Each parameter has the form name=value, where the name corresponds to one of the 10 <param> names describing image parameters.
The minimum parameter string for this method is something like Viewer.setImage('?img=../images/YourImage.jpg').

String getTitle()

returns the user-friendly image description.

String getProjection()

returns the image's projection mode: "fast", "flat", or "spherical".

double getImageHorzFov()

Returns the source image's horizontal FOV (in degrees).

double getImageVertFov()

Returns the source image's vertical FOV (in degrees).

double getImageWidth()

Returns the source image's width (in pixels).

double getImageHeight()

Returns the source image's height (in pixels).

double getDispHorzFov()

Returns the visible image's horizontal FOV (in degrees).

double getDispVertFov()

Returns the visible image's vertical FOV (in degrees).

double getDispWidth()

Returns the visible image's width (in pixels).

double getDispHeight()

Returns the visible image's height (in pixels).

void reset()

Resets the image to the initial direction, speed, and scale values.

void reload()

Resets the image. Unlike reset, this method is able to reflect changes of the source image file.

void pan(double pan, double tilt)

Changes the viewing direction by the specified values (degrees).

void panTo(double pan, double tilt)

Sets the viewing direction to the specified values (degrees).

void zoom(double scale)

Changes the current scale by multiplying it with the specified value.

void zoomTo(double scale)

Sets the scale to the specified value (1=100%).

double getScale()

Returns the current scale.

void moveTo(double pan, double tilt, double scale)

Sets the viewing direction degrees) and the scale to the specified values.

double getPan()

Returns the current horizontal viewing angle (0...360 degrees; left edge=0).

double getTilt()

Returns the current vertical viewig angle (-90...+90 degrees; horizon=0).

double getMousePan()

Returns the current horizontal position of the mouse cursor (0...360 degrees; left edge=0).

double geMousetTilt()

Returns the current vertical position of the mouse cursor (-90...+90 degrees; horizon=0).

void setSpeed(double panSpeed, double tiltSpeed)

Sets the horizontal and vertical speed to the specified values.

double getPanSpeed()

Returns the current horizontal speed.

double getTiltSpeed()

Returns the current vertical speed.

void setEnabled(boolean bSet)

Enables or disables mouse and keyboard interaction (true=enabled, false=disabled)

boolean getEnabled()

Returns if mouse and keyboard interaction is currently enabled.

void setGrabMode(boolean bSet)

Sets the current mouse mode (true="grab", false="pan")

boolean getGrabMode()

Returns the current mouse mode.

void setCompass(boolean bShow)

Shows or hides the compass scale (true="show", false="hide").

boolean getCompass()

Returns if the compass scale is visible.

void clearAllTracks()

Deletes all existing track steps.

boolean addTrack(String strParams)

Creates a new track step.
Parameters are concatenated into one parameter string using URL parameter syntax:
A question mark (?), followed by a list of parameters which are separated from each other by ampersand (&) marks. Each parameter has the form name=value.
For details, see the description of the track<nn> applet parameter.

void startTracks()

Starts execution of the track list which has been previously set up from addTrack calls.

void setTracks(String strMode)

Defines if tracks are used, and if they are to be repeated. Options: "no", "once" oder "repeat".

String getTracks()

Returns the way how tracks are to be used: "no", "once" oder "repeat".

void clearAllHotspots()

Deletes all existing hotspots.

boolean addHotspot(String strParams)

Creates a new hotspot.
Parameters are concatenated into one parameter string using URL parameter syntax:
A question mark (?), followed by a list of parameters which are separated from each other by ampersand (&) marks. Each parameter has the form name=value.
For details, see the description of the hotspot<nn> applet parameter.

void gotoHotspotUrl(int i)

Simulates clicking the specified index. i is a 0-based index.

void setHotspotImage(String strFileName)

Sets a custom hotspot image path, relative to the document path.

void setHotspotsVisible(boolean bSet)

Shows or hides hotspots. (true="show", false="hide").

boolean getHotspotsVisible()

Returns if hotspots are visible.

 

Some test results

The applet version presented here has been tested on various versions of Microsoft Internet Explorer, Netscape, Mozilla Firefox, and Opera, using Java v1.4 and v1.5 runtime environments.

We found out that the Netscape, Firefox (< v1.5), and Opera browsers were not able to handle resizing the height of applets at runtime correctly. If you want to use this feature on the other browsers, you should make a programmatic distinction to set the window parameters. This is illustrated for the sample page below.

The applet has some restrictions on Java runtime environments prior to v1.4 (which are getting rare). We recommend to inform visitors about the posiibility of a free Java update.

Information about Java applet security are on the Sun Developer Network page on the Internet.

Some popup blockers can prevent the applet from opening a hotspot link in a new window. You can avoid this only by disabling the popup blocker temporarily or permanently.

 

Sample pages

We like to present three sample HTML pages for illustrating how the applet can be integrated.

Please start with opening the first page. Here the applet is right in the middle of a page, surrounded by text elements. The applet is intended to show only one single image. As you will learn later, this requires a simple <applet> element with some parameters.

Calling the second page from a link on the first page will require some programming. When the link is clicked, it calls a JavaScript function with a parameter indicating which image is to appear in that page's popup window. The second page receives the image parameter, and a JavaScript function (again) passes the image filename to the page's viewer applet.
This programmatic approach is well suited for image galleries, and it still can be extended - i. e. on this website's Panorama Gallery.

The third page demonstrates the use of hotspots.

We suggest that you open the source code of these sample pages. You may copy the whole or parts of it and use it on your own pages. If you are familiar with HTML and/or JavaScript, you can examine the code - with the help of the following explanations.

 

Source code - first sample page:

Please skip the <script> element in the header section and look at the document's <body> first.

There you'll find the <applet> element with some <param> child elements. The applet's name="Viewer" attribute will be used later to address the applet from JavaScript code. The archive="Panorado.jar" attribute refers to the Java archive file in the same folder which contains the applet code. The width und height attributes are mandatory for applets.

There are many more parameters for the applet than those used here. The applet will use default values if parameters are not specified.

There's a <img> element in a table row below the applet. If this is clicked (onclick), the viewer's info() method will be called.

The next element is a <img> again, showing some buttons. The usemap="#Buttons" attribute refers to the <map> element (below the table). This is an image map made out of <area> child elements which are able to receive onclick events. These events are defined to trigger some of the viewer's methods like Viewer.reset() or Viewer.setSpeed(0,0). So this is JavaScript again!

If you click on the links at the bottom of the page, this will activate the second sample page in a popup window. Since we want to determine the window's appearance in some detail, we don't just use a <a href="..."> but a JavaScript function called showPano(...).

This function's code is in the header section of the page. It computes some window parameters which depend on the screen size and the kind of browser used, and then opens a popup window showing the second sample page. Please note that a question mark and the name of the image file is appended to the page's URL. This is the usual way to pass parameters to a HTML document.

 

Source code - second sample page:

This page basically contains a viewer applet and some buttons, much like on the first sample page. But strange enough, the <applet> element doesn't have any child elements! This means that the viewer will be loaded without an image.

The image will be loaded as soon as the whole page is loaded. This is signaled by an onload event to the <body> element which triggers the execution of a JavaScript function. This function will take the parameter part of the URL (remember?) and instruct the applet to load a new image described by this parameter string.

That's all. Almost. We still like to notify you about the width and height attributes of the <table>, <tr> und <applet> elements. This enables the applet to adjust its size when the user resizes the popup window.

 

Source code - third sample page:

The hotspots inside the image are intended to provide textual information. When a hotspot which is assigned a link is clicked, this link will be executed.

The <applet> element contains some additional <param> sub-elements:

hotspotsvisible with the value of yes defines that hotspots are to be visible initially.
Each hotspotNN element defines a hotspot with its coordinates within the image (here: in degrees), the text to be displayed, an optional link URL and an optional name for the window where this link is to be displayed.

The hotspots #01 through #06 contain a descriptive text only, hotspots #07 through #10 contain an additional link to a small image which is to be displayed in the same window, and hotspot #11 is a JavaScript command which will bring up a message box.

Unlike on the other sample pages, the elements for switching hotspots on and off are not implemented as image maps but as simple text links, calling a JavaScript function: javascript:Viewer.setHotspotsVisible(true);

This page also demonstrates the use of an event handler function:
<param name="ondoubleclick" value="onDoubleClick()"> defines a function which, on a double-click event, retrieves the current mouse coordinates from the applet and displays them in a HTML element - in a format suitable for defining a new hotspot.

 

Mouse and keyboard interaction

Clicking on the applet moves the input focus to it. This allows you to control the viewer...

...using the mouse:

Click & drag
left mouse key		 Pans the image.
Click middle mouse button/mouse wheel Shows as much of the image as possible.
Rotate mouse wheel Zooms (in/out).

...using the keyboard:

F5 Restarts the image.
F4 Toggles between mouse modes.
1 Sets the scale to 100%.
2 Sets the scale to 200%.
5 Sets the scale to 50%.
A Shows as much of the image as possible.
+/- Zooms (in/out).
Cursor keys Pans the image.
Shift+Cursor keys Moves the image evenly.
Escape Stops moving the image.
C Toggles visibility of the compass scale.
H Toggles visibility of hotspots.