Historical:Panotools plugins Readme
Jump to navigation
Jump to search
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.