<?xml version='1.0' ?> 
  <sect1 id="using" xreflabel="Using the plug-in">
    <title>Using the plug-in</title>
  <para>You can start the plug-in by clicking with the right
    mouse-button in the image, and then select from the
    <guibutton>Filters</guibutton> menu <guibutton>Enhance/Refocus</guibutton>.</para>
    <para>The plug-in window looks something like this:</para>
    <mediaobject>
      <imageobject>
        <imagedata fileref="images/gui.png"/>
      </imageobject>
    <textobject>
      <phrase>GUI screen dump</phrase>
    </textobject>
    </mediaobject>
    <para>The plug-in window contains a preview of the image on the left
    and on the right a set of
    spin-buttons to change its parameters. 
    </para>
    <para>
     The bottom of the preview contains the following buttons:
      <variablelist>
        <varlistentry>
          <term><guibutton>OK</guibutton></term>
          <listitem>
            <para>Quit the plug-in and apply the selected transformation to
            the image.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guibutton>Defaults</guibutton></term>
          <listitem>
            <para>Select default values for all parameters.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guibutton>Preview</guibutton></term>
          <listitem>
            <para>Compute the new transformation matrix and show the results in the
            preview. 
            Because computing the transformation matrix can take a lot of time, it
            is not automatically recomputed, when the parameters in the
            spin-buttons have changed.
            When you have changed parameters the <guibutton>Preview</guibutton> button
            will change to active, i.e. it is no longer grayed out. 
              <warning>
                <para>When the plug-in starts it shows the original untransformed
                image.
                When you press the <guibutton>Preview</guibutton> button the
                transformation matrix is computed and the transformed image
                will be shown in the preview.
                </para>
              </warning>
              </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guibutton>Cancel</guibutton></term>
          <listitem>
            <para>Quit the plug-in without applying the selected transformation to
            the image.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <sect2>
      <title>The preview</title>
      <para>The preview allows you to preview the output of the plug-in.</para>
      <para>
     You can scroll the preview by pressing the first mouse-button and dragging in the
     preview. During scrolling, the original unprocessed image will be shown, because
     the plug-in is not fast enough to compute the processed image. When you
     release the mouse-button the plug-in will start computing the processed image.
     Immediately below the preview is a progress-bar that shows the plug-in's progress.
      </para>
      <para>You can scale (or zoom) the image with the <guibutton>+</guibutton> and
      <guibutton>-</guibutton> buttons under the preview. 
       When you zoom out the plug-in has to render a larger area which takes more time.</para>
      <para>The size of the preview can be changed by dragging the paned widgets below and to the right of the preview.
      These widgets are marked with "....".
      </para>
    </sect2>
    <sect2>
      <title>The parameters</title>
      
      <para>The plug-in has the following parameters:
      <variablelist>
          <varlistentry>
            <term><parameter>Matrix Width</parameter></term>
            <listitem>
              <para>This parameter determines the size of the transformation matrix.
              Increasing the <parameter>Matrix Width</parameter> may give better results,
              especially when you have chosen large values for <parameter>Radius</parameter> or <parameter>Gauss</parameter>.
              Note that the plug-in will become very slow when you select large
              values for this parameter.
              In most cases you should select a value in the range 3-10.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>Radius</parameter></term>
            <listitem>
              <para>This is the <parameter>Radius</parameter> of the circular convolution.
              This is probably the most important parameter for using the plug-in.
              For normal images, the default value of 1 should give good results.
              Select a higher value when your image is very blurred.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>Gauss</parameter></term>
            <listitem>
              <para>This is the radius for the Gaussian convolution.
              Use this parameter when you blurring is Gaussian.
              In most cases you should set this parameter to 0, because it causes nasty artifacts.
              When you use non-zero values you will probably have to increase the <parameter>Correlation</parameter> and/or <parameter>Noise</parameter> parameters, too.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>Correlation</parameter></term>
            <listitem>
              <para>Increasing the <parameter>Correlation</parameter> may help reducing artifacts.
              The correlation can range from 0-1.
              Useful values are 0.5 and values close to 1, e.g. 0.95 and 0.99.
              Using a high value for the correlation will reduce the sharpening effect of the plug-in.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>Noise</parameter></term>
            <listitem>
              <para>Increasing the <parameter>Noise</parameter> parameter may help reducing artifacts.
              The <parameter>Noise</parameter> can range from 0-1. When the <parameter>Noise</parameter> value is to low, e.g.
              0 the image quality will be horrible. A useful value is 0.01.
              Using a high value for the <parameter>Noise</parameter> will reduce the sharpening effect of the plug-in.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
</para>
    </sect2>
    <sect2>
      <title>Tips and tricks</title>
      <para>
      This section describes a few hints to help you work with the &prog;
      plug-in.
      </para>
      <sect3>
        <title>General</title>
        <para>Perform all color corrections on the image before using
        this plug-in.</para>
        <para>In many cases you should use this plug-in before performing
        other operations on the image.
        The reason is that many operations on
        the image will leave boundaries that are not immediately visible
        but that will leave nasty artifacts.</para>
        <para>When you are scanning images and compress them, e.g. to jpg,
        you should use the plug-in on the uncompressed image.
        </para>
      </sect3>
      <sect3>
        <title>Performance</title>
        <para>The performance of the plug-in when you are previewing depends
        heavily on the <parameter>Matrix Width</parameter>, the size of the preview and the scale of the
        preview.</para>
        <para>The execution time for transforming the image depends quadratically
        on the <parameter>Matrix Width</parameter>.
        So when you double the <parameter>Matrix Width</parameter>, it takes four times as long to
        process the image.
        Values in the range of 3-8 usually give good results.</para>
        <para>The plug-in has to transform the entire part of the image
        that is shown in the preview. Using a smaller preview and/or a larger
        scale will improve the plug-in's performance.</para>
        <para>The time needed for computing the transformation matrix
          after you have pressed the <guibutton>Update</guibutton> button depends
          dramatically on the <parameter>Matrix Width</parameter>. Using a smaller value for <parameter>Matrix Width</parameter>
          will give you much better performance for this part of the computations.
          You should also consider using ATLAS (see <xref linkend="atlas"/>).
          </para>
      </sect3>
    </sect2>
  <sect2>
    <title>Technical background</title>
    <para>A wide range of image transformations
      can be described mathematically as convolutions.
    A convolution is a linear transformation where each
    destination pixel is the weighted sum of the pixels in
    the neighborhood of the original pixel.</para>
    <para>For example, the following matrix describes the convolution
    where each pixel is the average of the source pixel and its 8
    immediate neighbors:</para>
    <informaltable frame="none" colsep="0" rowsep="0">
      <tgroup cols="3">
        <tbody>
          <row>
            <entry>1/9</entry>
            <entry>1/9</entry>
            <entry>1/9</entry>
          </row>
          <row>
            <entry>1/9</entry>
            <entry>1/9</entry>
            <entry>1/9</entry>
          </row>
          <row>
            <entry>1/9</entry>
            <entry>1/9</entry>
            <entry>1/9</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>A wide range of image degradations, e.g. bad focusing and motion blur, can adequately be described with convolutions. </para>
    <para>In this case we are interested in undo-ing the effect of a
      convolution. Using Fourier analysis it is possible to show that for
      each convolution there exists an inverse convolution. </para>
    <para>
      Unfortunately, this inverse convolution is of little practical use.
      The reason is that image transformations virtually always introduce
      some form of error, e.g. due to noise in the scanner or simply
      round-off errors. The unmodified inverse convolution greatly
      amplifies these errors. In many cases the result of the
      inverse convolution is completely dominated by the noise.
      If you want to get a feeling what this means, run the plug-in
      with <parameter>Gauss</parameter> = 2 and <parameter>Correlation</parameter> and <parameter>Noise</parameter> = 0.
    </para>
    <para>A standard solution is to use Wiener filtering. Wiener filtering
      finds an inverse convolution that attempts to minimize noise.
      Normally Wiener filtering is implemented with Fourier transforms.
    </para>
    <para>Standard Wiener filters have two disadvantages for our purpose:</para>
    <itemizedlist>
      <listitem>
        <para>The memory requirements are high.The Fourier transform of the image requires two floating point numbers for each pixel.</para>
      </listitem>
      <listitem>
        <para>Wiener filtering is a global transform. 
          The results for a specific region can be influenced by completely unrelated regions in the image. 
          During experiments with Wiener filtering I found that this
          frequently produces unexpected and undesirable results.
        </para>
      </listitem>
    </itemizedlist>
    <para>The &prog; plug-in is based on a modified form of the Wiener
    filter, called the FIR (Finite Input Response) Wiener filter.
      A FIR Wiener filter only uses a limited neighborhood of the
      source pixels and can be easily implemented as a convolution
      matrix.
    </para>
    <para>FIR Wiener filtering has the following advantages:</para>
    <itemizedlist>
      <listitem>
        <para>Low memory requirements. Only the convolution matrix must be
        stored.</para>
      </listitem>
      <listitem>
        <para>Ease of implementation. There is no need to do a full
        Fourier transform.</para>
      </listitem>
      <listitem>
        <para>The transformation is local. The results only
        depend on a small neighborhood of the original pixel.</para>
      </listitem>
    </itemizedlist>
    <para>For technical background on the FIR Wiener deconvolution see
      <xref linkend="Jain89"/>.</para>
    <sect3>
      <title>Modeling the convolution</title>
      <para>In most cases you don't know precisely what convolution
        caused the image degradation.
        There are two convolutions that are frequently used to
        model image degradation:
        <itemizedlist>
          <listitem>
            <para>The <emphasis>Gaussian</emphasis> convolution</para>
          </listitem>
          <listitem>
            <para>The <emphasis>Circular</emphasis> convolution</para>
          </listitem>
        </itemizedlist>
        </para>
      <sect4>
        <title>The Gaussian convolution</title>
        <para>
        The Gaussian convolution is mathematically similar to the
        normal distribution, with its bell-shaped curve.
        From a theoretical point of view the mathematical justification
        for using the Gaussian convolution is that when you a apply
        a large number of independent random convolutions the results
        will always approach a Gaussian convolution.
        </para>
      </sect4>
      <sect4>
        <title>The circular convolution</title>
        <para>The circular convolution spreads each source point
        uniformly across a small disk with a fixed radius.
          Technically this describes the effects of using
          a (ideal) lens that is not correctly focused.
        </para>
      </sect4>
      <sect4>
        <title>Convolutions in the plug-in</title>
        <para>
        The &prog; plug-in supports both the Gaussian and the circular
        convolution plus mixtures of both.
        </para>
        <para>The <parameter>Radius</parameter> parameter determines
          the radius of the circular convolution. 
          The <parameter>Gauss</parameter> parameter determines
        the width of Gaussian convolution.</para>
        <para>The actual convolution that is used by the plug-in
        is in fact the result of convolving both the Gaussian and
        the circular convolution with one another.
          Both of these convolutions are identical to the identity
          convolution when their parameter is equal to 0.
          Therefore, when the <parameter>Gauss</parameter> parameter
          equals 0, the result is a circular convolution, and 
          likewise when the <parameter>Radius</parameter> equals
          0 the result is a Gaussian convolution.
        </para>
        <para>In practice, I found that in most cases the circular
        convolution works much better than the Gaussian convolution.
          The Gaussian convolution has a very long tail, so mathematically
          the result of the convolution also depends on source pixels
          at a large distance from the original source pixel.
          The FIR Wiener inverse of a Gaussian convolution in
          most cases is heavily influenced by source pixels at a large
          distances, and in most cases this produces undesirable results.
        </para>
        <para>The circular convolution generally produces much better
          results. One reason is that the FIR Wiener inverse of the
          circular convolution in general influenced by source pixels
          in the immediate neighborhood of the original source pixel.
          Another reason is that a circular convolution is theoretically
          a good mathematical model for images that are slightly unfocused.
        </para>
      </sect4>
      <sect4>
        <title>Comparison with other techniques</title>
        <para>Two other techniques that are frequently used to enhance
        images are:</para>
        <itemizedlist>
          <listitem>
            <para>Sharpening</para>
          </listitem>
          <listitem>
            <para>Unsharp mask</para>
          </listitem>
        </itemizedlist>
        <para>Sharpening applies a small convolution matrix that
        increases the difference between a source pixel and its
        immediate neighbors. FIR Wiener filtering is a more
        general technique because it allows a much larger neighborhood 
          and better parameterizations.
          Sharpening only works when your images are very slightly
          blurred. 
          Furthermore, for high values of the sharpening parameter
          the results frequently look "noisy". 
          With FIR Wiener filtering this noise can be greatly reduced
          by selecting higher values for the <parameter>Correlation</parameter>
          and <parameter>Noise</parameter> parameters.
        </para>
        <para>Unsharp masking is another very popular image enhancement technique. 
          From a mathematical point of view its justification is a bit
          obscure but many people are very fond of it.
          The first step is to blur the source image, hence the name 
          <emphasis>unsharp</emphasis> masking. Then the difference
          between the source image and the blurred image is subtracted
          from the source image.
        </para>
        <para>In general, unsharp masking produces better results
          than sharpening. 
          This is probably caused by the fact that unsharp masking
          uses a larger neighborhood than sharpening.
        </para>
        <para>From a theoretical point of view unsharp masking
        must always introduce artifacts. Even under optimal
        circumstances it can never completely undo the effect of
        blurring. For Wiener filtering it is possible to prove
        that it is the optimal linear filter.</para>
        <para>In practice I found that in virtually all cases
          the results of the FIR Wiener filter were at least
          as good as those of unsharp masking. The FIR Wiener filter
          is frequently better in restoring small details.
        </para>
        <para>As a side note, unsharp masking generally uses
        a Gaussian convolution, I suspect that in some cases
        a circular convolution should give better results.</para>
      </sect4>
    </sect3>
  </sect2>
    <bibliography>
      <biblioentry id="Jain89" xreflabel="[Jain89]">
        <title>Fundamentals of Digital Image Processing</title>
        <author>
          <firstname>Anil K.</firstname>
          <surname>Jain</surname>
        </author>
        <publisher>
          <publishername>Prentice Hall</publishername>
        </publisher>
        <pubdate>1989</pubdate>
      </biblioentry>
    </bibliography>
  </sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("doc.xml" "sect1")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->