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