Manual for the JsphereLite Spherical+Cylindrical Panorama Viewer Applet

1. Interactive Commands

Mouse:

The mouse is used to change the viewing direction (panning). Click inside the applet and drag the mouse in order to change the direction and the speed of change. The center is the neutral zone: simply drag the mouse cursor towards one of the edges - the closer you get to the edge, the bigger will the change in viewing direction be.

By pressing either the SHIFT or CTRL key before clicking inside the applet you can zoom in or zoom out, respectively.

Keyboard:

Panning can also be controlled by the cursor keys LEFT, RIGHT, UP and DOWN. Several other keys are associated with actions too as is shown in the following table:

Key	Action
LEFT RIGHT UP DOWN	Panning
+ > a	Zoom in
- < z	Zoom out
0 HOME	Zero - reset viewing direction to initial value
s SPACE	Stop/Start - toggle auto-rotate action (= continuously panning through 360 degrees)
i	Info - show software version
h ?	Help - open the Jsphere software Web page
q	Quit - exit the JsphereLite viewer (only available when started as a standalone JAVA application)

2. Variables to Query and Set

Variables are queried via JavaScript using the getValue("variable-name") function.

For changing values there are two functions that JsphereLite provides:
 setValue("variable-name", "new-value")
modifies the variable with immediate effect.
 defValue("variable-name", "new-value")
on the other hand just stores a new value. The new setting will take effect when a reset() call is issued. This allows for several variables to be changed "at the same time".

The list of functions:

Function	Parameters	Description
getValue(var)	var: variable name	Returns the variable's current value, or the string "unknown variable" if the variable does not exist.
setValue(var, val)	var: variable name val: value	Assigns a new value to the given variable with immediate effect. The function returns an empty string in case of success, or the message "range error" if the value is outside the allowed range, or "unknown variable" if no variable exists with the given name.
defValue(var, val)	var: variable name val: value	Defines the new default value for the given variable. This value is silently stored but not applied to the viewer's current state. The new value will become effective when the reset() function is called. This function returns an empty string in case of success, or the message "range error" if the value is outside the allowed range, or "unknown variable" if no variable exists with the given name.
reset()		Makes all variables' default values to become effective. If the defValue() function was never called since the applet started, this function simply resets the applet to its initial state.

Variables are identified by strings, more precisely names separated by dots. The table below lists all supported variable identifiers, their attribute (read-only, read-write), the range and default value as well as a description of the variable. Note that variable names are all lowercase.

Identifier	Attr	Range / Default Value	Description
image.form	read-only	sphere, cylinder	This variable is set depending on the current image's height:width ratio. A 1:2 ratio will be treated as an equirectangular (spherical) image, while any other ratio will be treated as a cylindrical projection. Note that in both cases we assume a horizontally complete 360 degree panorama.
image.url		URL Default: null	The current image's URL. Setting a new value to this variable forces a load of a new panorama. The URL must point to a (possibly scrambled) GIF or JPG file.
init.autorot		-N ... 0 ... +N default: -60.0	Number of seconds needed for a full circumscription of the panorama. A negative number specifies reverse direction. Setting this variable to a non-zero value enables auto-rotation at the specified speed. Default is ON, with such an "auto-tour" reaching its starting point after 60 seconds again and continuing indefinitely. Note that this is a machine independent parameter i.e., the number of frames displayed during a circumscription depends on the speed of the machine: But after the specified N seconds all machines will display the same view again.
init.callback.view		fct_name(pan, tilt, hfov) Default: null	Name of a JavaScript callback function. If specified, the Jsphere applet will call this JavaScript function each time a new view has been rendered. The current pan, tilt and hfov values (in degrees) are passed as parameters. The applet tag must have a mayscript=true attribute in order to enable callbacks. Note that callbacks do not work for Netscape 6.0 as well as all versions of MacIntosh browsers.
init.render.quality		simple, bilinear Default: bilinear	The rendering quality which can be either bilinear (default) or simple. The simple quality, which selects the "next neighbor" pixels, is much faster than bilinear rendering. However, pixel borders are clearly visible.
init.render.pan.mode		full, incremental Default: incremental	The rendering mode when interactively panning through a panorama. Incremental pan mode (default setting) means that the view is rendered in consequtively smaller blocks until a time limit is reached. This enables fast panning even on slow machines, at the price of reduced resolution. In full rendering mode each pixel is rendered before a next view is computed.
overlay.url		URL Default: null	URL of a (possibly scrambled) transparent GIF image. This image enables arbitrary contours being overlayed to the panorama view. The overlay image is center aligned. Set this variable to the empty string in order to disable the overlay.
software.copyright	read-only	"Copyright (C) 2000-2001 Panopan"	Constant value. Although read-only, the correct variable value must be specified in an applet context. See the note further below in the section on applet parameters.
software.home	read-only	http://www.panopan.com/sw/jsphere/	Constant value.
software.name	read-only	JsphereLite	Constant value.
software.version	read-only	1.4.10	Constant value.
splash.url		URL Default: null	URL of a (possibly scrambled) GIF or JPEG image which will be displayed during the loading of the panorama image. This value can only be set via the applet's parameter list and is used during applet initialization time only, center alignment.
splash.bgcolor		000000 ... ffffff Default: ffffff (=white)	RGB value in hexadecimal notation of the applet's background color during the loading of the panorama image. The background color is only visible if a splash image is specified that is smaller than the applet's size.
view.caption		String Default: JsphereLite copyright string	A string that is displayed in the status bar of the browser each time the mouse enters the applet window.
view.hfov		1.0 ... 179.9 Default: 95.0	Horizontal-field-of-view value, in degrees. New values are subject to the limits defined in the view.limit.hfov.min/max variables and other constraints (e.g., pan limits or VFOV limits imposed by a cylindrical panorama) and will be automatically adjusted.
view.pan		-180.0 ... +180.0 Default: 0.0	Pan (yaw) position of the current view, in degrees. Pan values refer to the horizontal axis. Note that JsphereLite uses the mathematical coordinate system where pan values increase counter-clock wise. The same coordinate system is also used in Apple's Quicktime environment. New values are subject to the limits defined in the view.limit.pan.min/max variables and will be automatically adjusted.
view.tilt		-90.0 ... +90.0 Default: 0.0	Tilt (pitch) position of the current view, in degrees. Tilt values refer to the vertical axis, zenith is +90 degrees, nadir is -90 degrees. New values are subject to the limits defined in the view.limit.pan.min/max variables and will be automatically adjusted.
view.vfov	read-only	1.0 ... 179.9 Default: depends on HFOV and applet proportions	Vertical-field-of-view value, in degrees. This variable is recomputed each time a new HFOV value is set.
view.limit.hfov.min view.limit.hfov.max		1.0 ... 179.9 Default: 5.0 / 145.0	Zoom limits, expressed for the horizontal-field-of-view, in degrees.
view.limit.pan.min view.limit.pan.max		-180.0 ... +180.0 Default: 0.0 / 0.0	Border values of the allowed panning area, in degrees. Setting both limits to the same value effectively disables pan limits. The pan region can wrap around the +180/-180 degree position. Thus, it is perfectly valid to specify the following min/max pan limits: +160.0 / -160 which defines a 40 degree pan region. Pan regions affect the way autorotation behaves: once one of the borders has been reached, the JsphereLite applet automatically reverses the sign of the init.autorot variable. The autorot tour then continues in the other direction, continuously sweeping the region from left to right and back.
view.limit.tilt.min view.limit.tilt.max		-90.0 ... +90.0 Default: 0.0 / 0.0	Border values of the allowed tilting area, in degrees. Setting both limits to the same value effectively disables tilt limits. Note that cylindrical panoramas implicitely define tilt limits that can not be overriden. Special rules apply for equitectangular panoramas. With tilt limits disabled (e.g., both variables set to 0.0), the view center is restricted to the -90...90 tilt range. With differing min/max values for tilt, these limits apply the view border, instead.

3. Applet Parameters

Start values for the JsphereLite applet are put in HTML parameter tags as shown below.

  <applet name=jsphere code=JsphereLite.class width=320 height=200>
    <param name=splash.url           value=myWaitImg.jpg>
    <param name=splash.bgcolor       value=4040ff>
    <param name=image.url            value=thePano.jpg>
    <param name=view.caption         value="Look at this great panorama!">
    <param name=view.hfov            value=60.0>
    <param name=view.limit.hfov.min  value=60.0>
    <param name=view.limit.hfov.max  value=60.0>
    <param name=view.pan             value=-37.5>
    <param name=view.limit.pan.min   value=-90.0>
    <param name=view.limit.pan.max   value=10.0>
    <param name=init.autorot         value=-135.0>
    <param name=software.copyright   value="Copyright (C) 2000-2001 Panopan">
    JAVA required to view this content.
  </applet>

JAR File - HTML Code Example

  your_prompt> jar cvfM my-jsphere-lite.jar JsphereLite.class myWaitImg.jpg

The HTML code below shows how to reference such a jar file:

  <applet name=jsphere archive=my-jsphere-lite.jar
          code=JsphereLite.class width=320 height=200>
    <param name=image.url          value=thePano.jpg>
    <param name=splash.url         value=myWaitImg.jpg>
    <param name=software.copyright value="Copyright (C) 2000-2001 Panopan">
    JAVA required to view this content.
  </applet>

