close panorama

krpano HTML5 Viewer Version

The krpano HTML5 viewer is a HTML5 / Javascript application which uses HTML5 and the new CSS 3D transforms technology for displaying panoramas without the need for browser plugins. The viewer uses the same XML files as the krpano Flash viewer. So it's possible to control and setup both viewers by using the same files.


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

Supported Systems and Browsers

The HTML5 CSS 3D transforms is a very new technology and many browsers and systems still have different implementations and a different level of support and so also different issues. The krpano HTML5 Viewer internally deals with all these differences and tries to provide the same output on all systems and browsers.

The currently supported systems and browsers of the krpano HTML5 Viewer are:
(State: October 2012 - krpano Version Build 2012-10-05)

  • 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 Safari / WebView based browsers and apps, but there can be issues, like a wrong display orientation, when these features are not correctly implemented in these browsers or 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) then the Safari Browser will simply crash. To avoid this, always keep an eye on the pixel-sizes of the images (pano and layout / skin images).
    • iOS Version Notes:
      • iOS version 5.1 or higher is recommended. This is the currently most stable version when it comes to memory-related browser crashes.
      • In iOS version 4.x the distorted hotspots can be touchable, even when they are visually behind other elements.
      • Sound and Video are available since iOS version 4.0.
      • The Bing Maps Plugin requires iOS version 4.0 or higher.
      • In iOS version 3.x the 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.
  • Desktop Safari (Windows and Mac)
    • Safari 5.0 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 (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.
  • 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 display will be only correct when hardware-acceleration is available and enabled.
    • The overall working and performance is very good.
    • Notes for local testing - Chrome doesn't allow reading local files for security reasons by default. To enable that for testing add --allow-file-access-from-files as application parameter.
  • Mozilla Firefox (Windows, Mac, Linux)
    • Firefox Version 10 or higher is needed (the first version with CSS 3D support).
    • The display will be only correct when hardware-acceleration is available and enabled.
    • The overall working and performance is good, there are only some small issues - there can be sometimes a short flickering of the cube-images and the blending between the panos can be partially not correct.
    • Note - Firefox doesn't support mp3/h264 audio/video codecs, so there different file-formats need to be used.
  • Microsoft Internet Explorer (Windows 8)
    • Internet Explorer Version 10 (Release Preview) or higher is needed (the first version with correct HTML5/XML and CSS 3D support).
    • Works the same for the Desktop and the Metro version.
    • Windows 8 Tablets with IE10 are currently untested - so their support is currently unknown, there might be rendering and controlling issues without adjustments.
    • The overall working and performance is good.
    • Clicking through disabled elements to underlaying child-elements will be not possible. The IE Browser doesn't support the CSS 'pointer-events' property yet.
    • Notes for local testing - the IE Browser doesn't allow reading local files for security reasons by default. For local testing the security settings of the Browser need to be changed.
  • Android - Default System Browser
    • Android 4.0 or higher is needed.
    • The CSS 3D transforms support in the Android system browsers is still a bit unreliable and unpredictable at the moment. Even with the same Android version there can be rendering differences between different Android devices.
    • Distorted hotspots can be a problem on Android - either their clipping is wrong or it's not possible to touch them.
    • The CSS 3D transforms will be only displayed correct when the Android Browser is using hardware-acceleration. In some situations (low-gpu-memory?) the Browser will switch automatically to an internal 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 all is working, then the performance is okay. But for a really good support like on iOS or Desktop, the Android system (or browser) itself still need to evolve and get better.
  • Android - Chrome Browser (partially)
    • Currently only Chrome Version 18 is available for Android and this version has the same CSS 3D clipping bugs like the old desktop version, maybe Chrome Version 20 for Android will finally fix them on Android too.
    • Everything else (except the CSS 3D transform display) is already working correctly and with good performance.

Test Devices

The krpano viewer is currently being developed and tested on:
  • Several Windows systems
  • Several Mac OSX systems
  • Asus Transformer Pad TF700T (Android 4.0.3)
  • Medion Lifetab S9512 (Android 4.0.4)
  • Samsung Galaxy Tab 10.1 (Android 3.2)
  • Google Nexus S (Android 4.0.4)
  • Google Nexus One (Android 2.3.6)
  • iPad 1 (iOS 5.1.1)
  • iPad 2 (iOS 6.0)
  • iPad 3 (iOS 6.0)
  • iPhone 3GS (iOS 6.0)
  • iPhone 4 (iOS 4.3.3)
  • iPhone 4 (iOS 6.0)
  • iPhone 5 (iOS 6.0)
  • 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, different Projections, ...) 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 or useHTML5 embedding settings are 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 a fullscreen pano (100% width and height) from the beginning.
  • To open the krpano log on touch devices (iPhone/iPad/Android) 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 like in the Flash viewer.

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', the Webkit Browsers (Chrome, Safari) are currenlty not reporting this, so the fullscreensupport devices setting will tell a wrong availability of the fullscreen support 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>

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.

  • 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
  • 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:

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, flat/partial-pano or fisheye/stereographic projections) 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: build 2012-10-05)

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. New browsers and new devices are making this finally possible.
  • The direct usage of spherical or cylindrical images - with CSS 3D transforms it is not possible toe use such images. With WebGL they would be possible but when aiming cross-browser / cross-device support, then their usage doesn't make sense. The krpano tools should be used to convert them to cubical. And there are tool-based plans to support partial panos better without wasting image space.
  • Flat pano images - currently not possible but already in work.
  • Fisheye / Stereographic / Pannini projections - with CSS 3D transforms not possible, but maybe in future in WebGL enabled browsers.
  • Mouse over / out events - currently not supported, but planed for desktop.
  • Keyboard controls - currently not supported but manually already possible via xml events and actions.
  • Polygonal hotspots - the desktop browsers would be theoretically fast enough for drawing polygonal hotspots, but on iPhone, iPad and Android they are currently still too slow for that, so there they are currently not supported.
  • Lensflares - currently not supported (no 'blendmode=add' in HTML5 yet).

Unsupported xml elements / variables / actions: