close panorama

krpano HTML5 Viewer Version 1.16

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 2013 - krpano Version 1.16.9)

  • 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 5.1 or higher is recommended.
      • In iOS version 4.x distorted hotspots can be touchable, even when they are visually behind other elements.
      • Sound and Video are available only since iOS version 4.0.
      • The Bing Maps Plugin requires iOS version 4.0 or higher.
      • In iOS version 3.x distorted hotspots can be displayed at the wrong position.
      • In iOS version 3.1.x the text of the combobox plugin will be displayed not correctly.
      • The minimum iOS version is 3.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
      • Android 4.0 or higher is needed.
      • 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
  • BlackBerry devices
    • Playbook (OS 2.1)
  • iOS devices
    • iPad 1 (iOS 5.1.1)
    • iPad 2 (iOS 6.0)
    • iPad 3 (iOS 7.0.3)
    • iPad Mini (iOS 7.0.3)
    • iPhone 3GS (iOS 6.0)
    • iPhone 4 (iOS 4.3.3)
    • iPhone 4 (iOS 7.0)
    • iPhone 5 (iOS 6.1.3)
    • iPhone 5 (iOS 7.0.3)
    • iPod Touch 2.Gen (iOS 3.1.3)
    • iPod Touch 4.Gen (iOS 6.0)

Supported Panoramic-Image Formats

Viewer support - Cubical only

The krpano HTML5 Viewer itself currently only supports cubical 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.

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 krpanoiphone.js file, and the license for it is the krpanoiphone.license.js file (don't get confused by the 'iphone' in the filenames, this has historical reasons, the viewer itself can be used on all devices).

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. By default the loading of the Flash viewer will be preferred because the Flash viewer still supports more features (Multi-Resolution, Flat-Panos ...) and has a better support for older systems. The HTML5 viewer will be only loaded when the Flashplayer is not available or when the html5 embedding settings was set accordingly.

When using the krpano.swf Flash viewer directly without embedded licenses, then the HTML5 viewer files must be either placed in the same folder as the swf file or included manually in the html file. When using the krpano Droplets with the default settings, a single all-contained '.js' file will be created. In that js file the embedding script, the HTML5 viewer and the license for it 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, alternative smaller cube images should 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>
  • Or use multi-resolutions images and let the viewer automatically load a level that is small enough. For Non-Retina iPhones and iPods the level size should be smaller than or equal to 512px and for the iPad and Retina iPhones the level size should be smaller than 1100px.
Note - see the also the mobile usage notes for embedding the viewer into the html page.

Implementation Details

  • When blending between panos, both panos need to have preview-pano images. Mobile devices like iPhone and iPad doesn't have enough memory to hold two full panos at the same time in the memory. So only the preview images were used during blending.
  • The automatic url-bar hidding on the iPhone Safari browser is triggered every 4 seconds and only when the pano is embedded as fullscreen/fullwindowed pano (100% width and height) from the beginning.
  • To open the krpano log on touch devices touch on the right bottom corner and move the finger upward a 1/3 of the screen. On the Desktop simply press the 'O' key on the keyboard.

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 kmakemultires 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=always 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'
    • IE10: Settings Icon ⇒ Security Menu ⇒ check 'ActiveX-Filtering'
  • Change the UserAgent to iPhone or iPad - Safari only!
    • Preferences ⇒ Advanced Tab ⇒ check 'Show Develop menu'
    • Develop Menu ⇒ User Agent ⇒ select any iPhone or iPad User Agent

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 important features (like multi-resolution or flat-panos) 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.16)

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:

  • Multiresolution - currently not possible, but already in work.
  • Flat pano images - currently not possible, but already in work.
  • Multiple pano frames - currently not possible, but already in work.
  • The direct usage of spherical or cylindrical images - with CSS 3D transforms it is not possible to use such images. With WebGL that would be theoretical possible, but when aiming for cross-browser / cross-device support, then their usage doesn't make sense. The krpano tools should be used in this case to convert them to cubical images. There are already tool-based plans to support partial panos better in this case without wasting image space.
  • Polygonal hotspots - the desktop browsers are theoretical fast enough for drawing polygonal hotspots, but on iPhone, iPad and Android the rendering of them is currently still too slow for an efficient usage, so they are currently not supported, but there are plans to implement them anyway.
  • Lensflares - currently not supported (no 'blendmode=add' in HTML5 yet).

Unsupported xml elements / variables / actions: