<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry version="5.0-subset Scilab" xml:id="imnoise" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <pubdate>July, 2006</pubdate>
  </info>

  <refnamediv>
    <refname>imnoise</refname>

    <refpurpose>Add noise (gaussian, etc.) to an image</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>imn = imnoise(im, type [,parameters])</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>im</term>

        <listitem>
           Input image. 
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>type</term>

        <listitem>
           String having one of these values: 

          <variablelist>
            <varlistentry>
              <term>'salt &amp; pepper'</term>

              <listitem>drop-out/On-off noise</listitem>
            </varlistentry>

            <varlistentry>
              <term>'speckle'</term>

              <listitem>multiplicative noise</listitem>
            </varlistentry>

            <varlistentry>
              <term>'gaussian'</term>

              <listitem>Gaussian white/additive noise</listitem>
            </varlistentry>

            <varlistentry>
              <term>'localvar'</term>

              <listitem>Pixel-specific variance (Zero-mean
              Gaussian)</listitem>
            </varlistentry>

            <varlistentry>
              <term>'poisson'</term>

              <listitem>Not yet implemented</listitem>
            </varlistentry>
          </variablelist>

           
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>parameters</term>

        <listitem>
           A sequence of parameters to control the noise distribution, depending on the chosen type. If omitted, default values are used (see below). 
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>imn</term>

        <listitem>
           Noisy image, which has the same size and type as input image 

          <literal>im</literal>

          . 
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>

    <para><literal>imnoise(im, type [, parameters])</literal> adds a type of
    noise to the intensity image <literal>im</literal>. Optionally, you can
    control the noise parameters starting at the 3rd. Argument to imnoise.
    Here are example of noise types and their parameterss:</para>

    <para><literal>imn = imnoise(im,'salt &amp; pepper',d)</literal> adds
    drop-out noise, where <literal>d</literal> is the noise density
    (probability of swapping a pixel). (default: d=0.05).</para>

    <para><literal>imn = imnoise(im,'gaussian',m,v)</literal> adds Gaussian
    additive noise of mean m and variance v. (default: m=0 and v=0.01)</para>

    <para><literal>im = imnoise(im,'localvar',V)</literal> additive zero-mean
    Gaussian noise where the variance at im(i,j) is V(i,j).</para>

    <para><literal>imn = imnoise(im,'localvar', intensity, V)</literal>
    additive zero-mean Gaussian noise, and the local variance of the noise,
    var, is a function of the image intensity values in <literal>im</literal>.
    The variance is <literal>matrix( interp1(intensity(:),V(:),im(:)),
    size(im) )</literal></para>

    <para><literal>imn = imnoise(im,'speckle',v)</literal> adds multiplicative
    noise, using <literal>imn = im + noise*im</literal>, where noise is
    uniformly distributed with mean 0 and variance v. (default: v=0.04)</para>

    <para>By default, we consider that "1" corresponds to the maximum
    intensity value of the image, and "0" to minimum. If the input image
    <literal>im</literal> is an integer image, it will be converted to double
    using <literal>im2double</literal> function first. Before return the
    result, the image will be converted to the same type as the input image.
    The elements in the output matrix <literal>imn</literal> that exceed the
    range of the integer or double type will be truncated.</para>

    <para>Supported classes: INT8, UINT8, INT16, UINT16, INT32, DOUBLE.</para>
  </refsection>

  <refsection>
    <title>Examples</title>

    <programlisting role="example">    im = imread(fullpath(getSIVPpath() + "/images/" + 'lena.png'));

    imn = imnoise(im, 'gaussian');
    imshow(imn);

    imn = imnoise(im, 'salt &amp; pepper');
    imshow(imn);

    imn = imnoise(im(:,:,1), 'salt &amp; pepper', 0.2);
    imshow(imn);

    lowtri = tril(ones(im(:,:,1)));
    imn = imnoise( im(:,:,1), 'localvar', lowtri/5);
    imshow(imn);

    imn = imnoise( im(:,:,1), 'localvar', [0:0.1:1], [0:0.1:1].^3);
    imshow(imn);

    imn = imnoise(im, 'speckle' );
    imshow(imn);</programlisting>
  </refsection>

  <refsection>
    <title>Bugs and Shortcomings</title>

    <para>'poisson' noise is not yet implemented.</para>
  </refsection>

  <refsection>
    <title>Authors</title>

    <simplelist type="vert">
      <member>Shiqi Yu &lt;shiqi.yu[at]gmail.com&gt;</member>

      <member>Ricardo Fabbri &lt;ricardofabbri [at] users.sf.net&gt;</member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Availability</title>

     The latest version of SIVP can be found at 

    <para>http://sivp.sf.net</para>

     
  </refsection>

  <refsection>
    <title>See Also</title>

    <simplelist type="inline"></simplelist>
  </refsection>
</refentry>
