close panorama

krpano HTML5 Viewer Version 1.18

The krpano HTML5 viewer is a HTML5 / Javascript based client-side application that uses either the HTML5 CSS 3D Transforms or WebGL for displaying panoramic images directly in the Browser, without the need for any plugins. The krpano HTML5 viewer uses the same xml files and the same images as the krpano Flash viewer. This way it's possible to control and setup both viewers by using the same files and the same codes. A pano or tour need to be made only once and will work automatically everywhere.


As introduction here an example for testing the HTML5 capabilities of your browser - the same tour once in HTML5 (left) and once in Flash (right):

More information about the html5 viewer-embedding setting

Supported Systems and Browsers

HTML5, CSS 3D Transforms and WebGL are a very new technologies and so many browsers and systems still have different implementations, a different level of support and also different issues. The krpano HTML5 Viewer internally deals with all these differences and tries to provide the same output with the best possible performance on all systems and browsers.

The currently supported systems and browsers of the krpano HTML5 Viewer are:
(State: October 2014 - krpano Version 1.18)

  • Mobile Safari on iOS Devices (iPhone, iPad, iPod Touch)
    • The viewer is perfectly optimized for these devices.
    • There should be no display or controlling issues.
    • The viewer should work also fine in all other Safari / WebView based iOS browsers and apps, but there can be issues, like a wrong display orientation, when these features are not correctly implemented in these browsers / apps.
    • The memory on these devices is limited and when too much memory will be used (too big or too much images at the same time on the html page) then the Safari Browser will simply crash. To avoid this, always keep an eye on the pixel-sizes of all images (pano and layout / skin images).
    • iOS Version Notes:
      • iOS version 7.1 or higher is recommended.
      • iOS version 7.0 has several memory leaks and is pretty instable.
      • The minimum iOS version for multi-resolution is 5.1.
      • The minimum iOS version for normal panos is 4.1.
  • Google Chrome (Windows, Mac, Linux)
    • Goolge Chrome Version 20 or higher is needed (Version 20 is the first Chrome version with correct CSS 3D rendering, all older versions had '3D-clipping' issues).
    • The pano display will be only correct when WebGL and/or hardware-accelerated CSS 3D Transforms is available.
    • The overall working, performance and support is very good.
    • Chrome supports Multi-touch-usage also on the desktop.
  • Mozilla Firefox (Windows, Mac, Linux)
    • Firefox Version 10 or higher is needed (the first version with CSS 3D support).
    • The pano display will be only correct when WebGL and/or hardware-accelerated CSS 3D Transforms is available.
    • Multi-touch-usage on the desktop is working the most time, but sometimes Firefox forgets the touch-control and starts sending mouse-events instead (Firefox bug).
    • The overall working, performance and support in WebGL-mode is very good. In CSS3D mode there can be several different rendering errors (depending on the Firefox version and on the system), so krpano embedding script tries to avoid using Firefox in CSS3D mode.
    • Note - Firefox doesn't support mp3/h264 audio/video codecs, so there different file-formats need to be used.
  • Microsoft Internet Explorer (Windows 7, Windows 8, Windows RT, Windows Phone 8)
    • Internet Explorer Version 10 or higher is needed (the first version with correct HTML5, XML and CSS 3D support).
    • Works the same for the desktop and the 'Metro/Windows 8' IE10 version.
    • Windows 8 Tablets are supported too, but non-ARM tablets will be detected as 'Desktop' - Microsoft doesn't allow to detect if the device is a desktop or just a tablet.
    • The overall working and performance is good. There are only some performance-problems when using textfields with shadows-effects. That means for best performance in IE, the usage of shadows should be avoided or limited.
    • The IE10 sometimes shows small graphics/display errors - the edges of elements (like the cube-faces or hotspots) can become visible because of rendering-errors.
    • IE10 supports Multi-touch-usage on mobiles, tablets and also on desktops.
    • New: With IE11 also WebGL and the HTML5 Fullscreen API will be supported.
  • Desktop Safari (Windows and Mac)
    • Safari 5.1 or higher is recommended.
    • Works fine with good performance.
    • Only the Window-Safari version has some issues - the mouse-moving can be sometimes blocked/hanging for a a short time (but the mouse-wheel and keyboard controls are working during this time) and the memory-need on can be very high and lead to browser crashes.
  • Android Browsers
    • Android Stock (WebView-based) Browser (before Android 4.4)
      • Android 4.0 or higher is needed.
      • For HTML5 multiresolution the Android browser need to support WebGL. The CSS3D support from the Android stock browser is too buggy for HTML5 multiresolution.
      • The CSS 3D transforms support in the Android stock (=typically WebView-based) browsers is still a bit unreliable and unpredictable at the moment. Even with the same Android version there can be rendering differences and issues between different Android devices. Some devices might work very well while others might have problems.
      • The CSS 3D transforms itself will be only displayed correctly when the Android browser is able to use Hardware-Acceleration! In some situations (low-gpu-memory?) the browser can switch automatically to an internal so called 'tiled based Software-Rendering', which is extremely slow and extremely bad and buggy. There will be strange graphics errors or mirrored cube images in this case.
      • When the CSS3D rendering itself is working, then the rendering performance is good up to very good. The browser stability depends often on the currently available RAM.
    • Android Chrome Browser
      • Goolge Chrome Version 20 or higher is needed (Version 20 is the first Chrome version with correct CSS 3D rendering, all older Chrome versions had '3D-clipping' issues). Many devices have a preinstalled Chrome 18 version - they will require an update via the Android Playstore before Chrome can be used to view panos. The krpano embedding script will report unsupported Browser for Chrome 18.
      • The overall working, support and stability is very good and the performance differes from okay up to very good.
    • Android Opera (Webkit-based) Browser
      • The new Webkit-based Opera browser works very fine.
      • It works like Android Chrome, but additionally has WebGL enabled by default. Both - CSS3D and WebGL are working very well.
      • Internally in krpano, the Opera browser will be detected as Chrome browser.
    • Android Firefox Browser
      • Firefox Version 18 or higher is needed (the first version with corrected touch-events and well performing CSS 3D support).
      • The Android Firefox browser provides CSS3D and WebGL for the pano rendering:
        • In CSS3D there are still some clipping bugs (can become visible when zooming out) but the performance itself is very good.
        • WebGL is slow before Android Firefox 22, but with version 22 Mozilla has dramatically improved the WebGL performance, so that, when Firefox 22 or higher will be used, the krpano viewer will automatically prefer WebGL over CSS3D.
        • See also the krpano embedding settings for information about these preference settings.
      • The overall working, support and performance (with Firefox 22 and WebGL) is very good.
  • BlackBerry Devices
    • Some BlackBerry devices are supporting WebGL and when WebGL is available and enabled the panos are working fine.
    • There is only one small issue/bug in the BlackBerry browser - images that were build via <canvas> elements can't be uploaded as textures - they will be always black. For krpano support/functionality this means that the preview-panos will be always black on BlackBerry devices.
    • Everything else is working fine with very good performance.

