<chapter id="lensdistortion">
<chapterinfo>

<title>Lens Distortion Correction</title>

<authorgroup>
    <author>
        <firstname>Gilles</firstname><surname>Caulier</surname>
        <affiliation><address><email>caulier dot gilles at free.fr</email></address></affiliation>
    </author>
    
    <author>
        <firstname>Gerhard</firstname><surname>Kulzer</surname>
        <affiliation><address><email>gerhard at kulzer.net</email></address></affiliation>
    </author>
</authorgroup>

<abstract>
<para>
The digiKam image plugin <emphasis>Lens Distortion</emphasis> is a tool to correct spherical lens aberrations on the photos. It uses an algorithm copyrighted by David Hodson.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Digikam</keyword>
</keywordset>

</chapterinfo>

<title>Introduction</title>

<para>
<emphasis>Barrel distortion</emphasis> is associated with wide angle (or minimal zoom) lenses. It causes the images to appear slightly spherical (curved outward) like a barrel. You can notice this when you have straight features close to the image's peripheral sides. <emphasis>Pincushion distortion</emphasis> is the opposite defect and is associated with Telephoto lenses (maximum zoom) or underwater pictures. The images appear pinched (bent inward) toward the center. The Pincushion is often less noticeable than barrel but are equally visible near the edges. These distortions can easily be eliminated without visible loss in quality with this plugin. 
</para>

<note><para>
This plugin treats the geometrical distortions. Chromatic abberations will not be corrected by this plugin.
</para></note>

<para>
The following figures explain the main types of geometrical distortions:
<itemizedlist>            
    <listitem><para>(1): pincushion distortion.</para></listitem>
    <listitem><para>(2): no distortion.</para></listitem>
    <listitem><para>(3): barrel distortion.</para></listitem>
</itemizedlist>    
</para>

<figure>
    <title>Lens Distortion Types</title>
    <graphic srccredit="Lens Distortion Types" fileref="distortions.png"/>
</figure>

<para>
</para>

<sect1 id="using-plugin-lensdistortion">
<title>Using the plugin</title>

<note><para>
A bit of explanation first. The geometrical corrections use 4th-order polynominal coefficients.
    <itemizedlist>
        <listitem><para>The 1st-order coefficient changes the size of the image. The plugin calls this <guilabel>Zoom</guilabel>.</para></listitem>
        <listitem><para>The 2nd-order coefficient treats the main geometrical distortion of lenses and can correct the convex or concave shape of the image.</para></listitem>
        <listitem><para>The 3rd-order coefficient has a similar rounding effect but levels off towards the edges. This correction is not employed in the plugin.</para></listitem>
        <listitem><para>The 4th-order coefficient corrects the far edges inversely to the 2nd-order rounding. Combining it with the 2nd-order correction the geometrical distortions can be almost completely eliminated.</para></listitem>
    </itemizedlist>
</para></note>

<figure>
    <title>Lens Distortion Correction Dialog</title>
    <graphic srccredit="Lens Distortion Correction Dialog" fileref="lensdistortiondialog.png"/>
</figure>

<para>
Four sliders let you set the distortion correction filter:
</para>

<para>
<guilabel>Main</guilabel>: this value controls the amount of 2nd-order distortion. Negative values correct barrel distortions, while positive values correct pincushion distortion.
</para>

<para>
<guilabel>Edge</guilabel>: this value controls the amount of 4th-order distortion. The Edge control has more effect at the edges of the image than at the centre. For most lenses, the <guilabel>Edge</guilabel> parameter has the opposite sign of the <guilabel>Main</guilabel> parameter.
</para>

<para>
<guilabel>Zoom</guilabel>: this value rescales the overall image size (1st-order correction). Negative values zoom out of the image, while positive values zoom in.
</para>

<para>
<guilabel>Brighten</guilabel>: this control adjusts the brightness in image corners. Negative values decrease the brightness image corners, while positive values increase it.
</para>

<para>
To help you to choose the best filter settings, the plugin dialog illustrates with a thumbnail preview the distortion correction applied to a crossed mesh pattern. The values you apply to your image will be saved and come up with the same values as default the next time you call the plugin.
</para>

<note><para>
The barrel-pincushion correction should be done before any crop or size changes (including perspective correction). In fact the Barrel-Pincushion corrections should be the very first step on the original image. If you crop the image and then use barrel correction the effect would be obviously wrong.
</para></note>

<para>
To help you finding the best correction the tool provides a vertical and horizontal guide. Move the mouse cursor in the image preview to display the dashed lines guide. Move the cursor to an important place in the image like the sea level or a building border and press the left mouse button for freeze the dashed lines position. Now, adjust the barrel/pincushion correction to align with the guide.
</para>

<para>
When using pincushion correction the resulting image will have a black border in the corner. You will need to cut this out with a crop tool available in <menuchoice><guimenu>Transform</guimenu><guimenuitem>Crop</guimenuitem></menuchoice> Image Editor menu or via the zoom slider of this dialog.
</para>

<para>
On most images using the barrel correction is enough, however with some shots such as front pictures, frames, paintings, the next logical step is to use perspective correction to make all the angles 90 degrees. Note that when you hold your camera by hand you almost always introduce some kind of slight perspective distortion.
</para>

</sect1>

<sect1 id="inaction-plugin-lensdistortion">
<title>The plugin in action</title>

<para>
This is an example of a barrel correction applied to church in north Norway. The original image is (1), the corrected image (2).
</para>

<para>
The values used for this example are:
<itemizedlist>            
    <listitem><para>Main     = -40.</para></listitem>
    <listitem><para>Edge     = 0.</para></listitem>
    <listitem><para>Zoom     = -20.</para></listitem>
    <listitem><para>Brighten = 0.</para></listitem>
</itemizedlist>    
</para>

<figure>
    <title>Lens Distortion Correction Preview</title>
    <graphic srccredit="Lens Distortion Correction Preview" fileref="lensdistortionpreview.png"/>
</figure>

</sect1>

</chapter>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->

