Readme PanoTools:

PanoTools is a collection of free tools for Panorama and 3D Object creation . It consists of:

PTEditor: Interactive Panorama Editor. See the online tutorial here.
PTPicker: Java frontend to panorama stitcher and other tools. It provides a graphical interface for feature point selection and position optimization.
PTStitcher: Panorama stitching tool which remaps, adjusts and combines arbitrary images to panoramic views.
PTStereo: Creates 3-dimensional objects from 2 stereoscopic or more images.
PTInterpolate: Physically valid true view interpolator. Given two images of the same scene taken from different positions, this tool creates views from any intermediate position.
PTMorpher: Morphing tool.
PTAverage: Averages images to reduce noise and enhance density.
PTStripe: Combines images into movie-stripes for viewing in object-viewers.
Panorama Tools: Photoshop and GraphicConverter plug-ins for image correction and remapping.

PanoTools runs on the Macintosh platform (PPC), on Windows (32bit), and Linux.

Installation:

Most of the functionality of PanoTools is contained in the shared library (pano12.lib on MacOS, pano12.dll on Win32, libpano12.so on Linux) which has to be installed where shared libraries belong: On MacOS, drag the file pano12.lib onto the System Folder icon. You system then asks whether to put it into the Extensions folder. Click 'OK'. On Win32, move the file pano12.dll into the directory Windows\System\ .On Linux, put the file libpano12.so into the search path of the linker. This depends on your setup, but probably /usr/lib/ works.

The programs PTPicker and PTEditor are self-executing Java ('jar') files and requires the Java Runtime Environment (JRE) to be installed. This can be downloaded from www.javasoft.com (Win32 and Linux) or www.apple.com (Macintosh). At least version 1.1 is required. PTPicker is invoked by double-clicking the program icon on the Macintosh. This also works on Win32, if the newer JRE 1.2 is installed. On Linux, PTPicker is invoked from the command line in an X-Terminal in the directory where the program resides using the syntax:

    jre -cp ptpicker.jar ptpicker

or, if JRE1.2 is installed:

    java -jar ptpicker.jar

The 'Helpers' directory should be installed unchanged in the same directory as the PTPicker application. The installation of the plug-ins for Photoshop (Only Win32 and MacOS) and GraphicConverter (only MacOS) is described elsewhere.

The Linux version additionally requires the JPEG, TIFF and PNG shared libraries. These are contained in almost any linux distribution.

Working with PanoTools:

Please read the description of the individual programs about specific features and the online tutorial about the use of PTEditor and PTCrypt. In the following, only PTPicker will be explained in more detail.

PTPicker lets you select and edit feature points in pairs of images. These pairs are taken from a list of images comprising a project, which can be a panorama or a 3D-object. The coordinates of the feature points are written to a textfile, which is handed over to one of the appropriate helper applications (PTStitcher, PTStereo, PTInterpolate, PTMorpher). This is transparent to the user, who ideally should not get in contact with these programs directly. Any of the helper programs can be run directly with a rudimentary user interface, scripted via Applescript (MacOS) or run from the command line (Win and Linux).

There are updated examples for Panoramas and Objects on my website. Please download and experiment with the version appropriate for your system (for MacOS, for Win32 and for Linux).

To load images into PTPicker, you need to open or create a project file first. Use one of the examples from the tutorial, one
of your own Panorama Tools scripts, or create a new one. Then you can open a pair of (ideally overlapping) images. For details
of the scripting syntax, see the Examples package.

Control points:

Control points are locations in two images exhibiting identical features. Their coordinates are used by the optimizer to adjust images for stitching. PTPicker displays three types of feature points:

red: selected points
green: deselected points having a counterpart in the second image window
blue: deselected points having no counterpart in the second image window

You can hide blue points using the command 'Show linked points' in the View menu. They are displayed again by clicking 'Show All points'. Color and size of points is settable via Menu options (View->Point Colors/Size).

There are three cursor modes: Setting and selecting points, and only selecting points. You toggle between the modes using
the commands 'Select'/'Set Points' in the 'Edit' menu.

To set points, use the arrow cursor, and click in the front window. The small Lupe aids in placement of the control point. A red dot is set, and simultaneously another red dot appears in the second window (provided there is a second image open). Switch to the second window by clicking it, then click again onto the selected point, and while holding the mouse button down, drag it to the location it belongs.

If you click onto an existing point, this point becomes selected. Selected points are removed by typing backspace, or clicking 'clear' in the 'Edit' menu.

The Select Mode allows you to quickly select one or several points without the danger of accidentally setting new or moving old points. It is useful for setting triangles, see next paragraph.

You can find a control point from the list displayed in the project file by hitting'Find' in the 'Edit' menu, and entering the point number. The corresponding images are automatically loaded, and scrolled to the newly selected and highlighted point.

If a blue point is selected, ie a point having no counterpart in the second open window, only this point becomes highlighted (red). If you switch to the other window, and click at some location, a new control point is created which is now linked to the previously selected point. This feature allows you to link points among more than two images.

Zooming in and out is performed using the respective commands in the 'View' menu. You can revert to the original magnification by hitting 'Normal'. Zooming in automatically improves accuracy of point adjustment, since you can then set control points at fractional grid positions.

Triangles:

Triangles must be set for 3D-objects, but are not required and ignored for panoramas. Triangles are set by selecting three points, and clicking 'Set Triangle' in the 'Edit' menu. PTStereo, PTMorpher and PTInterpolate uses this triangular portion for texture mapping, hence it is only selected in one (the front) window. Triangles are removed by selecting the three corner points and clicking 'Remove Triangle'. Using 'clear' or Backspace removes the selected points together with the triangle which might
not be what you want. Triangles are also removed if any single of the corner points is removed using the 'clear' command.

Triangles are dimmed but still transparent. You can hide the filling using the 'Hide Triangles' command in the 'Edit' window. They reappear after hitting 'Show Triangles'.

There is an option to automatically triangulate all selected points in one (the front) window. Selecting Edit->Triangulate initiates the Delaunay-triangulation. Selecting 'Reduce' rearranges selected triangles according to the Delaunay rules. The option 'Copy Triangles' sets the selected triangles in the second window also.

Menus:

File->Open:
Open existing project file; must be a valid Panorama Tools script. All images belonging to the project must be in the same folder as this script.

File->New:
Invokes Project Editor. Choose output format, lens type, image count and focal length of your lens, and a standard project file for a single row panorama is created. This has to be saved in the same folder as your images. Please note that there are many more options to modify projects, which you can set by editing the project file using a text editor. See the commented example
script 'Optimizer Script' in the Examples package.

File->Close:
Close open project.

File->Save/Save as:
Save Project file with current set of control points/ triangles.

File->Revert to Saved:
Load saved version of Project file. This is required if the project
file has been edited with another program while open in PTPicker.

File->Quit:

Edit->Clear:
Remove selected points

Edit->Select:
Set cursor to cross/ select mode

Edit->Select All
Select all points in the front window

Edit->Deselect
Deselect all points

Edit->Set Point:
Set cursor mode to set points

Edit->set triangle:
Set a triangle comprising three selected points. Complains if there are not enough selected.

Edit->remove triangle:
Remove triangle comprising of three selected points.

Edit->Copy Triangles
Copies the selected triangles into the front window

Edit->Triangulate
Triangulates points in the front window

Edit->Reduce
Rearranges selected triangles

Edit->Find:
Find control point with selected number. Two images are opened and scrolled to the selected point.

View->Zoom in/out
Magnification of image is changed by a factor of 2. Control point size remains unchanged.

View->Normal
Recover original magnification.

View->Point Color
Set color for selected,deselected and single points

View->Point Size
Set size of points

View->Show all Points:
Display linked and single points.

View->Show linked Points:
Display only linked points

View->Show Triangles:
Triangles are filled with grey color.

View->Hide Triangles:
Triangles are not displayed.

Project->View Script:
Launch SimpleText and display Project File.

Project->Optimizer:
Call Panorama Tools optimizer to process Project file. Commands are added for PTStitcher. While optimizing, a progress dialog is displayed. This can be stopped at any time if the fit appears to be good enough. On Linux, Progress is reported in the XTerminal window. Press CTRL-c to interrupt at any time if the fit is acceptable.

Project->Stitcher:
Call PTStitcher to process images and project file. Please see the tutorial and PTStitchers documentation about the many options you have for panorama creation. Clicking this menu option must be preceded by a call to Project->Optimizer, since otherwise no Stitcher commands are added to the project file. This is also required, if the project has been written to disk using the 'save' or 'save as' command, since this also removes the stitcher commands.

Project->3D Stereo:
Call PTStereo to process images and project file. No optimization is required in this case, sinc PtStereo does all the necessary calculations.

Project->Morph
Call PTMorpher to morph the images.

Project->Interpolate
Call PTInterpolate to interpolate the images

Known Bugs:

- On some machines the keyboard shortcuts don't work.

Credits:
=======
The following resources are used in this program:
- I am using Andrew Regan's (ecuue@csv.warwick.ac.uk) ProgressCDEF package.
- Motorola's fast mathematical library 'libmoto' (Copyright © 1996 by Motorola, Inc. )
is linked with the program (Mac only).
- The Levenberg-Marquardt solver of the MINPACK program is used.
- The public domain solver 'PZeros' from D. Bini (bini@dm.unipi.it), available
from Netlib, is used in the program.
- The public domain Fast Fourier Transform package FFTN by Mark Olesen is used.
- The program is linked to the free JPEG-library of the Independent JPEG Group.
- The free TIFF-library (Copyright (c) 1988-1996 Sam Leffler, Copyright (c) 1991-1996
Silicon Graphics, Inc.) is linked to the program.