JavaScript - HTML Code Example

A) Use of radio buttons to enable/disable bilinear rendering:

  <head>
  <script language=JavaScript>
    function setval(varname,val) {
      document.jsphere.setValue(varname,val);
    }
  </script>
  </head><body>
  ...
  <form name=f>
  <input name=renderquality type=radio
      onclick="setval('init.render.quality','bilinear')" checked> bilinear
  <input name=renderquality type=radio
      onclick="setval('init.render.quality','simple')"> simple
  ...
  </form>

B) Use of a selection menu to offer preset HFOV values:

  <head>
  <script language=JavaScript>
    function setSelVal(varname,obj) {
      document.jsphere.setValue(varname,obj.options[obj.selectedIndex].value);
    }
  </script>
  </head><body>
  ...
  <form name=f>
     <select name=hfovsel onchange="setSelVal('view.hfov', document.f.hfovsel)>
       <option value=50> 50 </option>
       <option value=80> 80 </option>
       <option value=105 selected> 105 </option>
     </select>
  ...
  </form>

C) Enable the callback in order to get updates on current pan, tilt and Hfov values (and get the Vfov value by calling the applet!):

  <head>
  <script language=JavaScript>
    function onNewView(p,t,h) {
      document.f.pan.value = p;
      document.f.tilt.value = t;
      document.f.hfov.value = h;
      document.f.vfov.value = document.jsphere.getValue('view.vfov');
    }
  </script>
  </head><body>
  ...
  <applet name=jsphere code=JsphereLite.class width=320 height=200 mayscript=true>
    <param name=init.callback.view   value=onNewView>
    ...
  </applet>
  <form name=f>
    pan=<input type=text name=pan size=5>
    tilt=<input type=text name=tilt size=5>
    hfov=<input type=text name=hfov size=5>
    vfov=<input type=text name=vfov size=5>
  </formf>

Harddisk and CD Considerations

Best is to place the files in the following way:

  .../someDir/index.html
  .../someDir/JsphereLite.class
  .../someDir/img/myWaitImg.jpg
  .../someDir/img/thePano.jpg
  .../someDir/jar/my-jsphere-lite.jar

  <applet name=jsphere codebase="." archive=jar/my-jsphere-lite.jar 
          code=JsphereLite.class width=320 height=200>
    <param name=image.url           value=img/thePano.jpg>
    <param name=software.copyright  value="Copyright (C) 2000-2001 Panopan">
    JAVA required to view this content.
  </applet>

If a splash image should be included in the jar file then you have to add it with the right .../img path prefix. You can do it in the following way, for example:

  your_prompt> cd ".../someDir"
  your_prompt> jar cvfM jar/my-jsphere-lite.jar JsphereLite.class img/myWaitImg.jpg

Finally, some parameterization may be required depending on the browser and version:

• MSIE 3.0, 3.02: The images must be in the "CLASSPATH" which IE does not infer from the codebase attribute. Add the following definition to your AUTOEXEC.BAT file and reboot:

  set CLASSPATH=c:\...\someDir
  

• NS 4.x under Windosw: By following the file placement hints above you should be able to view your panoramas out of your local file system without (re-)configurations. However, you should remove the class files from the ..\someDir directory and let Netscape fetch the class code solely from the JAR file.
• NS, all environments: If you want to have complete freedom while placing the code files you can add at your own risk the following line to the preferences file (the Netscape browser should NOT be running):

    user_pref("signed.applets.low_security_for_local_classes", true);
    

  The preferences file can be found, depending on your operating system, at the following places:
  • UNIX: ~/.netscape/preferences.js
  • Win9x: "c:\program files\netscape\users\UserName\prefs.js"
  • WinNT: \Netscape\Users\UserName\prefs.js
  • Mac: "System Folder:Preferences:Netscape f:Netscape Preferences"

4. Standalone Panorama Viewer

  your_prompt> jre -cp . JsphereLite \
                   init.geometry=320x200 \
                   image.url=thePano.jpg

The pseudo variable  init.geometry  is used to set the viewer's window size. No "software.copyright" parameter is required (although it nevertheless applies!).

The execution of the standalone viewer is terminated by typing the lower case 'q' character.

5. Scrambler

6. Branded Version

7. License

Prices for the Web Commercial License

Software		Number of Panoramas		One-time License Fee
JsphereLite		< 50		$ 70
		< 150		$ 110
		unlimited		$ 280
Scrambler				$ 15	(only in conjunction with a JsphereLite Web Commercial License)
Branding upgrade				$ 15	(only in conjunction with a JsphereLite Web Commercial License)

Click here for secure online order!