Manual for the JsphereLite Spherical+Cylindrical Panorama Viewer Applet

JsphereLite is a free-for-non-commercial-use JAVA applet and standalone application for viewing equirectangular 360x180 degree and cylindrical 360xN degree panoramas. With its mere 9 KBytes file size it is the smallest panorama viewer ever made with bilinear rendering, full parametrization, JavaScript interface, incremental panning and much more included! It's extremely fast too! See here for a complete property list and a comparison with our other Jsphere viewer applets.

Download "JsphereLite" version 1.4.10. By downloading you agree with the license terms at the bottom of this WEB page.


JAVA required to view this content.  
Sample:
Pan:
Tilt:
HFOV:
Rendering:   bilinear
    simple
Pan mode:   incremental
    full
 
Autorot:
Pan limits:
Tilt limits:
HFOV limits:
Overlay:   enabled
    disabled
Callback:   enabled
    disabled
pan=   tilt=   hfov=   vfov=
Enable "callback" for continuous update of these fields.

  • The JavaScript actions linked to the buttons and fields above as well as the callback mechanism for updating the pan/tilt etc fields, do not work in Netscape 6.0, as well as in MSIE on Mac.
  • The difference between full and incremental panning mode might not be noticable on fast machines (approx. above Pentium-class 400 MHz). However, on slower machines it makes a big difference! Check it out on this big (760x550) or huge (1160x1100) panorama window if you have a fast CPU and a lot of browser memory.
  • Click here for direct access to the demo images used in this page.

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

JsphereLite makes quite a few variables accessible to external interogation and manipulation.

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

All JsphereLite variables described above that are not read-only can be set to self chosen values in the HTML applet tag. One noteworthy exception is the software.copyright variable which must be set to
"Copyright (C) 2000-2001 Panopan".

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>
These applet parameters disable zooming and establish a 100 degree pan region. Because HFOV is fixed to 60 degrees, the effective pan range will be limited to 40 degrees. Autorot is enabled with 135 seconds for a full circle. This means that the pan range will be covered in 15 seconds (360:40=9, 135:9=15) before the autorotation reverses direction.

JAR File - HTML Code Example

The transfer size of an applet can be reduced by packing it into a "jar file". It is also possible to put the splash image into the same jar file (and even the panorama image, although this is not optimal since it results in a long loading time). The jar file is created by the following command (consult your JAVA book):
  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>
It is recommended to not only copy the jar file to the web server but also all the files that it contains: old (pre-JAVA-1.1) browsers do not understand the "archive" attribute and thus will fetch the class and image files via an ordinary Web connection.

JavaScript - HTML Code Example

The HTML code of this WEB page provides the best example on how to steer the JsphereLite applet via JavaScript.

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>
There are many other ways to trigger JavaScript code, for example mouse event handlers and image maps. Please consult a good HTML and JavaScript reference.

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

If your panorama HTML page should be displayed from the harddisk or CDROM drive instead of a network connection, you have to take care of local file access restrictions that most browsers impose on applets. First, you should place your work in a subdirectory (more specifically: not a root directory in case of Windows). Second, for Netscape it depends on whether it can handle JAR files or not.

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
The corresponding HTML applet tag in .../someDir/index.html:
  <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:

 

4. Standalone Panorama Viewer

JsphereLite is both an applet and a JAVA standalone application at the same time. It can therefore been started without any browser or applet viewer; A JAVA runtime environment is required instead. The following example shows a minimal command line for starting JsphereLite in an UNIX environment:
  your_prompt> jre -cp . JsphereLite \
                   init.geometry=320x200 \
                   image.url=thePano.jpg
Variable values are separated from the variable name by the equal sign (=).

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

Protect your images and make them unreadable for non-Jsphere applications! The JsphereLite applet contains an on-the-fly descrambler for the "Jsphere scrambler #1" format. The scrambler (a JAVA standalone application for tranforming GIF and JPEG images to the scrambled format) is available in conjunction with the Web Commercial License.

 

6. Branded Version

Turn JsphereLite into your spherical+cylindrical viewer for your clients! A branded version of JsphereLite is available for a modest fee: it embeds (a) a URL to a customer specific help page that is activated by the 'h' or '?' key stroke, and (b) a self chosen logo and background color as a splash image. Note that your logo image and the URL will be an integral and non-removable part of the class file.

 

7. License

The JsphereLite JAVA applet (the software) described above and made available through this page is licensed free of charge for non-commercial use. It may not be sold, altered or reverse engineered and the copyright notice may not be removed. The software is provided "as is", without warranty of any kind, either expressed or implied.

Prices for the Web Commercial License

License is per WEB site, identified by the site's URL. The number of panoramas refers to the overall number of panoramas at that site which are accessible and viewable with one or more JsphereLite applet instance. Distribution of the JsphereLite applet on CDs etc requires another license agreement, please contact info@panopan.com.

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!


Copyright (c) 2000-2001 Panopan Immersive Media
This page  http://www.panopan.com/sw/jsphere/lite.html  last modified 2001-05-05