

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Gabor Code , Version 4

Salvador Moreno, Francesc J. Ferri, 2016

===========================================================================
Efficient Gabor Analysis and Synthesis using Implicit Canonical Dual Frames
===========================================================================


DOWNLOADING INSTRUCTIONS:~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The code is in a zip file that can be accessed as:
http://www.uv.es/prcv/GaborCode/GaborCode.zip
This file itself is inside this zip and can also be accessed as:
http://www.uv.es/prcv/GaborCode/readme.txt

The previous version of the code and readme files can still be accessed as:
http://www.uv.es/prcv/GaborCode/GaborCodeV3.zip
http://www.uv.es/prcv/GaborCode/readmeV3.txt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


This version of the code is slightly slower than the previous one but
is more clear, better structured and more general. In particular, it
includes general functions to compute DGT/DGE using the Implicit Dual 
in Algorithm 2 and a basic implementation of Algorithm 1. 
The main functions provided are:


dgtP   : DGT using Portnoff which is very efficient for short FIR windows

idgtP  : which is needed by Algorithm 2. You can use it also if you explicitly
         obtain the (usually longer) FIR dual window. 

idgtID : DGE using Algorithm 2


These functions do not have dependences on any specific toolbox but they are 
prepared to use signal, windows and transforms produced by the LTFAT toolbox.

The remaining functions/scripts are of internal use or to produce comparative
figures. gabor1 internally implements both DGT/DGE using Algorihm 1 just to 
compare CPU times.

+ use toyGabor.m to generate Figures 1 and 2 (see examples below)

+ use run_runGabors.m and show_runGabors to generate Figure 6

+ do repeated calls to run_runGabors changing frame parameters to
  generate data for Figure 7

+ A complete listing follows

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Callable scripts/functions
%

- GaborCode.m
     illustrates the use of the DGT/DGE functions

- compareLTFAT.m
     Mixes LTFAT and new functions for DGT/DGE

- toyGabor.m
     creates a toy example and shows matrices S, E and D
     Ex: toyGabor(48,2,3,10,21,false);

- runGabors.m (function)
     runs several alternatives for DGT/DGE (uses LTFAT toolbox)
     and computes or shows CPU times.
     Ex: runGabors(44100,120,40,60,[],1,{'verbose'});

- showBars.m
     graphically shows CPU times and reconstruction errors corresponding
     to runGabors (it is called by runGabors when using 'verbose')

- run_runGabors.m
     Performs experiments with varying signal and window sizes (uses LTFAT)

- show_runGabors.m
     Graphically shows the results of run_runGabors
     Examples: 
        run_runGabors     % performs an experimentation round
        show_runGabors;   % and shows corresponding results 
        
        ExpNm='000_40_60'; show_runGabors  % load saved results and show them
        
      

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% DGT/DGE functions (inputs and outputs can be combined with LTFAT)
%

- dgtP.m
     computes the DGT using Portnoff, c = G' f  
     [c, (gG)] = dgtP(f, g|gG ,a,M, ('timeinv'|'freqinv') )

- idgtP.m
     computes the inverse DGT using Portnoff, f = G c 
     [f] = idgtP(c, g|gG ,a,M, (Ls) , ('timeinv'|'freqinv') )

- idgtID.m
     computes the Inverse DGT using the Implicit Dual corresponding to g, c=dgt(f,g,a,M)
     [f] = idgtID(c,g,a,M, (Ls) , (tol), ('timeinv'|'freqinv') )


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Algorithm 2 (internal functions)
%

- InitGpars.m
     computes a reduced representation of G and parameters used in other algorithms
     [fa,gG,Ka,Ks,Lga] = InitGpars(f,g,a,M)

- InitS.m
      computes blocks P and V (Version 3) 

- BasicRecurrence.m
      solves recurrence (Version 3) 

- estimaJordan.m
      estimates window decay (Version 3)


- Steps678.m
     computes  E'^-1 D'^-1  D^-1 E^-1 f, where C=ED and S=CC'
     [f] = Steps678(f,Ks,No,iA,B,Q,tol)

- Steps678SP.m
     computes  E'^-1 D'^-1  D^-1 E^-1 f, where C=ED and S=CC'
     using sparsity patterns in block matrices 
     [f] = Steps678SP(f,a,M,Ks,No,iA,B,Q,tol)

     This function is asymptotically M times faster than the previous
     one but is slower in matlab for moderate Lg sizes. You can have
     a look at its behavior by typing (see above):
     ExpNm='000_60_90';show_runGabors

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Other auxiliar functions
%

- gabor1.m
     Basic implementation of Algorithm 1 for DGT/DGE for profiling purposes only.

- reduceMatrices.m
     reduces a stripped matrix to a collection of M dense small matrices.
     (used by Steps678SP.m)

- expandSignal.m
     expand signal (if needed) to be multiple of Ks, M and a. 

- showWin.m
     show fir windows centered

- showMatrix.m
     displays a matrix and add different grids (used by toyGabor)

- imagescMat.m
     displays a matrix logarithmically (used by showMatrix)

- computeG.m
     obtains the (full) matrix G (used by toyGabor)






