Readme Panorama Tools for Macintosh/ Windows/ Linux 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: ================= 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 . There is also some documentation and a few example panoramas. 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. 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: ====== - 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: ======================= 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: -------------------- 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: --------------------------- 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 . 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 . 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: ------------ 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: ------ 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: ------ 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 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). Pan Controls: ============= Internally, all 'Pan Controls' are special front ends to the 'adjust' tool. Externally they act like the toolbar of a WWW-viewer. Setting the Initial Viewport: ----------------------------- To start a session, load the panoramic image to be edited into Photoshop, and open 'adjust'. Select 'Extract Image' and 'Options'. Then click 'Set' to set the initial viewport. The dialog window that appears has entries for the viewport ('Image') and the panorama. The size of the viewing window can be arbitarily set (it can be changed later at any time during the interactive session). The camera type is also settable (most likely 'normal', but fisheye and panoramic (swing-lens) type is also possible. The field of view must also be set. The direction of the initial viewport is settable via the three angles yaw, pitch and roll. Leave them at 0 if you want to start in the center. Select the 'Panorama' characteristics. Required is 'format' and 'HFOV' (most likely QTVR and 360 degrees). Width and size is read from the source image and need not be set. Also select 'Save Buffer' since this saved image becomes the internally saved representation of the pano. Click ok once. Back in the 'Adjust' dialog select 'pref' and set only option (2) and (3) (ie 'create new image') This is required since the newly created image (the viewport) is likely to be of different size than the original (the panorama). Now click ok twice, and let Panorama Tools create the partial view. After this appears, you can close the original panorama: All further work is done using the newly created viewport-window. Panning: -------- To turn your viewport, select 'Pan Controls' and click 'Move Right' or 'Move left' or 'Tilt Up' or 'Tilt Down'. The viewing direction changes each time by an amount of 15 degrees. You can change this amount by pressing the 'Increment' button. Zooming is accomplished using the respective 'Pan Controls' and occurs by an amount of 30%. This is also settable in the 'Increment' dialog. It may be more conveniant to use the supplied actions instead of the filter menu. You can bind function keys to any of the commands. You can change the size of your viewport at any time through Photoshop's resizing commands. You can set and monitor the current position of the viewport by opening the 'adjust->options' dialog. Don't run 'adjust' since this will open a new viewport! Editing: -------- Edit your viewport like any other Photoshop image. All tools you normally use to work with images are available to you now. Please note that Panorama Tools uses the Filter interface of Photoshop which only acts upon the current active layer of your image, ie you have to collapse the image into one layer if you want to apply your changes later. Your editing changes are normally not applied to the saved buffer and get lost as soon as you pan away or zoom. You have to apply them by clicking 'Apply Changes' in the 'Pan Controls' plug-in (Or use the respective action). This command warps and inserts the current viewport back into the (invisible) buffer, and makes your changes permanent. Each 'Apply' step causes a lengthy warp-insert operation. Since the image gets resampled, it will lead to image degradation if you apply changes frequently to the same region of your panorama. That is the reason to not 'apply' changes automatically when panning. To minimize image degradation, the viewport to be inserted should have similar resolution as the original panoramic image. Getting Your Panoramic Image: ----------------------------- All editing acts upon the saved buffer panoramic image, not on the original! To get this buffer, 'Pan Controls' provides the command 'Get Panorama' which loads and displays this image to let you save it in any format you like. Caveats: -------- Panorama Tools uses the Filter-interface of Photoshop and hence has only the knowledge provided by this interface. Specifically, Panorama Tools does not detect whether you edited and changed the image, and warn you if you pan away without applying changes. If this happens, and you want to recover the edited image, you can use Photoshops 'Undo' to get the image back. Again, Panorama Tools does not notice this, and believes your viewport to be at the moved position. If you now click 'Apply' the image is inserted in the wrong place. To get that right, you have to manually use the 'adjust' tool with 'insert' option, and set the angles correctly as they were. 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: ======== - 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: ========== 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.