The immersive experience!

Home
News
Backgrounders

Panorado 4.0
Panorado JS 1.0
Panorado Flyer 1.2

Gallery
Links
Contact/Impressum

Panorado JS 1.0

- Technical Reference

Framework
Recommendations
PanoradoJS class
PanoradoJS properties
PanoradoJS methods
PanoradoJS events
PanoradoJS.image
PanoradoJS.image.hotspots
PanoradoJS.controls
Mouse and keyboard interaction
Browser specifics

Panorado JS Overview

Framework

A panorama viewer appears at least 3 times within an HTML5 page:

There's a <canvas> element as a placehoder for the viewer within the <body> element. This element is ignored by older browsers which, instead, render the objects included.
The real viewer code is inside a JavaScript class. A <script> element within the <head> element references the file containing this class (Panorado_min.js).
Loading the page should trigger the creation and initialization of the viewer object. This can be done within an event handler function for the window.onload event.

Thus, a very simple page looks like this:

<!DOCTYPE html>
<html>
   <head>
      <title>Panorado JS Demo</title>
      <script src="Panorado_min.js" type="text/javascript"></script>
      <script type="text/javascript">
         window.onload = function() {
            Viewer = new PanoradoJS();
            Viewer.canvas = document.getElementById("ViewerCanvas");
            Viewer.image = { src: 'PanoradoDemo.jpg', projection: 'spherical' };
         }
      </script>
   </head>
   <body>
      <canvas id="ViewerCanvas" style="width:800px;height:450px">
         Please update your browser for HTML5 support!
      </canvas>
   </body>
</html>

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:
The Viewer.image object should have the projection: "spherical" property.
Width of the source image: For a 360° image about the applet width * 3, or less if the horizontal angle is smaller.
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: Viewer.image.scale = 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.

PanoradoJS class

Technically, the Panorado JS Viewer is a JavaScript class like any other, with properties, methods, and events.

A freshly created viewer object needs to know 2 things to start working:

What is to be painted? The image file is defined by the image property.
Where will it be painted? A canvas object needs to be assigned.

Besides these 2 properties, there are lots more which will be described in detail below.

PanoradoJS properties

A Panorado JS viewer object supports these properties
(all angles in degrees):

`version`	[get; String] The script's version number.
`canvas`	[set, get; Object] the canvas object within the HTML page where the image is to be "painted".
`image`	[set, get; Object] The source image to be rendered. Besides the properties of a standard HTML Image object like `src`, `width` and `height`, this object has some more specific properties (description).
`imageList`	[set, get; Array] An optional list of image definitions. If such a list is defined, the viewer can switch between the list's images using its `selectImage()` and `nextImage()` methods.
`projection`	[set, get; String] The current projection mode: "flat" or "spherical". Default: "flat". Every image can be provided with its own initial projection mode.
`gridSize`	[set, get; Num] The nominal size of the grid used for spherical projection. A smaller grid provides better image quality but slower performance. Value: 1...8°, default: 5°.
`enabled`	[set, get; Boolean] Defines if mouse and keyboard interaction is possible. Default: true
`mouseMode`	[set, get; String] Defines if dragging the mouse will move the viewport ("pan") or the image ("grab"). Default: "pan".
`mouseWheel`	[set, get; String] Defines the zoom direction when rotating the mouse wheel up. "in" or "out"; default: "in".
`touch`	[set, get; Boolean] Defines if touch input (pen or finger tap) is enabled - instead of mouse input. This feature is currently experimental, like most browser implementations of touch features. Default: false.
`panCursor0`	[set, get; String] Defines the name of a .cur file used for the mouse cursor symbol in pan mode with the left mouse button released. Optional.
`panCursor1`	[set, get; String] Defines the name of a .cur file used for the mouse cursor symbol in pan mode with the left mouse button pressed. Optional.
`grabCursor0`	[set, get; String] Defines the name of a .cur file used for the mouse cursor symbol in grab mode with the left mouse button released. Optional.
`grabCursor1`	[set, get; String] Defines the name of a .cur file used for the mouse cursor symbol in grab mode with the left mouse button pressed. Optional.
`softPan`	[set, get; Num] Defines the duration of the SoftPan effect. SoftPan the delayed movement after the mouse button has been released. Value: 0...5; default: 2.
`softZoom`	[set, get; Num] Defines the duration of the SoftZoom effect. SoftZoom is a smooth transition effect applied when zooming in or out. Value: 0...5; default: 3.
`softFade`	[set, get; Num] Defines the duration of the SoftFade effect. SoftFade is a transition effect applied when switching between images. Value: 0...10; default: 0.5.
`loaded`	[get; Boolean] Defines if currently an image is loaded completely, ready for viewing.
`pan`	[set, get; Num] Defines the current horizontal viewing angle. Every image can be provided with its own initial viewing angle. Value: 0°...360°.
`tilt`	[set, get; Num] Defines the current vertical viewing angle. Every image can be provided with its own initial viewing angle. Value: -90°...+90°.
`scale`	[set, get; Num] Defines the current viewing scale. A value of 1 corresponds to 100%. Every image can be provided with its own initial scale. Value: 0.25...8.
`panSpeed`	[set, get; Num] Defines the current horizontal panning speed (degrees per second). Every image can be provided with its own initial panning speed. Value: 0...60.
`tiltSpeed`	[set, get; Num] Defines the current vertical panning speed (degrees per second). Every image can be provided with its own initial panning speed. Value: 0...60.
`mousePan`	[get; Num] Defines the horizontal viewing angle of the current mouse cursor position.
`mouseTilt`	[get; Num] Defines the vertical viewing angle of the current mouse cursor position.
`hotspotsVisible`	[set, get; Num] Defines if hotspots should be currently visible. Default: true.
`hotspotInfo`	[set, get; String] Defines the URL of an image file to be used for the symbol of an info hotspot. This global definition can be overidden for every single hotspot (description) Default: internal symbol.
`hotspotLink`	[set, get; String] Defines the URL of an image file to be used for the symbol of an link hotspot. This global definition can be overidden for every single hotspot (description) Default: internal symbol.
`compassVisible`	[set, get; Boolean] Defines if the compass scale should currently be visible. Loading an image with a compassNorth property turns this switch on. Default: false.
`fullWindow`	[set, get; Boolean] Defines if the viewer is to fill the entire area of the document window. Default: false.

