src/mathutils.h

   1 /*
   2          Copyright (C) 2003 Paul Brossier
   3
   4          This program is free software; you can redistribute it and/or modify
   5          it under the terms of the GNU General Public License as published by
   6          the Free Software Foundation; either version 2 of the License, or
   7          (at your option) any later version.
   8
   9          This program is distributed in the hope that it will be useful,
  10          but WITHOUT ANY WARRANTY; without even the implied warranty of
  11          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12          GNU General Public License for more details.
  13
  14          You should have received a copy of the GNU General Public License
  15          along with this program; if not, write to the Free Software
  16          Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 /** @file
  21  *  various math functions
  22  *
  23  *  \todo multichannel (each function should return -or set- an array sized to
  24  *  the number of channel in the input vector)
  25  *
  26  *  \todo appropriate switches depending on types.h content
  27  */
  28
  29 #ifndef MATHUTILS_H
  30 #define MATHUTILS_H
  31
  32 /** Window types
  33  *
  34  * inspired from
  35  *
  36  *  - dafx : http://profs.sci.univr.it/%7Edafx/Final-Papers/ps/Bernardini.ps.gz
  37  *  - freqtweak : http://freqtweak.sf.net/
  38  *  - extace : http://extace.sf.net/
  39  */
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 typedef enum {
  46         aubio_win_rectangle,
  47         aubio_win_hamming,
  48         aubio_win_hanning,
  49         aubio_win_hanningz,
  50         aubio_win_blackman,
  51         aubio_win_blackman_harris,
  52         aubio_win_gaussian,
  53         aubio_win_welch,
  54         aubio_win_parzen
  55 } aubio_window_type;
  56
  57 /** create window */
  58 void aubio_window(smpl_t *w, uint_t size, aubio_window_type wintype);
  59
  60 /** principal argument
  61  *
  62  * mod(phase+PI,-TWO_PI)+PI
  63  */
  64 smpl_t aubio_unwrap2pi (smpl_t phase);
  65
  66 /** calculates the mean of a vector
  67  *
  68  * \bug mono
  69  */
  70 smpl_t vec_mean(fvec_t *s);
  71 /** returns the max of a vector
  72  *
  73  * \bug mono
  74  */
  75 smpl_t vec_max(fvec_t *s);
  76 /** returns the min of a vector
  77  *
  78  * \bug mono
  79  */
  80 smpl_t vec_min(fvec_t *s);
  81 /** returns the index of the min of a vector
  82  *
  83  * \bug mono
  84  */
  85 uint_t vec_min_elem(fvec_t *s);
  86 /** returns the index of the max of a vector
  87  *
  88  * \bug mono
  89  */
  90 uint_t vec_max_elem(fvec_t *s);
  91 /** implement 'fftshift' like function
  92  *
  93  * a[0]...,a[n/2],a[n/2+1],...a[n]
  94  *
  95  * becomes
  96  *
  97  * a[n/2+1],...a[n],a[0]...,a[n/2]
  98  */
  99 void vec_shift(fvec_t *s);
 100 /** returns sum */
 101 smpl_t vec_sum(fvec_t *s);
 102 /** returns energy
 103  *
 104  * \bug mono
 105  */
 106 smpl_t vec_local_energy(fvec_t * f);
 107 /** returns High Frequency Energy Content
 108  *
 109  * \bug mono */
 110 smpl_t vec_local_hfc(fvec_t * f);
 111 /** return alpha norm.
 112  *
 113  * alpha=2 means normalise variance.
 114  * alpha=1 means normalise abs value.
 115  * as alpha goes large, tends to normalisation
 116  * by max value.
 117  *
 118  * \bug should not use POW :(
 119  */
 120 smpl_t vec_alpha_norm(fvec_t * DF, smpl_t alpha);
 121 /**  dc(min) removal */
 122 void vec_dc_removal(fvec_t * mag);
 123 /**  alpha normalisation */
 124 void vec_alpha_normalise(fvec_t * mag, uint_t alpha);
 125 /** add a constant to all members of a vector */
 126 void vec_add(fvec_t * mag, smpl_t threshold);
 127
 128 /** compute adaptive threshold of input vector */
 129 void vec_adapt_thres(fvec_t * vec, fvec_t * tmp,
 130     uint_t win_post, uint_t win_pre);
 131 /**  adaptative thresholding
 132  *
 133  * y=fn_thresh(fn,x,post,pre)
 134  * compute adaptive threshold at each time
 135  *    fn : a function name or pointer, eg 'median'
 136  *    x:   signal vector
 137  *    post: window length, causal part
 138  *    pre: window length, anti-causal part
 139  * Returns:
 140  *    y:   signal the same length as x
 141  *
 142  * Formerly median_thresh, used compute median over a
 143  * window of post+pre+1 samples, but now works with any
 144  * function that takes a vector or matrix and returns a
 145  * 'representative' value for each column, eg
 146  *    medians=fn_thresh(median,x,8,8)
 147  *    minima=fn_thresh(min,x,8,8)
 148  * see SPARMS for explanation of post and pre
 149  */
 150 smpl_t vec_moving_thres(fvec_t * vec, fvec_t * tmp,
 151     uint_t win_post, uint_t win_pre, uint_t win_pos);
 152
 153 /** returns the median of the vector
 154  *
 155  *  This Quickselect routine is based on the algorithm described in
 156  *  "Numerical recipes in C", Second Edition,
 157  *  Cambridge University Press, 1992, Section 8.5, ISBN 0-521-43108-5
 158  *
 159  *  This code by Nicolas Devillard - 1998. Public domain,
 160  *  available at http://ndevilla.free.fr/median/median/
 161  */
 162 smpl_t vec_median(fvec_t * input);
 163
 164 /** finds exact maximum position by quadratic interpolation*/
 165 smpl_t vec_quadint(fvec_t * x,uint_t pos);
 166
 167 /** finds exact minimum position by quadratic interpolation*/
 168 smpl_t vec_quadint_min(fvec_t * x,uint_t pos, uint_t span);
 169
 170 /** Quadratic interpolation using Lagrange polynomial.
 171  *
 172  * inspired from ``Comparison of interpolation algorithms in real-time sound
 173  * processing'', Vladimir Arnost,
 174  *
 175  * estimate = s0 + (pf/2.)*((pf-3.)*s0-2.*(pf-2.)*s1+(pf-1.)*s2);
 176  *    where
 177  *    \param s0,s1,s2 are 3 known points on the curve,
 178  *    \param pf is the floating point index [0;2]
 179  */
 180 smpl_t aubio_quadfrac(smpl_t s0, smpl_t s1, smpl_t s2, smpl_t pf);
 181
 182 /** returns 1 if X1 is a peak and positive */
 183 uint_t vec_peakpick(fvec_t * input, uint_t pos);
 184
 185 /** convert frequency bin to midi value */
 186 smpl_t aubio_bintomidi(smpl_t bin, smpl_t samplerate, smpl_t fftsize);
 187 /** convert midi value to frequency bin */
 188 smpl_t aubio_miditobin(smpl_t midi, smpl_t samplerate, smpl_t fftsize);
 189 /** convert frequency bin to frequency (Hz) */
 190 smpl_t aubio_bintofreq(smpl_t bin, smpl_t samplerate, smpl_t fftsize);
 191 /** convert frequency (Hz) to frequency bin */
 192 smpl_t aubio_freqtobin(smpl_t freq, smpl_t samplerate, smpl_t fftsize);
 193 /** convert frequency (Hz) to midi value (0-128) */
 194 smpl_t aubio_freqtomidi(smpl_t freq);
 195 /** convert midi value (0-128) to frequency (Hz) */
 196 smpl_t aubio_miditofreq(smpl_t midi);
 197
 198 /** check if current buffer level is under a given threshold */
 199 uint_t aubio_silence_detection(fvec_t * ibuf, smpl_t threshold);
 200 /** get the current buffer level */
 201 smpl_t aubio_level_detection(fvec_t * ibuf, smpl_t threshold);
 202 /**
 203  * calculate normalised autocorrelation function
 204  */
 205 void aubio_autocorr(fvec_t * input, fvec_t * output);
 206 /**
 207  * zero-crossing rate (number of zero cross per sample)
 208  */
 209 smpl_t aubio_zero_crossing_rate(fvec_t * input);
 210 /**
 211  * clean up cached memory at the end of program
 212  *
 213  * use this function at the end of programs to purge all
 214  * cached memory. so far this function is only used to clean
 215  * fftw cache.
 216  */
 217 void aubio_cleanup(void);
 218
 219 #ifdef __cplusplus
 220 }
 221 #endif
 222
 223 #endif
 224