9b3d4eacd390236d57f74a20711cb618a0ab2184
[scilab.git] / scilab / modules / signal_processing / help / en_US / transforms / dct.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 1997   - INRIA
5 * Copyright (C) 2012 - Serge Steer - INRIA
6
7 * This file must be used under the terms of the CeCILL.
8 * This source file is licensed as described in the file COPYING, which
9 * you should have received as part of this distribution.  The terms
10 * are also available at    
11 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12 *
13 -->
14 <refentry xmlns="http://docbook.org/ns/docbook" 
15           xmlns:xlink="http://www.w3.org/1999/xlink" 
16           xmlns:svg="http://www.w3.org/2000/svg" 
17           xmlns:mml="http://www.w3.org/1998/Math/MathML" 
18           xmlns:db="http://docbook.org/ns/docbook" 
19           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="dct">
20     <refnamediv>
21         <refname>dct</refname>
22         <refpurpose>Discrete cosine transform.</refpurpose>
23     </refnamediv>
24     <refnamediv xml:id="idct">
25         <refname>idct</refname>
26         <refpurpose>Inverse discrete cosine transform.</refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29         <title>Calling Sequence</title>
30         <synopsis>X=dct(A [,sign] [,option])
31             X=dct(A,sign,selection [,option])
32             X=dct(A,sign,dims,incr [,option])
33             X=idct(A [,option])
34             X=idct(A,selection [,option])
35             X=idct(A,dims,incr [,option])
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>A</term>
43                 <listitem>
44                     <para>a real or complex vector or real or complex array
45                         (vector, matrix or N-D array.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>X</term>
51                 <listitem>
52                     a real or complex array with same shape as <literal>A</literal>.
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>sign</term>
57                 <listitem>
58                     an integer. with possible values <literal>1</literal> or
59                     <literal>-1</literal>. Select direct or inverse
60                     transform. The default value is <literal>-1</literal>
61                     (direct transform).
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>selection</term>
66                 <listitem>
67                     a vector containing index on <literal>A</literal> array
68                     dimensions.  See the Description part for details.
69                 </listitem>
70             </varlistentry>
71             
72             <varlistentry>
73                 <term>dims</term>
74                 <listitem>
75                     a vector of positive numbers with integer values, or a
76                     vector of positive integers.  See the Description part for details.
77                     <para>
78                         Each element must be a divisor
79                         of the total number of elements of <literal>A</literal>. 
80                     </para>
81                     <para>
82                         The product of the elements must be less than the total
83                         number of elements of <literal>A</literal>.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>incr</term>
89                 <listitem>
90                     a vector of positive numbers with integer values, or a
91                     vector of positive integers.  See the Description part for
92                     details.
93                     <para>
94                         <literal>incr</literal> must have the same number of
95                         elements than <literal>dims</literal>.
96                     </para>
97                     <para>
98                         Each element must be a divisor of the total number of
99                         elements of <literal>A</literal>.
100                     </para>
101                     <para>
102                         The <literal>incr</literal> elements must be in strictly
103                         increasing order.
104                     </para>
105                 </listitem>
106             </varlistentry>
107             <varlistentry>
108                 <term>option</term>
109                 <listitem>
110                     a character string. with possible values
111                     <literal>"dct1"</literal>, <literal>"dct2"</literal>,
112                     <literal>"dct4"</literal> or <literal>"dct"</literal> for
113                     direct transform and <literal>"dct1"</literal>,
114                     <literal>"dct3"</literal>, <literal>"dct4"</literal> or
115                     <literal>"idct"</literal> for inverse transform.  The
116                     default value is <literal>"dct"</literal> for direct
117                     transform and <literal>"idct"</literal> for inverse
118                     transform. See the Description part for details.
119                 </listitem>
120             </varlistentry>
121         </variablelist>
122     </refsection>
123     <refsection>
124         <title>Description</title> 
125         <refsection>
126             <title>Transform description</title> 
127             <para>
128                 This function realizes direct or
129                 inverse 1-D or N-D Discrete Cosine Transforms with shift depending on the <literal>option</literal> parameter value. For a 1-D array  <latex>$A$</latex> of length  <latex>$n$</latex>:
130             </para>
131             <itemizedlist>
132                 <listitem>
133                     <para>
134                         For <literal>"dct1"</literal> the function computes the unnormalized DCT-I transform: 
135                     </para>
136                     <para>
137                         <latex>
138                             $X(k) = X(1)+(-1)^{k-1}X(n)+2\sum_{i=2}^{n-1} {A(i)
139                             \cos\frac{\pi (i -1)(k-1)}{n-1}}, k=1\ldots n$
140                         </latex>
141                     </para>
142                 </listitem>
143                 <listitem>
144                     <para>
145                         For <literal>"dct2"</literal>  the function computes the unnormalized DCT-II transform:
146                     </para>
147                     <para>
148                         <latex>
149                             $X(k) =2 \sum_{i=1}^{n} {A(i) \cos\frac{\pi (i
150                             -1/2)(k-1)}{n}}, k=1\ldots n$
151                         </latex>
152                     </para>
153                 </listitem>
154                 <listitem>
155                     <para>
156                         For <literal>"dct3"</literal> the function computes the unnormalized DCT-III transform:
157                     </para>
158                     <para>
159                         <latex>
160                             $X(k) =X(1)+ 2 \sum_{i=2}^{n} {A(i) \cos\frac{\pi (i
161                             -1)(k-1/2)}{n}}, k=1\ldots n$
162                         </latex>
163                     </para>
164                 </listitem>
165                 
166                 
167                 <listitem>
168                     <para>
169                         For <literal>"dct4"</literal>  the function computes the unnormalized DCT-IV transform:
170                     </para>
171                     <para>
172                         <latex>
173                             $X(k) =2 \sum_{i=1}^{n} {A(i) \cos\frac{\pi (i
174                             -1/2)(k-1/2)}{n}}, k=1\ldots n$
175                         </latex>
176                     </para>
177                 </listitem>
178                 <listitem>
179                     <para>
180                         For <literal>"dct"</literal> the function computes the normalized DCT-II transform:
181                     </para>
182                     <para>
183                         <latex>
184                             $X(k) = \omega(k)
185                             \sum_{i=1}^n {A(i) \cos\frac{\pi (i
186                             -1/2)(k-1)}{n}}, k=1\ldots n \quad\text{with }
187                             \omega(1)=\frac{1}{\sqrt{n}} \quad\text{and }
188                             \omega(k)=\sqrt{\frac{2}{n}} , k>1$ 
189                         </latex>
190                     </para>
191                 </listitem>
192                 
193                 <listitem>
194                     <para>
195                         For <literal>"idct"</literal> the function computes the normalized DCT-III transform:
196                     </para>
197                     <para>
198                         <latex>
199                             $X(i) = \sum_{k=1}^n {\omega(k) A(k) \cos\frac{\pi (i
200                             -1/2)(k-1)}{n}}, k=1\ldots n \quad\text{with }
201                             \omega(1)=\frac{1}{\sqrt{n}} \quad\text{and }
202                             \omega(k)=\sqrt{\frac{2}{n}} , k>1$ 
203                         </latex>
204                     </para>
205                 </listitem>
206             </itemizedlist>
207             <para>
208                 The multi-dimensional DCT transforms , in general, are the
209                 separable product of the given 1d transform along each dimension
210                 of the array. For unnormalized transforms , computing the
211                 forward followed by the backward/inverse multi-dimensional
212                 transform will result in the original array scaled by the
213                 product of the dimension sizes.
214             </para>
215             <para>
216                 The normalized multi-dimensional DCT transform of an array
217                 <literal>A</literal> with dimensions <latex>$n_1, n_2, \ldots, n_p$</latex>
218                 is given by
219             </para>
220             <para>
221                 <latex>
222                     $\begin{array} \\X(k_1, \dots, k_p) =
223                     \omega_1(k_1) \ldots \omega_p(k_p)
224                     \sum_{i_1=1}^{n_1} \ldots \sum_{i_p=1}^{n_p}
225                     {A(i_1,\ldots ,i_p) \cos\frac{\pi (2 i_1
226                     -1)(k_1-1)}{2 n} \ldots \cos\frac{\pi (2 i_p
227                     -1)(k_p-1)}{2 n}}, k_j=1\ldots n_j\\
228                     \text{with}\\
229                     \omega_j(1)=\frac{1}{\sqrt{n_j}}\\
230                     \omega_j(k)=\sqrt{\frac{2}{n_j}} , k>1
231                     \end{array}$ 
232                 </latex>
233             </para>
234             <para>
235                 The normalized multi-dimensional DCT inverse transform of an
236                 array <literal>A</literal> with dimensions <latex>$n_1, n_2, \ldots, n_p$</latex>is given by
237             </para>
238             <para>
239                 <latex>
240                     $\begin{array} \\X(i_1, \dots, i_p) = \sum_{k_1=1}^{n_1}
241                     \ldots \sum_{k_p=1}^{n_p} {\omega_1(i_1) \ldots \omega_p(i_p)
242                     A(k_1,\ldots ,k_p) \cos\frac{\pi (2 k_1 -1)(i_1-1)}{2 n}
243                     \ldots \cos\frac{\pi (2 k_p -1)(i_p-1)}{2 n}}, i_j=1\ldots
244                     n_j\\
245                     \text{with}\\
246                     \omega_j(1)=\frac{1}{\sqrt{n_j}}\\
247                     \omega_j(k)=\sqrt{\frac{2}{n_j}} , k>1 \end{array}$
248                 </latex>
249             </para>
250             
251         </refsection>
252         <refsection>
253             <title>Syntax description</title>
254             <variablelist>
255                 <varlistentry>
256                     <term>Short syntax </term>
257                     <listitem>
258                         <variablelist>
259                             <varlistentry>
260                                 <term>direct</term>
261                                 <listitem>
262                                     <para>
263                                         <literal>X=dct(A,-1 [,option])</literal> or
264                                         <literal>X=dct(A [,option])</literal> gives a direct
265                                         transform according to the option value. The default is normalized DCT-II direct transform.
266                                     </para>
267                                     <para>
268                                         If <literal>A</literal> is a vector (only one
269                                         dimension greater than 1) a 1-d transform is performed
270                                         and in the other cases a n-dimensional transform is
271                                         done.
272                                     </para>
273                                     <para>
274                                         (the <literal>-1</literal> argument refers
275                                         to the sign of the exponent..., NOT to
276                                         "inverse"),
277                                     </para>
278                                 </listitem>
279                             </varlistentry>
280                             <varlistentry>
281                                 <term>inverse</term>
282                                 <listitem>
283                                     <para>
284                                         <literal>X=dct(A,1 [,option])</literal> or
285                                         <literal>X=idct(A [,option])</literal>performs the inverse
286                                         transform. 
287                                     </para>
288                                     <para>
289                                         If <literal>A</literal> is a vector (only one
290                                         dimension greater than 1) a 1-d transform is performed
291                                         and in the other cases a n-dimensional transform is
292                                         done.
293                                     </para>
294                                 </listitem>
295                             </varlistentry>
296                         </variablelist>
297                     </listitem>
298                 </varlistentry>
299                 
300                 <varlistentry>
301                     <term>Long syntax for DCT along specified dimensions</term>
302                     <listitem>
303                         <itemizedlist>
304                             <listitem>
305                                 <para>
306                                     <literal>X=dct(A,sign,selection [,option])</literal>
307                                     allows to perform efficiently all direct or inverse
308                                     dct of the "slices" of <literal>A</literal> along
309                                     selected dimensions.
310                                 </para>
311                                 <para>
312                                     For example, if <literal>A</literal> is a 3-D array
313                                     <literal>X=dct(A,-1,2)</literal> is equivalent to:
314                                 </para>
315                                 <programlisting role=""><![CDATA[ 
316             for i1=1:size(A,1),
317               for i3=1:size(A,3),
318                 X(i1,:,i3)=dct(A(i1,:,i3),-1);
319               end
320             end
321             ]]></programlisting>
322                                 <para>
323                                     and <literal>X=dct(A,-1,[1 3])</literal> is equivalent to:
324                                 </para>
325                                 <programlisting role=""><![CDATA[ 
326             for i2=1:size(A,2),
327               X(:,i2,:)=dct(A(:,i2,:),-1);
328             end
329             ]]></programlisting>
330                             </listitem>
331                             <listitem>
332                                 <para>
333                                     <literal>X=dct(A,sign,dims,incr)</literal> is
334                                     an old  syntax that also allows to perform all direct or
335                                     inverse dct of the slices of <literal>A</literal> along
336                                     selected dimensions.
337                                 </para>
338                                 <para>
339                                     For example, if <literal>A</literal> is an array with
340                                     <literal>n1*n2*n3</literal> elements
341                                     <literal>X=dct(A,-1,n1,1)</literal> is equivalent to
342                                     <literal>X=dct(matrix(A,[n1,n2,n3]),-1,1)</literal>.
343                                     and <literal>X=dct(A,-1,[n1 n3],[1 n1*n2])</literal>
344                                     is equivalent to
345                                     <literal>X=dct(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>.
346                                 </para>
347                             </listitem>
348                         </itemizedlist>
349                     </listitem>
350                 </varlistentry>
351             </variablelist>
352         </refsection>
353         <refsection>
354             <title>Optimizing dct</title>
355             <para>
356                 Remark: function automatically stores his last parameters in
357                 memory to re-use it in a second time. This improves greatly
358                 the time computation when consecutives calls (with same
359                 parameters) are performed.
360             </para>
361             <para> 
362                 It is possible to go further in dct optimization using
363                 <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>, <link
364           linkend="set_fftw_wisdom">set_fftw_wisdom</link> functions.
365             </para>
366         </refsection>
367     </refsection>
368     <refsection>
369         <title>Algorithms</title>
370         <para>
371             This function uses the  <ulink url="http://www.fftw.org/">fftw3</ulink> library.
372         </para>
373     </refsection>
374     <refsection>
375         <title>Examples</title>
376         <para>1-D dct</para>
377         <programlisting role="example"><![CDATA[ 
378   //Frequency components of a signal
379   //----------------------------------
380   // build a sampled at 1000hz  containing pure frequencies 
381   // at 50 and 70 Hz
382   sample_rate=1000;
383   t = 0:1/sample_rate:0.6;
384   N=size(t,'*'); //number of samples
385   s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
386   d=dct(s);
387   // zero low energy components
388   d(abs(d)<1)=0;
389   size(find(y1<>0),'*') //only 30 non zero coefficients out of 600
390   clf;plot(s,'b'),plot(dct(d,1),'r')
391
392   ]]></programlisting>
393         
394         <para>2-D dct</para>
395         <programlisting role="example"><![CDATA[ 
396   ----------------------------------
397   x=-2:0.1:2;
398   A=eval3d(milk_drop,x,x);
399   d=dct(A);
400   d(abs(d)<1)=0;
401   size(find(d1<>0),'*')
402   A1=dct(d,1);
403   clf();fig=gcf();fig.color_map=graycolormap(128);
404   subplot(121),grayplot(x,x,A)
405   subplot(122),grayplot(x,x,A1)
406   ]]></programlisting>
407         
408         
409     </refsection>
410     <refsection role="see also">
411         <title>See Also</title>
412         <simplelist type="inline">
413             <member>
414                 <link linkend="fft">fft</link>
415             </member>
416             <member>
417                 <link linkend="dst">dst</link>
418             </member>
419             <member>
420                 <link linkend="fftw_flags">fftw_flags</link>
421             </member>
422             <member>
423                 <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>
424             </member>
425             <member>
426                 <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>
427             </member>
428             <member>
429                 <link linkend="fftw_forget_wisdom">fftw_forget_wisdom</link>
430             </member>
431         </simplelist>
432     </refsection>
433     <refsection>
434         <title>Bibliography</title>
435         <para>
436             Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink
437     url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
438         </para>
439     </refsection>
440 </refentry>