The immersive experience!

Framework

A panorama viewer normally appears 3 times within an HTML5 page:

  • There's a <canvas> element serving as a placehoder for the viewer within the <body> element.
  • 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 #1</title>
      <meta http-equiv='X-UA-Compatible' content='IE=edge'>
      <script src="Panorado_min.js"></script>
      <script>
         window.onload = function() {
            viewer = new PanoradoJS(document.getElementById("viewerCanvas"));
            viewer.image = { src: 'MyPano.jpg', projection: 'spherical' };
         }
      </script>
   </head>
   <body>
      <canvas id="viewerCanvas" style="width:800px;height:450px"></canvas>
   </body>
</html>

v.2.2+ also supports XHTML5 syntax (which is still used sometimes but losing popularity).

Recommendations

  • Place a short advisory notice close to the viewer explaining basic mouse and touch interaction.
  • Panoramic images should have the projection: "spherical" property.
  • For 360° images, the source image should be about 3 times as wide as the <canvas> element.
  • For images with a small field of view, we recommend flat projection (which is the default).
    Start with a reduced scale, fitting the image into the viewer frame: viewer.image.scale = -1.
    Encourage the visitor to zoom into the image.
  • Please keep in mind 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 two 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 two 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):

canvas [get; object] the canvas object within the HTML page where the image is to be "painted".
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.
currentImageId [set, get; numeric] The index of the image currently selected from the image list (0-based).
A value of -1 means that no image is selected from an image list.
dispHorzFov [set, get; numeric] The horizontal field of view currently displayed (in degrees).
Refers to the viewer looking straightly horizontally (tilt = 0).
dispVertFov [set, get; numeric] The vertical field of view currently displayed (in degrees).
enabled [set, get; boolean] Defines if mouse/keyboard/touch interaction shall possible. Default: true.
fullWindow [set, get; boolean] Defines if the viewer is to fill the entire area of the document window. This is different from the browser's full screen mode (F11).
Default: false.
fullWindowEnabled [set, get; boolean] Defines if enlarging the viewer to full windows size interactively shall be possible. Default: true
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.
gridSize [set, get; numeric] The nominal size of the grid used for spherical projection. A smaller grid provides better image quality but slower performance. Value: 1...8°, default: 4°.
hotspotsVisible [set, get; boolean] Defines if hotspots should be currently visible.
Default: true.
hotspotTemplate [set; object] Defines default properties for hotspots.
These global definitions can be overidden for every single hotspot.
Object properties:
  • imgInfo [string]: URL of an image file for info hotspots.
    Default: internal symbol.
  • imgLink [string]: URL of an image file for link hotspots.
    Default: internal symbol.
  • border [boolean]: Show hospot popups with border? Default: false.
  • shadow [boolean]: hotspot popups with shadow effect? Default: false.
  • opacity [numeric]: Show hotspot popups with transparency effect?
    0.0 .. 1.0; Default: 1.0.
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.
info [get; string] Information about The viewer's environment.
initialized [get; boolean] Returns if the viewer could be initialized.
isOrientationAvailable [get; boolean] Returns if device orientation can provide pan/tilt/roll parameters. Mobile devices normally support this using gyroscope/accelerometer/compass sensors.
Some browsers claim to support orientation without checking for device capabilities.
Currently, not all devices/browsers do this perfectly.
isTouchAvailable [get; boolean] Returns if touchscreen input is available.
isWebGlAvailable [get; boolean] Returns if WebGL hardware graphics support is available.
licenseKey [set, get; string] A 16-digit key assigned to a commercial license. If omitted, the viewer may be used on private websites, displaying a product symbol in the bottom-right corner.
loaded [get; boolean] Defines if currently an image is loaded completely, ready for viewing.
maxScale [set, get; numeric] Sets a limit for zoomin in.
The specified scale will never be exceeded.
Value: 0.125...8; default: 8.0.
minLivestreamWidth [set, get; numeric] The minimum horizontal resolution of the livestream video image. (pixels)
Default: 640. Currently interpreted by Opera & Chrome browsers. MISE doesn't yet support livestreams; Firefox uses about:config settings.
minScale [set, get; numeric] Sets a limit for zoomin out.
The specified scale will never be exceeded.
Value: 0.125...8; default: 0.125.
mouseMode [set, get; string] Defines if dragging the mouse will move the viewport ("pan") or the image ("grab").
Default: "grab" for touchscreens, else "pan".
mousePan [get; numeric] Defines the horizontal viewing angle of the current mouse cursor position.
mouseTilt [get; numeric] Defines the vertical viewing angle of the current mouse cursor position.
mouseWheel [set, get; string] Defines the zoom direction when rotating the mouse wheel up.
"in", "out", or "ignore"; default: "in".
orientationMode [set, get; boolean] Defines how device orientation shall be used to navigate the viewer. Options:
"none" = Ignore
"absolute" = Position image according to device cardinal direction (pan), tilt, and roll
Default: "none".
overlaysVisible [set, get; boolean] Defines if overlays should be currently visible.
Default: true.
overlayTemplate [set; object] Defines default properties for overlays.
These global definitions can be overidden for every single overlay.
Object properties:
  • popupClose [string]: Defines how popups get closed.
    Options: "auto" (default) or "button".
  • popupPerspective [boolean]: Display overlay popups in perspective?
    Default: false.
  • popupPosition [string]: Position of overlay popups
    Options: "auto" (default) or "center".
  • popupScaling [string]: Scale overlay popups depending on image scale.
    Options: "fixed", "logarithmic" (default), or "linear".
  • symbolPerspective [boolean]: Display overlay symbols in perspective?
    Default: false.
  • symbolSrc [string]: URL of an image file for overlays.
    Default: internal symbol.
  • symbolScaling [string]: Scale overlay symbols depending on image scale.
    Options: "fixed", "logarithmic" (default), or "linear".
pan [set, get; numeric] Defines the current horizontal viewing angle.
Every image can be provided with its own initial viewing angle.
"Pan" is synonymous to "yaw". Value: 0°...360°.
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.
panSpeed [set, get; numeric] Defines the current horizontal panning speed (degrees per second).
Every image can be provided with its own initial panning speed.
Value: 0...60.
projection [set, get; string] The current projection mode: "flat" or "spherical". Default: "flat".
Every image can be provided with its own initial projection mode.
roll [set, get; numeric] Defines the current rotation angle of the image around the length of the lens.
The roll value is used when controlling the view by device orientation.
Value: -180°...+180°.
rollSpeed [set, get; numeric] Defines the current roll speed (degrees per second).
Every image can be provided with its own initial roll speed.
Value: 0...60.
scale [set, get; numeric] Defines the current viewing scale.
A value of 1 is equivalent to 100%.
A value of 0 zooms out as much as possible while filling the viewport on at least two sides.
A value of -1 zooms out as much as possible without showing margins.
Every image can be provided with its own initial scale.
Value: 0.125...8.
softFade [set, get; numeric] Defines the duration of the SoftFade effect.
SoftFade is a transition effect applied when switching between images.
Value: 0...10; default: 0.5.
softPan [set, get; numeric] 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; numeric] Defines the duration of the SoftZoom effect.
SoftZoom is a smooth transition effect applied when zooming in or out.
Value: 0...5; default: 3.
tilt [set, get; numeric] Defines the current vertical viewing angle.
Every image can be provided with its own initial viewing angle.
"Tilt" is synonymous to "pitch". Value: -90°...+90°.
tiltSpeed [set, get; numeric] Defines the current vertical panning speed (degrees per second).
Every image can be provided with its own initial panning speed.
Value: 0...60.
useTouch [set, get; boolean] Defines if touchscreen input shall be used to navigate the viewer - instead of mouse input.
Default: true if available.
useWebGl [set, get; boolean] Defines if WebGL hardware graphics support shall be used.
Default: true if available.
version [get; string] The viewer's version Number.
videoCurrentTime [set, get; numeric] Defines the current playing position of a video file (if loaded). In seconds.
videoDuration [get; numeric] Returns the total playing time of a video file (if loaded). In seconds.
videoPlaying [set, get; boolean] Defines if a video file (if loaded) is currently playing.
videoSound [set, get; boolean] Defines if a video file (if loaded) is currently playing sound.
waitImage [set, get; string] Defines the name of an image file to be displayed when waiting for an image to load. If defined, this replaces the "Loading..." message. Optional.

PanoradoJS
methods

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

new PanoradoJS(canvas)

Constructor. Requires existing canvas element as parameter.
about() Opens a popup window displaying information about The viewer's environment.
move(panOff, tiltOff, rollOff) Shifts the image's viewing angle by the offset values specified (angles).
moveTo(pan, tilt, scale) Sets the current view according to the specified values:
pan/tilt are angle coordinates of the target viewing direction.
scale is the target scale.
Parameters set to null will be ignored.
moveToEx(pan, tilt, roll, scale, duration, onMoveCompleted) Sets the current view according to the specified values:
pan/tilt/roll are angle coordinates of the target viewing direction.
scale is the target scale.
duration defines the time for the animation (seconds; 0...60).
onMoveCompleted is a callback function that will be executed on arrival at the target view.
Parameters set to null will be ignored. (New in version 2.5)
nextImage(offset) If the imageList property has been set, this will switch to the list's image with the positive or negative offset specified (previous/next).
reset() Restarts the current image with its initial viewing angle, scale, and speed.
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.
setSpeed(panSpeed, tiltSpeed, rollSpeed) Sets the current speed to the angle values specified.
null parameter values will be ignored.
zoom(factor) Multiplies the current scale by the factor specified, preserving the viewing angle of the center of the viewport.
zoomToCursor(factor) Multiplies the current scale by the factor specified, preserving the viewing angle under the mouse cursor.

PanoradoJS
events

A Panorado JS viewer object fires events which you can assign approprate handler functions.
Within the handler functions, you can use this to refer to the viewer object (new in v. 2.5.1.2).

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. Not reliable on some touch devices.
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.
onResize [set, get] Function to be called after the canvas element gets resized.

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.image = { src: "MyPano.jpg", projection: "spherical" };

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

