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
  23   Various math functions
  24
  25   \example test-mathutils.c
  26   \example test-mathutils-window.c
  27
  28  */
  29
  30 #ifndef MATHUTILS_H
  31 #define 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 energy of a vector
 112
 113   This function compute the sum of the squared elements of a vector, normalised
 114   by its length.
 115
 116   \param v vector to get the energy from
 117
 118   \return the energy of v
 119
 120 */
 121 smpl_t fvec_local_energy (fvec_t * v);
 122
 123 /** compute the High Frequency Content of a vector
 124
 125   The High Frequency Content is defined as \f$ \sum_0^{N-1} (k+1) v[k] \f$.
 126
 127   \param v vector to get the energy from
 128
 129   \return the HFC of v
 130
 131 */
 132 smpl_t fvec_local_hfc (fvec_t * v);
 133
 134 /** computes the p-norm of a vector
 135
 136   Computes the p-norm of a vector for \f$ p = \alpha \f$
 137
 138   \f$ L^p = ||x||_p = (|x_1|^p + |x_2|^p + ... + |x_n|^p ) ^ \frac{1}{p} \f$
 139
 140   If p = 1, the result is the Manhattan distance.
 141
 142   If p = 2, the result is the Euclidean distance.
 143
 144   As p tends towards large values, \f$ L^p \f$ tends towards the maximum of the
 145 input vector.
 146
 147   References:
 148
 149     - <a href="http://en.wikipedia.org/wiki/Lp_space">\f$L^p\f$ space</a> on
 150   Wikipedia
 151
 152   \param v vector to compute norm from
 153   \param p order of the computed norm
 154
 155   \return the p-norm of v
 156
 157 */
 158 smpl_t fvec_alpha_norm (fvec_t * v, smpl_t p);
 159
 160 /**  alpha normalisation
 161
 162   This function divides all elements of a vector by the p-norm as computed by
 163 fvec_alpha_norm().
 164
 165   \param v vector to compute norm from
 166   \param p order of the computed norm
 167
 168 */
 169 void fvec_alpha_normalise (fvec_t * v, smpl_t p);
 170
 171 /** add a constant to each elements of a vector
 172
 173   \param v vector to add constant to
 174   \param c constant to add to v
 175
 176 */
 177 void fvec_add (fvec_t * v, smpl_t c);
 178
 179 /** remove the minimum value of the vector to each elements
 180
 181   \param v vector to remove minimum from
 182
 183 */
 184 void fvec_min_removal (fvec_t * v);
 185
 186 /** compute moving median threshold of a vector
 187
 188   This function computes the moving median threshold value of at the given
 189 position of a vector, taking the median among post elements before and up to
 190 pre elements after pos.
 191
 192   \param v input vector
 193   \param tmp temporary vector of length post+1+pre
 194   \param post length of causal part to take before pos
 195   \param pre length of anti-causal part to take after pos
 196   \param pos index to compute threshold for
 197
 198   \return moving median threshold value
 199
 200 */
 201 smpl_t fvec_moving_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre,
 202     uint_t pos);
 203
 204 /** apply adaptive threshold to a vector
 205
 206   For each points at position p of an input vector, this function remove the
 207 moving median threshold computed at p.
 208
 209   \param v input vector
 210   \param tmp temporary vector of length post+1+pre
 211   \param post length of causal part to take before pos
 212   \param pre length of anti-causal part to take after pos
 213
 214 */
 215 void fvec_adapt_thres (fvec_t * v, fvec_t * tmp, uint_t post, uint_t pre);
 216
 217 /** returns the median of a vector
 218
 219   The QuickSelect routine is based on the algorithm described in "Numerical
 220 recipes in C", Second Edition, Cambridge University Press, 1992, Section 8.5,
 221 ISBN 0-521-43108-5
 222
 223   This implementation of the QuickSelect routine is based on Nicolas
 224 Devillard's implementation, available at http://ndevilla.free.fr/median/median/
 225 and in the Public Domain.
 226
 227   \param v vector to get median from
 228
 229   \return the median of v
 230
 231 */
 232 smpl_t fvec_median (fvec_t * v);
 233
 234 /** finds exact peak index by quadratic interpolation
 235
 236   See [Quadratic Interpolation of Spectral
 237   Peaks](https://ccrma.stanford.edu/~jos/sasp/Quadratic_Peak_Interpolation.html),
 238   by Julius O. Smith III
 239
 240   \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$
 241
 242   \param x vector to get the interpolated peak position from
 243   \param p index of the peak in vector `x`
 244   \return \f$ p + p_{frac} \f$ exact peak position of interpolated maximum or minimum
 245
 246 */
 247 smpl_t fvec_quadratic_peak_pos (fvec_t * x, uint_t p);
 248
 249 /** Quadratic interpolation using Lagrange polynomial.
 250
 251   Inspired from ``Comparison of interpolation algorithms in real-time sound
 252 processing'', Vladimir Arnost,
 253
 254   \param s0,s1,s2 are 3 consecutive samples of a curve
 255   \param pf is the floating point index [0;2]
 256
 257   \return \f$ s0 + (pf/2.)*((pf-3.)*s0-2.*(pf-2.)*s1+(pf-1.)*s2); \f$
 258
 259 */
 260 smpl_t aubio_quadfrac (smpl_t s0, smpl_t s1, smpl_t s2, smpl_t pf);
 261
 262 /** return 1 if v[p] is a peak and positive, 0 otherwise
 263
 264   This function returns 1 if a peak is found at index p in the vector v. The
 265 peak is defined as follows:
 266
 267   - v[p] is positive
 268   - v[p-1] < v[p]
 269   - v[p] > v[p+1]
 270
 271   \param v input vector
 272   \param p position of supposed for peak
 273
 274   \return 1 if a peak is found, 0 otherwise
 275
 276 */
 277 uint_t fvec_peakpick (fvec_t * v, uint_t p);
 278
 279 /** return 1 if a is a power of 2, 0 otherwise */
 280 uint_t aubio_is_power_of_two(uint_t a);
 281
 282 /** return the next power of power of 2 greater than a */
 283 uint_t aubio_next_power_of_two(uint_t a);
 284
 285 /** compute normalised autocorrelation function
 286
 287   \param input vector to compute autocorrelation from
 288   \param output vector to store autocorrelation function to
 289
 290 */
 291 void aubio_autocorr (fvec_t * input, fvec_t * output);
 292
 293 #ifdef __cplusplus
 294 }
 295 #endif
 296
 297 #endif
 298