Using PTools

If you have a set of images on your hard drive try this:
Theoreticaly you could proceed like this: open one image, process it with the your settings in the Create Panorama Options. Close the image and proceed with the next image. Each time an image is processed, PTools internal buffer is updated with another piece of your final panoramic picture. When your have added all your component images to the panorama you are building, select Filter - Pan Controls - Get Pano. An image will now open showing the result.

How can I know how to set the parameters in the Create Panorama dialogue?

First of all you will notice that often you dont know the exact parameters for many of the fields in the Create Panorama dialogue window. Probably you don't know exactly the yaw because you have no protractor on your tripod. And even if you had, there is always some inaccuracy with setting the pitch and roll. Maybe your lens produces some barrel or pincussion distortion that is not noticeable visually.

For this reason PTools can find the missing parameters and uses a concept that many other stitching programs use: corresponding features (or controlpoints). From the overlapping area of two images the user places corresponding controlpoints on the locations of distinctive features in both images showing the same 'object'. PTools requires to be given the coordinates of these locations in its own variety of script.

E.g. a line c n0 N1 x374 y554 X58 Y560 in a Ptools stitcher script means that a control point with coordinates (374,554) in image number 0 has coordinates (58,560) in image number 1. Given this information PTools can derive pitch/roll/yaw and even the degree of barrel/pincussion distortion in the lens. You just need to ask PTools using a v-line - this is a script line where you tell PTools what unknown variables - yaw, fov etc you want it to solve for.

You give the program the control point information in c-lines There are currently three ways to generate a c-line:

  1. Open the Info window in Phototshop (or whatever) and write down the displayed coordinates by hand.
  2. Use the PTools Pixel Picker
  3. Use PTools 'Read Control Points' command which is described now.
Helmut Dersch has prepared an image file which contains a set of control point markers whichyou can copy and paste into your source images. A five times enlarged control point looks like this:
The more control point markers you place on your image the better PTools will optimize parameters. See the example pictures with 12 controlpoints (50% reduced).
A cutout of the image (original size):

This is how to get PTools to scan your images for contol points: Create a text file with a text editor but leave it blank. Save it in your working directory as control.txt. Open the first image which has been marked with the control point markers (it has to be an single layer image - flattened), then select Filter - Panorama Tools - Adjust. In the Create Panorama dialogue select Read Control Points and Use Script. Press Browse and select the file control.txt in your working directory. Back in Create Panorama Press Ok. Within a second PTools has scanned the image for control point locations and added the following lines to your control.txt:

c n0 N-1 x374 y554 X0 Y0
c n0 N-1 x363 y483 X0 Y0
c n0 N-1 x363 y334 X0 Y0
c n0 N-1 x372 y230 X0 Y0
c n0 N-1 x369 y113 X0 Y0
But leave control.txt closed and open the second image. Again select Filter - Panorama Tools - Adjust. Since PTools remebered the previous settings just click Ok. control.txt now looks like this:
c n0 N1 x374 y554 X58 Y560
c n0 N1 x363 y483 X44 Y488
c n0 N1 x363 y334 X43 Y335
c n0 N1 x372 y230 X54 Y230
c n0 N1 x369 y113 X54 Y109
Now you are done with reading the control point locations. Now you will run the Optimizer to find out e.g. the pitch, roll and yaw. Add the following lines to control.txt.
p w600 h300 v60
i w480 h640 f0 v42 r0 p0 y0
i w480 h640 f0 v42 r0 p0 y30
The lines beginning with i means you want to tell PTools some information about your pictures, which you more or less know. Image width/heigth is 480/640 (w480 h640). The source images are rectilinear (f0). The HFOV is 42 degrees (v42). The roll/pitch/yaw is 0/0/0 in the first and 0/0/30 degrees as far as you know. Adapt the lines to your image properties.

Because you want to know about the roll/pitch/yaw that happened to your camera before taking the second image (which is image number 1 for PTools) you add the line

v r1 y1 p1
Now save control.txt and close it, then select Filter - Panorama Tools - Adjust. In the dialogue Create Panorama select Run Optimizer and Use Script. Press Browse and select the file control.txt in your working directory. Back in dialog Create Panorama click Ok. Among other lines PTools adds the following to your text file:
# (*) - optimized         (p) - preset
# Image No 0:
# Yaw:	0 deg (p)	Pitch:	0 deg (p)
# Roll:	0 deg (p)	HFov:	42 deg (p)
o f0 r0 p0 y0 v42 -buf

# Image No 1:
# Yaw:	28.0078 deg (*)	Pitch:	0.114398 deg (*)
# Roll:	0.841227 deg (*)	HFov:	42 deg (p)
o f0 r0.841227 p0.114398 y28.0078 v42 +buf
This would be the information you need to know to fill in the fields for the parameters in the dialog Create Panorama Options. You might repeat the process of placing control points, let them be scanned by PTools, ask for parameters and then fill in the dialog Create Panorama Options. Quite roundabout you might say. But there is a better way.

Using scripts

You might have seen that the Optimizer has generated lines beginning with o. These gives the same information that can be set in dialog Create Panorama Options. Instead of having to enter the parameters the program has found for each image one image at a time and building the panorama that way the program has generated a script which can automate the process. The illustration below shows tha analogy.
Instead of using the dialog and building the panorama one image at a time you can use a script with one p-line and as many o-lines as you want images to be inserted. Imagine you have a set of six pictures and the Optimizer found the pitch/roll/yaw of each image and generated o-lines. Knowing the HFOV of your lens you write the following lines into a text file:
p v360 f2 w600
o f0 r0.873   p0.174    y0.735    v90        -buf
o f0 r0.564   p0.623    y90.992   v90  +buf  -buf
o f0 r0.651   p0.524    y180.194  v90  +buf  -buf
o f0 r0.663   p0.552    y270.362  v90  +buf  -buf
o f0 r-89.02  p90.91    y0.112    v90  +buf  -buf
o f0 r90.154  p-90.38   y0.834    v90  +buf
The first line means a 600 pixels wide spherical panoramic image is desired. Save the text file as script.txt and close your text editor. So after you have created a script you can stitch your panorama thus: After you have created a script, there are currently two ways to stitch your source images to one single panoramic image:

To sumarize...

The process of creating panoramic images with PTools can be described as follows:
  1. Write a script containing one p-line - what kind and size of target panorama do you want.
  2. Insert as many i-lines (information about the images) to the script as you have source images are to be processed.
  3. Place control point markers and image numbers in your source images.
  4. Let PTools scan these control point markers and generate c-lines (which tell the program the locations of the corresponding control point markers).
  5. Add a v-line (to tell the program what parameters you need to find) and let the Optimizer generate o-lines for you (which tell the program how to build the panorama with the values it has Optimized for each image).
  6. Open each source image in and let PTools run your script - or use the PTStitcher instead with no scripting.
  7. Finaly it is agood idea to sharpen your final panoramic image.
With step two, three and four you can use the PTools Pixel Picker instead of using Helmut's control point markers for generating the c-lines as mentioned before.

What is 'stitching by hand'?

If you are just interested in cylindrical panos, there is an easy way: the remap command can distort your images corresponding to the HFOV of your lens (if you own a fisheye lens you can even create spherical panos with this method). The distorted images can then be copied into one multi layer image and 'moved by hand' until they fit together. That is, yaw is applied by hand. Note that pitch and roll should be avoided when photographing - so use a tripod! See an example of two images stitched together (taken in Vienna where I live):
Open your first image, correct barrel/pincushion distortion as far as possible (with the Correct tool). Then select Filter - Panorama Tools - Remap. Select the HFOV and Convert from Normal, Convert to QTVR Panoramic (note that the VFOV is ignored in this case). The distortion will now be applied to your image (depending on your 'Prefs' an new image is opened or not). Repeat these steps with your second image. The images should now look like this:
Select the entire image and copy both into one new much wider image (in a single layer each). With the magic wand tool (tolerance set to 0 pixels) select the black areas in the upper layer and just delete them. Move the upper layer until the edge fits to the lower layer.
Finally just crop the image to remove the black area. This process sound quite easy but it has its difficulties as well:
  1. If you did not select the correct HFOV, the edges of the component images will probably not fit.
  2. If you did not correct the barrel/pincushion distortion since you do not know the radial factors the edges will probably not fit.
  3. If you did not use a tripod, the edges will probably not fit once more. Try to rotate or transform the layer in this case.
  4. If your camera has no exposure lock, a seam will be more or less visible (see my example). The Adjust command provides color correction in this case. You might try to correct the color balance with your image editing program, which is fairly difficult with more than two layers. Another possibility to solve this problem is to switch to quick mask mode and use the gradient tool to select an area as shown here (lower layer is invisible).
    Then switch to standard mode and press delete. If you make the lower layer visible again you will see that the upper layer is faded out, which gives a soft seam.
  5. If you want a 360 degree pano it should wrap around correctly. Then you must cut one of your images in two pieces and use them as border images (left and right border). You can test if the right and left edges fit together when the flattened image is wrapped around: In Photoshop use the Offset filter with the option wrap around selected. Select a horizontal offset of e.g. 100 pixels. If you can see an misalignment like in the image below, your image is sheared. Try to find out how many pixels the vertical offset is (e.g. by selecting one strip and move it vertical with the cursor buttons - count how many times you depressed them). After you found out, close your unsaved image and reopen it. Then select Filter - Panorama Tools - Correct. Use the Shear option and set a vertical shift of twice the number of pixels you counted before. If you have done everything right, you can apply the offset filter again, but no seam will appear this time.
    Try to find out how many pixels the vertical offset is (e.g. by selecting one strip and move it vertical with the cursor buttons - count how many times you depressed them). After you found out, close your unsaved image and reopen it. Then select Filter - Panorama Tools - Correct. Use the Shear option and set a vertical shift of twice the number of pixels you counted before. If you have done everything right, you can apply the offset filter again, but no seam will appear this time.
Peter Murphy describes the creation of a spherical pano with 'stitching by hand' in one of his
articles, but as mentioned before a fisheye lens is required.

How do I produce a QuickTimeVR file?

The QuickTime file format is commonly used in multimedia editors such as Macromedia Director or iShell. QuickTime files can be embeded in HTML-files using the embed tag. It supports pictures, movies and cylindrical panoramic images - so called QuickTimeVR movies. If you have created a panoramic image (with cylindrical projection), you need to convert it to the QuickTime fileformat with Apples VRMakePano, a converter which is available for free at this URL:

Note that QuickTime 3 or higher has to be installed on your computer. The image width should be divisible by 24, so scale it carefully before sharpening your image. Then the panoramic image must be rotated 90 degrees counterclockwise from its normal orientation, so that the image is taller than it is wide. Start VRMakePano and select Test - Make Pano Movie. When the Open dialog appears select your panoramic image and click OK - an open dialog appears again, where you can select a mask for hot spots, but click Cancel this time. A Save as dialog appears twice, where you enter the name of the tile file (this is just a temporary file which is deleted afterwards) and your final QTVR movie file. As far as I know VRMakePano can only create full 360 degree QTVR movies. If the HFOV of your pano is less than 360 this will look somewhat strange since the pano is wrapped around anyway. But QTVR supports panos with any HFOV (less or equal to 360). Let me know if you know a solution for this problem.

How do I get my Live Picture ZoomIt file?

The Live Picture ZoomIt technologie displays cylindrical and even spherical panos. It is more easy to handle since you do not need to convert your panoramic image. Your image is simply embeded in an ivr-file looking something like this:
#VRML V2.0 utf8

Viewpoint {
   fieldOfView    .5
   orientation    0 1 0 0

   type "SPHERE"
   filename "my_pano.jpg"
   vFov -1.6 1.6
   pitchRange -1.6 1.6
If you have an cylindrical pano set the type to "CYLINDER". You then need to reduce the vFov and pitchRange to +/- .5 or less. ivr-files can be viewed with Live Pictures free ZoomIt viewer, which can be downloaded at the
Live Picture website. Since it is Java based it is platform independend. You can embed ivr-panos using the applet- and param tag. A native code plug-in Version is available for Macintosh and Windows.

As mentioned before the PTStitcher can create the ivr-file for you. Basically you just need to modify the p-line correspondingly. Consult the PTStitcher documentation.

<< Introduction Comments welcome: Sascha Kerschhofer Reference >>