Introducing Pannellum

After a year of on and off development, Pannellum, a free and open source panorama viewer for the web, is ready for release. Built using HTML5, CSS3, JavaScript, and WebGL, it is plug-in free. The lightweight viewer, just 18kB gzipped, can be deployed using a single file and displays full equirectangular panoramas. One can easily embed panoramas in web pages as an <iframe>, using code generated by the included configuration utility.


Almost all previous web panorama viewers have been plug-in based, be it Java, Flash, QuickTime, et cetera. With growing browser support for WebGL, this is no longer necessary. As of writing, approximately half of the browsers currently in use support WebGL. With proper graphics drivers, recent versions of Firefox and Chrome support WebGL by default. In addition, recent versions of Safari and preview versions of Opera have WebGL support, although it is turned off by default. The notable exception to WebGL support is Internet Explorer, with no versions, including the preview release of IE 10, having support. Although large swaths of Internet users run browsers that do not support WebGL, support is steadily growing. Plug-in based solutions may have better support today, but WebGL and standards based development is the future.

One last feature that gave Flash an advantage over HTML5, was full screen support, but in the past few months this has changed. While still an early draft, the Full Screen API allows for web applications to programmatically enter full screen much in the way Flash does, allowing for a more immersive experience. When development on Pannellum started, this was not the case, and I originally implemented more limited full window support by opening a larger popup window. This original method is still supported for older browsers that support WebGL but do not support the Full Screen API.

Pannellum was started as I could not find a good plug-in free panorama viewer. The closest I could find was a three.js demo that displayed an equirectangular panorama. While it worked for the one image, everything was hard-coded, it lacked user friendly controls, and was missing basic features. In addition, it relied on a large, 64kB gzipped, JavaScript library. Pannellum displays a panorama using the same method as this demo, but the similarities end there. Although featuring a much improved user interface; embedding support; configuration using URL parameters; title, author, and license information; and full screen support among other things, Pannellum is still much smaller and easier to deploy. This is in large part due to work to carefully strip the three.js library down to the bare minimum needed using a JavaScript profiler. A Python build system is used to first minify the JavaScript using the Closure Compiler and the CSS using the YUI Compressor, then insert these along with data URIs of the images into the HTML file before finally running it through an HTML Compressor to produce the final viewer.

The initial release of Pannellum can be downloaded here, or one can see the project on Github.

This entry was posted in and tagged , , , , . Bookmark the permalink.

