“Geometry” Processing Tab

Lensfun is a set of filters dealing with errors and distortions introduced by imperfect lenses – and no lens is perfect. Lensfun is used to

• correct lateral/transversal chromatic aberration,
• correct vignetting,
• correct geometric distortions like barrel, pincushion or mustache distortion,
• convert between lens geometries, e.g. from fisheye to normal rectilinear.

In Photivo the whole of Lensfun is split up into four processing tools and one configuration tool that affects all the others. All have Lensfun in their caption.

The Lens Parameters (Lensfun) tool contains the global Lensfun configuration. The values you set here affect all the other tools simultaneously.

Focal length (35mm equiv.) represents the focal length the image was taken with, if necessary converted to its 35mm film equivalent. So if you took the picture with a 14mm lens and your camera has a crop factor of 1.5 – which is very common for digital SLR cameras – the correct value for the Focal length field is 14 × 1.5 = 21mm. Photivo tries to set this value automatically from the image’s Exif data.

Aperture is the aperture (f-stop) the image was shot with. Photivo sets this value automatically if it is present in the image’s Exif data.

Distance is the distance to the subject of the image. The Lensfun documentation is not very specific about this value. I assume it is the distance between the camera and the main subject of the image in meters. However it does not seem to have a major influence on the results.

Scale is used to adjust the image scale. After a distortion correction and/or geometry conversion the dimensions of the input might not be the same as the pipe size dimensions. Scale lets you adjust how much of the corrected image you lose. See the following figure for an illustration of what happens.

On the left you see the the input image. On the right is the output after applying Lensfun distortion correction and/or geometry conversion. The red rectangle represents the pipe size. The correction/conversion is likely to produce an output image that is larger or smaller than the pipe size dimensions. In our example it is larger (green box). Since Photivo treats the pipe size dimensions as the definite image boundaries, everything outside the red box gets chopped off.

This is where the Scale slider comes in. It changes the size of the green box. Effectively it lets you control how much of the corrected/converted output image actually appears inside the pipe size boundaries and therefore is visible and usable by the filters further down the processing pipe.

Output images smaller than the pipe size (green box smaller than red box) do not change that logic. The unused pipe size area is just filled with black.

If the Auto scale checkbox is active, Lensfun tries to set the scale factor in such a way as to fit as much image area as possible into the pipe size box without creating black borders.

The Chromatic Aberration (Lensfun) tool corrects lateral/transversal chromatic aberration. CA correction depends on the focal length value from the Lens Parameters tool.

Model sets the mathematical model used to correct CAs. None means CA correction is disabled. Each model has a set of parameters. Those appear as sliders below the combo box and adjust according to the model you choose. The values represent parameters in a (set of) mathematical equations and don’t really have an easily explained individual meaning for the output. Just play around with the values until you are satisfied with the result.

The Vignetting (Lensfun) tool corrects vignetting. Vignetting correction depends on the focal length, aperture and distance values from the Lens Parameters tool.

Model sets the mathematical model used to correct vignetting. None means the correction is disabled. Each model has a set of parameters. Those appear as sliders below the combo box and adjust according to the model you choose. The values represent parameters in a (set of) mathematical equations and don’t really have an easily explained individual meaning for the output. Just play around with the values until you are satisfied with the result.

The Lens Distortion (Lensfun) tool corrects geometric distortion like barrel, pincushion or mustache distortion. Distortion correction depends on the focal length value from the Lens Parameters tool.

Model sets the mathematical model used to correct distortions. None means the correction is disabled. Each model has a set of parameters. Those appear as sliders below the combo box and adjust according to the model you choose. The values represent parameters in a (set of) mathematical equations and don’t really have an easily explained individual meaning for the output. Just play around with the values until you are satisfied with the result.

The Geometry Conversion (Lensfun) tool converts between different lens geometries. Its main purpose is to straighten the bended lines produced by a fisheye lens. Like the distortion correction geometry conversion depends on the focal length value from the Lens Parameters tool.

Source geometry is the geometry of the lens the picture was taken with. Target geometry is the lens geometry you want to convert to. If source and target are the same, Photivo skips the tool when processing the pipe, i.e. no conversion takes place.

• Unknown stands for an unknown or just not specified lens geometry. If either source or target is Unknown, Photivo skips the tool and no conversion is performed.
• Rectilinear stands for the normal type of lens that keeps straight lines (like a building corner) straight in the image but may distort angles. Usually this is the geometry you want your final result to have.
• Fisheye lenses bend straight lines into curves. Generally, the shorter the focal length, the stronger the bending effect.
• Panoramic stands for special lenses used in panoramic photography.
• Equirectangular represents the equirectangular projection. No such lenses exist, but using them as source or target might give interesting effects.

Defish is a specialised version of the Lensfun geometry conversion. It is used to “defish” images taken with a fisheye lens, i.e. straighten the bent fisheye lines which results in an image with normal rectilinear geometry.

Enable activates or deactivates the Defish tool.

Focal length (35mm equiv.) represents the focal length the image was taken with, if necessary converted to its 35mm film equivalent. So if you took the picture with a 14mm lens and your camera has a crop factor of 1.5 – which is very common for digital SLR cameras – the correct value for the Focal length field is 14 × 1.5 = 21mm. Photivo tries to set this value automatically from the image’s Exif data.

Scale is used to adjust the image scale. After a distortion correction or geometry conversion parts of the corrected/converted image might lie outside the bounding box defined by the pipe size. Everything outside that box gets chopped off. Scale lets you adjust how much of the corrected image you lose. If the value is 0.0 or the Auto scale checkbox is active, Lensfun tries to set the scale factor in such a way as to fit as much image area as possible into the bounding box without creating black borders.

With the Rotation and Perspective tool you rotate the image or tilt and turn (perspective correction) it.

The Crop tool crops out rectangular regions from the source image.

The Crop checkbox enables and disables the current crop. If no previously selected crop region is available, Photivo automatically enters cropping mode. This mode is also activated by the Make a crop button to the right of the checkbox.

Enabling Aspect Ratio restricts the shape of the cropped image region to a certain aspect ratio. You can set this ratio with the W (width) and H (height) comboboxes.

The Guidelines combobox below displays common guiding lines used for image composition; for example the “rule of thirds” lines or image diagonals.

Making a crop:

• When entering crop mode all filters are disabled and the image is zoomed so that it completely fits into the viewport. The Make a crop button is replaced by the Confirm crop and Abort crop buttons. You can change the inital zoom behaviour in the Crop tab on the Settings page.
• If you did not crop the current image before, the initial crop rectangle contains the full image (if permitted by the aspect ratio setting). Otherwise crop mode starts with the previous crop rectangle.
• Adjust the rectangle’s size and position with the mouse. When you move your mouse over different parts of the rectangle the mouse cursor changes according to the action that is possible there.
  • Drag the corners with the left mouse button to change the size of both adjacent edges simultaneously. Drag the edges to change only the width or height of the rectangle.
  • Drag the center to move the rectangle around without changing its size.
  • Crop works on all zoom levels. If the image is too large to fit into the viewport completely and you want to drag it to make another part of the image visible, hold down the Ctrl key.
  • Pressing the Alt key cycles through “LightsOut” modes. Changing the LightsOut combo box does the same. There are three modes: None just displays the rectangle (and guidelines) on top of the image. Dimmed additionally dims the image outside the rectangle. Black completely blacks out areas outside the rectangle and also does not show the rectangle borders or guidelines. That way you have an distraction-free preview of your current crop.
  • You can also change the guidelines or aspect ratio restriction at any point during cropping.

• When you are satisfied with your crop selection, click the Confirm crop button or press Enter or double click inside the crop rectangle.
• Click the Abort crop button or hit Esc to cancel the crop. Photivo will return to the previous crop (if there is one) or the uncropped image.

Seam carving allows you to rescale and change the aspect ratio of your image while preserving important image features and avoiding distorted proportions as would happen with normal non-proportional rescaling. The Wikipedia article on seam carving gives a good explanation.

Photivo uses Liquid Rescale for seam carving. The tool lets you choose the type of energy evaluation function and of course the amount of rescaling.

Energy evaluation functions are different methods to search for rescaling seams in the image.

• Directional grad brightness: absolute value of the brightness gradient in the direction of the rescaling
• Average grad brightness: sum of absolute values of the brightness gradients in both directions
• Norm brightness: norm of the brightness gradient
• Directional grad luminance: absolute value of the luminance gradient in the direction of the rescaling
• Average grad luminance: sum of absolute values of the luminance gradients in both directions
• Norm luminance: norm of the luminance gradient

It is hard to predict which function produces the best results for a particular image, so just play around with them till you like the result.

Scaling sets the scaling mode. With Relative you choose a percentage based on the current image size. With Absolute you specify the target width and height in pixels.

The Vertical first checkbox controls which dimension is rescaled first. Usually Photivo rescales horizontally first, then vertically. Enable Vertical first to revert this order.

The Resize tool changes the image’s size. Resizing is always proportional, i.e. the aspect ratio stays the same.

Check the Resize checkbox to enable resizing. With Size you set the output size in pixels of the longer image dimension. I.e. Size sets the output width for images with landscape orientation (wider than high) and the output height for images with portrait orientation (higher than wide).

The Filter combobox lets you choose the resize algorithm. Resizing is done through GraphicsMagick and all of GraphicsMagick’s filters are available. It is probably safe to stay with Mitchell or Lanczos3.

Automatic pipe size automatically matches pipe size and output resolution to avoid unnecessarily large pipe sizes and save processing time. It uses the smallest possible pipe size that is still larger than the specified output size of the resize tool.

The Flip tool allows you to flip your image either along the horzontal or the vertical axis.

When the Block pipe checkbox is enabled, all the tabs from RGB to EyeCandy will not be processed, i.e. only Camera, Geometry and Output stay active. This tool is mostly there as a convenient way to temporarily disable a heavy processing pipe when you want to adjust settings on the early tabs.