source: src/mathutils.h @ eb7f743

feature/autosinkfeature/constantqfeature/pitchshiftfeature/pydocstringsfeature/timestretchpitchshiftsamplertimestretchyinfft+
Last change on this file since eb7f743 was eb7f743, checked in by Paul Brossier <piem@piem.org>, 11 years ago

src/mathutils.{c,h}: loop over channels when possible, improve documentation, indent

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