mp_book.h

LastWave

/*..........................................................................*/
/*                                                                          */
/*      L a s t W a v e    P a c k a g e 'mp' 2.1                           */
/*                                                                          */
/*      Copyright (C) 2000 R.Gribonval, E.Bacry and J.Abadia.               */
/*      Copyright (C) 2001-2002 Remi Gribonval                              */
/*      email  : [e-mail]                                    */
/*      email  : [e-mail]                             */
/*                                                                          */
/*..........................................................................*/
/*                                                                          */
/*      This program is a free software, you can redistribute it and/or     */
/*      modify it under 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                      */
/*                                                                          */
/*      This program is distributed in the hope that it will be useful,     */
/*      but WITHOUT ANY WARRANTY; without even the implied warranty of      */
/*      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the       */
/*      GNU General Public License for more details.                        */
/*                                                                          */
/*      You should have received a copy of the GNU General Public License   */
/*      along with this program (in a file named COPYRIGHT);                */
/*      if not, write to the Free Software Foundation, Inc.,                */
/*      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA             */
/*                                                                          */
/*..........................................................................*/



#ifndef MP_BOOK_H

#define MP_BOOK_H

#include "signals.h"
#include "atom.h"

/*********************************************/
/* MOLECULES = arrays of dim*nChannels atoms */
/*********************************************/
typedef struct molecule {
  ValueFields;
  /* The data : array of atoms. */
  unsigned short dim;
  unsigned char  nChannels;
  unsigned short sizeAlloc;
  ATOM *atoms;
  /* Coefficient with which the molecule was selected: the sum of the atom->coeff2 */
  LWFLOAT coeff2;
} Molecule, *MOLECULE;

/* 
 * The basic variables and functions for &molecule variable management 
 */
extern char *moleculeType;
extern TypeStruct tsMolecule;
extern int   tMOLECULE;
extern int   tMOLECULE_;
extern MOLECULE NewMolecule(void);
extern MOLECULE TNewMolecule(void);
extern MOLECULE DeleteMolecule(MOLECULE molecule); 
extern void     ClearMolecule(MOLECULE molecule);
/* Generate an error if the molecule is empty */
extern void   CheckMoleculeNotEmpty(const MOLECULE molecule);

/*
 * If 'sizeAlloc' is smaller than molecule->dim*molecule->nChannels, an error is generated.
 * Else the allocation size of the array of atoms is adjusted to 'sizeAlloc'.
 * -the newly allocated part of the array is initialized to NULL atoms;
 * -the previously allocated part is kept (molecule->dim and molecule->nChannels are not changed)
 */
extern void   SizeMolecule(MOLECULE molecule,unsigned int sizeAlloc);
#define MP_DEFAULT_MOLECULE_SIZE 16

/*
 * Get the <k>th atom of a <channel> in a molecule. 
 * Generates an error if <k> is bigger than molecule->dim or <channel> larger than molecule->nChannels
 */
extern ATOM   GetMoleculeAtom(const MOLECULE molecule,unsigned char channel,unsigned short k);

/*
 * Adds an atom to a MONOCHANNEL molecule, and increases the molecule->dim. 
 * If the molecule is not monochannel, an error is generated. The allocation size in the molecule
 * is automatically managed, and an error is generated if the atom 'TFContent' does not
 * match that of those previously contained in the molecule.
 */
extern void   AddAtom2Molecule(MOLECULE molecule,ATOM atom);

/*
 * Adds a new channel (the atoms of a monochannel molecule) to a molecule, and increases the molecule->nChannels. 
 * If the added molecule is not monochannel, or the molecule is empty, an error is generated.
 * An error is also generated if the channel 'TFContent' or 'dim' does not match that of the molecule.
 * The allocation size in the molecule is automatically managed.
 * WARNING : the atoms of the channel are not copied, a REFERENCE is added, 
 * so the channel should rather be deleted than modified.
 */
extern void   AddChannel2Molecule(MOLECULE molecule,MOLECULE channelMol);

extern MOLECULE CopyMolecule(const MOLECULE moleculeIn,MOLECULE moleculeOut);
extern MOLECULE CopyMoleculeChannel(const MOLECULE moleculeIn,unsigned char channel,MOLECULE moleculeOut);


extern void   PrintMolecule(const MOLECULE molecule,char flagShort);

