close panorama

krpano on iPhone / iPad / iPod Touch
via the krpanoJS Javascript / HTML5 / 3D CSS Viewer Version

Introducing Videos

First - just have a look at these videos:

krpano Virtual Tours on the iPad / iPhone4 / iPod Touch and Android Nexus One:

Test the tours from the video by yourself: (the tours are also included in the viewer download package)

krpano on the iPad:

krpano on the iPhone 3G:

How does it work?

The viewer is Javascript based and uses the new HTML5 CSS 3D transforms for displaying the panoramas. These CSS 3D transforms are currently only available in the Mobile Safari and in Safari 5 Browser.

The possibilities compared to Flash are limited. It's only possible to use cubical pano images.
A triangle based 3D rendering, which would allow things like Fisheye / 'Little Planet' projections, spherical / cylindrical and partial panos is not possible with the CSS 3D transforms. Maybe there will be more possibilities in future when some real 3D graphics APIs (like WebGL) become available. But the current quality and performance is already really good and viewing panos makes fun, especially on the iPad ;-)

The viewer reads and parses the same XML file as the krpano Flash viewer. So it's possible to control and setup both viewers by the same file.

But due to the limited memory resources of the mobile devices, it's not possible to use the same large images as in the Flash viewer - e.g. several 2000x2000 pixel images will let the Safari Browser simply crash, no error throw or something...
As solution there are new settings in the xml to specify (smaller) images for the mobile and tablet devices, more details about that here in the How to use it section.