Test Devices

The krpano viewer is currently being developed and tested on:
  • Windows systems
    • Several typical Desktop and Notebook devices with different Windows versions (XP, Vista, Windows 7 and Windows 8.1)
    • Sony Vaio Tap 20 (Windows 8.1 Multitouch desktop system)
    • Microsoft Surface (Windows 8.1 RT)
  • Mac OSX systems
    • MacMini 2011
    • MacBook 2010
  • Android devices
    • Samsung Galaxy S3 (Android 4.3)
    • Samsung Galaxy S5 (Android 4.4.2)
    • Samsung Galaxy Tab 10.1 (Android 4.0.4)
    • Google Nexus One (Android 2.3.6)
    • Google Nexus S (Android 4.1.2)
    • Google Nexus 7 (Android 4.4.2)
    • Google Nexus 9 (Android 5.0)
    • Asus Transformer Pad TF700T (Android 4.2.1)
    • Medion Lifetab S9512 (Android 4.0.4)
  • BlackBerry devices
    • Playbook (OS 2.1)
  • iOS devices
    • iPad 1 (iOS 5.1.1)
    • iPad 2 (iOS 6.0)
    • iPad 3 (iOS 8.0.2)
    • iPad Air (iOS 8.1)
    • iPad Air 2 (iOS 8.1)
    • iPad Mini (iOS 7.1)
    • iPad Mini Retina (iOS 8.0.2)
    • iPhone 3GS (iOS 6.0)
    • iPhone 4 (iOS 4.3.3)
    • iPhone 4 (iOS 8.1)
    • iPhone 5 (iOS 8.0.1)
    • iPhone 5 (iOS 8.1.1 beta)
    • iPhone 6 (iOS 8.1)
    • iPhone 6 Plus (iOS 8.1)
    • iPod Touch 2.Gen (iOS 3.1.3)
    • iPod Touch 4.Gen (iOS 6.0)
  • Windows Phone devices
    • Nokia 630 (Windows Phone 8.1)
    • Nokia 930 (Windows Phone 8.1 Update 1)

Supported Panoramic-Image Formats

Viewer support - Cubical and flat panos only

The krpano HTML5 Viewer itself currently only supports cubical and flat panoramic images.
Why? ⇒ With the HTML5 CSS 3D transforms it is only possible to transform flat html surfaces in 3D space. And this only allows to the usage of panoramic formats with flat surfaces like the six flat sides of a cubical pano or the flat surface of a flat pano.

Tools support - Spherical, Cylindrical and Cubical

To be able to use also other formats like spherical or cylindrical, the krpano Tools and Droplets can be used. They can convert such images (only images with hfov=360) automatically to cubical images and also set automatically viewing-range-limitations to avoid seeing the unused parts of the converted cubical images.

How to use it?

The krpano HTML5 Viewer itself is the krpano.js file.

The krpano HTML5 Viewer can be only loaded by the krpano Embedding script. That embedding script will load the HTML5 viewer automatically when needed and available (depending on the html5 embedding setting).

When using the krpano Droplets, a single all-contained '.js' file will be created. In that .js file the embedding script and the HTML5 viewer are merged into one single file. In this case, only that file need to be included in the html file.

Notes about the usage on mobile devices (iPhone, iPad, Android)

For optimal performance and stability on mobile devices like iPhone, iPad and Android mobiles and tablets, either multi-resolution panos should be used - or alternative smaller cube images be provided.
The krpano HTML5 viewer would be able to load also the bigger desktop images and scale them down on-the-fly, but for more efficiency the availability of already downscaled images would be better. The loading is also faster this way.
For controlling the cube sizes on the mobiles devices there are html5 display settings available.

There are several ways for providing smaller images for mobile devices:
  • Use dedicated mobile images (for mobiles and tablets) and specify them in xml via a <mobile> element inside the <image> element:
      <cube url="pano_%s.jpg" />
        <cube url="mobile_%s.jpg" />
  • Use dedicated images and use the devices setting to control which images should be used on which device:
    <image devices="Desktop">     <cube url="pano_%s.jpg"   /> </image>
    <image devices="Mobile">      <cube url="mobile_%s.jpg" /> </image>
    <image devices="Tablet">      <cube url="tablet_%s.jpg" /> </image>
    <image devices="iPad+Retina"> <cube url="ipad3_%s.jpg"  /> </image>
  • Combine both methods from above - e.g.:
      <cube url="pano_%s.jpg" />
      <mobile devices="mobile"> <cube url="mobile_%s.jpg" /> </mobile>
      <mobile devices="tablet"> <cube url="tablet_%s.jpg" /> </mobile>
Note - see the also the mobile usage notes for embedding the viewer into the html page.

HTML5 Fullscreen Mode

  • Since version build 2012-10-05, the krpano HTML5 viewer is also supporting the HTML5 Fullscreen API. With it and when the browser supports it (btw - iOS currently not), it is possible to switch to fullscreen mode also with HTML5.
  • For detecting if the fullscreen mode is supported and available, the fullscreensupport xml devices setting and the actions device.fullscreensupport variable should be used.
  • Notes about <iframe> usage: When trying to use the HTML5 Fullscreen mode from an viewer within an iframe, it is necessary to add the allowfullscreen parameter (and the non-standard browser versions of it) to the <iframe> declaration. This tells the browser that this iframe is allowed to switch to Fullscreen mode.

    <iframe ... allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>

    Note - when the iframe usage is not 'allowed', some browsers might not report this correctly, so the fullscreensupport devices setting can tell a wrong availability in this case!

Tools / Droplets

The krpano makepano tool and its MAKE PANO / MAKE VTOUR droplets are having new config settings for automatically using the krpano HTML5 viewer and for automatically generating smaller images for mobile usage.

The settings which are important for HTML5 are (click on the setting for details about it):
# set the html5 usage

# convert spherical/cylindrical to cubical

# generate dedicated smaller mobile images
customimage[mobile].xml=<mobile> <cube url="[PATH]" /> </mobile>
Note - when increasing the default sizes for mobile images, then also the display.hardwarelimit setting need be increased!

Testing the krpano HTML5 Viewer on Desktop

There are several ways to test the krpano HTML5 Viewer on Desktop while keeping the default Flash usage.

  • Use the html5 setting as url parameter
    • Add and enable the passQueryParameters setting in the html:
      embedpano({...., passQueryParameters:true});
    • Enter the pano / tour url and add html5=only as parameter:
  • Disable (temporary) the Flash plugin
    • Firefox: Add-Ons ⇒ Plugins ⇒ 'Shockwave Flash' ⇒ Disable
    • Chrome: enter 'chrome://plugins/' ⇒ click on 'disable' for all 'Shockwave Flash' plugins
    • Safari: Settings Menu ⇒ Security Tab ⇒ uncheck 'enable Plugins'
    • IE: Settings Icon ⇒ Security Menu ⇒ check 'ActiveX-Filtering'

Testing iPhone / iPad Layouts and Images on Desktop

For testing / simulating iPhone or iPad devices on Desktop a HTML5 compatible browser and the simulatedevice embedding setting can be used. When this settings is set, the viewer will act like on these devices (except the mouse/touch controlling) - the same layout scaling, the same devices settings, the same pano images.

The krpano iPhone/iPad Simulator (included in the viewer download package) is using that setting together with an iPhone / iPad background and an original sized viewing window.

Future Developments

The krpano HTML5 Viewer is still missing some features (like partial-panos and object-movies) that are only available in the krpano Flash Viewer, but it is only a matter of time until they will become available / supported too.

The HTML5 browsers and devices are becoming better and better with each version and krpano will do so and take advantage of these improvements. Having the same interface for the two systems - Flash and HTML5 - has already some big advantages - a pano or tour need to done only once, the transition from Flash to HTML5 itself is almost seamless.

Supported / Unsupported Functionality (State: krpano 1.18)

The krpano Flash and HTML5 Viewers are already offering almost the same level of functionality, so listing all supported functionality would be too long and therefore only the currently not supported functionality will be listed here:

Unsupported functionality:

  • Multiple pano frames (multiframe/objects) - currently not possible, but already in work.
  • Lensflares - currently not possible, but already in work (for WebGL).

Unsupported xml elements / variables / actions: