Panotools plugins Readme

From PanoTools.org Wiki
(Difference between revisions)
Jump to: navigation, search
m (Added Category)
(Pointed to new mirror)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Version Notes ==
+
== Editors Note ==
<pre>
+
'''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]].
Readme Panorama Tools for Macintosh/ Windows/ Linux
+
  
Notes to version 2.1:
+
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 [[Mirrors|mirror]].
=====================
+
o GraphicConverter version updated for new Plugin interface.
+
Now requires at least GC version 2.8
+
  
Notes to version 2.0.b1/2:
+
== Version Notes ==
=========================
+
  Readme Panorama Tools for Macintosh/ Windows/ Linux
o Seamer rewritten. Performs faster on large
+
images and yields better results.
+
Notes to version 2.1:
 
+
=====================
Notes to version 2.0.b0:
+
o GraphicConverter version updated for new Plugin interface.
=======================
+
Now requires at least GC version 2.8
 
+
o Tiff-writer for temporary files corrected (Only non Photoshop
+
Notes to version 2.0.b1/2:
  hosts for Photoshop plug-in affected).
+
=========================
 
+
o Seamer rewritten. Performs faster on large
Notes to version 1.9.2:
+
images and yields better results.
=======================
+
 
+
Notes to version 2.0.b0:
o Correction mode for scanning cameras (PanoScan) added.
+
=======================
 
+
Notes to version 1.9.1:
+
o Tiff-writer for temporary files corrected (Only non Photoshop
=======================
+
  hosts for Photoshop plug-in affected).
 
+
 
o Adjust Tool accepts 'PSphere' images as input
+
Notes to version 1.9.2:
 
+
=======================
o Bug fixes regarding Photoshop file creation.
+
 
+
o Correction mode for scanning cameras (PanoScan) added.
Notes to version 1.9.0:
+
=======================
+
Notes to version 1.9.1:
 
+
=======================
o Scaling function in 'Correct'-menu changed: If one
+
  of width/height is set to 0, aspect ratio is preserved.
+
o Adjust Tool accepts 'PSphere' images as input
 
+
o Some compatibility problems with PTStitcher/PTOptimizer
+
o Bug fixes regarding Photoshop file creation.
  solved.
+
</pre>
+
Notes to version 1.9.0:
== General Feature ==
+
=======================
<pre>
+
General Features:
+
o Scaling function in 'Correct'-menu changed: If one
=================
+
  of width/height is set to 0, aspect ratio is preserved.
 
+
Panorama Tools is a free program which can be used to  
+
o Some compatibility problems with PTStitcher/PTOptimizer
generate, edit and transform many kinds of panoramic images.  
+
  solved.
Its five main functionalities are:
+
 
+
== General Features ==
o Correction of images.  
+
  General Features:
  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.
+
Panorama Tools is a free program which can be used to  
  Correct chromatic errors (colour separation) of your lens.
+
generate, edit and transform many kinds of panoramic images.  
  Correct chromatic errors (colour separation) of your scanner.
+
Its five main functionalities are:
  Skew/Unskew your images horizontally or vertically.
+
  Correction of scanning slit cameras
+
o Correction of images.  
  Fourier Transform Filtering/Wiener Filter                                                                                                                     
+
  Automatic cropping of images to brightest rectangle.           
 
+
  Remove all sorts of barrel and/or pincussion distortion.
o Perspective Control
+
  Correct light fall-off at edges of your wide angle shots.
  Simulates a shift lens in software
+
  Correct chromatic errors (colour separation) of your lens.
  For normal and fisheye lenses
+
  Correct chromatic errors (colour separation) of your scanner.
 
+
  Skew/Unskew your images horizontally or vertically.
o Remap from any projection to any projection
+
  Correction of scanning slit cameras
  Warp and unwarp normal, panoramic and fisheye images.
+
  Fourier Transform Filtering/Wiener Filter                                                                                                                     
  Convert equirectangular LivePicture panos to QTVR-panos and vice-versa
+
 
  Convert mirror images (BeHere-setup or similar) to any panorama and  
+
o Perspective Control
  vice-versa. Convert fisheye images to any panorama and vice-versa
+
  Simulates a shift lens in software
  Unwarp panorama sections (QTVR and LivePicture) to edit in Photoshop, then  
+
  For normal and fisheye lenses
  rewarp and seamlessly insert back.
+
 
 
+
o Remap from any projection to any projection
o Adjust images into a panoramic view
+
  Warp and unwarp normal, panoramic and fisheye images.
  Generate full panoramic view using any mixture of normal, fisheye
+
  Convert equirectangular LivePicture panos to QTVR-panos and vice-versa
  and panoramic images.
+
  Convert mirror images (BeHere-setup or similar) to any panorama and  
  Built-in optimizer to find optimum pitch/roll/yaw for a given image           
+
  vice-versa. Convert fisheye images to any panorama and vice-versa
  to fit a panorama
+
  Unwarp panorama sections (QTVR and LivePicture) to edit in Photoshop, then  
  Built-in optimizer to find optimum correction settings for a given image.
+
  rewarp and seamlessly insert back.
  Built-in stitching tool to automatically merge images into a panoramic     
+
 
  view.
+
o Adjust images into a panoramic view
  Automatic colour adjustment of to be merged images
+
  Generate full panoramic view using any mixture of normal, fisheye
  Extract any view (normal/fisheye/panoramic) from any                           
+
  and panoramic images.
  panorama (RealVR/QTVR/rectilinear)                                             
+
  Built-in optimizer to find optimum pitch/roll/yaw for a given image           
  Insert any image (normal/fisheye/panoramic) into any                           
+
  to fit a panorama
  panorama (RealVR/QTVR/rectilinear)                                             
+
  Built-in optimizer to find optimum correction settings for a given image.
 
+
  Built-in stitching tool to automatically merge images into a panoramic     
o Realtime Panorama Editor      (only Photoshop/Gimp version)                           
+
  view.
  The realtime Panorama Editor is a separate Plug-in which
+
  Automatic colour adjustment of to be merged images
  makes the Photoshop window an editable VR-viewer. You can pan
+
  Extract any view (normal/fisheye/panoramic) from any                           
  left and right, tilt up and down, and zoom in and out. At any
+
  panorama (RealVR/QTVR/rectilinear)                                             
  time you can use all Photoshop/Gimp tools to edit the image and
+
  Insert any image (normal/fisheye/panoramic) into any                           
  instantly apply the changes to the warped panoramic image  
+
  panorama (RealVR/QTVR/rectilinear)                                             
  while keeping the interactive window open. This can be done
+
 
  with any view ("camera") and any panorama (see 'adjust' above).
+
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
The latest version is alway available from my website
+
  time you can use all Photoshop/Gimp tools to edit the image and
<http://www.fh-furtwangen.de/~dersch>. There is also some  
+
  instantly apply the changes to the warped panoramic image  
documentation and a few example panoramas.
+
  while keeping the interactive window open. This can be done
 
+
  with any view ("camera") and any panorama (see 'adjust' above).
</pre>
+
 
 +
 
 +
 +
The latest version is alway available from my website
 +
<[http://www.panotools.org/dersch <nowiki>http://www.fh-furtwangen.de~dersch></nowiki>]. There is also some  
 +
documentation and a few example panoramas.
 +
 +
 
== Requirements and Installation ==
 
== Requirements and Installation ==
 
=== Windows ===
 
=== Windows ===
<pre>
 
 
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  
+
Requirements and Installation:
  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.
+
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 ===
 
    
 
    
- Place the files 'correct.8bf', 'adjust.8bf', 'perspect.8bf'
+
Macintosh:
  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.
+
There are two Macintosh versions of Panorama Tools: One ('PTools')
 
+
which runs as plug-in in any Photoshop-compatible host, and
- The file 'PanCntrl.8bf' contains the plug-ins for the interactive
+
one (the files 'correct', 'perspect', 'remap', 'adjust')  that runs
  editor. Place it also in the 'Filter' directory. It only works
+
as plug-in under the shareware program 'GraphicConverter'.
  if your plug-in host accepts multiple plug-ins in one file (Photoshop
+
GraphicConverter is available from http://www.lemkesoft.de.
  works, but Picture Publisher not ). If you want to use shortcuts
+
Both versions use and need the library file 'pano12.lib'.
  for these commands, you can install the action-set 'PanActions',
+
  and set function keys for each command.
+
 +
(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.
 
    
 
    
- Restart Photoshop. You should find the Tools in the Filters submenu.
+
(b) GraphicConverter (version 3.4 or above required!)
 
+
Requirements and Installation
+
 
+
</pre>
+
=== Macintosh ===
+
<pre>
+
 
+
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.
+
- If you have a previous installation of Panorama Tools:  Remove
  Your system should ask whether to put the file into the  
+
  all plug-ins (the files 'correct', 'perspect', 'remap', 'adjust').
  'Extensions' folder. Click OK.
+
  There is currently no version of the pan-controls for GraphicConverter.
 
+
  Delete the library file  'pano12.lib'  from  your System's 'Extensions'
- Place the file 'PTools' into Photoshop's Plugins folder for
+
  folder, and the preferences file  'pano.pref' from your System's 'Preferences'
  'Filters'. Please note that this file contains all four Panorama Tools
+
  folder. Panorama Tools may crash if it loads an obsolete preferences file.
  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.
+
- Drop the file 'pano12.lib' onto your 'System Folder' icon.
  This file also holds the new plug-ins 'Pan Controls'. If you want to use
+
  Your system should ask whether to put the file into the  
  shortcuts for these commands, you can install the action-set 'PanActions',
+
  'Extensions' folder. Click OK.
  and set function keys for each command.
+
 
+
- Place the files 'correct', 'perspect', 'remap', 'adjust' into
- Restart Photoshop. You should find the Tools in the Filters submenu.
+
  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.
 
   
 
   
(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.
 
 
</pre>
 
 
=== Linux ===
 
=== Linux ===
<pre>
+
  Linux:
Linux:
+
======                                                                                                   
======                                                                                                   
+
 
+
- If you have a previous installation of Panorama Tools:  Remove  
- If you have a previous installation of Panorama Tools:  Remove  
+
  the plug-in (the file 'PanTools') from your plug-ins folder,
  the plug-in (the file 'PanTools') from your plug-ins folder,
+
  and the preferences file  'pano12.prf' from your '.gimp' directory.
  and the preferences file  'pano12.prf' from your '.gimp' directory.
+
  Panorama Tools may crash if it loads an obsolete preferences file.
  Panorama Tools may crash if it loads an obsolete preferences file.
+
 
 
+
- Put the plug-in (the file 'PanTools') into your plug-ins folder
- Put the plug-in (the file 'PanTools') into your plug-ins folder
+
  (eg HOME/.gimp/plug-ins/).
  (eg HOME/.gimp/plug-ins/).
+
 
+
- Restart Gimp. You should find the Tools in the 'Filters' submenu.
- Restart Gimp. You should find the Tools in the 'Filters' submenu.
+
 
+
</pre>
+
 
=== How to use the filters ===
 
=== How to use the filters ===
<pre>
+
  How to use the filters:
How to use the filters:
+
=======================
=======================
+
 
+
This is just a very brief introduction of the various features. You can get
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
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
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,
of other publications at my site describing other uses of Panorama Tools,
+
like
like
+
o Using Fisheye lenses for Architecture. Dewarping, Shift and Tilt correction
o Using Fisheye lenses for Architecture. Dewarping, Shift and Tilt correction
+
  can be performed in one step.
  can be performed in one step.
+
o Making micropanoramas with convex mirrors.
o Making micropanoramas with convex mirrors.
+
o Barrel and Pincussion corrections of any lens.
o Barrel and Pincussion corrections of any lens.
+
o Making spherical and cylindrical panoramas
o Making spherical and cylindrical panoramas
+
o etc
o etc
+
 
+
There are more on-line resources available which are maintained by
There are more on-line resources available which are maintained by
+
users and supporters of this program. A list with links is
users and supporters of this program. A list with links is
+
published at my site.
published at my site.
+
 
+
</pre>
+
 
==== Setting Preferences ====
 
==== Setting Preferences ====
<pre>
+
  Setting Preferences:                                                                                                     
Setting Preferences:                                                                                                     
+
--------------------
--------------------
+
The "Filter"-plug-in interface of Photoshop does not allow the user to  
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  
resize images, which is required by some Panorama Tools.  If the resultimage  
+
is equally sized (eg most transformations in the 'correct' submenu), it  
is equally sized (eg most transformations in the 'correct' submenu), it  
+
simply replaces the  source image.
simply replaces the  source image.
+
 
+
If the resultimage is larger or smaller than the source, you can set options how
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
Panorama Tools should handle this situation by clicking the 'pref' button, which
+
each  tool displays. You can select among the options:
each  tool displays. You can select among the options:
+
 
+
(a) display cropped/framed version of resultimage. This image replaces your
(a) display cropped/framed version of resultimage. This image replaces your
+
  source image. Please note that you not only loose image information, but  
  source image. Please note that you not only loose image information, but  
+
  also some image characteristics: The horizontal field of view changes! Other  
  also some image characteristics: The horizontal field of view changes! Other  
+
  than that it is the most convenient mode, and default.
  than that it is the most convenient mode, and default.
+
 
 
+
(b) create a temporary file which holds the total resultimage. You can select
(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  
  place and name for this file. Panorama Tools adds a unique identifier and  
+
  the extension '.tif' or '.psd' for Photoshop hosts to this name.  
  the extension '.tif' or '.psd' for Photoshop hosts to this name.  
+
  If you only select (b), and deselect (a) and (c), only one outputfile       
  If you only select (b), and deselect (a) and (c), only one outputfile       
+
  in Photoshop format is generated (only on Photoshop hosts). Subsequent
  in Photoshop format is generated (only on Photoshop hosts). Subsequent
+
  images are added as additional layers to this file. If these images  
  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,
  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.
  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
  This allows the user to stitch images into a panoramic view, and later
+
  edit and adjust each image separately. See the tutorial 'HowToStitch'
  edit and adjust each image separately. See the tutorial 'HowToStitch'
+
  about details.
  about details.
+
 
 
+
(c) Open this file using any suitable program to display the result. On the
(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  
  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  
  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
  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  
  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
  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!
  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
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.
(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  
Finally, combinations of the options are allowed (not in Gimp!), eg displaying  
+
a cropped image and saving the full sized image simultaneously is possible.
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     
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
'ResEdit'. It is now set to 0, which results in maximum speed but prohibits
+
background operations. To enable background operations, open the library
background operations. To enable background operations, open the library
+
file 'pano12.lib' (should be in your Extensions Folder) inside 'ResEdit',  
file 'pano12.lib' (should be in your Extensions Folder) inside 'ResEdit',  
+
and find the resource named 'SLEP'. Open it, and change its value from
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
"0000 0000" to something in the range "0000 0010" to "0000 0100". The
+
larger this value, the more time is granted to background processes.
larger this value, the more time is granted to background processes.
+
Save and close the library file again.
Save and close the library file again.
+
 
+
Previous versions of Panorama Tools used a sleep value of 10, which on some
Previous versions of Panorama Tools used a sleep value of 10, which on some
+
machines caused significant slowdown when batch-converting.
machines caused significant slowdown when batch-converting.
+
 
+
</pre>
+
 
==== Selecting the Interpolator ====
 
==== Selecting the Interpolator ====
<pre>
+
  Selecting the Interpolator:                                               
Selecting the Interpolator:                                               
+
---------------------------
---------------------------
+
Transforming an image usually requires some interpolations, since the new
Transforming an image usually requires some interpolations, since the new
+
pixel positions generally do not coincide with grid-positions of the screen.
pixel positions generally do not coincide with grid-positions of the screen.
+
The effort spent for this interpolation largely determines the quality of
The effort spent for this interpolation largely determines the quality of
+
the final image.
the final image.
+
 
+
Panorama Tools uses bicubic or better interpolation. Pressing 'More' in the             
Panorama Tools uses bicubic or better interpolation. Pressing 'More' in the             
+
'Set Preferences' dialog (see above) brings up a dialog allowing the user to
'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  
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  
and in speed as indicated by the arrows. Please note that many commercial  
+
packages use bilinear interpolation, which is far inferior to the  
packages use bilinear interpolation, which is far inferior to the  
+
lowest quality bicubic scheme offered by 'Panorama Tools'. The previous versions
lowest quality bicubic scheme offered by 'Panorama Tools'. The previous versions
+
of 'Panorama Tools' used the 'Polynomial' method, which is also default now.
of 'Panorama Tools' used the 'Polynomial' method, which is also default now.
+
 
+
Photoshop also offers a 'bicubic' interpolation method for its scaling and
Photoshop also offers a 'bicubic' interpolation method for its scaling and
+
rotation functions. However, I do not know the details of their algorithm.
rotation functions. However, I do not know the details of their algorithm.
+
The 'Polynomial'-interpolator has been adjusted to closely match 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.
The other three are better, but slower, especially the new 'Sinc' function.
+
 
+
You can read more about interpolators, test images and comparisons with  
You can read more about interpolators, test images and comparisons with  
+
other graphics packages at
other graphics packages at
+
<[http://www.panotools.org/dersch/interpolator/interpolator.html <nowiki>http://www.fh-furtwangen.de~dersch/interpolator/interpolator.html></nowiki>].
<http://www.fh-furtwangen.de/~dersch/interpolator/interpolator.html>.
+
 
+
</pre>  
+
 
==== Gamma Correction ====
 
==== Gamma Correction ====
<pre>
+
  Gamma Correction:                                                                                                                                       
Gamma Correction:                                                                                                                                       
+
----------------
----------------
+
The dialog described above also exhibits a 'Gamma' entry, which is set to 1.0
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
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
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
transformations, and later gamma-correct them again. This means the output
+
should look almost the same.
should look almost the same.
+
 
+
Theoretically, any calculation on images should be done on linearized data,
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
but practically, no graphics program seems to care. Most often, you do not see
+
any differences. Errors show up when transforming images having adjacent
any differences. Errors show up when transforming images having adjacent
+
areas of complementary colors. Then you might experience dark stripes at the edges.
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-
You can avoid this by setting gamma, or by doing the transformation in Lab-
+
colourspace.  
colourspace.  
+
 
+
Using always gamma correction has its own disadvantages, like (very slight)
Using always gamma correction has its own disadvantages, like (very slight)
+
brightness changes.
brightness changes.
+
 
+
A more detailed discussion is available at
A more detailed discussion is available at
+
<[http://www.panotools.org/dersch/gamma/gamma.html <nowiki>http://www.fh-furtwangen.de~dersch/gamma/gamma.html></nowiki>].
<http://www.fh-furtwangen.de/~dersch/gamma/gamma.html>.
+
 
+
</pre>  
+
 
==== Correct ====
 
==== Correct ====
<pre>
+
  Correct:
Correct:
+
--------
--------
+
 
+
Correct consists of several tools:  
Correct consists of several tools:  
+
- Radial  shifts all pixelpositions radially as specified by a third order
- Radial  shifts all pixelpositions radially as specified by a third order
+
  polynomial. The coefficients are entered in the options submenu for each  
  polynomial. The coefficients are entered in the options submenu for each  
+
  individual color. This enables correction of barrel and pincussion distortions  
  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 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
  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  
  fisheye-lenses, which often don't follow the theoretical angle dependence  
+
  (see below). Once you have determined the optimum  coefficients for your  
  (see below). Once you have determined the optimum  coefficients for your  
+
  lens (either by trial and error, or by some fitting process) you can  
  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  
  save them. The radial distance r_src for each point in the source image  
+
  is computed by the formula:
  is computed by the formula:
+
                               
                               
+
          r_src  =      (a * r_dest   3 + b * r_dest   2 + c * r_dest + d) * r_dest
        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
  Units for  r_src and r_dest is  image width / 2, ie the edge of the image
+
  corresponds to r_src = 1.
  corresponds to r_src = 1.
+
 
 
+
  If you check the option 'vertical', only the vertical axis is affected
  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  
  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  
  used to correct lens distortions in Panoramic cameras. Finally, the option  
+
  'horizontal' shifts each pixel horizontally by an amount determined by its  
  'horizontal' shifts each pixel horizontally by an amount determined by its  
+
  vertical distance from the center line. This can be used to correct  
  vertical distance from the center line. This can be used to correct  
+
  deregistration errors in scanning cameras, and will be described in a  
  deregistration errors in scanning cameras, and will be described in a  
+
  separate documentation at my website.
  separate documentation at my website.
+
 
+
- Vertical and Horizontal shift pixelpositions linearly by a constant amount
- Vertical and Horizontal shift pixelpositions linearly by a constant amount
+
  which can be set for each color. This corrects scanner errors, which  
  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
  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
- 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
  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  
  images but may exhibit problems when reducing image size by more than  
+
  a factor of 2 (see Changes). All parameters are measured in screenpoints.
  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
  You can preserve aspect ratio upon scaling by setting one of width or
+
  height to 0.
  height to 0.
+
 
+
- Radial Luminance  is a center gradient filter, which compensates light fall off
- 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.
  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,
  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.
  whereas the other half will be added to the edge pixels.
+
 
 
+
- Cut Frame is an automatic cropping tool. You can select a           
- Cut Frame is an automatic cropping tool. You can select a           
+
  rectangle by setting width and height in the 'options' dialog. The
  rectangle by setting width and height in the 'options' dialog. The
+
  tool 'Cut Frame' now searches the whole image for the brightest rectangle
  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
  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!
  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,
  It automates the tedious task of cropping frames around scanned images,
+
  especially around circular fisheye images. If you are scanning negatives,
  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,
  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
  then run it through 'Cut Frame', and invert it back. This can be easily
+
  automated in Photoshop or GraphicConverter's batch menu.
  automated in Photoshop or GraphicConverter's batch menu.
+
 
+
- Fourier Filter. This filter will be documented separately.   
- Fourier Filter. This filter will be documented separately.   
+
 
 
+
</pre>
+
 
==== Perspective ====
 
==== Perspective ====
<pre>
+
  Perspective:
Perspective:
+
------------
------------
+
 
+
This tool is essentially a shift lens. It enables you to change viewing
This tool is essentially a shift lens. It enables you to change viewing
+
direction. Specify the desired new direction either by  entering horizontal  
direction. Specify the desired new direction either by  entering horizontal  
+
and vertical tilt angles (in degrees) or by entering the screen coordinates   
and vertical tilt angles (in degrees) or by entering the screen coordinates   
+
of the new direction. Specify the format of your image (rectilinear or  
of the new direction. Specify the format of your image (rectilinear or  
+
fisheye). In most cases you also have to specify the horizontal
fisheye). In most cases you also have to specify the horizontal
+
field of view of the source image in degrees (Hfov)  to get meaningful  
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  
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  
is not  required if you just want to rotate the image. Finally you  
+
can specify the dimensions of the  destination image: Pushing  
can specify the dimensions of the  destination image: Pushing  
+
'source' sets height and width to the values of the source image.  
'source' sets height and width to the values of the source image.  
+
You may also specify it seperately.  Notice, that this does not  
You may also specify it seperately.  Notice, that this does not  
+
change the scaling of the image but rather changes the field of view  
change the scaling of the image but rather changes the field of view  
+
of the destination image.
of the destination image.
+
 
+
 
+
</pre>
+
 
==== Remap ====
 
==== Remap ====
<pre>
+
  Remap:
Remap:
+
------
------
+
 
+
Various mappings are available:
Various mappings are available:
+
 
+
- normal, i.e. rectilinear. This is what most lenses deliver.
- normal, i.e. rectilinear. This is what most lenses deliver.
+
 
+
- QTVR-panorama, which is a cylindrical projection employed by many panoramic
- QTVR-panorama, which is a cylindrical projection employed by many panoramic
+
  cameras (most rotating lens designs). The horizontal axis is proportional  
  cameras (most rotating lens designs). The horizontal axis is proportional  
+
  to viewing angle, and the vertical axis is identical to the rectilinear  
  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  
  format. This format is also required for Apple's QTVR movies, and for  
+
  LivePicture's cylindrical panos.
  LivePicture's cylindrical panos.
+
 
+
- PSphere, ie equirectangular, which is another cylindrical projection often used
- PSphere, ie equirectangular, which is another cylindrical projection often used
+
  in maps. The vertical axis is  angle-proportional. This format is used for  
  in maps. The vertical axis is  angle-proportional. This format is used for  
+
  LivePicture's RealVR movies in 'Sphere' mode.
  LivePicture's RealVR movies in 'Sphere' mode.
+
 
+
- spherical, which is the format of fisheye lenses. Two modes are available:
- 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
  Fisheye-vertical is an image shot with the camera held vertically up. The
+
  panorama is extracted from the circumpherence of the image.  
  panorama is extracted from the circumpherence of the image.  
+
  Fisheye-Horizontal is an image shot with the camera held horizontally. The
  Fisheye-Horizontal is an image shot with the camera held horizontally. The
+
  equator is now in the center of the image.
  equator is now in the center of the image.
+
 
+
- convex mirror. This is the reflection of a convex, spherical image. The
- convex mirror. This is the reflection of a convex, spherical image. The
+
  horizontal field of view is calculated using the formula
  horizontal field of view is calculated using the formula
+
                HFov = 2*arcsin(radius of mirror/radius of curvature of mirror)
                HFov = 2*arcsin(radius of mirror/radius of curvature of mirror)
+
  This format is used to convert images from the BeHere and Cyclovision systems.
  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
  A single step panorama set-up can be easily constructed using a spherical
+
  mirror and this transformation.
  mirror and this transformation.
+
       
       
+
Not all possible conversions are implemented (yet). See the table below for
Not all possible conversions are implemented (yet). See the table below for
+
implemented formats. Most transformations can be performed in a single  
implemented formats. Most transformations can be performed in a single  
+
step and all in two steps:
step and all in two steps:
+
 
+
   
 
+
  To  -->  rect    QTVR    PSphere    fish-hor    fish-vert      mirror
  To  -->  rect    QTVR    PSphere    fish-hor    fish-vert      mirror
+
From  
From  
+
rect      -        x        x          x            -          -
rect      -        x        x          x            -          -
+
QTVR      x        -        x          -            -          -
QTVR      x        -        x          -            -          -
+
PSphere    x        x        -          x            x          -
PSphere    x        x        -          x            x          -
+
fish-hor  x        x        x          -            x          -
fish-hor  x        x        x          -            x          -
+
fish-vert  -        x        x          x            -          x
fish-vert  -        x        x          x            -          x
+
mirror    -        x        x          -            x          -
mirror    -        x        x          -            x          -
+
 
+
 
+
 
+
 
+
Notice that you have to provide the  horizontal field of view (HFOV) of the
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
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
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
conversion fisheye-vert - to - panorama. It is ignored in all other
+
cases. See the following table for HFOV-values of lenses for 35mm equipment.
cases. See the following table for HFOV-values of lenses for 35mm equipment.
+
Actual lens paramters may vary somewhat:
Actual lens paramters may vary somewhat:
+
 
+
***************************** Field of View Table ****************************
***************************** Field of View Table ****************************
+
*                                                                            *
*                                                                            *
+
*  Focal Length        HFOV  Landscape          HFOV  Portrait            *
*  Focal Length        HFOV  Landscape          HFOV  Portrait            *
+
*                                                                            *
*                                                                            *
+
*  8mm Fisheye          180                      180                      *
*  8mm Fisheye          180                      180                      *
+
*  15mm Fisheye          130                      90                      *
*  15mm Fisheye          130                      90                      *
+
*                                                                            *
*                                                                            *
+
*  15mm Rectilinear      100                      77                      *
*  15mm Rectilinear      100                      77                      *
+
*  17mm Rectilinear        93                      70                      *
*  17mm Rectilinear        93                      70                      *
+
*  20mm Rectilinear        84                      62                      *
*  20mm Rectilinear        84                      62                      *
+
*  24mm Rectilinear        74                      53                      *
*  24mm Rectilinear        74                      53                      *
+
*  28mm Rectilinear        65                      46                      *
*  28mm Rectilinear        65                      46                      *
+
*  35mm Rectilinear        54                      38                      *
*  35mm Rectilinear        54                      38                      *
+
*  50mm Rectilinear        40                      27                      *
*  50mm Rectilinear        40                      27                      *
+
*                                                                            *
*                                                                            *
+
******************************************************************************
******************************************************************************
+
 
+
 
+
</pre>
+
 
==== Adjust ====
 
==== Adjust ====
<pre>
+
  Adjust:
Adjust:
+
------
------
+
 
+
The user interface of the adjust tool has been redesigned for version 1.7.
The user interface of the adjust tool has been redesigned for version 1.7.
+
The main functionality of 'adjust' is to  
The main functionality of 'adjust' is to  
+
 
+
o Extract arbitary views from any panorama
o Extract arbitary views from any panorama
+
 
+
In this mode the current image is assumed to be a  
In this mode the current image is assumed to be a  
+
panoramic image, and Panorama Tools creates a view.
panoramic image, and Panorama Tools creates a view.
+
The characteristics of this view can be set by an 'options'-
The characteristics of this view can be set by an 'options'-
+
dialog or read from a textfile ('script'). Only the
dialog or read from a textfile ('script'). Only the
+
parameters not obviously available have to be set:
parameters not obviously available have to be set:
+
- image width/height/format/hfov
- image width/height/format/hfov
+
- panorama format/hfov
- panorama format/hfov
+
If the panorama is needed in a later processing step
If the panorama is needed in a later processing step
+
(eg if you want to reinsert the view, or merge it
(eg if you want to reinsert the view, or merge it
+
with another image) you can save it to the internal
with another image) you can save it to the internal
+
buffer by clicking 'Save to Buffer'.
buffer by clicking 'Save to Buffer'.
+
 
+
 
+
o Insert arbitrary images into any panorama
o Insert arbitrary images into any panorama
+
 
+
Again, only not available paramaters have to be specified,
Again, only not available paramaters have to be specified,
+
in this case
in this case
+
- image format/hfov
- image format/hfov
+
- panorama width/height/format/hfov
- panorama width/height/format/hfov
+
If the buffer is not used, a panoramic image containing
If the buffer is not used, a panoramic image containing
+
the view (warped and scaled properly) is generated.
the view (warped and scaled properly) is generated.
+
If you selected 'Load Buffer' Panorama Tools attempts to
If you selected 'Load Buffer' Panorama Tools attempts to
+
load a previously saved buffer image and merges both
load a previously saved buffer image and merges both
+
images into one. You have a couple of stitiching options:
images into one. You have a couple of stitiching options:
+
'blend' places the seam into the middle of the overlap
'blend' places the seam into the middle of the overlap
+
between the two images, while 'paste' pastes the image
between the two images, while 'paste' pastes the image
+
completely into the buffer. A feather can be selected which
completely into the buffer. A feather can be selected which
+
hides the seam. Color correction of the two images
hides the seam. Color correction of the two images
+
can be automatically performed: Panorama Tools analyzes
can be automatically performed: Panorama Tools analyzes
+
the overlap of the images, and tries to adjust the
the overlap of the images, and tries to adjust the
+
colour channels to match both images. The found correction
colour channels to match both images. The found correction
+
can be applied to either or both of the images.
can be applied to either or both of the images.
+
Finally, if you need the panorama in a later processing step
Finally, if you need the panorama in a later processing step
+
again (maybe to add some more images) you can save it
again (maybe to add some more images) you can save it
+
by clicking  'Save to Buffer'.
by clicking  'Save to Buffer'.
+
 
+
 
+
It also includes tools to find the optimum position of an image in a
It also includes tools to find the optimum position of an image in a
+
panorama. See the documentation at <[http://www.panotools.org/dersch <nowiki>http://www.fh-furtwangen.de~dersch></nowiki>]
panorama. See the documentation at <http://www.fh-furtwangen.de/~dersch>  
+
for details. It contains flags which you have to paste into the image
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 mark feature points, and which are then read by Panorama Tools
+
to adjust image position.
to adjust image position.
+
 
+
Adjust can be used to create panoramic images from a set of photographs.
Adjust can be used to create panoramic images from a set of photographs.
+
It uses an internal buffer to load images and automatically stitch
It uses an internal buffer to load images and automatically stitch
+
them into a wide angle view.
them into a wide angle view.
+
 
+
The tool can be driven by setting options in a dialog (image and panorama
The tool can be driven by setting options in a dialog (image and panorama
+
characteristics are settable, as well as position and stitching options),
characteristics are settable, as well as position and stitching options),
+
or read from an external script (text file). This way it is possible
or read from an external script (text file). This way it is possible
+
to merge several images in a single operation.
to merge several images in a single operation.
+
 
+
More uses of 'Adjust':
More uses of 'Adjust':
+
 
+
o You can extract the six cubic face images needed for VRML-viewers
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
  from any QTVR-Cylinder or RealVR-sphere by using the 'extract' option
+
  set to rectilinear images (HFOV=90degree).
  set to rectilinear images (HFOV=90degree).
+
 
+
o  The opposite is also possible, ie merging six cubic face images  
o  The opposite is also possible, ie merging six cubic face images  
+
  into any QTVR-Cylinder or RealVR-sphere (use the 'insert' option).
  into any QTVR-Cylinder or RealVR-sphere (use the 'insert' option).
+
 
+
 
+
</pre>
+
(PanControls part deleted since not functional anymore)
(PanControls part deleted since not functional anymore)
+
 
<pre>
+
The tools are free to use. Send me emails if you like them. The latest version is
 
+
available from [http://www.panotools.org/dersch <nowiki>http://www.fh-furtwangen.de~dersch</nowiki>].
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)
 
+
Helmut Dersch (der@fh-furtwangen.de)
+
 
+
 
+
</pre>
+
 
=== Credits ===
 
=== Credits ===
<pre>
+
 
 
+
Credits:
Credits:
+
========
========
+
- I am using Andrew Regan's (ecuue@csv.warwick.ac.uk) ProgressCDEF package.
- I am using Andrew Regan's (ecuue@csv.warwick.ac.uk) ProgressCDEF package.
+
- Motorola's fast mathematical library 'libmoto' (? Motorola) is linked with the
- Motorola's fast mathematical library 'libmoto' (Motorola) is linked with the
+
  program (Mac only).
  program (Mac only).
+
- The Levenberg-Marquardt solver of the MINPACK program is used.
- The Levenberg-Marquardt solver of the MINPACK program is used.
+
- The public domain solver 'PZeros' from D. Bini (bini@dm.unipi.it), available
- The public domain solver 'PZeros' from D. Bini (bini@dm.unipi.it), available
+
  from Netlib, is used in the program.
  from Netlib, is used in the program.
+
- The public domain Fast Fourier Transform package FFTN by Mark Olesen is used.
- The public domain Fast Fourier Transform package FFTN by Mark Olesen is used.
+
- Thanks to Andrew Nemeth and Dan Slater for many helpful suggestions.
- Thanks to Andrew Nemeth and Dan Slater for many helpful suggestions.
+
 
+
 
+
</pre>
+
 
==== Copyright ====
 
==== Copyright ====
<pre>
+
  Copyright:
Copyright:
+
==========
==========
+
 
+
This program is distributed under GNU license. Parts of this program (libmoto,
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
and the NETLIB math-solvers) have their own copyrights. Please see the separate
+
Sources package for details of the various licenses.
Sources package for details of the various licenses.
+
 
</pre>
+
[[Category:Info]]
 
+
[[Category:Protected]]
+

Latest revision as of 02:23, 22 May 2011

Contents

[edit] 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.

[edit] 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.

[edit] 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.


[edit] Requirements and Installation

[edit] 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


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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>.


[edit] 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>.


[edit] 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.  
  

[edit] 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.



[edit] 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                       *
*                                                                            *
******************************************************************************



[edit] 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)



[edit] 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.



[edit] 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.
Personal tools
Namespaces

Variants
Actions
Navigation
tools
Tools