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 #include "fvec.h"
  29 #include "musicutils.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /** compute the mean of a vector
  36
  37   \param s vector to compute mean from
  38
  39   \return the mean of v
  40
  41 */
  42 smpl_t fvec_mean (fvec_t * s);
  43
  44 /** find the max of a vector
  45
  46   \param s vector to get the max from
  47
  48   \return the value of the minimum of v
  49
  50 */
  51 smpl_t fvec_max (fvec_t * s);
  52
  53 /** find the min of a vector
  54
  55   \param s vector to get the min from
  56
  57   \return the value of the maximum of v
  58
  59 */
  60 smpl_t fvec_min (fvec_t * s);
  61
  62 /** find the index of the min of a vector
  63
  64   \param s vector to get the index from
  65
  66   \return the index of the minimum element of v
  67
  68 */
  69 uint_t fvec_min_elem (fvec_t * s);
  70
  71 /** find the index of the max of a vector
  72
  73   \param s vector to get the index from
  74
  75   \return the index of the maximum element of v
  76
  77 */
  78 uint_t fvec_max_elem (fvec_t * s);
  79
  80 /** swap the left and right halves of a vector
  81
  82   This function swaps the left part of the signal with the right part of the
  83 signal. Therefore
  84
  85   \f$ a[0], a[1], ..., a[\frac{N}{2}], a[\frac{N}{2}+1], ..., a[N-1], a[N] \f$
  86
  87   becomes
  88
  89   \f$ a[\frac{N}{2}+1], ..., a[N-1], a[N], a[0], a[1], ..., a[\frac{N}{2}] \f$
  90
  91   This operation, known as 'fftshift' in the Matlab Signal Processing Toolbox,
  92 can be used before computing the FFT to simplify the phase relationship of the
  93 resulting spectrum. See Amalia de Götzen's paper referred to above.
  94
  95 */
  96 void fvec_shift (fvec_t * v);
  97
  98 /** compute the sum of all elements of a vector
  99
 100   \param v vector to compute the sum of
 101
 102   \return the sum of v
 103
 104 */
 105 smpl_t fvec_sum (fvec_t * v);
 106
 107 /** compute the energy of a vector
 108
 109   This function compute the sum of the squared elements of a vector.
 110
 111   \param v vector to get the energy from
 112
 113   \return the energy of v
 114
 115 */
 116 smpl_t fvec_local_energy (fvec_t * v);
 117
 118 /** compute the High Frequency Content of a vector
 119
 120   The High Frequency Content is defined as \f$ \sum_0^{N-1} (k+1) v[k] \f$.
 121
 122   \param v vector to get the energy from
 123
 124   \return the HFC of v
 125
 126 */
 127 smpl_t fvec_local_hfc (fvec_t * v);
 128
 129 /** computes the p-norm of a vector
 130
 131   Computes the p-norm of a vector for \f$ p = \alpha \f$
 132
 133   \f$ L^p = ||x||_p = (|x_1|^p + |x_2|^p + ... + |x_n|^p ) ^ \frac{1}{p} \f$
 134
 135   If p = 1, the result is the Manhattan distance.
 136
 137   If p = 2, the result is the Euclidean distance.
 138
 139   As p tends towards large values, \f$ L^p \f$ tends towards the maximum of the
 140 input vector.
 141
 142   References:
 143
 144     - <a href="http://en.wikipedia.org/wiki/Lp_space">\f$L^p\f$ space</a> on
 145   Wikipedia
 146
 147   \param v vector to compute norm from
 148   \param p order of the computed norm
 149
 150   \return the p-norm of v
 151
 152 */
 153 smpl_t fvec_alpha_norm (fvec_t * v, smpl_t p);
 154
 155 /**  alpha normalisation
 156
 157   This function divides all elements of a vector by the p-norm as computed by
 158 fvec_alpha_norm().
 159
 160   \param v vector to compute norm from
 161   \param p order of the computed norm
 162
 163 */
 164 void fvec_alpha_normalise (fvec_t * v, smpl_t p);
 165
 166 /** add a constant to each elements of a vector
 167
 168   \param v vector to add constant to
 169   \param c constant to add to v
 170
 171 */
 172 void fvec_add (fvec_t * v, smpl_t c);
 173
 174 /** remove the minimum value of the vector to each elements
 175
 176   \param v vector to remove minimum from
 177
 178 */
 179 void fvec_min_removal (fvec_t * v);
 180
 181 /** compute moving median theshold of a vector
 182
 183   This function computes the moving median threshold value of at the given
 184 position of a vector, taking the median amongs post elements before and up to
 185 pre elements after pos.
 186
 187   \param v input vector
 188   \param tmp temporary vector of length post+1+pre
 189   \param post length of causal part to take before pos
 190   \param pre length of anti-causal part to take after pos
 191   \param pos index to compute threshold for
 192
 193   \return moving median threshold value
 194
 195 */
 196 smpl_t fvec_moving_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre,
 197     uint_t pos);
 198
 199 /** apply adaptive threshold to a vector
 200
 201   For each points at position p of an input vector, this function remove the
 202 moving median threshold computed at p.
 203
 204   \param v input vector
 205   \param tmp temporary vector of length post+1+pre
 206   \param post length of causal part to take before pos
 207   \param pre length of anti-causal part to take after pos
 208
 209 */
 210 void fvec_adapt_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre);
 211
 212 /** returns the median of a vector
 213
 214   The QuickSelect routine is based on the algorithm described in "Numerical
 215 recipes in C", Second Edition, Cambridge University Press, 1992, Section 8.5,
 216 ISBN 0-521-43108-5
 217
 218   This implementation of the QuickSelect routine is based on Nicolas
 219 Devillard's implementation, available at http://ndevilla.free.fr/median/median/
 220 and in the Public Domain.
 221
 222   \param v vector to get median from
 223
 224   \return the median of v
 225
 226 */
 227 smpl_t fvec_median (fvec_t * v);
 228
 229 /** finds exact peak index by quadratic interpolation*/
 230 smpl_t fvec_quadint (fvec_t * x, uint_t pos);
 231
 232 /** Quadratic interpolation using Lagrange polynomial.
 233
 234   Inspired from ``Comparison of interpolation algorithms in real-time sound
 235 processing'', Vladimir Arnost,
 236
 237   \param s0,s1,s2 are 3 consecutive samples of a curve
 238   \param pf is the floating point index [0;2]
 239
 240   \return s0 + (pf/2.)*((pf-3.)*s0-2.*(pf-2.)*s1+(pf-1.)*s2);
 241
 242 */
 243 smpl_t aubio_quadfrac (smpl_t s0, smpl_t s1, smpl_t s2, smpl_t pf);
 244
 245 /** return 1 if v[p] is a peak and positive, 0 otherwise
 246
 247   This function returns 1 if a peak is found at index p in the vector v. The
 248 peak is defined as follows:
 249
 250   - v[p] is positive
 251   - v[p-1] < v[p]
 252   - v[p] > v[p+1]
 253
 254   \param v input vector
 255   \param p position of supposed for peak
 256
 257   \return 1 if a peak is found, 0 otherwise
 258
 259 */
 260 uint_t fvec_peakpick (fvec_t * v, uint_t p);
 261
 262 /** return 1 if a is a power of 2, 0 otherwise */
 263 uint_t aubio_is_power_of_two(uint_t a);
 264
 265 /** return the next power of power of 2 greater than a */
 266 uint_t aubio_next_power_of_two(uint_t a);
 267
 268 /** compute normalised autocorrelation function
 269
 270   \param input vector to compute autocorrelation from
 271   \param output vector to store autocorrelation function to
 272
 273 */
 274 void aubio_autocorr (fvec_t * input, fvec_t * output);
 275
 276 #ifdef __cplusplus
 277 }
 278 #endif
 279
 280 #endif
 281