src/mathutils.h

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