Putting Panoramas and Object movies in a web page

Once you have created some panoramas by far the easiest way to publish them is for someone else to do all the work for you - once you are registered and logged-in to panoguide, you can upload panoramic images and this website will do the hard work for you. If you have your own website, this page gives you an overview of the process of adding your panoramic images to your pages.

Choosing a "viewer" to use in the web page

It is important to realise that the software you use to create your panoramas or object movies with will not necessarily create the web page for you. Also you will need a different piece of software - a "viewer" to display the panorama in the web page. This "viewer" need not be from the same company as the software you used to create your pictures and movies

All viewers need two things: (a) the image itself, and (b) metadata information about the image, such as whether it is 360 degrees wide or less than that, whether the image file is cylindrical or spherical projection, etc.

Special file formats such as QuickTime VR (.mov) and ImmerVision's Open Panorama format (.ivp) contain all the image data and the metadata in one file. The advantage of a special file format is that the web page code is generally simpler. Also QuickTime VR movies can also be opened in QuickTime Player (no web page required) so can be emailed to friends or colleagues, and put onto CD or DVD.

Viewers that do not use special file formats require you to supply the metadata in the HTML page where you add the code to make the viewer appear. (Some viewers make it also possible to put the metadata into a separate text file.)

If you are not confident creating or editing web pages, you may want to start by using QuickTime or ImmerVision's Open Panorama format. Most image stitching software supports QuickTime VR (although not necessarily all the advanced features of QuickTime). The OpenPanorama format is open source but the easiest way to create IVP files is using ImmerVision's inexpensive PURE Starter Toolkit, which creates panoramas ready for ImmerVision's PURE Player.

Otherwise, the main thing that should influence your choice of viewer is what you want it to look like. For both objects and panoramas you will probably want to think about the functionality you want: do you want to create hotspots to link panoramas and objects together into a virtual tour? Do you want to include music or sound effects? Do you want those sound effects to be directional?

Do I need to buy any special additional software?

You don't have to. If you want to use QuickTime VR and your stitching software doesn't support it, or maybe doesn't include all the features you want, then you might want to buy additional software for this. You may decide you like ImmerVision's PURE Player and to make your work easier you may decide to purchase the PURE Starter Toolkit. But no, you don't have to buy anything extra. It depends on what you want to do. All the viewers themselves are free - but it is up to you to decide whether additional software will make creating the panoramas or web pages easier.

Note you can convert a panoramic image to QuickTime VR using a variety of tools including GoCubic.

Complicated HTML: Plugins, ActiveX Controls and Java applets

Before we dive into some code examples, we need to briefly explain what is meant by plugins, ActiveX controls and Java applets, and why we have so many ways of including rich content in web pages.

Netscape created the idea of a web browser plugin or helper application back in the 1990s - an additional piece of software that you install which adds functionality to the web browser. Microsoft decided to add a different way of doing the same thing: the ActiveX Control. Plugins are generally not self-installing, whereas an ActiveX control will attempt to automatically install itself, so the end user doesn't have to do anything except say 'yes' to get the additional software.

However, ActiveX controls only work in Microsoft's Internet Explorer for Windows. Also starting in Internet Explorer version 5.5 SP2 for Windows, plugins are no longer supported, only ActiveX controls. The HTML tag used for plugins is <EMBED> and the HTML tag for an ActiveX control is <OBJECT>. Fortunately by putting the <EMBED> tag inside the <OBJECT> tags, you can create a web page that works on both Netscape and Internet Explorer browsers.

In 2006 Microsoft lost a patent infringement dispute with Eolas Technology and was forced to modify the way ActiveX controls work in Internet Explorer. Today ActiveX controls will display a small "click to activate" message when they first load in Internet Explorer. For example, if you display a QuickTime VR movie, you have to click once to activate and then you can click and drag to look around the scene. If you want to prevent this happening you have to use JavaScript in the web page to generate the required HTML dynamically. Apple have published QuickTime Eolas workaround code and a tutorial on how to do this for QuickTime movies.

So what about Java? Not all web browsers have built-in Java applet support. The version of Internet Explorer supplied with the first version of Windows XP did not include Java (but subsequent versions do). Mozilla and other web browsers require you to install a Java Runtime Environment (JRE for short) of your own, such as from java.sun.com.

Example: QuickTime VR in a web page

This example is based on the example from Apple's Developer connection article. Let's assume you want to publish a QuickTime VR movie in a file called frontroom.mov:

<script language="JavaScript" type="text/javascript">
  QT_WriteOBJECT_XHTML('frontroom.mov', '320', '256', '',
    'autoplay', 'true',
    'emb#bgcolor', 'black',
    'align', 'middle'); 
</script>
<noscript>
	<object classid="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B" 
	width="320" height="256" align="middle"
	codebase="http://www.apple.com/qtactivex/qtplugin.cab#version=6,0,2,0" >
		<param name="src" value="frontroom.mov" />
		<param name="autoplay" value="true" />
		<embed src="sample.mov" width="320" height="256" 
		pluginspage="http://www.apple.com/quicktime/download/"
		align="middle" autoplay="true" bgcolor="black" > </embed>
	</object>
</noscript>

For this to work you need to get yourself a copy of the JavaScript library AC_QuickTime.js from Apple and add it to your page in the "head" block as shown below. For more information see the full instructions on Apple's website.

<script src="AC_QuickTime.js" language="JavaScript" type="text/javascript"></script>

Note I have included a <noscript> block above so that someone with JavaScript switched off can still see the panorama, but if they are using Internet Explorer they may be asked to "click to activate" the control before they can use it.

In Netscape web browsers this only works if QuickTime is installed. If it is not, a grey box or an empty box with a broken plugin symbol is displayed. Some web browsers will prompt the user immediately to download the plugin, but generally this will not happen unless the user clicks on the empty space where the QuickTime movie should appear.

For more information about QuickTime on Web sites, see: QuickTime for the Web, published by Morgan Kaufmann Publishers (see http://developer.apple.com/techpubs/quicktime/qtdevdocs/
QT4WebPage/QT4WebBook.htm
)

You can also publish a QuickTime VR movie using PTViewer (java), Flash or DevalVR.

Using Java

Although everyone using an Apple Mac will have QuickTime installed, not everyone on a Windows PC will. If, for example, you publish your panoramas using the QuickTime viewer, you risk alienating some people who do not have QuickTime and perhaps they do not know how to, cannot or choose not, to install the additional software. (There are many reasons why someone might not be able to install it, such as being on a corporate network and not having administrator privileges to be able to install software.)

This is where Java applets come in. Well, more-or-less. As mentioned above, not everyone will have a Java Runtime Environment installed on their computers - many people do, but not everyone. For those people that are Java enabled, the Java viewer you use will be automatically downloaded to their computers and executed to display the panoramic image.

I have created my own eolas-workaround APPLET JavaScript (right-click or CTRL-click and select "save as") based on the article from Apple mentioned above. The code used on panoguide for displaying panoramas using Pure Player is similar to this:-

<script type="text/javascript" language="JavaScript">
writeAPPLET_HTML('PurePlayerPro', '100%', '100%', 
 				    'archive', '/code/immervision/PurePlayerPro_107.jar',
 				    'panorama', 'frontroom.xml',
 				    'lockzenithnadir', 'true',
 			    	'optimizememory', 'true',
	 			    'singlepanorama', 'true');
</script>
<noscript>
	<applet archive="/code/immervision/PurePlayerPro_107.jar" code="PurePlayerPro" 
	width="100%" height="90%" mayscript>
		<param name="panorama" value="frontroom.xml"/>
		<param name="lockzenithnadir" value="true"/>
		<param name="optimizememory" value="true"/>
		<param name="singlepanorama" value="true"/>
	</applet>
</noscript>

Strictly speaking the <applet> is deprecated but Sun recommend to still use the deprecated <applet> tag because the specification for the object tag is vague and the way different web browsers implement the tag is inconsistent. For more information see Sun Java plugin: using tags. Also I found that when using the <object> tag, I cannot use percentage width and height. I am of course talking about setting the width and height to "100%" - I have found this works with an <applet> tag in all web browsers but not with an <object> tag.

There is one more problem with using Java. Some browsers (notably Netscape/Mozilla) have memory limits which prevent large images being used. Various viewers use work arounds to allow high resolution panoramas to be displayed beyond the limit, but you should watch out for 'OutOfMemory' errors whenever you publish very large images. ImmerVision's PURE Player, used on this website, uses particularly good memory management and can display large images quickly. PTViewer can also avoid the problem by similarly splitting the image into smaller sections.

Making sure it works for everyone

If you want to be sure your panoramas can be viewed on the maximum number of computers, with or without QuickTime, with or without JavaScript or Java, you need to consider making your panoramas available in multiple formats/viewers and either giving your users a choice, or using JavaScript to attempt to detect what they have installed on their computers. That is beyond the scope of this article and is described elsewhere on the web:

Pure HTML: No plugins, no JavaScript

You can easily create a (fairly crude and unsophisticated) way of viewing panoramas without any viewer involved just using a popup window (requires JavaScript) and/or an IFRAME. For simple panoramas this works quite well. Here is a simple example that uses an IFRAME in this web page to display a panoramic image with a scrollbar.

Note that this works quite well for panoramas with a fairly narrow vertical field-of-view but wider angle panoramas will look a little strange as the curves in the equirectangular image are not perspective corrected when displayed like this.