The current version ( of the Javascript krpano viewer (krpanoJS) supports almost all possibilities of the krpano xml format: Including and placing images via the <plugin> tag, defining hotspots via the <hotspot> tag, scenes, loading and blending to other panos and allmost all actions. For a listing of currently not supported functions have a look - here.

How to use it?

The Javascript viewer is an additional file - the krpanoiphone.js. It must be placed in the same folder as the krpano.swf and will be loaded automatically on the iPhone / iPad / iPod Touch devices by swfkrpano.js embedding script. When using the krpano tools droplets a single Javascript file with all files embedded (the Flash embedding script, the krpanoJS Viewer and the licneses) will be created by default.

This viewer is an Add-on to the normal krpano licenses, so there is an additional license necessary - get it here - it's a personalized license file - the krpanoiphone.license.js, it must be placed in the same folder as the krpanoiphone.js.

The embedding syntax is the same like for the krpano Flash Panorama viewer, no changes are necessary here, but note - it's important to set some iPhone specific meta settings in HTML for correctly scaling - just use the default HTML template, which is included in the viewer and tools download packages!

Only cubical panoramic images are supported at the moment!
And their size is limited (the exact size is unknown), for the iPhone cube face sizes like 480x480 to 640x640 seems to be good, and for the iPad something around 1024x1024 to 1280x1280. Just play around and find what size is good in your eyes.
BUT NOTE - too large images can slow down or crash the Mobile Safari Browser!

There are two ways to add images for the iPhone and iPad:
  • Either use multiresolutions panos and make sure that there are levels that are small enough. For the iPhone 3 / iPod touch levels smaller than 512 pixels and for the iPad / iPhone 4 levels that are smaller than 1100 pixels.

  • Specify dedicated images via the <mobile> and <tablet> tags:

    The paths to the iPhone / iPad images will be set in the XML in the <image> node by the <mobile> and <tablet> tags.

    On the iPhone 3G/3GS or iPod Touch 3 the <mobile> tag will be loaded and on the iPad and the iPhone 4 the <tablet> tag or if that doesn't exists also then the <mobile> tag.

Here an example of the XML structure:
<image ...>
    <!-- here the normal pano image paths -->

    <!-- mobile phone / iphone images -->
        <left  url="mobile_l.jpg" />
        <front url="mobile_f.jpg" />
        <right url="mobile_r.jpg" />
        <back  url="mobile_b.jpg" />
        <up    url="mobile_u.jpg" />
        <down  url="mobile_d.jpg" />

    <!-- tablet pc / ipad images -->
        <left  url="tablet_l.jpg" />
        <front url="tablet_f.jpg" />
        <right url="tablet_r.jpg" />
        <back  url="tablet_b.jpg" />
        <up    url="tablet_u.jpg" />
        <down  url="tablet_d.jpg" />    

Implementation Details

Details about the current version (
  • The new version is much more stable than the previous version on the iPhone and iPad. The Mobile Safari has only very limited memory and a very buggy memory handling. Every time when the memory gots too low it simply crashes.
    The current version uses many tricks and hacks to keep the memory usage always as low as possible. This should reduce the crashes of the Mobile Safari to a minimum.
  • The viewer is optimized to work on all iOS versions (3.x and 4.x) and all iOS devices (iPhone 3G, iPhone 3GS, iPhone 4, iPad, iPod Touch) with the best possible performance.
  • The rendering is sharper on the desktop. On the Desktop (Safari 5 and Chrome 9) the normal full images were used. Tiled and multires panos can be to 2200 pixels. Additionally a different rendering method is used that avoids the automatic mipmapping which would smooth the panos unnecessary and uncontrolable.
  • The edges of cubes faces are fit correctly together.
  • When loading and blending to a new pano - then a both panos must use preview images. The iPhone and iPad don't have enough memory to hold two full panos in the memory. Therefore only the preview images were used during blending.
  • The krpanoJS viewer has an internal implementation of the textfield plugin. When a plugin with a url named "textfield.swf" should be loaded then the internal textfield will be used. But ntoe - the internal textfield plugin is supports only the very basic features at the moment.
  • The hotspots and plugin images can use automatically an alternative image when running in the krpanoJS viewer. Therefore there is the new alturl setting in the xml. For example - to use an animtated gif instead of an animtated flash as hotspot.
  • Addtional there is also an alternative scaling (altscale) and an alternative onloaded event (altonloaded) to set alternative settings.
  • The use/display an certain plugin or hotspot element only on specific device then new devices setting can be used.
  • 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.
  • There is no dot button to open the krpano trace log anymore.
    Now touch on iPhone/iPad the right bottom corner and move the finger upward a 1/3 of the screen to open the log. On the desktop simply press the 'O' key like in the flash viewer.
  • The krpanoJS viewer was developed and tested on iPhone 3G (iOS 4.0.1), iPhone 4 (iOS 4.0.1), iPhone 4 (iOS 4.1), iPad (iOS 3.2.1) and iPod Touch (iOS 3.1.3).

Tools / Droplets

The kmakemultires Tool and its MAKE PANO Droplets have also been extended for automatically creating down-scaled iPhone and iPad images and for automatically copying or embedding the krpanoJS script.

There are these new settings the kmakemultires .config files:

The buildmobileimages and buildtabletimages settings say if the tools should also build images for mobile and tablet devices. Possible settings are yes, no or auto, where auto means - build the images only when there is a krpanoiphone.license.js file in the tools folder.
The settings buildmobileres and buildtabletres are used to set the resolution / size of the panos.
With the copyiphonejs it's possible to control if the krpanoJS should be used and automatically copied.
The embedlicenses=true settings goes one step fruther and automatically creates single Flash and Javascript files with the viewer and licenses embedded. This reduces the number of files to handle. This setting is enabled for all current droplets.

Test the Viewer on your PC/MAC with Safari 5

It's possible to test the krpano Javascript viewer also on the Pc and Mac with the Safari 5 browser by changing the User Agent setting in the browser:
  1. Mac: Click on Safari on the menu bar and go to Preferences.
    Windows: Click on Edit on the menubar and go to Preferences.
  2. Go to the Advanced tab.
  3. Check the checkbox for Show Develop menu in menu bar.
  4. Now a new Develop menu will show up in the menu bar.
  5. Click on this new Develop menu and then select User Agent.
  6. There select the Mobile Safari 3.2 - iPad item.
  7. Reload the pano page.

Example links for testing

The tours from the video above: (also included in the viewer download package)

The viewer package examples:

What about Android?

On Android 2.2 devices there is the Flashplyer 10.1 available in the Android Market.
With it the normal krpano Flash viewer panos can be used. Using the krpanoJS HTML5 viewer is not possible because on Android there is no CSS 3D transforms support.

The current krpano version ( has some automatic optimations when running on a Android device:
  • The controlmode will be "drag2D".
  • There will be no mouse cursor.
  • There are unfortunately no multi-touch gestures available in Android 2.2, not in the Flashplayer and also not via Javascript. So a two-finger zooming gesture is not possible. But to have anything to zoom krpano uses the trackpad instead (trackpadzoom).
  • Large single images will slow down the rendering, to avoid this the smaller <mobile> or <tablet> images will be used when available.
  • It's possible to control if some elements should be shown on Android or not via the new devices setting.
  • Note - for using the native resolution of the Android device it is necessary to have the "target-densitydpi=device-dpi" viewport meta setting defined in the html. Otherwise the elements will look scaled wrongly. The krpano templates and examples should have set this already.

Some addtional notes about Android - the rendering performance itself is good/okay but the touch inputs are recognized very jerky (on the Nexus One, maybe other Android devices behave different) so the rendering sometimes seem to be jerky too. But there are already plans for a new control mode that will 'smooth' the input for a smoother moving experience also on Android.

What about the Future?

Having the same interface for two systems - Flash and HTML/Javascript - has some interesting perspectives - regardless of which system will be prefered in the future - only one interface to serve panos for both systems will be necessary!
Interesting news on the Flash side are the upcomming Flashplayer with 3D Hardware acceleration (Codename Molehill) and on the HTML side the WebGL support of the browsers.
The big steps regarding HTML5/Javascript support are now already done with the new krpanoJS viewer. The rendering output - now via CSS 3D Transforms - is only one small part of the viewer, adding also other rendering possibilites (like WebGL) should be not that big thing.

Supported / Unsupported Functionality (State:

Listing all supported functionality would be too long, therefore only the currently not supported functionality is listed here:

Unsupported functionalty:

  • Multiresolution - it's currently simply not possible do this with HTML/CSS and a good performance! Beside of the peformance there is no real memory control and the Safari browser is very buggy when using much memory.
  • Spherical / partial / flat panos or fisheye / stereographic projections - the limited 3D possibilities of HTML/CSS don't allow distorting / rendering such images.
  • Mouse over / out events. On desktop they would be possible, but on touch devices not. Therefore no support for over / out events at all for the moment.
  • Polygonal hotspots - the desktop browsers would be fast enough to do that with canvas but on the iPhone/iPad devices the canvas is so incredible slow, so there they are not possible at the moment.

Unsupported xml tags / variables:

  • showerrors
  • lasterror
  • colorcorrection
  • bgcolor
  • mouse.stagex
  • mouse.stagey
  • multireslevel
  • lockmultireslevel
  • downloadlockedlevel
  • actionintervalbase
  • xml.content (partially, available for loadscene and loadxml calls)
  • display.*
  • area.*
  • events.onloaderror
  • view.camroll
  • view.hfov
  • view.vfov
  • view.maxpixelzoom
  • view.limitfov
  • view.fisheye
  • view.fisheyefovlink
  • view.stereographic
  • view.pannini
  • view.architectural
  • view.architecturalonlymiddle
  • view.hlookatmin
  • view.hlookatmax
  • control.usercontrol
  • control.keybinvert
  • control.movetocursor
  • control.cursorsize
  • control.headswing
  • control.keycodesleft
  • control.keycodesright
  • control.keycodesup
  • control.keycodesdown
  • control.keycodesin
  • control.keycodesout
  • control.zoomtocursor
  • control.zoomoutcursor
  • cursors.*
  • progress.*
  • image.prealign
  • image.hfov
  • image.vfov
  • image.voffset
  • image.multiresthreshold
  • image.frame
  • image.frames
  • image.layer
  • image.left/front/right/back/up/down.rotate
  • image.left/front/right/back/up/down.strip
  • image.left/front/right/back/up/down.flip
  • image.sphere.*
  • image.cylinder.*
  • image.qtvr.*
  • image.zoomify.*
  • contextmenu.*
  • network.*
  • memory.*
  • plugin/hotspot.visible
  • plugin/hotspot.enabled
  • plugin/hotspot.alpha
  • plugin/hotspot.layer
  • plugin/hotspot[].capture
  • plugin/hotspot[].children
  • plugin/hotspot[].preload
  • plugin/hotspot[].hovering
  • plugin/hotspot[].accuracy
  • plugin/hotspot[].blendmode
  • plugin/hotspot[].usecontentsize
  • plugin/hotspot[].scale9grid
  • plugin/hotspot[].onovercrop
  • plugin/hotspot[].mask
  • plugin/hotspot[].effect
  • plugin/hotspot[].smoothing
  • plugin/hotspot[].onover
  • plugin/hotspot[].onhover
  • plugin/hotspot[].onout
  • hotspot[].edge
  • hotspot[].distorted
  • hotspot[].details
  • hotspot[].rx
  • hotspot[].ry
  • hotspot[].rz
  • hotspot[].inverserotation
  • hotspot[].ismovie
  • hotspot[].refreshrate
  • hotspot[].fill*
  • hotspot[].border*
  • hotspot[].fade*
  • hotspot[].point*
  • hotspot[].state*
  • textstyle.*
  • lensflareset*
  • lensflare*

Unsupported actions: (they are there but functionless)

  • showtext
  • addlensflare
  • reloadpano
  • removelensflare
  • freezeview
  • fscommand