PanoradoJS methods

The Panorado JS viewer object supports these methods
(all angles in degrees):

`reset()`	Restarts the current image with its initial viewing angle, scale, and speed.
`move(panOff, tiltOff)`	Shifts the image's viewing angle by the offset values specified (angles).
`setSpeed(panSpeed, tiltSpeed)`	Sets the current speed to the angle values specified. `null` parameter values will be ignored.
`zoom(factor)`	Changes the current scale by the factor specified, preserving the viewing angle of the center of the viewport.
`zoomToCursor(factor)`	Changes the current scale by the factor specified, preserving the viewing angle under the mouse cursor.
`moveTo(pan, tilt, scale)`	Sets the current viewing angle Sets alos the current scale if the third parameter is unequal `null`.
`resize(width, height)`	Changes the canvas element's size to the values specified.
`selectImage(index)`	If the `imageList` property has been set, this will switch to the list's image with the index specified.
`nextImage(offset)`	If the `imageList` property has been set, this will switch to the list's image with the offset specified.

PanoradoJS events

A Panorado JS viewer object supports these events which you can assign approprate handler functions:

`onClick`	[set, get] Function to be called when the left mouse button is clicked while the mouse cursor is within the viewer's area.
`onDblClick`	[set, get] Function to be called when the left mouse button is double-clicked while the mouse cursor is within the viewer's area.
`onImageLoaded`	[set, get] Function to be called after an image has been loaded completely.
`onImageMove`	[set, get] Function to be called when changing the viewing angle or the scale.
`onMouseMove`	[set, get] Function to be called when moving the mouse within the viewer's area.

PanoradoJS.image

If you assign an image assigned to the viewer, you have to provide a more or less complex JSON object containing image properties. Example:

Viewer.img = { src: "MyPano.jpg", projection: "spherical" };

The properties set here can be read afterwards one by one:

`src`	[get; String] The URL of the image file. Mandatory.
`title`	[get; String] A plain text image description.
`projection`	[get; String] The initial projection mode: "flat" oder "spherical"; Default: "flat". The current setting can be changed afterwards by means of the `Viewer.projection` property.
`horizon`	[get; Num] The distance between the horizon and the source image's vertical center line, in degrees. Default: 0°.
`pan`	[get; Num] The initial horizontal viewing angle. Default: 0°.
`tilt`	[get; Num] The initial vertical viewing angle. Default: 0°.
`scale`	[get; Num] The initial viewing scale. Default: 0 (fit).
`horzFov`	[get; Num] The horizontal field of view of the source image. Default: 360°.
`panSpeed`	[get; Num] The initial horizontal viewing speed (degrees per second). Value: 0...60; default: 3.
`tiltSpeed`	[get; Num] The initial vertical viewing speed (degrees per second). Wert: 0...60; default: 0.
`compassNorth`	[get; Num] The distance (degrees) between the left image margin and the direction considered as pointing north. Value: 0...360; default: null (don't show a compass scale).
`hotspots`	[get; Array] An optional list of hotspot definitions (description)

More image properties that dont't have to be set explicitly:

`vertFov`	[get; Num] The vertical field of view of the source image (degrees). Calculated from the horzFov, width, and height properties.
`is360`	[get; Boolean] Indicates if the horizontal field of view is 360°.
`width`	[get; Num] The image width (pixels).
`height`	[get; Num] The image height (pixels).

PanoradoJS. image.hotspots

An image description can contain an optional array of hotspot definitions in JSON format. Example:

{ pan: 120, tilt:10, text: "Show detailed description", url: "Description.htm", target: "_blank" };

When reading Viewer.img.hotspots[index], you can retrieve hotspot definitions.
The hotspot object supports these properties:

`pan`	[get; Num] The horizontal viewing angle. Mandatory.
`tilt`	[get; Num] The vertical viewing angle. Mandatory.
`text`	[get; String] A descriptive text to be displayed when hovering the hotspot with the mouse.
`url`	[get; String] If not set, this a merely informative hotspot. If set, this is the URL (link) of a page to be displayed when the hotspot is clicked. Instead of a URL, you could assign a JavaScript funcion call like `"javascript:doSomething();"`
`target`	[get; String] The name of the window where the linked target is to be displayed. Default: "_self". >ou can specify "_blank" for a popup window, or any other name at your choice.
`img`	[get; String] The URL of an image file to be used for the hotspot's symbol. Optional.

PanoradoJS.controls

The Viewer.controls object allows to define the appearance of the control buttons which can be provided within the viewer's display area.
The controls object supports these properties:

`visible`	[set, get; Boolean] Defines if internal controls are to be used at all. Default: true.
`reset`	[set, get; Boolean] Defines if an internal reset button is to be displayed. Default: true.
`motion`	[set, get; Boolean] Defines if internal buttons for moving the image are to be displayed. Default: true.
`browse`	[set, get; Boolean] Defines if internal buttons for switching between images are to be displayed. Default: true. This assumes that an `Viewer.imageList` object has been defined.
`hotspots`	[set, get; Boolean] Defines if an internal button for showing/hiding hotspots is to be displayed. Default: true.
`helpUrl`	[set, get; String] Defines a URL for an optional popup page containing helpful instructions.
`closeWindow`	[set, get; Boolean] Defines if an internal button for closing the viewer window is to be displayed. Default: true. The button is only shown if the viewer is within a popup window.
`size`	[set, get; Boolean] Defines an indicator for the size of the internal buttons. Value: 0.7...2; default: 1.

Notice: All the above underlying functions (and many more) can also be implemented using external HTML elements!

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.
Rotate mouse wheel	Zooms in/out (using smaller steps if shift key is pressed).

...using the keyboard:

M	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).
+/-	Zooms in/out (using smaller steps if shift key is pressed).
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.
I	Displays information about the viewer.

Browser specifics

The script version presented here has been tested on
Microsoft Internet Explorer, Mozilla Firefox, Opera, Chrome, and Safari,
running on a Windows 7/x64 system.

Rendering tests revealed significant image quality and performing differences between these browsers, though no browser failed completely.

Chrome performed extremely better after opening the configuration page about:flags and setting the GPU Accelerated Canvas 2D flag explicitly.

Some rendering and poor performance issues could be compensated by browser-specific implementation. With these optimizations made, there were still differences in performance, which don't allow to make general statements, but a relative comparison of canvas rendering qualities.

Tests with Panorado JS 1.0.1.32, time for rendering a spherical image (1280/720px, scale=0):

MSIE 9.0	31 ms
Firefox 9.0	44 ms
Opera 11.6	69 ms
Chrome 16.0 (Factory Settings)	114 ms
Chrome 16.0 (2D Canvas HW Accelerated)	19 ms
Chrome 16.0	114 ms
Safari 5.1	107 ms

The processor utilization value was very similar on all browsers, ranging between 47 and 54% while panning and virtually 0% while idle, measured on a Windows7 x64 / Intel Core2 Duo 3.0 GHz system.

Some popup blockers can prevent the viewer from opening a hotspot link in a new window. You can avoid this only by disabling the popup blocker temporarily or permanently, or by implementing the popup as an <iframe> element.