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