<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the Scilab time frequency toolbox.
This file must be used under the terms of the  terms of the GNU General Public License 
as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 1996 by CNRS (France).
-->

<refentry xml:id="tfrgabor" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:scilab="http://www.scilab.org"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">

  <refnamediv>
    <refname>tfrgabor</refname>
	<refpurpose>Gabor representation of a signal</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [TFR,DGR,GAM] = tfrgabor(SIG, N, Q)
      [TFR,DGR,GAM] = tfrgabor(SIG, N, Q, H)
      [TFR,DGR,GAM] = tfrgabor(SIG, N, Q, H, TRACE)
      [TFR,DGR,GAM] = tfrgabor(...,'plot')
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>	SIG :</term>
        <listitem>
          <para> signal to be analyzed (length(SIG)=N1).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	N   :</term>
        <listitem>
          <para> number of Gabor coefficients in time (N1 must be a
          multiple of N) (default : divider(N1)).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	Q   :</term>
        <listitem>
          <para> degree of oversampling ; must be a divider of N
          (default : Q=divider(N)).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	H   :</term>
        <listitem>
          <para> synthesis window, which was originally chosen as a
          Gaussian window by Gabor. Length(H) should be as closed as
          possible from N, and must be &gt;=N (default : Gauss(N+1)).
          H must be of unit energy, and CENTERED.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term> TRACE :</term> <listitem><para> if nonzero, the
        progression of the algorithm is shown (default : 0).</para>
      </listitem>
      </varlistentry>
      <varlistentry>
        <term>'plot':</term>
        <listitem>
          <para>if one input parameter is 'plot', tfrgabor runs
          tfrqview. and TFR will be plotted</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	TFR :</term>
        <listitem>
          <para>a N1 by N1 real matrix: the Square modulus of the Gabor coefficients.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	DGR :</term>
        <listitem>
          <para>a N1 by N1 complex matrix: the Gabor coefficients.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	GAM :</term>
        <listitem>
          <para>a column vector of size N: the biorthogonal (dual frame) window associated to H.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      tfrgabor computes the Gabor representation of signal X, for a
      given synthesis window H, on a rectangular grid of size (N,M) in
      the time-frequency plane. M and N must be such that N1 = M * N /
      Q where N1=length(X) and Q is an integer corresponding to the
      degree of oversampling.  If Q=1, the time-frequency plane (TFP)
      is critically sampled, so there is no redundancy in the TFP.  If
      Q&gt;1, the TFP is oversampled, allowing a greater numerical
      stability of the algorithm.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    N1 = 128;
    sig = fmlin(N1);
    N = N1/2; q = N/2;
    [tfr,dgr,gam] = tfrgabor(sig,N,q);
    t = 1:2:N1;
    nf = size(tfr,1)/2;
    f = (0.5*(0:nf-1)/nf);
    clf; gcf().color_map = jetcolormap(128);
    grayplot(t,f,tfr(1:$/2,:)');
    ]]></programlisting>
    <scilab:image><![CDATA[
    N1 = 128;
    sig = fmlin(N1);
    N = N1/2; q = N/2;
    [tfr,dgr,gam] = tfrgabor(sig,N,q);
    t = 1:2:N1;
    nf = size(tfr,1)/2;
    f = (0.5*(0:nf-1)/nf);
    clf; gcf().color_map = jetcolormap(128);
    grayplot(t,f,tfr(1:$/2,:)');
   ]]></scilab:image>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>O. Lemoine, October 1995 - February 1996.</member>
    </simplelist>
  </refsection>
</refentry>
