scilab/modules/signal_processing/help/en_US/correlation_convolution/conv2.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en_US" xml:id="conv2">
   3     <refnamediv>
   4         <refname>conv2</refname>
   5         <refpurpose>discrete 2-D convolution. </refpurpose>
   6     </refnamediv>
   7     <refsynopsisdiv>
   8         <title>Syntax</title>
   9         <synopsis>
  10             C = conv2(A,B [,shape])
  11             C = conv2(hrow,hcol,B [,shape])
  12         </synopsis>
  13     </refsynopsisdiv>
  14     <refsection>
  15         <title>Parameters</title>
  16         <variablelist>
  17             <varlistentry>
  18                 <term>hrow</term>
  19                 <listitem>
  20                     <para>
  21                         a real or complex vector.
  22                     </para>
  23                 </listitem>
  24             </varlistentry>
  25             <varlistentry>
  26                 <term>hcol</term>
  27                 <listitem>
  28                     <para>
  29                         a real or complex vector.
  30                     </para>
  31                 </listitem>
  32             </varlistentry>
  33             <varlistentry>
  34                 <term>A</term>
  35                 <listitem>
  36                     <para>
  37                         a real or complex 2-D array.
  38                     </para>
  39                 </listitem>
  40             </varlistentry>
  41             <varlistentry>
  42                 <term>B</term>
  43                 <listitem>
  44                     <para>
  45                         a real or complex 2-D array.
  46                     </para>
  47                 </listitem>
  48             </varlistentry>
  49             <varlistentry>
  50                 <term>shape</term>
  51                 <listitem>
  52                     <para>
  53                         an optional character string with possible values:
  54                     </para>
  55                     <itemizedlist>
  56                         <listitem>
  57                             <literal>"full"</literal>, <literal>conv2</literal>
  58                             computes the full two-dimensional convolution. It is the
  59                             default value.
  60                         </listitem>
  61                         <listitem>
  62                             <literal>"same"</literal>, <literal>conv2</literal>
  63                             computes the central part of the convolution of the same
  64                             size as <literal>A</literal>.
  65                         </listitem>
  66                         <listitem>
  67                             <literal>"valid"</literal>, <literal>conv2</literal>
  68                             computes the convolution parts without the zero-padding of <literal>A</literal>.
  69                         </listitem>
  70                     </itemizedlist>
  71                 </listitem>
  72             </varlistentry>
  73             <varlistentry>
  74                 <term>C</term>
  75                 <listitem>
  76                     <para>
  77                         a real or complex 2-D array.
  78                     </para>
  79                 </listitem>
  80             </varlistentry>
  81         </variablelist>
  82     </refsection>
  83     <refsection>
  84         <title>Description</title>
  85         <para>
  86             <literal>conv2</literal> uses a straightforward formal
  87             implementation of the two-dimensional convolution equation in
  88             spatial form.
  89         </para>
  90         <para>
  91             <literal>C=conv2(A,B [,shape])</literal> computes the
  92             two-dimensional convolution of the arrays <literal>A</literal>
  93             and <literal>B</literal>:
  94         </para>
  95         <itemizedlist><listitem>
  96                 With <literal>shape=="full"</literal> the
  97                 dimensions of the result<literal>C</literal> are given by
  98                 <literal>size(A)+size(B)+1</literal>. The indices of the
  99                 center element of <literal>B</literal> are defined as
 100                 <literal>floor((size(B)+1)/2)</literal>.
 101             </listitem>
 102             <listitem>
 103                 With <literal>shape=="same"</literal> the dimensions
 104                 of the result<literal>C</literal> are given by
 105                 <literal>size(A)</literal>. The indices of the center element of
 106                 <literal>B</literal> are defined as
 107                 <literal>floor((size(B)+1)/2)</literal>.
 108             </listitem>
 109             <listitem>
 110                 With <literal>shape=="valid"</literal> the dimensions
 111                 of the result <literal>C</literal> are given by
 112                 <literal>size(A)-size(B)+1)</literal> if
 113                 <literal>and(size(A)-size(B))&gt;=0</literal> else
 114                 <literal>C</literal> is empty . The indices of the center
 115                 element of <literal>B</literal> are defined as <literal>[1
 116                     1]
 117                 </literal>
 118                 .
 119             </listitem>
 120         </itemizedlist>
 121         <para>
 122             The separable form <literal>C=conv2(hrow,hcol,B [,shape])</literal>is equivalent to <literal>C=conv2(hrow(:)*hcol(:).',B [,shape])</literal>
 123         </para>
 124         .
 125         <para>
 126             Note that <link linkend="convol2d">convol2d</link> can be more efficient for large arrays.
 127         </para>
 128     </refsection>
 129     <refsection>
 130         <title>Examples</title>
 131         <programlisting role="example"><![CDATA[
 132     s = [1 2 1; 0 0 0; -1 -2 -1];//Sobel horizontal edge kernel
 133     A = zeros(10,10);A(3:7,3:7) = 1;
 134     conv2(s,A);
 135
 136     //separable form
 137     u=[1;0;-1];v=[1 2 1];// u*v=s
 138     conv2(u,v,A)
 139     ]]></programlisting>
 140     </refsection>
 141     <refsection role="see also">
 142         <title>See also</title>
 143         <simplelist type="inline">
 144             <member>
 145                 <link linkend="convol2d">convol2d</link>
 146             </member>
 147             <member>
 148                 <link linkend="conv">conv</link>
 149             </member>
 150         </simplelist>
 151     </refsection>
 152     <refsection>
 153         <title>History</title>
 154         <revhistory>
 155             <revision>
 156                 <revnumber>5.4.0</revnumber>
 157                 <revremark>Function conv2 introduced.</revremark>
 158             </revision>
 159         </revhistory>
 160     </refsection>
 161 </refentry>