  <sect3 id="editor-enhance-distortion" >
    <sect3info>
      <title>Lens Distortion Correction</title>
      <abstract>
        <para>
&digikam;
The  <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>Digikam</keyword>
      </keywordset>
    </sect3info>
    <title>Introduction</title>
    <anchor id="lensdistortion.anchor" />
    <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 images. 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 tool.
</para>
    <note>
      <para>
This tool treats the geometrical distortions. Chromatic aberrations will not be corrected by this tool.
</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>
    <para>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="&path;editor-distortions.png" format="PNG" />
        </imageobject>
        <textobject>
          <phrase>Lens Distortion Types</phrase>
        </textobject>
      </inlinemediaobject>
    </para>
    <para/>
    <sect4 id="using-lensdistortion" >
      <title>Using the lens distortion tool</title>
      <note>
        <para>
A bit of explanation first. The geometrical corrections use 4th-order polynomial coefficients.
    <itemizedlist>
            <listitem>
              <para>The 1st-order coefficient changes the size of the image. The tool 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 tool.</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>
      <para>
        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="&path;editor-lensdistortion.png" format="PNG" />
          </imageobject>
          <textobject>
            <phrase>Lens Distortion Correction Dialog</phrase>
          </textobject>
        </inlinemediaobject>
      </para>
      <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 center. 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 widget 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 tool.
</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 &LMB; 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 images, 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>
    </sect4>
    <sect4 id="inaction-lensdistortion" >
      <title>The lens distortion tool 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>
      <para>
        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="&path;editor-lensdistortion-preview.png" format="PNG" />
          </imageobject>
          <textobject>
            <phrase>Lens Distortion Correction Preview</phrase>
          </textobject>
        </inlinemediaobject>
      </para>
    </sect4>
  </sect3>

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