/************************************/
/* BOOKS : arrays of words          */
/************************************/
/* The number of signals in a book that are accessible using the '<i>book' syntax */
#define NBookSignals 10

typedef struct book{
  /* The fields of the ATFCONTENT structure */
  ATFContentFields;
  char * name;	/* name of the book. TODO : explain ? */
  /* The signals that are accessible using the '<i>book' syntax */
  SIGNAL theSignals[NBookSignals]; 
  
  /* The content : */
  int size;        	   /* The number of molecules in book TODO : unsigned */
  unsigned long sizeAlloc; /* The allocation size */
  MOLECULE *molecules;           /* The array[size] of molecules */
} Book,*BOOK;

/* 
 * The basic variables and functions for &book variable management 
 */
extern char *bookType;
extern TypeStruct tsBook;
extern int   tBOOK;
extern int   tBOOK_;
extern BOOK NewBook(void);
extern BOOK TNewBook(void);
/* Delete the arrays of molecules. The rest is kept. */
extern void DeleteBookMolecules(BOOK book); 
extern void ClearBook(BOOK book); 
extern BOOK CopyBook(const BOOK bookIn,BOOK bookOut);
extern BOOK DeleteBook(BOOK book);

extern BOOK GetBookCur(void);

/*
 * If 'sizeAlloc' is smaller than book->size, an error is generated.
 * Else the allocation size of the array of molecules is adjusted
 * to 'sizeAlloc'.
 * -the newly allocated part of the array is initialized to NULL molecules;
 * -the previously allocated part is kept (book->size is not changed)
 */
extern void     SizeBook(BOOK book,unsigned long sizeAlloc);
#define MP_DEFAULT_BOOK_SIZE 128
extern void     AddMolecule2Book    (BOOK book,MOLECULE molecule);
extern void     DeleteMoleculeFromBook(BOOK book,unsigned long rank);
/* Get the <n>th molecule in a book. Generates an error if <n> is bigger than book->size. */
extern MOLECULE 	GetBookMolecule  	(const BOOK book,unsigned long n);

// TODO : renew this 
/* I/O */
/* to deal with obsolete formats */
extern void ReadBookOld(BOOK book,FILE *stream,unsigned long forceMaxFreqId,SIGNAL residualEnergy);
extern void WriteBook(const BOOK book,char flagBinary,FILE * stream);
extern void ReadBook(BOOK book,FILE *stream);

/*
 * Functions and variables related to books
 */

extern void 	CheckBook	(const BOOK book);
extern void 	CheckBookNotEmpty(const BOOK book);


/* Utilities */
extern void 	AddShiftedSignals(SIGNAL input,SIGNAL output,long shift);
extern void 	DefineGraphBook(void);

/*************************************/
/* DICTIONARIES AND SUB-DICTIONARIES */
/*************************************/
typedef struct subDict {
  struct subDictMethods *methods;// The GetMax and Update methods 
  char flagMain;                 // If YES, then the GetMax searches through this sub-dictionary, else it does not
  unsigned char channel;         // Indicates to which of the nChannels of a dictionary this sub-dictionary corresponds.
  // When dict->nChannels==1 this is always 0.
  // When there are several channels, each sub-dictionary is either associated to a particular channel
  // (0<=channel<dict->nChannels, and then it is necessarily an 'auxiliary' sub-dictionary)
  // or it is 'multichannel' (channel==dict->nChannels) which indicates that it sums over all channels
  // some measure of correlation.
  char flagUpToDate;             // If NO, then the sub-dictionary needs to be updated
  VALUE dataContainer;           // Points to the actual data of the sub-dictionary
  struct dict *dict;             // The dictionary of which the sub-dictionary is a part
} SubDict, *SUBDICT;

#define DICT_MAX_NCHANNELS 8

typedef struct dict {
  ATFContentFields;
  // The array of analyzed channel(s).
  unsigned char nChannels;
  unsigned char nChannelsAlloc;
  SIGNAL *channels;
  LWFLOAT signalEnergy;

  // The range [updateTimeIdMin, updateTimeIdMax] where an update of the 
  // sub-dictionaries has to take place because the channels have changed.
  // When an update has just taken place, it is the empty range
  // [dict->signalSize,0]
  unsigned long updateTimeIdMin;
  unsigned long updateTimeIdMax;
  MOLECULE removedMolecule;
  // The number of sub-dictionaries
  unsigned short size;
  // The allocation size for the array of sub-dictionaries