360° panorama viewer

I've shot so many panoramas over the years, but these are basically impossible to view on SmugMug as it doesn't support a panorama viewer. The alternative is to make a page for my panoramas on an external website and just link to that from my SmugMug gallery. But this is ugly (as I'm definitely no designer), hard to maintain, and requires the extra expense of a third-party webhost. As a result, I haven't been able to share my panoramas.

So, I built a panorama viewer customisation which allows you to seamlessly embed PTGui, SaladoPlayer or Microsoft Deep Zoom panoramas into your SmugMug galleries.

Live demo

You can see a live demo of this working in my Panoramas gallery! Just click any panorama to launch the viewer, then click and drag to pan the image.

Installation

If you were able to tweak your YUI configuration, you might do something like this to it:

if (!YUI.GlobalConfig.groups["sherlockphotography"]) {
	YUI.GlobalConfig.groups["sherlockphotography"] = {modules: {}};
} 

YUI.GlobalConfig.groups["sherlockphotography"].modules["ss-openseadragon"] = {
    fullpath: "http://s3.sherlockphotography.org/smugmug/panorama/v2/seadragon/openseadragon.js",
};

YUI.GlobalConfig.groups["sherlockphotography"].modules["ss-panorama-view"] = {
    fullpath: "http://s3.sherlockphotography.org/smugmug/panorama/v2/ss-panorama-view.js",
    requires: ["io", "json-parse", "ss-openseadragon", "event-synthetic"],
    condition: {
    	trigger: "sm-lightbox-view"
    }
};

That will cause this code to be automatically loaded in your galleries to enable panorama display:

Preparing your galleries

These panorama viewers break your panorama up into many smaller images, so you'll need to create a new gallery to hold those fragments for each panorama that you make. I like to title these galleries with a prefix like "Panorama: John Bull Gully", so that I remember that it is a gallery of panorama parts. In the settings for this panorama-parts gallery, make sure that "filenames" is set to "yes", "privacy" is set to "unlisted", and "largest size" is set to "original". You can save these settings as a Quick Setting to speed up this process in future!

You need to know the ID for your panorama-parts gallery. This can be found by going to the gallery, and clicking View Source in your web browser. Search for the text "AlbumKey", you should find this section:

Combine the "albumId" and "albumKey" together with an underscore in the middle, and this is the ID of the gallery you need to use for the panorama viewer (in this case, that would be "22821295_SMgRHM"). Make a note of that ID.

Preparing your panorama

The method for preparing your panorama is different for each of the three viewers (PTGui, SaladoPlayer, and Deep Zoom), so here's a section explaining each approach:

PTGui

PTGui (ptgui.com) is a commercial panorama stitching package which includes the ability to publish a panorama to a website. It includes a panorama viewer which can display panoramas using either HTML5 or Flash. It's designed to view panoramas which approach 360 degrees x 180 degrees in size (panoramas which cover less area are padded with blank space and so are relatively inefficient). The PTGui viewer runs very smoothly with lower-resolution panoramas, but gets memory hungry with more detailed panoramas as it loads the entire panorama into memory at once. On the plus side, after it loads in, PTGui always displays the highest-quality version of your panorama.

PTGui's JavaScript and Flash viewer have both been modified to work on SmugMug. Big thanks to the team at PTGui for giving permission to make this modification!

Your panorama should use the equirectangular projection for best results. In PTGui's Panorama Editor, set the projection to equirectangular and frame your panorama as you like. Make a note of the horizontal field of view shown in the status bar (in degrees):

Once you've stitched (and edited) your panorama, click on the "tools" menu, then "publish to website". Add in the panorama file you stitched, set the projection to equirectangular, and fill in the horizontal field of view that you remembered from earlier:

Save this template file to your computer in a useful place.

In PTGui, tick the "Use Custom Template" box on the right hand side, then click the Browse... button and select the .htm file you just downloaded.

Now click the Convert button. PTGui will create a series of 15 JPEG images for your panorama, plus an HTML file which describes them. Upload these images to the SmugMug panorama-parts gallery that you prepared earlier. Open the HTML file in a text editor like notepad, you'll see something like this:

My panorama's title<span class='my-panorama' title='{
  gallery: "fill your gallery ID in here",
  pano: "mypan_",
  format: "14faces",
  pan: 0,
  minpan: -180,
  maxpan: 180,
  tilt:0,
  mintilt: -39.77504448549261,
  maxtilt: 39.77504448549261,
  fov: 90,
  minfov: 10,
  maxfov: 120,
  autorotatespeed: 5,
  autorotatedelay: 10,
  maxiosdimension: 567,
  showfullscreenbutton_flash: 1,
  showfullscreenbutton_html: 1,
  enablegyroscope: 1
}'></span>

Write the ID of the panorama-parts gallery that you found earlier into the "gallery" space, so you'll end up with something like:

My panorama's title<span class='my-panorama' title='{
  gallery:"19744646_gQ5Hn2",
  pano: "mypan_",
  format: "14faces",
  ...

Now you can use this panorama descriptor to add the panorama to your public gallery, check out the next major section.

SaladoPlayer

SaladoPlayer (panozoma.com) is Open Source software for viewing panoramas within a webpage using Flash. It's designed to view panoramas which approach 360 degrees x 180 degrees in size (panoramas which cover less area are padded with blank space and so are relatively inefficient). This is a high-performance panorama viewer, with low memory usage and fast loading times. It achieves this by storing scaled-down versions of your panorama to display when the view is zoomed out, with increasingly higher magnification images available as you zoom in (you may be familiar with this effect from Google Maps). This is the recommended viewer to use for high-resolution, immersive panoramas.

SaladoPlayer has been modified for use on SmugMug. If you're a programmer, you can check out the modified sourcecode for SaladoPlayer, which is based on SaladoPlayer 1.3.2.

SaladoPlayer requires you to first stitch your panorama in equirectangular format, with a 360 degree horizontal field of view and a 180 degree vertical field of view. This panorama must be converted using a tool called SaladoConverter into the SaladoPlayer format ready for upload. You can download SaladoConverter for SmugMug here (sourcecode for programmers).

SaladoConverter requires Java to be installed on your computer. If you don't have Java installed yet, then you can install it from http://www.java.com/.

Run SaladoConverter by double-clicking on "saladoconverter.jar". In the window that appears, click "add" to add your equirectangular panorama for processing. In the drop-down box at the bottom, set the action to "Equirectangular to SmugMug cubic panorama", and choose an output folder by clicking the "output" button. Then click the "run" button to start processing:

SaladoConverter creates a folder full of panorama fragments, and a text file:

Upload those images the panorama-parts gallery you created earlier. Open up the text file, you'll see something like this:

<span class='my-panorama' title='{
  pano:"mypan_",
  gallery:"fill your gallery ID in here",
  format:"deepzoomcubic",
  tileSize:512,
  tileOverlap:1,
  width:4608,
  height:4608
}'></span>

Write the ID of the panorama-parts gallery that you found earlier into the "gallery" space, so you'll end up with something like:

<span class='my-panorama' title='{
  pano:"mypan_",
  gallery:"19744646_gQ5Hn2",
  format:"deepzoomcubic",
  tileSize:512,
  tileOverlap:1,
  width:4608,
  height:4608
}'></span>

Now you can use this panorama descriptor to add the panorama to your public gallery, check out the next major section.

Microsoft Deep Zoom

Microsoft Deep Zoom (http://zoom.it) is a technology which allows a single high-resolution image to be zoomed and panned around using a JavaScript viewer. This is suitable for panoramas which cover a small range of angles, like panoramas which cover less than 180 degrees horizontally (so that the distortion provided by immersive panorama viewers isn't required). It's also useful for displaying single very-high resolution photos.

Panoramas must be converted with a tool like SaladoConverter into the deep zoom format ready for upload. You can download SaladoConverter for SmugMug here (sourcecode for programmers).

SaladoConverter requires Java to be installed on your computer. If you don't have Java installed yet, then you can install it from http://www.java.com/.

Run SaladoConverter by double-clicking on "saladoconverter.jar". In the window that appears, click "add" to add your panorama image for processing. In the drop-down box at the bottom, set the action to "Single image to SmugMug zoom", and choose an output folder by clicking the "output" button. Then click the "run" button to start processing:

SaladoConverter creates a folder full of panorama fragments, and a text file:

Upload those images the panorama-parts gallery you created earlier:

Open up the text file, you'll see something like this:

<span class='my-panorama' title='{
  pano:"mypan_",
  gallery:"fill your gallery ID in here",
  format:"deepzoom",
  tileSize:512,
  tileOverlap:1,
  width:4608,
  height:4608
}'></span>

