Historical:Panotools plugins Readme

Editors Note

Warning! This text was published in 2000 and probably written even earlier. Some termes might not be used in the same context as we use it now. It is provided her as the original source for Panotools plugins documentation. For an up to date description see Panorama Tools Plugins.

The text of the links mentioned in the document was left as in the original. However, when you click them you get directed to a page on a mirror.

Version Notes

 Readme Panorama Tools for Macintosh/ Windows/ Linux

Notes to version 2.1:
=====================
o GraphicConverter version updated for new Plugin interface.
Now requires at least GC version 2.8

Notes to version 2.0.b1/2:
=========================
o Seamer rewritten. Performs faster on large
images and yields better results.

Notes to version 2.0.b0:
=======================

o Tiff-writer for temporary files corrected (Only non Photoshop
  hosts for Photoshop plug-in affected).
  
Notes to version 1.9.2:
=======================

o Correction mode for scanning cameras (PanoScan) added.

Notes to version 1.9.1:
=======================

o Adjust Tool accepts 'PSphere' images as input

o Bug fixes regarding Photoshop file creation.

Notes to version 1.9.0:
=======================

o Scaling function in 'Correct'-menu changed: If one
  of width/height is set to 0, aspect ratio is preserved.

o Some compatibility problems with PTStitcher/PTOptimizer
  solved.

General Features

 General Features:
=================

Panorama Tools is a free program which can be used to 
generate, edit and transform many kinds of panoramic images. 
Its five main functionalities are:

o Correction of images. 
  Automatic cropping of images to brightest rectangle.          
  Remove all sorts of barrel and/or pincussion distortion.
  Correct light fall-off at edges of your wide angle shots.
  Correct chromatic errors (colour separation) of your lens.
  Correct chromatic errors (colour separation) of your scanner.
  Skew/Unskew your images horizontally or vertically.
  Correction of scanning slit cameras
  Fourier Transform Filtering/Wiener Filter                                                                                                                     
  
o Perspective Control
  Simulates a shift lens in software
  For normal and fisheye lenses
  
o Remap from any projection to any projection
  Warp and unwarp normal, panoramic and fisheye images.
  Convert equirectangular LivePicture panos to QTVR-panos and vice-versa
  Convert mirror images (BeHere-setup or similar) to any panorama and 
  vice-versa. Convert fisheye images to any panorama and vice-versa
  Unwarp panorama sections (QTVR and LivePicture) to edit in Photoshop, then 
  rewarp and seamlessly insert back.
  
o Adjust images into a panoramic view
  Generate full panoramic view using any mixture of normal, fisheye
  and panoramic images.
  Built-in optimizer to find optimum pitch/roll/yaw for a given image           
  to fit a panorama
  Built-in optimizer to find optimum correction settings for a given image.
  Built-in stitching tool to automatically merge images into a panoramic    
  view.
  Automatic colour adjustment of to be merged images
  Extract any view (normal/fisheye/panoramic) from any                          
  panorama (RealVR/QTVR/rectilinear)                                            
  Insert any image (normal/fisheye/panoramic) into any                          
  panorama (RealVR/QTVR/rectilinear)                                            
  
o Realtime Panorama Editor      (only Photoshop/Gimp version)                           
  The realtime Panorama Editor is a separate Plug-in which
  makes the Photoshop window an editable VR-viewer. You can pan
  left and right, tilt up and down, and zoom in and out. At any
  time you can use all Photoshop/Gimp tools to edit the image and
  instantly apply the changes to the warped panoramic image 
  while keeping the interactive window open. This can be done
  with any view ("camera") and any panorama (see 'adjust' above).
  
  

The latest version is alway available from my website
<http://www.fh-furtwangen.de~dersch>. There is also some 
documentation and a few example panoramas.

Requirements and Installation

Windows

Requirements and Installation:
==============================

Windows:
========

A Photoshop compatible plug-in host running under 32bit-Windows
is required. Installation:

- If you have a previous version of Panorama Tools: Remove 
  all plug-ins (the files 'correct.8bf', 'adjust.8bf', 'perspect.8bf'
  and 'remap.8bf'), the library file 'pano12.dll' and all preferences
  files ('pano12.prf' for the most recent version). The current
  version generates just one preferences file 'pano12.prf'.
  Panorama Tools may crash if it loads an obsolete preferences file.
  
- Place the file 'pano12.dll' into the same directory as the 
  Photoshop program (or your plug-in host). If you use PTStitcher
  and/or PTOptimizer together with Panorama Tools, you should place
  the library 'pano12.dll' into your \Windows\System directory instead.
  
- Place the files 'correct.8bf', 'adjust.8bf', 'perspect.8bf'
  and 'remap.8bf' into the Plugins folder for 'Filters'. If you have
  a non-Photoshop plug-in host, check the documentation of your 
  program about how to generate and register this folder.

- The file 'PanCntrl.8bf' contains the plug-ins for the interactive
  editor. Place it also in the 'Filter' directory. It only works
  if your plug-in host accepts multiple plug-ins in one file (Photoshop
  works, but Picture Publisher not ). If you want to use shortcuts
  for these commands, you can install the action-set 'PanActions',
  and set function keys for each command.
  
- Restart Photoshop. You should find the Tools in the Filters submenu.

Requirements and Installation

Macintosh

Macintosh:
=========

There are two Macintosh versions of Panorama Tools: One ('PTools') 
which runs as plug-in in any Photoshop-compatible host, and
one (the files 'correct', 'perspect', 'remap', 'adjust')  that runs
as plug-in under the shareware program 'GraphicConverter'.
GraphicConverter is available from http://www.lemkesoft.de.
Both versions use and need the library file 'pano12.lib'.


(a) Photoshop compatible host

- If you have a previous installation of Panorama Tools:  Remove 
  the plug-in (the file 'PTools'), delete the library file 
  'pano12.lib'  from  your System's 'Extensions' folder, and the 
  preferences file  'pano.pref' from your System's 'Preferences' folder.
  Panorama Tools may crash if it loads an obsolete preferences file.
  
- Drop the file 'pano12.lib' onto your 'System Folder' icon.
  Your system should ask whether to put the file into the 
  'Extensions' folder. Click OK.

- Place the file 'PTools' into Photoshop's Plugins folder for 
  'Filters'. Please note that this file contains all four Panorama Tools
  and the pan control plug-ins.If you have a non-Photoshop plug-in host, check the 
  documentation of your  program about how to generate and register this folder.
  This file also holds the new plug-ins 'Pan Controls'. If you want to use 
  shortcuts for these commands, you can install the action-set 'PanActions',
  and set function keys for each command.

- Restart Photoshop. You should find the Tools in the Filters submenu.
 
(b) GraphicConverter (version 3.4 or above required!)
 
- If you have a previous installation of Panorama Tools:  Remove 
  all plug-ins (the files 'correct', 'perspect', 'remap', 'adjust').
  There is currently no version of the pan-controls for GraphicConverter. 
  Delete the library file   'pano12.lib'  from  your System's 'Extensions' 
  folder, and the preferences file  'pano.pref' from your System's 'Preferences' 
  folder. Panorama Tools may crash if it loads an obsolete preferences file.
  
- Drop the file 'pano12.lib' onto your 'System Folder' icon.
  Your system should ask whether to put the file into the 
  'Extensions' folder. Click OK.

- Place the files 'correct', 'perspect', 'remap', 'adjust' into
  GraphicConverter's Plugins folder.If you don't have this folder: check the 
  documentation of GraphicConverter about how to generate and register it.

- Restart GraphicConverter. You should find the Tools in the 'Effects' submenu.

Linux

 Linux:
======                                                                                                  

- If you have a previous installation of Panorama Tools:  Remove 
  the plug-in (the file 'PanTools') from your plug-ins folder,
  and the preferences file  'pano12.prf' from your '.gimp' directory.
  Panorama Tools may crash if it loads an obsolete preferences file.
  
- Put the plug-in (the file 'PanTools') into your plug-ins folder
  (eg HOME/.gimp/plug-ins/).

- Restart Gimp. You should find the Tools in the 'Filters' submenu.

How to use the filters

 How to use the filters:
=======================

This is just a very brief introduction of the various features. You can get
more info in the documentation package at my site, which contains a tutorial
with example images on how to make panoamic images. There are also a couple
of other publications at my site describing other uses of Panorama Tools,
like
o Using Fisheye lenses for Architecture. Dewarping, Shift and Tilt correction
  can be performed in one step.
o Making micropanoramas with convex mirrors.
o Barrel and Pincussion corrections of any lens.
o Making spherical and cylindrical panoramas
o etc

There are more on-line resources available which are maintained by
users and supporters of this program. A list with links is
published at my site.

Setting Preferences

 Setting Preferences:                                                                                                    
--------------------
The "Filter"-plug-in interface of Photoshop does not allow the user to 
resize images, which is required by some Panorama Tools.  If the resultimage 
is equally sized (eg most transformations in the 'correct' submenu), it 
simply replaces the  source image.

If the resultimage is larger or smaller than the source, you can set options how
Panorama Tools should handle this situation by clicking the 'pref' button, which
each  tool displays. You can select among the options:

(a) display cropped/framed version of resultimage. This image replaces your
  source image. Please note that you not only loose image information, but 
  also some image characteristics: The horizontal field of view changes! Other 
  than that it is the most convenient mode, and default.
  
(b) create a temporary file which holds the total resultimage. You can select
  place and name for this file. Panorama Tools adds a unique identifier and 
  the extension '.tif' or '.psd' for Photoshop hosts to this name. 
  If you only select (b), and deselect (a) and (c), only one outputfile       
  in Photoshop format is generated (only on Photoshop hosts). Subsequent
  images are added as additional layers to this file. If these images 
  have an alpha channel, which automatically is the case for the adjust-tool,
  the image is blended with the other layers, and a feathered mask is added.
  This allows the user to stitch images into a panoramic view, and later
  edit and adjust each image separately. See the tutorial 'HowToStitch'
  about details.
  
(c) Open this file using any suitable program to display the result. On the
  Macintosh this is always the currently running Plug-in host, so to the 
  user it looks as if the result were returned by the filter. On the PC 
  this works with some plug-in hosts (Photoshop 4 and 5, Picture Publisher 6) but
  not with some others (Paint Shop Pro). In this case you have to select 
  another application to display the result (the file format is PSD on Photoshop
  and Color It!, else TIFF). For this option to work, you have to check (b) also!

  
GraphicConverter and Gimp can handle size changes, and thus display only option
(a) and (b), (b) not creating a file, but displaying the full-sized result.

Finally, combinations of the options are allowed (not in Gimp!), eg displaying 
a cropped image and saving the full sized image simultaneously is possible.

On the Macintosh, the 'sleep' value can be set using the Resource editor     
'ResEdit'. It is now set to 0, which results in maximum speed but prohibits
background operations. To enable background operations, open the library
file 'pano12.lib' (should be in your Extensions Folder) inside 'ResEdit', 
and find the resource named 'SLEP'. Open it, and change its value from
"0000 0000" to something in the range "0000 0010" to "0000 0100". The
larger this value, the more time is granted to background processes.
Save and close the library file again.

Previous versions of Panorama Tools used a sleep value of 10, which on some
machines caused significant slowdown when batch-converting.

Selecting the Interpolator

 Selecting the Interpolator:                                               
---------------------------
Transforming an image usually requires some interpolations, since the new
pixel positions generally do not coincide with grid-positions of the screen.
The effort spent for this interpolation largely determines the quality of
the final image.

Panorama Tools uses bicubic or better interpolation. Pressing 'More' in the             
'Set Preferences' dialog (see above) brings up a dialog allowing the user to
select the options for the interpolator. The four options differ in quality 
and in speed as indicated by the arrows. Please note that many commercial 
packages use bilinear interpolation, which is far inferior to the 
lowest quality bicubic scheme offered by 'Panorama Tools'. The previous versions
of 'Panorama Tools' used the 'Polynomial' method, which is also default now.

Photoshop also offers a 'bicubic' interpolation method for its scaling and
rotation functions. However, I do not know the details of their algorithm.
The 'Polynomial'-interpolator has been adjusted to closely match their algorithm.
The other three are better, but slower, especially the new 'Sinc' function.

You can read more about interpolators, test images and comparisons with 
other graphics packages at
<http://www.fh-furtwangen.de~dersch/interpolator/interpolator.html>.

Gamma Correction

 Gamma Correction:                                                                                                                                       
----------------
The dialog described above also exhibits a 'Gamma' entry, which is set to 1.0
by default. You can enter the gamma-value for your display (typical values
are 2.5). This will cause Panorama Tools to linearize the images prior to
transformations, and later gamma-correct them again. This means the output
should look almost the same.

Theoretically, any calculation on images should be done on linearized data,
but practically, no graphics program seems to care. Most often, you do not see
any differences. Errors show up when transforming images having adjacent
areas of complementary colors. Then you might experience dark stripes at the edges.
You can avoid this by setting gamma, or by doing the transformation in Lab-
colourspace. 

Using always gamma correction has its own disadvantages, like (very slight)
brightness changes.

A more detailed discussion is available at
<http://www.fh-furtwangen.de~dersch/gamma/gamma.html>.

Correct

 Correct:
--------

Correct consists of several tools: 
- Radial  shifts all pixelpositions radially as specified by a third order
  polynomial. The coefficients are entered in the options submenu for each 
  individual color. This enables correction of barrel and pincussion distortions 
  as well as many chromatic errors. d=1 and c=b=a=0 leaves all positions 
  as they are. It may also be used to correct the radial mapping of
  fisheye-lenses, which often don't follow the theoretical angle dependence 
  (see below). Once you have determined the optimum  coefficients for your 
  lens (either by trial and error, or by some fitting process) you can 
  save them. The radial distance r_src for each point in the source image 
  is computed by the formula:
                                
         r_src  =       (a * r_dest   3 + b * r_dest   2 + c * r_dest + d) * r_dest

  Units for  r_src and r_dest is  image width / 2, ie the edge of the image
  corresponds to r_src = 1.
  
  If you check the option 'vertical', only the vertical axis is affected
  by the shift, and the unit is relative to image height/2. This can be 
  used to correct lens distortions in Panoramic cameras. Finally, the option 
  'horizontal' shifts each pixel horizontally by an amount determined by its 
  vertical distance from the center line. This can be used to correct 
  deregistration errors in scanning cameras, and will be described in a 
  separate documentation at my website.

- Vertical and Horizontal shift pixelpositions linearly by a constant amount
  which can be set for each color. This corrects scanner errors, which 
  are often misalignments by a fraction of a point between each color channel

- Shear does what you expect, as does scale. GraphicConverter has its own scaling
  tool, but this one uses another algorithm. It is somewhat better when enlarging
  images but may exhibit problems when reducing image size by more than 
  a factor of 2 (see Changes). All parameters are measured in screenpoints.
  You can preserve aspect ratio upon scaling by setting one of width or
  height to 0.

- Radial Luminance  is a center gradient filter, which compensates light fall off
  at the edges of your image. Specify an amplitude value between -255 and +255.
  Half of that amount will be subtracted from the center pixels of the image,
  whereas the other half will be added to the edge pixels.
  
- Cut Frame is an automatic cropping tool. You can select a          
  rectangle by setting width and height in the 'options' dialog. The
  tool 'Cut Frame' now searches the whole image for the brightest rectangle
  with these dimensions, and removes the frame around it. Please set the preferences
  options to (b) and (c), since this tool changes the size of the image!
  
  It automates the tedious task of cropping frames around scanned images,
  especially around circular fisheye images. If you are scanning negatives,
  the frame may be white. To crop this frame, invert the colours of the image,
  then run it through 'Cut Frame', and invert it back. This can be easily
  automated in Photoshop or GraphicConverter's batch menu.

- Fourier Filter. This filter will be documented separately.  
  

Perspective

 Perspective:
------------

This tool is essentially a shift lens. It enables you to change viewing
direction. Specify the desired new direction either by  entering horizontal 
and vertical tilt angles (in degrees) or by entering the screen coordinates  
of the new direction. Specify the format of your image (rectilinear or 
fisheye). In most cases you also have to specify the horizontal
field of view of the source image in degrees (Hfov)  to get meaningful 
results. Look into the specs of your lens to determine this value. This 
is not  required if you just want to rotate the image. Finally you 
can specify the dimensions of the  destination image: Pushing 
'source' sets height and width to the values of the source image. 
You may also specify it seperately.  Notice, that this does not 
change the scaling of the image but rather changes the field of view 
of the destination image.

Remap

 Remap:
------

Various mappings are available:

- normal, i.e. rectilinear. This is what most lenses deliver.

- QTVR-panorama, which is a cylindrical projection employed by many panoramic
  cameras (most rotating lens designs). The horizontal axis is proportional 
  to viewing angle, and the vertical axis is identical to the rectilinear 
  format. This format is also required for Apple's QTVR movies, and for 
  LivePicture's cylindrical panos.

- PSphere, ie equirectangular, which is another cylindrical projection often used
  in maps. The vertical axis is  angle-proportional. This format is used for 
  LivePicture's RealVR movies in 'Sphere' mode.

- spherical, which is the format of fisheye lenses. Two modes are available:
  Fisheye-vertical is an image shot with the camera held vertically up. The
  panorama is extracted from the circumpherence of the image. 
  Fisheye-Horizontal is an image shot with the camera held horizontally. The
  equator is now in the center of the image.

- convex mirror. This is the reflection of a convex, spherical image. The
  horizontal field of view is calculated using the formula
                HFov = 2*arcsin(radius of mirror/radius of curvature of mirror)
  This format is used to convert images from the BeHere and Cyclovision systems.
  A single step panorama set-up can be easily constructed using a spherical
  mirror and this transformation.
        
Not all possible conversions are implemented (yet). See the table below for
implemented formats. Most transformations can be performed in a single 
step and all in two steps:


 To  -->  rect     QTVR    PSphere    fish-hor     fish-vert      mirror
From 
rect       -        x         x          x            -           -
QTVR       x        -         x          -            -           -
PSphere    x        x         -          x            x           -
fish-hor   x        x         x          -            x           -
fish-vert  -        x         x          x            -           x
mirror     -        x         x          -            x           -




Notice that you have to provide the  horizontal field of view (HFOV) of the
source image (in degrees) for most conversions to get meaningful  results. The
vertical field of view for the destination image  (Vfov) is only required for the
conversion fisheye-vert - to - panorama. It is ignored in all other
cases. See the following table for HFOV-values of lenses for 35mm equipment.
Actual lens paramters may vary somewhat:

***************************** Field of View Table ****************************
*                                                                            *
*  Focal Length         HFOV   Landscape          HFOV   Portrait            *
*                                                                            *
*   8mm Fisheye           180                      180                       *
*  15mm Fisheye           130                       90                       *
*                                                                            *
*  15mm Rectilinear       100                       77                       *
*  17mm Rectilinear        93                       70                       *
*  20mm Rectilinear        84                       62                       *
*  24mm Rectilinear        74                       53                       *
*  28mm Rectilinear        65                       46                       *
*  35mm Rectilinear        54                       38                       *
*  50mm Rectilinear        40                       27                       *
*                                                                            *
******************************************************************************

Adjust

 Adjust:
------

The user interface of the adjust tool has been redesigned for version 1.7.
The main functionality of 'adjust' is to 

o Extract arbitary views from any panorama

In this mode the current image is assumed to be a 
panoramic image, and Panorama Tools creates a view.
The characteristics of this view can be set by an 'options'-
dialog or read from a textfile ('script'). Only the
parameters not obviously available have to be set:
- image width/height/format/hfov
- panorama format/hfov
If the panorama is needed in a later processing step
(eg if you want to reinsert the view, or merge it
with another image) you can save it to the internal
buffer by clicking 'Save to Buffer'.


o Insert arbitrary images into any panorama

Again, only not available paramaters have to be specified,
in this case
- image format/hfov
- panorama width/height/format/hfov
If the buffer is not used, a panoramic image containing
the view (warped and scaled properly) is generated.
If you selected 'Load Buffer' Panorama Tools attempts to
load a previously saved buffer image and merges both
images into one. You have a couple of stitiching options:
'blend' places the seam into the middle of the overlap
between the two images, while 'paste' pastes the image
completely into the buffer. A feather can be selected which
hides the seam. Color correction of the two images
can be automatically performed: Panorama Tools analyzes
the overlap of the images, and tries to adjust the
colour channels to match both images. The found correction
can be applied to either or both of the images.
Finally, if you need the panorama in a later processing step
again (maybe to add some more images) you can save it
by clicking  'Save to Buffer'.


It also includes tools to find the optimum position of an image in a
panorama. See the documentation at <http://www.fh-furtwangen.de~dersch> 
for details. It contains flags which you have to paste into the image
to mark feature points, and which are then read by Panorama Tools
to adjust image position.

Adjust can be used to create panoramic images from a set of photographs.
It uses an internal buffer to load images and automatically stitch
them into a wide angle view.

The tool can be driven by setting options in a dialog (image and panorama
characteristics are settable, as well as position and stitching options),
or read from an external script (text file). This way it is possible
to merge several images in a single operation.

More uses of 'Adjust':

o You can extract the six cubic face images needed for VRML-viewers
  from any QTVR-Cylinder or RealVR-sphere by using the 'extract' option
  set to rectilinear images (HFOV=90degree).

o  The opposite is also possible, ie merging six cubic face images 
  into any QTVR-Cylinder or RealVR-sphere (use the 'insert' option).



(PanControls part deleted since not functional anymore)
 
The tools are free to use. Send me emails if you like them. The latest version is
available from http://www.fh-furtwangen.de~dersch.


Helmut Dersch (der@fh-furtwangen.de)

Credits

Credits:
========
- I am using Andrew Regan's (ecuue@csv.warwick.ac.uk) ProgressCDEF package.
- Motorola's fast mathematical library 'libmoto' (? Motorola) 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.
- Thanks to Andrew Nemeth and Dan Slater for many helpful suggestions.

Copyright

 Copyright:
==========

This program is distributed under GNU license. Parts of this program (libmoto,
and the NETLIB math-solvers) have their own copyrights. Please see the separate
Sources package for details of the various licenses.