autoplay [get; boolean] Defines if video is to start playing automatically.
Not supported by all browsers.
Default: false (don't play).
compassNorth [get; numeric] 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).
description [get; string] Text describing the image.
horizon [get; numeric] The distance between the horizon and the source image's vertical center line, in degrees. Default: 0°.
horzFov [get; numeric] The horizontal field of view of the source image. Default: 360°.
hotspots [get; array] An optional list of hotspot definitions (description)
loop [get; boolean] Defines if playing a video file is automatically repeated.
Default: false (don't loop).
overlays [get; array] An optional list of overlay definitions (description)
pan [get; numeric] The initial horizontal viewing angle. Default: 0°.
panSpeed [get; numeric] The initial horizontal viewing speed (degrees per second).
Value: 0...60; default: 3.
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.
roll [get; numeric] The initial roll angle. Default: 0°.
rollSpeed [get; numeric] The initial roll speed (degrees per second).
Value: 0...60; default: 0.
scale [get; numeric] The initial viewing scale.
1 is equivalent to 100%.
0 zooms out as much as possible while filling the viewport on at least two sides (default).
-1 zooms out as much as possible without showing margins.
src [get; string] The URL of the image or video file. Mandatory for "imagefile", "cubefile", and "videofile".
If the file comes from another domain (like Picasa), the server should deliver it with an Access-Control-Allow-Origin HTTP header.
For video files, you can specify multiple sources of different types, separated by semicolons; the first source supported by the browser will be used.
tilt [get; numeric] The initial vertical viewing angle. Default: 0°.
tiltSpeed [get; numeric] The initial vertical viewing speed (degrees per second).
Value: 0...60; default: 0.
title [get; string] A plain text image title.
type [get; string] The type of the image source:
"imagefile", "cubefile", "videofile", or "livestream".
Video formats supported for "videofile" type:
- MP4: MSIE, Firefox, Chrome, Safari
- WebM: Chrome, Firefox, Opera
- Ogg: Firefox, Opera, Chrome.
Browsers supporting "livestream" type:
Firefox, Opera, Chrome
Optional; default: "imagefile".
userData [get; any] An arbitrary user defined property. Default: null.

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

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

PanoradoJS.image.hotspots

Hotspots are represented by small symbols within the image, providing a textual description when the mouse is above it, and linking to another page when clicked.

An image description can contain an optional array of hotspot objects in JSON notation.

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

You can set define default hotspot properties using the viewer's hotspotTemplate property (see above).

When reading viewer.image.hotspots[index], you can retrieve hotspot definitions.
A hotspot object supports these properties:

border [get; boolean] Show popup with border? Optional; Default: false.
img [get; string] The URL of an image file to be used for the hotspot's symbol. Optional.
opacity [get; boolean] Show popup with transparency effect?
Optional; 0.0 .. 1.0; Default: 1.0.
pan [get; numeric] The horizontal viewing angle. Mandatory.
shadow [get; boolean] Show popup with shadow effect? Optional; Default: false.
target [get; string] The name of the window where the linked target is to be displayed. Default: "_self".
You can specify "_blank" for a popup window, or any other name at your choice.
text [get; string] A descriptive text to be displayed when hovering the hotspot with the mouse.
Define line breaks by a <br> sequence.
tilt [get; numeric] The vertical viewing angle. Mandatory.
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();"

PanoradoJS.image.overlays

Overlays are similar to hotspots, but allow to define complex HTML elements like <div> which pop up when the overlay symbol is clicked.

An image description can contain an optional array of overlay objects in JSON notation.

Example:
{ pan: 120, tilt:10, popupElementId: "overlay1" }

You can set define default overlay properties using the viewer's overlayTemplate property (see above).

When reading viewer.image.overlays[index], you can retrieve overlay definitions.
An overlay object supports these properties:

pan [get; numeric] The horizontal viewing angle. Mandatory.
popupClose [get; string] Defines how the popup gets closed.
Options: "auto" (default), "button".
popupElement [get; object] An HTML (DOM) element which pops up when the symbol gets clicked.
Apart from <div>, you can use elements like <iframe>, <a>, <img>, some of them even with nested sub elements.
The referenced element can be defined somewhere within the HTML body of the page.
It is recommended to set its style visible=hidden. Block elements should have width and height styles. There are more interesting styles like overflow, background-color, border, and box-shadow.
A popup can be defined alternatively by a popupElementId property (see below).
popupElementId [get; string] Instead of the popup element itself (see above), you can define its id property.
popupPerspective [get; boolean] Defines if the overlay popup is to be displayed in perspective, centered above the symbol.
Combining perspective with popupScaling: "linear" allows you to display variants of image areas.
Default: false.
popupPosition [get; string] Position of the overlay popup.
Options: "auto" (close to symbol, within viewer; default), "center" (centered above the symbol).
popupScaling [get; string] Scale overlay popup depending on image scale.
Options: "fixed", "logarithmic" (default), or "linear".
symbolElement [get; object] An HTML (DOM) element to be shown as a symbol.
Apart from <div>, you can use elements like <iframe>, <a>, <img>, some of them even with nested sub elements.
The referenced element can be defined somewhere within the HTML body of the page.
It is recommended to set its style visible=hidden. Block elements should have width and height styles.
If multiple overlays are defined by the symbolElement property, each one needs to use a separate element.
A symbol can be defined alternatively by a symbolElementId property (see below).
symbolElementId [get; string] Instead of the symbol element itself (see above), you can define its id property.
symbolHref [get; string] The URL of an HTML page to be opened immediately after clicking the overlay symbol. Optional.
symbolPerspective [get; boolean] Defines if the overlay symbol is to be displayed in perspective.
Default: false.
symbolScaling [get; string] Scale overlay symbol depending on image scale.
Options: "fixed", "logarithmic" (default), or "linear".
symbolSrc [get; string] The URL of an image file to be used for the overlay's symbol. Optional.
You can use PNG files with shadow and transparency effects or GIF files for animations.
symbolTitle [get; string] A descriptive text to be displayed when the mouse pointer hovers above the overlay symbol. Optional.
tilt [get; numeric] The vertical viewing angle. Mandatory.

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:

browse [set, get; boolean] Defines if internal buttons for switching between images are to be displayed. Default: true.
Available if an viewer.imageList object has been defined with more than one image.
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 full-sized within a popup window.
fullWindow [set, get; boolean] Defines if an internal button for resizing the viewer to full window size is to be displayed. Default: true.
helpUrl [set, get; string] Defines a URL for an optional popup page containing helpful instructions. If set, an internal button will bring it up.
hotspots [set, get; boolean] Defines if an internal button for showing/hiding hotspots and overlays is to be displayed. Default: true.
Available if hotspots or overlays are defined.
info [set, get; boolean] Defines if an internal button for displaying information about The viewer's environment in a popup window is to be displayed. Default: true.
motion [set, get; boolean] Defines if internal buttons for moving the image are to be displayed. Default: true if not touch screen.
orientation [set, get; boolean] Defines if an internal button for switching to device orientation mode is to be displayed. Default: true if device orientation is supported.
reset [set, get; boolean] Defines if an internal reset button is to be displayed. Default: true.
scale [set, get; boolean] Defines if internal buttons for scaling (zooming) the image are to be displayed. Default: true if not touch screen.
size [set, get; boolean] Defines an indicator for the size of the internal buttons.
Value: 0.7...2; default: 1.
video [set, get; boolean] Defines if internal buttons for video control are to be displayed. Default: true. For video files only.
visible [set, get; boolean] Defines if internal controls are to be used at all. Default: true.

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

CMS pages

If you are using a Content Management System like WordPress, Joomla, TYPO3, or Drupal to create your website, access to the HTML-<head> section and Javascript might be restricted.

Recommendation in that case: Use a plain text editor and create a HTML page containing the viewer according to the above specifications. Include that page into your CMS content using an <iframe> element.

Mouse, touch, and keyboard interaction

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

...using the mouse:

Click & drag Pans the image.
Rotate mouse wheel Zooms in/out (using smaller steps if shift key is pressed).

...using your fingers:

Drag
with one finger
Pans the image.
Spread two fingers Zooms in/out (pinch zoom).

...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 without a margin.
+/- 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.
Enter Enlarges viewer to full window size.
Escape Stops moving the image or resizes viewer from full window to normal.
C Toggles visibility of the compass scale.
H Toggles visibility of hotspots.
I Displays information about the viewer.

Sample Page II

An HTML page with some more explicit settings might look like this:

<!DOCTYPE html>
<html>
   <head>
      <title>Panorado JS Demo #2</title>
      <script src="Panorado_min.js"></script>
      <script>
         var imgList;

         window.onload = function() {
            imgList = [
               { src: 'Panorama1.jpg', title: 'Panorama #1', projection: 'spherical',
                  pan: 90, scale: 1, horzFov: 180, horizon: 3,
                  hotspots: [
                     { pan: 6, tilt: 0, text: "More about this spot...", url: "More.htm", target: "_blank" },
                     { pan: 88.3, tilt: 5, text: "This is something to notice", img: "HsInfo.png" }
                  ],
                  overlays: [
                     { pan: 120.6, tilt: -5, elementId: "overlay1" }
                  ]
               },
               { src: 'MyPano2.jpg', title: 'Panorama #2', horzFov: 360, projection: 'spherical' },
               { src: 'MyFlatImage1.jpg', title: 'Flat Image #1', horzFov: 20, projection: 'flat' }
            ];

            viewer = new PanoradoJS(document.getElementById("viewerCanvas"));
            viewer.imageList = imgList;
            viewer.selectImage(0);
            viewer.onImageLoaded =
               function() { document.getElementById('imageTitle').innerHTML = this.image.title; };
            viewer.onDblClick =
               function() { this.zoomToCursor(2); };
            document.getElementById("version").innerHTML = viewer.version;
         };
      </script>
   </head>
   <body>
      <h1>Panorado JS v.<span id="version">???</span> Demo #2</h1>
      <p id="imageTitle">Loading image...</p>
      <canvas id="viewerCanvas" style="width:800px;height:450px"></canvas>
      <div id="overlay1">Hello World!</div>
   </body>
</html>