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