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
  25 #ifndef MATHUTILS_H
  26 #define MATHUTILS_H
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /** create window
  33
  34   References:
  35
  36     - <a href="http://en.wikipedia.org/wiki/Window_function">Window
  37 function</a> on Wikipedia
  38     - Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional (?)
  39 implementations of a phase vocoder: the tricks of the trade. In Proceedings of
  40 the International Conference on Digital Audio Effects (DAFx-00), pages 37–44,
  41 Uni- versity of Verona, Italy, 2000.
  42   (<a href="http://profs.sci.univr.it/%7Edafx/Final-Papers/ps/Bernardini.ps.gz">
  43   ps.gz</a>)
  44
  45 */
  46 fvec_t *new_aubio_window (char_t * window_type, uint_t size);
  47
  48 /** compute the principal argument
  49
  50   This function maps the input phase to its corresponding value wrapped in the
  51 range \f$ [-\pi, \pi] \f$.
  52
  53   \param phase unwrapped phase to map to the unit circle
  54
  55   \return equivalent phase wrapped to the unit circle
  56
  57 */
  58 smpl_t aubio_unwrap2pi (smpl_t phase);
  59
  60 /** compute the mean of a vector
  61
  62   \param s vector to compute mean from
  63
  64   \return the mean of v
  65
  66 */
  67 smpl_t fvec_mean (fvec_t * s);
  68
  69 /** compute the mean of a vector channel
  70
  71   \param s vector to compute mean from
  72   \param i channel to compute mean from
  73
  74   \return the mean of v
  75
  76 */
  77 smpl_t fvec_mean_channel (fvec_t * s, uint_t i);
  78
  79 /** find the max of a vector
  80
  81   \param s vector to get the max from
  82
  83   \return the value of the minimum of v
  84
  85 */
  86 smpl_t fvec_max (fvec_t * s);
  87
  88 /** find the min of a vector
  89
  90   \param s vector to get the min from
  91
  92   \return the value of the maximum of v
  93
  94 */
  95 smpl_t fvec_min (fvec_t * s);
  96
  97 /** find the index of the min of a vector
  98
  99   \param s vector to get the index from
 100
 101   \return the index of the minimum element of v
 102
 103 */
 104 uint_t fvec_min_elem (fvec_t * s);
 105
 106 /** find the index of the max of a vector
 107
 108   \param s vector to get the index from
 109
 110   \return the index of the maximum element of v
 111
 112 */
 113 uint_t fvec_max_elem (fvec_t * s);
 114
 115 /** swap the left and right halves of a vector
 116
 117   This function swaps the left part of the signal with the right part of the
 118 signal. Therefore
 119
 120   \f$ a[0], a[1], ..., a[\frac{N}{2}], a[\frac{N}{2}+1], ..., a[N-1], a[N] \f$
 121
 122   becomes
 123
 124   \f$ a[\frac{N}{2}+1], ..., a[N-1], a[N], a[0], a[1], ..., a[\frac{N}{2}] \f$
 125
 126   This operation, known as 'fftshift' in the Matlab Signal Processing Toolbox,
 127 can be used before computing the FFT to simplify the phase relationship of the
 128 resulting spectrum. See Amalia de Götzen's paper referred to above.
 129
 130 */
 131 void fvec_shift (fvec_t * v);
 132
 133 /** compute the sum of all elements of a vector
 134
 135   \param v vector to compute the sum of
 136
 137   \return the sum of v
 138
 139 */
 140 smpl_t fvec_sum (fvec_t * v);
 141
 142 /** compute the energy of a vector
 143
 144   This function compute the sum of the squared elements of a vector.
 145
 146   \param v vector to get the energy from
 147
 148   \return the energy of v
 149
 150 */
 151 smpl_t fvec_local_energy (fvec_t * v);
 152
 153 /** compute the High Frequency Content of a vector
 154
 155   The High Frequency Content is defined as \f$ \sum_0^{N-1} (k+1) v[k] \f$.
 156
 157   \param v vector to get the energy from
 158
 159   \return the HFC of v
 160
 161 */
 162 smpl_t fvec_local_hfc (fvec_t * v);
 163
 164 /** computes the p-norm of a vector
 165
 166   Computes the p-norm of a vector for \f$ p = \alpha \f$
 167
 168   \f$ L^p = ||x||_p = (|x_1|^p + |x_2|^p + ... + |x_n|^p ) ^ \frac{1}{p} \f$
 169
 170   If p = 1, the result is the Manhattan distance.
 171
 172   If p = 2, the result is the Euclidean distance.
 173
 174   As p tends towards large values, \f$ L^p \f$ tends towards the maximum of the
 175 input vector.
 176
 177   References:
 178
 179     - <a href="http://en.wikipedia.org/wiki/Lp_space">\f$L^p\f$ space</a> on
 180   Wikipedia
 181
 182   \param v vector to compute norm from
 183   \param p order of the computed norm
 184
 185   \return the p-norm of v
 186
 187 */
 188 smpl_t fvec_alpha_norm (fvec_t * v, smpl_t p);
 189
 190 /**  alpha normalisation
 191
 192   This function divides all elements of a vector by the p-norm as computed by
 193 fvec_alpha_norm().
 194
 195   \param v vector to compute norm from
 196   \param p order of the computed norm
 197
 198 */
 199 void fvec_alpha_normalise (fvec_t * v, smpl_t p);
 200
 201 /** add a constant to each elements of a vector
 202
 203   \param v vector to add constant to
 204   \param c constant to add to v
 205
 206 */
 207 void fvec_add (fvec_t * v, smpl_t c);
 208
 209 /** remove the minimum value of the vector to each elements
 210
 211   \param v vector to remove minimum from
 212
 213 */
 214 void fvec_min_removal (fvec_t * v);
 215
 216 /** compute moving median theshold of a vector
 217
 218   This function computes the moving median threshold value of at the given
 219 position of a vector, taking the median amongs post elements before and up to
 220 pre elements after pos.
 221
 222   \param v input vector
 223   \param tmp temporary vector of length post+1+pre
 224   \param post length of causal part to take before pos
 225   \param pre length of anti-causal part to take after pos
 226   \param pos index to compute threshold for
 227
 228   \return moving median threshold value
 229
 230 */
 231 smpl_t fvec_moving_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre,
 232     uint_t pos, uint_t channel);
 233
 234 /** apply adaptive threshold to a vector
 235
 236   For each points at position p of an input vector, this function remove the
 237 moving median threshold computed at p.
 238
 239   \param v input vector
 240   \param tmp temporary vector of length post+1+pre
 241   \param post length of causal part to take before pos
 242   \param pre length of anti-causal part to take after pos
 243
 244 */
 245 void fvec_adapt_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre,
 246     uint_t channel);
 247
 248 /** returns the median of a vector
 249
 250   The QuickSelect routine is based on the algorithm described in "Numerical
 251 recipes in C", Second Edition, Cambridge University Press, 1992, Section 8.5,
 252 ISBN 0-521-43108-5
 253
 254   This implementation of the QuickSelect routine is based on Nicolas
 255 Devillard's implementation, available at http://ndevilla.free.fr/median/median/
 256 and in the Public Domain.
 257
 258   \param v vector to get median from
 259   \param channel channel to get median from
 260
 261   \return the median of v
 262
 263 */
 264 smpl_t fvec_median_channel (fvec_t * v, uint_t channel);
 265
 266 /** finds exact peak index by quadratic interpolation*/
 267 smpl_t fvec_quadint (fvec_t * x, uint_t pos, uint_t channel);
 268
 269 /** Quadratic interpolation using Lagrange polynomial.
 270
 271   Inspired from ``Comparison of interpolation algorithms in real-time sound
 272 processing'', Vladimir Arnost,
 273
 274   \param s0,s1,s2 are 3 consecutive samples of a curve
 275   \param pf is the floating point index [0;2]
 276
 277   \return s0 + (pf/2.)*((pf-3.)*s0-2.*(pf-2.)*s1+(pf-1.)*s2);
 278
 279 */
 280 smpl_t aubio_quadfrac (smpl_t s0, smpl_t s1, smpl_t s2, smpl_t pf);
 281
 282 /** return 1 if v[p] is a peak and positive, 0 otherwise
 283
 284   This function returns 1 if a peak is found at index p in the vector v. The
 285 peak is defined as follows:
 286
 287   - v[p] is positive
 288   - v[p-1] < v[p]
 289   - v[p] > v[p+1]
 290
 291   \param v input vector
 292   \param p position of supposed for peak
 293
 294   \return 1 if a peak is found, 0 otherwise
 295
 296 */
 297 uint_t fvec_peakpick (fvec_t * v, uint_t p);
 298
 299 /** convert frequency bin to midi value */
 300 smpl_t aubio_bintomidi (smpl_t bin, smpl_t samplerate, smpl_t fftsize);
 301
 302 /** convert midi value to frequency bin */
 303 smpl_t aubio_miditobin (smpl_t midi, smpl_t samplerate, smpl_t fftsize);
 304
 305 /** convert frequency bin to frequency (Hz) */
 306 smpl_t aubio_bintofreq (smpl_t bin, smpl_t samplerate, smpl_t fftsize);
 307
 308 /** convert frequency (Hz) to frequency bin */
 309 smpl_t aubio_freqtobin (smpl_t freq, smpl_t samplerate, smpl_t fftsize);
 310
 311 /** convert frequency (Hz) to midi value (0-128) */
 312 smpl_t aubio_freqtomidi (smpl_t freq);
 313
 314 /** convert midi value (0-128) to frequency (Hz) */
 315 smpl_t aubio_miditofreq (smpl_t midi);
 316
 317 /** return 1 if a is a power of 2, 0 otherwise */
 318 uint_t aubio_is_power_of_two(uint_t a);
 319
 320 /** return the next power of power of 2 greater than a */
 321 uint_t aubio_next_power_of_two(uint_t a);
 322
 323 /** compute sound pressure level (SPL) in dB
 324
 325   This quantity is often wrongly called 'loudness'.
 326
 327   \param v vector to compute dB SPL from
 328
 329   \return level of v in dB SPL
 330
 331 */
 332 smpl_t aubio_db_spl (fvec_t * v);
 333
 334 /** check if buffer level in dB SPL is under a given threshold
 335
 336   \param v vector to get level from
 337   \param threshold threshold in dB SPL
 338
 339   \return 0 if level is under the given threshold, 1 otherwise
 340
 341 */
 342 uint_t aubio_silence_detection (fvec_t * v, smpl_t threshold);
 343
 344 /** get buffer level if level >= threshold, 1. otherwise
 345
 346   \param v vector to get level from
 347   \param threshold threshold in dB SPL
 348
 349   \return level in dB SPL if level >= threshold, 1. otherwise
 350
 351 */
 352 smpl_t aubio_level_detection (fvec_t * v, smpl_t threshold);
 353
 354 /** compute normalised autocorrelation function
 355
 356   \param input vector to compute autocorrelation from
 357   \param output vector to store autocorrelation function to
 358
 359 */
 360 void aubio_autocorr (fvec_t * input, fvec_t * output);
 361
 362 /** zero-crossing rate (ZCR)
 363
 364   The zero-crossing rate is the number of times a signal changes sign,
 365   divided by the length of this signal.
 366
 367   \param v vector to compute ZCR from
 368
 369   \return zero-crossing rate of v
 370
 371 */
 372 smpl_t aubio_zero_crossing_rate (fvec_t * v);
 373
 374 /** clean up cached memory at the end of program
 375
 376   This function should be used at the end of programs to purge all cached
 377   memory. So far it is only useful to clean FFTW's cache.
 378
 379 */
 380 void aubio_cleanup (void);
 381
 382 #ifdef __cplusplus
 383 }
 384 #endif
 385
 386 #endif
 387