28 Responses to Introducing Pannellum

  1. Very cool! Well done!

  2. John Watkins says:

    Excellent! Thanks for your fine work.
    My only suggestions would be support for partial panoramas (not sure if this has it, but this may be due to my lack of technical competence) and the ability to use keyboard controls for tilt, pan, zoom and pull (cursor arrows to control panning (again I have no idea if there are cross platform compatibility issues preventing this.) It seems like there might be fewer difficulties with this in the full screen mode, where interactive target of focus is less of an issue.
    Again, thanks. This is a really fine effort!

  3. Habi says:

    Awesome! I’ve been looking for a nice flash-free panorama presenting tool for a long time. Now I’m looking forward to put panellum through several tests ;)

  4. Pingback: habi.gna.ch » Blog Archive » Das Rolex Learning Center an der EPFL in Lausanne, revisited

  5. Very nice! I am looking for an panorama viewer like this for a long time. One question: Is it possible to add auto rotation of the pano? Controls as mentioned by John would be very nice to.

    Keep up the good work!!

    • Matthew Petroff says:

      It is possible to add auto-rotation. Implementing it would be very similar to adding keyboard panning controls.

  6. Jorge Rego says:

    Hi Matthew,

    Very nice job, congrats!

    I’ve also played with that same demo of three.js and it seems you came a long way.
    Do you have any plans in developing it further, i.e. it’s very very nice to have a FREE webGL panorama player, but what about navigation hotspots jumps for tours and plugins like: link to html text, photos, videos or other common web content (in that flash is yet ahead … self made plugins, like photozoom and such).
    I totally understand the time already invested and by no means intent to “complain”, just wondering (and hoping) if that’s on your mind.

    Best regards

    • Matthew Petroff says:

      I might add that eventually but not in the immediate future. A higher priority in my option is image pyramid support, so higher resolutions can be load progressively.

  7. Light john says:

    Hi, very good work.
    I have a question: i make panoramas that are 360° from right to left but only ~90° from top to bottom, is it possible to use Pannellum for that ?

    I think John Watkins was wondering the same thing.

    • Matthew Petroff says:

      Currently, it does not support that but may in the future. The only way right now is to add black bars to your image.

      • Light john says:

        It’s working thanks for your fast answer.

        For a 1300 height panorama i add to create a new image of 3000 height but it works.

        Thanks again for your nice, free, open source work.

  8. Charles Daniels says:

    How would I go about adding hotspots? Would mapping the image work?

  9. Julian says:

    Hi Matthew,

    Thanks for making pannellum. I have downloaded pannellum-1.2.1 and wasn’t able to get it to work in chrome. At first I thought it was my fault in integration.

    But then I see that even the demo on your site is also not working in Chrome

    http://www.mpetroff.net/archives/2012/05/28/introducing-pannellum/

    A little trace of the console log I see that:
    , WebGL: INVALID_VALUE: texImage2D: width or height out of range

    Wonder if you can help fix it.

    Also I was wondering what stitching program did you use to stitch the examplepano.jpg

    Is it Equirectangular Projection?

    Do you also support Cubic Projection?

    And do you also plan to make one so we can zoom into the image in more detail?

    • Matthew Petroff says:

      That error is caused by the image being too big for your graphics driver, in this case 5000px by 2500px. The example image is in equirectangular projection and was stitched with Hugin. Cubic projection is also supported and allows for higher resolution images on older machines as the image is split into six images instead of one. I plan on adding functionality to allow for multi-resolution tiling for the display of very high resolution panoramas, but I don’t have an estimate for when I will finish it.

      • Thank you for this insanely cool open-source flash-free panorama viewer. For what felt like ages, I tinkered around with Three.js, suffered from the occasional regressions and arbitrary API changes. You do a great work here.
        I grabbed the development version from git and I can say, the awesome multi-texturing feature works reasonably well. I tested it with my favorite panorama. However, I propose supporting an additional path substitution character in libpanellum.js . I introduced .replace('%i',x+y*Math.pow(2,level-1)) so the filenames align nicely with batch-cut cube-faces produced by ImageMagick’s convert -crop 512x512 cubeface-b.jpg b.png.

  10. This is awesome! I already installed it on my portfolio website. It’s really lightweight and looks good. Thank you very much.

    I have a few more feature suggestions for your consideration:

    Offset:
    -let the user define a starting point by giving a value ranging from 0 to 360.
    Slideshow:
    -let the panorama turn automatically at a slow speed

    • Matthew Petroff says:

      I’ve already added those features in the development version:
      One can set initial parameters with fov=, lat=, and lon=.
      One can also set automatic rotation with the autorotate= option. The numeric value is rotation speed in degrees/second.

  11. Mitthraw says:

    Thanks very much, this is great script you are sharing here. Well done!

  12. Mitthraw says:

    A question. I want to load image stored on another location. I have it on my googledrive and it can be easily accessed with url from the browser.

    I’ve used encoded URL and then changed in pannellum.htm this d.src=getURLParameter(“panorama”) to this d.src=getURLParameter(decodeURIComponent(“encode url here”)) although it works on jsfidlle it wont load panorama in the pannellum, why?

    I even tried hardcoding the url in d.src=”http… bla bla” and still nothing.

    How can I do it this way? It would speed the loading time for me greatly as googledrive is much faster than my website server.

    • Matthew Petroff says:

      I assume you are using the last release (build/pannellum.htm in Git). The image isn’t loading due to the browser’s same-origin security policy preventing access to content from a different domain. A few months ago, I added CORS support to the development version (src/pannellum.htm in Git) that will allow an image from Google Drive or any other provider that supports CORS to be used. Thus, if you use the development version, it should work.

  13. Mitthraw says:

    I have downloaded the master version from Github, and it works perfect. Thank you very much Matthew, this is truly a great viewer!

  14. George says:

    Very nice! any way to may height responsive?

  15. I have the “Jordan pond” example on my web site and it works OK mackiefamily.net/pano/example.htm .
    I also have pano.html in the same directory which has the image I want to display. The preview is displayed OK. When I press “click to load panorama” I can see that the browser is downloading the image. However the message “browser does not have the necessary WebGL support to display the panorama” is eventually displayed. This happens in both current (Dec 2014) versions of Firefox and Chrome. The Pannellum version is 2.1.

    There are two differences between example.htm and pano.html. The files being displayed are .png rather than .jpg, and the sizes are 2.1Mb/25.4Mb for my preview/image, rather than 39kb/2.1Mb for the example.

    I’m assuming that pannellum is encountering an error for some reason. Any ideas as to what the problem could be or suggestions as to what to change to prevent the problem?

    Could it be the “graphics driver” problem mentioned above (Aug 11 2013), my image is 10904 x 1600. I have another, even bigger, of 23602 x 3000 that I’d like to display. Is there a way to determine if this is the problem (I dont know what the “console log” referred to in the post (Aug 10 2013) refers to)?

    TIA.

    • Matthew Petroff says:

      The most likely cause is your image being too big for your graphics driver. Images wider than 8192px are not supported by most devices. In this case, you’ll get a WebGL: INVALID_VALUE: texImage2D: width or height out of range error in Chrome’s JavaScript console (Ctrl+Shift+J) or a WebGL: texImage2D: the maximum texture size for level 0 is [max size] error in Firefox’s Web Console (Ctrl+Shift+K). To display large panoramas, you need to convert them to Pannellum’s multires format. The utils/multires/generate.py script does this, requiring Python 3 and nona from Hugin; while it should work on Windows and Mac, I’ve only tested it on Linux.

  16. Hiro Abejo says:

    First of all, I would like to congratulate and thank you for this wonderful panorama viewer. I have used your library on one of our clients (I hope it is fine for you). I added some additional functions such as floorplans and hotspots on floorplans. However, it sometimes works and then sometimes won’t work on Chrome browsers, especially for Chrome on Android. I hope you can help me with this.

    • Matthew Petroff says:

      There are no known issues with the standard, desktop version of Chrome. Mobile support can be a bit spotty however, since not all mobile devices support WebGL and of those that do, some don’t support larger texture sizes (which limits the maximum panorama size). I generally recommend limiting equirectangular images to 4096px or smaller to maximize device support.