hugin Manual
A easy to use GUI for Panorama Tools.
Hugin currently supports most features of panorama tools, and can be used for to create different kinds of panoramic images.
Introduction
This is the reference manual (hah, good joke... :-) for hugin. It does not cover general panorama creation, but tries to document keyboard shortcuts and other things that are not obvious from the first look at the interface.
The hugin homepage contains more general information and even some tutorials.
Credits
- Main programming:Pablo d'Angelo <pablo@mathematik.uni-ulm.de>
- Additional programming: Kai-Uwe Behrmann
- Tutorials and rpm packages: Bruno Postle
Thanks to all people on the ptx mailing list, for many interesting ideas and for testing.
Main Window
This window consists of a toolbar that provides quick access to important functions. It also contains the Images, Lens, Control Point, Optimizer and Panorama Tab, which will be explained below.
Images Tab
The images tab is used to manage the images in the project. Additionally the positions of the images in the final panorama can be edited here.
Adding images
Images can either be added with the Add and Add time series button or via drag and drop. Add time series prompts adds all images with a similar file modification time as the selected image.
Reference images can be set for position of the image in the panorama and color/brightness compensation (currently only supported by PTStitcher). The Adjust the anchor spot opens a new window where the position of the horizon in the anchor image can be set with the left mouse button and rotated with the right mouse button. This dialog is currently a bit buggy and the rotation behaviour is inconsistent (the horizon is aways rotated around the image center). If possible, vertical (and sometime horizontal) control points should be used to archive a straight horizon in the panorama. See the http://hugin.sf.net/tutorials for more information on this topic.
Automatic creation of control points can be done by selecting the images between those control points should be found and pressing the Create Ctrl Points button. hugin will then launch autopano or Autopano-SIFT and add the detected control points to the project. The Preferences is used to select which program should be used, and set further options Remove Points does exactly what its name suggests, it removes control points between the selected images, or all control points if no image is selected.
In the Image Orientation section, the position of the selected images in the final panorama can be specified by yaw, pitch and roll angle (in degrees). The Reset button will reset all angles to zero. This is useful if the optimizer could not determine the image orientation well and got stuck with a suboptimal result. It is possible to select multiple images at the same time. Changes in orientation will be applied to all selected images
Camera and Lens Tab
The lens tab looks a lot like the Images tab, except that the lens settings can be edited here. As in the Images Tab, multiselection can be used to change the parameters for multiple images.
Panorama Tools and hugin allow the usage of images shot with different lenses and settings inside the same project. Each image is associated with a lens number. All images that share the same lens number use the same lens type, and may be forced to share the same lens parameters.
The most important parameters are the Lens type and the hor. field of view. hugin support the following projections in input images:
- rectilinear This is the projection used by most cameras. It keeps straight lines straight. The maximum horizontal field of view is 180 degrees (for an image of infinite size, that is).
- Panoramic is used by panoramic cameras, such as the Horizon, Roundshot and Spheron cameras. This projection is also called cylindrical projection.
- Circular fisheye This is projection is used by fisheye lenses. If the image is circular, or the corners of the image are black, use this type of fisheye lens. A circular crop (see Cropping can be used for cutting away the edge borders.
- Full frame fisheye Exactly the same projection as above, but the crop option will crop to an rectangle instead of a circle. This should be used for full frame fisheye images.
After the lens type has been specified, an estimate for the horizontal field of view (HFOV) is required. The HFOV specifies the horizontal opening angle of the image in degrees. Since most photographers are more familar with focal length as a measure for the HFOV, it can be entered into hugin, and hugin will compute the HFOV from it. For this calculation the actual focal length and the crop factor of the camera are required. If the 35mm film equivalent focal length is known, a crop factor of 1 should be used.
In case of jpeg images, hugin can usually automatically calculate the HFOV based on the EXIF information.
Usually lenses do not project images exactly according to the selected projection type, but suffer from distortions. In many cases the distortions are acceptable for single image shots, but they need to be corrected when stitching a panorama. The a,b and c parameters are used to remove that distortion. They are applied radially from the image center, which can be moved by changing the d and e parameters. TODO: link to distortion model
Scanned images might also suffer from image shearing. This can be corrected using the g and t parameters.
The distortion parameters usually vary with the focal length, and to a lesser degree with the focus. The link checkbox indicates wether the parameter is linked or not. A linked parameter is forced to the same value for all images with the same lens number. This is the default for the HFOV and distortion parameters. If a parameter is not linked each images is allowed to have individual values for the respective parameter. This is useful if a different zoom or focus setting has been used for some images. If scanned images are used, they are usually not perfectly centered, and each image should have individual d and e parameters.
The photometric corrections include vignetting correction and color/brightness adjustment. TODO: document
Control Point Tab
Control points a central to Panorama Tools and hugin, because they are used to estimate the position of image position and lens parameters described above. A control point specifies a corresponding point between two images. Using these corresponding points, the optimizer can estimate the image position and lens parameters. It is therefore important that the control points are accurate and usually at least 3 well distributed control points should be used to estimate the image position (yaw, roll and pitch) and maybe the HFOV. For accurate estimation of the a,b,c distortion parameters, many well distributed control points, and a large overlap (up to 50%) are required.
The Tab consists of two image displays and tab bars to switch images to be editied. The bottom contains a list view where Points can be selected and some fields to edit a selected point. Points can also be selected by clicking or dragging on them in the images. It is possible to zoom out to show the full image.
Adding a control point works by selecting one point in the left or right image, and then clicking onto the corresponding point in the other image. If auto add is not set, the points can be moved by clicking at some other place in the images. They are added to the list of control points by pressing the right mouse button, the "a" key or by pushing the Add button or by pushing the Add button. If you press the right mouse button when only one point is slected, the point selection will be aborted. auto add adds the control point as soon as both points have been specified.
If the images are zoomed out (fit to window), the first click zooms to a temporary 100% view to give you the chance to refine your selection. Note that only the second click will trigger the auto estimate.
Often it is hard to select the corresponding point exactly. However, the control points should be as accurate as possible, for good results. Once a point pair has been roughly selected, the fine tune function of hugin can be used to estimate the corresponding point up to one tenth of a pixel. The keyboard shortcut for the fine tune function is the f key. Fine tune only search in a small neighbourhood of the currently selected points. The size of this neighbourhood can be controlled by opening the preferences panel and setting the "Local area search width".
Note that the fune tune function estimates the translation of the patch around the point selected in the other image with respect to the current image. This works well if the rotation between the images is small and narrow angle lenses have been used. If wide angle or fisheye images are used, rotation search should be activated in the preferences panel. Then hugin also searches for rotated occurences of the patch around the selected point.
The image can be scrolled by pressing the middle mouse button or the CTRL key while moving the mouse. If the shift key is pressed instead, both images will be scrolled. This is very useful, if control points are set using the 100% zoom level.
Control point creation is also influenced by the following checkboxes:
- auto fine tune hugin helps you to find the second point by looking for it in a search region (shown by a rectange around the cursor). This might not always work, but usually is reliable, if the image distortions are not too big. Try and play with it.
- auto add A control point is automatically added when both points are know. You won't have time to refine the selection before adding the point.
- auto estimate Tries to estimate the position of the second point by estimating the translation between the two images. This is very crude and probably only works for single row panoramas created from rectilinear images.
All these flags can be combined. I typically use auto fine tune and auto estimate at the same time. Then hugin usually automatically selects the second point correctly, at least for normal, rectilinear images that are not rotated too much.
hugin also includes an experimental control point creation algorithm. It can be invoked by pressing the "g" key. Corners in the currently selected image are detected, and corresponding control points are set, based on the
Here is a summary of the keyboard shortcuts available in the Control Point tab:
Key | Function |
---|---|
a | add a new point that has been selected in both images, and the auto add is switched off. |
cursor keys | scroll image under the mouse cursor |
shift + cursor keys | scroll both images at the same time |
f | fine tune currently selected control point pair. Same as the Fine Tune button |
g | experimental control point generation algorithm. |
Del | Remove currently selected control point. |
0 | Zoom out to full view. |
1 | 100% view. |
Mouse function | Function |
---|---|
control key + mouse movement | Scroll image under cursor |
shift key + mouse movement | Scroll both images |
left button | Use left mouse button to select new points or drag existing points. |
right mouse button | Add control point, if auto add is switched off |
middle mouse button | Scroll image under cursor |
shift + middle mouse button | Scroll both images |
Optimizer Tab
The optimizer moves the images into the right position, so that they can be assembled into a hopefully seamless panorama.
To select what the optimiser should try to estimate, use the Optimize combo box, then click the Optimize Button. If you select the "custom" setting, you can change
Pano Panel
Options concerning the output panorama can be set here. FIXME, write some more...
This document was written by Pablo d'Angelo <pablo.dangelo@web.de>