Write the ID of the panorama-parts gallery that you found earlier into the "gallery" space:

<span class='my-panorama' title='{
  pano:"mypan_",
  gallery:"19744646_gQ5Hn2",
  format:"deepzoom",
  tileSize:512,
  tileOverlap:1,
  width:4608,
  height:4608
}'></span>

Now you can use this panorama descriptor to add the panorama to your public gallery, check out the next section.

Adding the panorama to your user-visible gallery

From the previous steps, you should now have a hidden gallery full of parts of your panorama, and a panorama descriptor (enclosed by <span> tags). Now you can use that descriptor to publish your panorama in your user-visible galleries.

Create an image which will represent your panorama. I suggest cropping your panorama for this image so that the aspect ratio is much closer to the monitor's aspect ratio. You might also add a symbol on top of the image which suggests that users click on it to view the panorama. Add this image to your user-viewable gallery where you want your panorama to appear.

In the caption of the image, add the panorama descriptor, like so:

My super cool panorama! <span class='my-panorama' title='{
  pano:"mypan_",
  gallery:"19744646_gQ5Hn2",
  format:"salado",
  tileSize:512,
  tileOverlap:1,
  width:4608,
  height:4608
}'></span>

The "span" tag prevents the descriptor from actually being visible in your caption. Once you've saved the caption and reloaded the page, you're done! In your gallery, the image you created will be displayed:

When visitors click on the panorama to view it in SmugMug's lightbox, the panorama viewer will load automatically:

Tweaking the result

PTGui

PTGui's Publish to Website dialog box has a range of options you can tweak to alter the finished result, check out the help file for more details.

SaladoPlayer

SaladoPlayer has been modified to use the same configuration format as PTGui. You can configure it by manually adding parameters to the panorama descriptor in your image's caption. Here's the options which are derived from those in the SaladoPlayer documentation.

minpan: Range: -180 to 0 degrees, default: -180. The furtherest that the camera can pan left, for panoramas which don't span the full 360 horizontal degrees.
maxpan: Range: 0 to 180 degrees, default: 180. The furtherest that the camera can pan right.
mintilt: Range: -90 to 0 degrees, default: -90. The furtherest that the camera can tilt down, for panoramas which don't span the full 180 vertical degrees.
maxtilt: Range: 0 to 90 degrees, default: 90. The furtherest that the camera can tilt up.
pan: Range: -180 to 180 degrees, default: 0. The initial pan of the camera.
tilt: Range: -90 to 90 degrees, default: 0. The initial tilt of the camera.
fov: Range: 0.1 to 179.9 degrees, default: 90. The field of view of the camera.
minfov: Range: 0.1 to 179.9 degrees, default: 30. The minimum field of view of the camera.
maxfov: Range: 0.1 to 179.9 degrees, default: 120. The maximum field of view of the camera.
autorotatedelay: In seconds, default: 30. If the user is idle for this amount of time, start automatically rotating the panorama.
autorotatespeed: In degrees per second, default: 3. The speed of autorotation, or 0 to disable autorotation entirely.
mousedrag: True or false, default: false. Set to true if you want to drag the panorama with the mouse instead of the regular drag-spin action.
buttons: default: ["out", "in", "fullscreen"]. This is a list of the toolbar buttons to display. Possible buttons are "left", "right", "up", "down", "in", "out", "fullscreen", "drag", "autorotation". Use buttons: [] to disable the toolbar completely.