src/mathutils.h

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