Typo fixes
[scilab.git] / scilab / modules / signal_processing / help / en_US / 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>
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>