the Free way

Tutorial Author:
Pete Black

Introduction ==>

Step by Step



3.Camera FOV

4.Scripting PT

5.Invoking PT

6.Viewer applet


Netscape users: due to a bug in the way Netscape renders CSS positioning [within nested <DIV> elements] some links may appear not to be active or not work properly. Rather than re-work the page around this bug, I've included duplicate links where necessary, denoted by a navigator icon, for your convenience, and sincerely hope Netscape get around to fixing this bug in later releases.

Introduction and Background

My interest in panoramic photography was sparked a few years ago when i was working on a website for a helicopter-skiing company. They sent us a really cool panoramic photograph that someone had taken from the summit of Mt. Everest. Needless to say, this was pretty impressive, supplied as it was on 2 rolls of paper about 1.2m x 40cm long

Thinking it would be cool to try and get something like this on the website, I looked at ways to create a panorama. This was before the advent of companies like IPIX, LivePicture, Smoothmove and others, and it seemed the logical way to do it was by simply mapping the images onto a cylinder and letting the viewer rotate the cylinder to see the view as it turned.

This was fairly easily accomplished using VRML. I made a 12-sided polygonal cylinder, cut each image into 6 equal-sized pieces, planar-mapped each image tile to one of the cylinder's polygons and made a little button to spin the polygon when the viewer pressed it.

This worked pretty well, and was a neat toy.

About a year and a half later, I was working as a web developer for an ISP when my boss dropped a package called 'LivePicture PhotoVista' on my desk and told me to look at it and see if it would be any use to us. I immediately installed it, broke out the digital camera, and after about an hour, had our office spinning around on my screen.

This too, was very cool. The most exciting thing was that Live Picture provided a Java-based viewer which completely removed the hassle I had had with people trying to view my previous panorama and complaining that they needed a VRML plugin.

Basically i was sold, and we bought the software, and made various panoramas of various things for various clients.

I quit my job some time later, since management basically sucked, but my interest in panoramic stuff remains. Now I work part time as a sys admin and general geek for a web design company while I concentrate on my 3D animation, with hopes of making graphics for games etc. at some point.

Now, this place is a Mac shop, and I had left all my LivePicture stuff back at my previous job. An opportunity came up recently to do some panoramic photography of the inside of a hotel and I thought to myself 'There must be a way to do this stuff for free.' So, a quick Google search and bingo, there was a link to Helmut Dersh's Free Panorama Tools. "Yeeah, this looks like the stuff", I thought to myself and proceeded to download the docs and code.

What I found was that the documentation supplied with the tools was not the best for a casual user, and I had to spend practically a whole day trying to figure out how to use the tools to do what I wanted. So, after seeing a discussion on I offered to write a tutorial on how to put together cool 360 degree panoramas using these tools. Here it is.

How to make Panoramas using the Free Panorama Tools by Helmut Dersch.

I'd just like to take the opportunity to thank Helmut for all his work, and his willingness to release the software for free. The world needs more people like you, Mr. Dersch.

[Works fine with Graphic Converter for the Mac too. KW.]

This tutorial is unfortunately restricted to those of you who use Photoshop, as the version of the GIMP I got with Redhat 5.2 refuses to work after I upgraded to the lastest gtk/glib. I will recomplie it one day, and extend this tutorial to cover the GIMP specifically. It should be broadly applicable, however, so give it a try. I welcome additions and modifications by others. I use Windows 95 for this tutorial.

Step 1 - The Photographs

The first thing you will need to obtain are a set of photographs of your location.

These should be a set of photographs, taken from a central point, equally spaced. I consider a decent tripod to be mandatory for this type of thing, but it is possible just to stand there, turn a bit, snap a pic and do that till you're back facing the same way.

tripod diagram

Make sure the camera stays level, and make sure the pictures you take overlap each other by at least a little bit. I usually take 12 images for each 360 degree panorama, at 30 degree spacing.

HANDY TIP - I marked my tripod around it's base by cutting a little strip of paper the length of my tripod base's circumference and marking 12 equal divisions on it. I then wrapped the paper around the tripods base and stuck it on with tape. Instant calibration! this works great, and while not 100% accurate is more than good enough for our purposes.

You can use any standard camera, but a digital camera is best since you don't need to tediously scan images that have to be developed.

Snap your 12 pictures, and save them to your hard drive, making sure you name them in a consistent manner. I use something like pic001.jpg, pic002.jpg, pic003.jpg....

HANDY TIP - Put these pics in a separate folder. This will save frustration when you attempt to use Photoshops 'Batch' Action mode later on.

OK, thats it. you now have a set of photos ready to turn into a panorama.

Step 2 - Install the software

This bit is easy, and if you already have the Panorama Tools installed, you can skip this section. Grab the version of the plugins from Helmut's site, and install them on your platform as per instructions in the file. For Photoshop this simply involves copying the .8bf plugin files to a location Photoshop recognizes as containing plugins.

Step 3 - Find the Horizontal FOV (Field of View) of your camera

[There's a tutorial on that too, but I can't remember where??? KW.]

I'm not sure on the exact method for determining this mathematically, but a standard digital camera seems to have a FOV of abour 40-50 degrees. assume 45 for the moment, you can see after we create a panorama if it looks wierd, and tweak this value till it is correct.

HANDY TIP - LivePicture's PhotoVista has a library of common digital camera lens settings built in ,so you might want to download the free demo and check your cameras settings there.

Step 4 - Write a script file for Panorama Tools

Navigator users linkexample of a script file

[For the full spherical pano, I adapted this script to fit my wobbly freehand images. It is designed for a tripod mounted set with 5 rows of 12 images (80, 40, 0, -40 and -80 degrees). KW.]

Navigator users linkStep 1

Navigator users linkStep 3

This sounds more daunting than it is. Here's an example of a script file for the settings above. You can tweak this to your preference, by following the docs supplied with Panorama Tools.

Save the file somewhere on your system (i just leave them on my desktop) and call it 'panorama.scr'

That's it. The script is pretty simple to follow, p sets the panorama type (we'll leave it at the default setting) and the width of the final panorama, which we'll say should be 800 pixels. f0 just means we're dealing with rectangular images from a normal camera, r and p are the roll and pitch values for each image (should be 0 if the camera is level) y is the rotation around the vertical axis (each one corresponding with the angle the camera was set to on the tripod for the pictures taken in step 1). v is the Horizontal FOV we guessed was 45 in Step 3.

OK, thats it. Lets make a panorama.

Step 5 - Invoking the Panorama Tools plugin

We'll start by doing this the hard way. We will manually process each image with the panorama tools plugin.

Open Photoshop, and load up the first image, in this case pic001.jpg.

Go to the menu 'Filter'-> 'Panorama Tools'-> Adjust.

A dialog box will open, and several options will be presented. Don't worry about them, and just click the 'Insert' radio button, and the 'Use Script' radio button. Then click 'Browse' and give Panorama Tools the location of the script we made in Step 4.

Now click 'OK'

Panorama Tools will do its magic, and warp the image so it will fit on our panorama. The image will change to reflect this, but just close that image, as the pixels are stored in a buffer in memory.

Repeat for each image i.e. open it, run the 'Adjust' filter on it (you don't need to re-select the script each time) and close it.

After you have done all 12 images, you are left with a blank screen. 'Great', you say, 'a blank screen. Thanks a lot Pete.'

Open a new image, 800 x 400 pixels in size, and go to the menu 'Filter'->'Pan Controls'->'Get Pano' and your panorama should appear in all its glory in this new image. Panorama Tools has just copied it's memory buffer to the new image. It will likely have large borders on the top and bottom, which we will leave on for the moment, as it makes it easier for the viewer applet to deal with.

Save this image out as a JPEG file in the folder you intend to set up your panorama for viewing. For this example, we'll call it 'roompano.jpg'

HANDY TIP After Panorama Tools has processed a script, you will find you will have to go and replace the '#' symbols it has replaced the original 'o' symbols with. If you only get halfway through processing a panorama, you will have to go back to the script file and make sure the 'o's are back in it, or else Panorama Tools will get confused as to which image it is supposed to start from.

Actions and Batch Mode Photoshop 4 and above have had the facility to automate your work with 'Actions'. To make an action so you don't have to repeat the process of adjusting each image, take the following steps.

On the Actions palette, click the 'new' button. Call this action something intelligent. I call mine 'make pano'.

While the action is recording, open the first image, Go to the menu 'Filter'-> 'Panorama Tools' -> Adjust, click 'OK', let Panorama Tools do it's thing, then close the file.

Click the 'Stop' button on the actions palette and that's it. You have an action you can use in 'Batch' mode to automatically process all the files in a folder using your script (remember you have to replace the '#'s with 'o's each time you make a new panorama though). Click the action you just made, but don't run it. Click the little triangle on the 'Actions' palette and select 'Batch...'. Select 'Folder' for the 'Source' setting, and click the option button forcing the Action to 'Override Open commands'. Leave 'Destination as 'None' and click 'OK'. Woohoo! Photoshop automatically processes each file in turn, adds them to the pano and closes them while you go away and drink coffee.

Follow the 'Get Pano' step above to get the pano to a new file and save it as above.

Step 6 Set up the Viewer Applet

The easiest, most cross-platform way to get your panoramas up on the web is to use Live Picture's free Java applet. Live Picture is to be commended for releasing such a useful piece of software for free.

Grab the Java Viewer archive from the Live Picture website. Place the relevant files in the same folder as your panoramic JPEG:

There will be an example HTML file in the docs which is extremely handy to make sure all the browsers show the panorama correctly. I will list it below for completeness. Cut and Paste the text below, and save it as a file called 'index.html' in same folder the panoramic JPEG and the Java Viewer applet are saved. The options are covered in the documentation, and should be pretty self-explanatory.

[There seems to be a missing opening APPLET tag, but as Pete says, this is the sample file straight from the Live Picture docs. I modified the code on my spherical pano page somewhat, view the source here. KW.]

--------cut here-------------------

<BODY BGCOLOR="#000000">
<script language="JavaScript">
var myBrowser = navigator.appName;
var myVersion = parseFloat(navigator.appVersion);
if (myBrowser == 'Netscape' && myVersion < 4.0)
document.write('<applet archive="" code="LPPano.class" width=320 height=200>');
document.write('<applet archive="" code="LPPano.class" width=320 height=200>');
<PARAM name=cabbase value="">
<PARAM name=file value="./pano.ivr">

--------cut here-------------------

The Java Viewer works by reading an .ivr file, which tells it where to find the panorama image for it to display, and also how the Panoramic image is configured. An .ivr file is really a VRML 2.0 file, and the Java Viewer is a type of VRML browser.

I don't think the Java Viewer currently supports VRML geometry as well, but it may do in the future.

Navigator users linklike this

[The ivr file used for the spherical pano is here. KW.]

[If you have named your jpg source file differently, you will need to change the source image file name in the .ivr file as well.]

The .ivr file should look like this. Save it as a file called 'pano.ivr' in the same folder the panoramic JPEG, the Java Viewer applet and the 'index.html' files are saved.

The only things you might want to edit in this file are the 'vFov' and the 'pitchRange' value. The pano we just created is basically just a 'strip' of images, and the top and bottom of the file are black.

If your file looks vertically compressed or expanded, you can play with the vFov setting (set it lower than this, say -0.5 0.5, and watch the effect it has). make sure pitchRange is not higher than vFov (if you set vFov to -0.5 0.5, then set pitchRange to -0.5 0.5 as well), this just restricts the viewer from panning too far vertically i.e. so you cant look up too far and see just the black pixels.

OK, if youve done all of this correctly, you should be able to load up 'index.html' in a web browser, the Java Applet will fire up and your panorama will be displayed in all its 360 degree glory. Take care to check for case sensitivity issues, as this can be a problem when mounting content to a *NIX server from a Windows environment.

In case of problems, you should have the following items in your folder:

If you are experiencing problems, it is most likely your .ivr file that isn't set up correctly. Cut 'n' Paste the example .ivr above and it should work.

Tweak the settings in the various parts of the process till you get a set that precisely match your camera, and you'll be making panoramas for free in no time. Panorama Tools also has numerous tools for correcting lens distortions etc., which i haven't covered here. Perhaps in the future.

I hope you find this little tutorial helpful, I will add to it as time allows.


Navigator users linkpeterb

[Additional comments, layout and CSS by KathyW.]

Created and maintained by Pete Black
Version 1 - 31 May 1999