move libc aliases from mathutils.h to to aubio_priv.h
[aubio.git] / src / mathutils.h
1 /*
2          Copyright (C) 2003 Paul Brossier
3
4          This program is free software; you can redistribute it and/or modify
5          it under the terms of the GNU General Public License as published by
6          the Free Software Foundation; either version 2 of the License, or
7          (at your option) any later version.
8
9          This program is distributed in the hope that it will be useful,
10          but WITHOUT ANY WARRANTY; without even the implied warranty of
11          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12          GNU General Public License for more details.
13
14          You should have received a copy of the GNU General Public License
15          along with this program; if not, write to the Free Software
16          Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17
18 */
19
20 /** @file
21  *  various math functions
22  *
23  *  \todo multichannel (each function should return -or set- an array sized to
24  *  the number of channel in the input vector)
25  *
26  *  \todo appropriate switches depending on types.h content
27  */
28
29 #ifndef MATHUTILS_H
30 #define MATHUTILS_H
31
32 /** Window types 
33  * 
34  * inspired from 
35  *
36  *  - dafx : http://profs.sci.univr.it/%7Edafx/Final-Papers/ps/Bernardini.ps.gz
37  *  - freqtweak : http://freqtweak.sf.net/
38  *  - extace : http://extace.sf.net/
39  */
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 typedef enum {
46         aubio_win_rectangle,          
47         aubio_win_hamming,
48         aubio_win_hanning,
49         aubio_win_hanningz,
50         aubio_win_blackman,
51         aubio_win_blackman_harris,
52         aubio_win_gaussian,
53         aubio_win_welch,
54         aubio_win_parzen
55 } aubio_window_type;
56
57 /** create window */
58 void aubio_window(smpl_t *w, uint_t size, aubio_window_type wintype);
59
60 /** principal argument
61  *
62  * mod(phase+PI,-TWO_PI)+PI 
63  */
64 smpl_t aubio_unwrap2pi (smpl_t phase);
65
66 /** calculates the mean of a vector
67  *
68  * \bug mono 
69  */
70 smpl_t vec_mean(fvec_t *s);
71 /** returns the max of a vector
72  *
73  * \bug mono 
74  */
75 smpl_t vec_max(fvec_t *s);
76 /** returns the min of a vector
77  *
78  * \bug mono 
79  */
80 smpl_t vec_min(fvec_t *s);
81 /** returns the index of the min of a vector
82  *
83  * \bug mono 
84  */
85 uint_t vec_min_elem(fvec_t *s);
86 /** returns the index of the max of a vector
87  *
88  * \bug mono 
89  */
90 uint_t vec_max_elem(fvec_t *s);
91 /** implement 'fftshift' like function
92  * 
93  * a[0]...,a[n/2],a[n/2+1],...a[n]
94  * 
95  * becomes
96  * 
97  * a[n/2+1],...a[n],a[0]...,a[n/2]
98  */
99 void vec_shift(fvec_t *s);
100 /** returns sum */
101 smpl_t vec_sum(fvec_t *s);
102 /** returns energy 
103  *
104  * \bug mono 
105  */
106 smpl_t vec_local_energy(fvec_t * f);
107 /** returns High Frequency Energy Content
108  *
109  * \bug mono */
110 smpl_t vec_local_hfc(fvec_t * f);
111 /** return alpha norm.
112  *
113  * alpha=2 means normalise variance. 
114  * alpha=1 means normalise abs value. 
115  * as alpha goes large, tends to normalisation 
116  * by max value.
117  *
118  * \bug should not use POW :(
119  */
120 smpl_t vec_alpha_norm(fvec_t * DF, smpl_t alpha);
121 /*  dc(min) removal */
122 void vec_dc_removal(fvec_t * mag);
123 /**  alpha normalisation */
124 void vec_alpha_normalise(fvec_t * mag, uint_t alpha);
125
126 void vec_add(fvec_t * mag, smpl_t threshold);
127
128 void vec_adapt_thres(fvec_t * vec, fvec_t * tmp, 
129     uint_t win_post, uint_t win_pre);
130 /**  adaptative thresholding 
131  *
132  * y=fn_thresh(fn,x,post,pre)
133  * compute adaptive threshold at each time 
134  *    fn : a function name or pointer, eg 'median'
135  *    x:   signal vector
136  *    post: window length, causal part
137  *    pre: window length, anti-causal part
138  * Returns:
139  *    y:   signal the same length as x
140  *
141  * Formerly median_thresh, used compute median over a 
142  * window of post+pre+1 samples, but now works with any
143  * function that takes a vector or matrix and returns a
144  * 'representative' value for each column, eg
145  *    medians=fn_thresh(median,x,8,8)  
146  *    minima=fn_thresh(min,x,8,8)  
147  * see SPARMS for explanation of post and pre
148  */
149 smpl_t vec_moving_thres(fvec_t * vec, fvec_t * tmp, 
150     uint_t win_post, uint_t win_pre, uint_t win_pos);
151
152 /** returns the median of the vector 
153  *
154  *  This Quickselect routine is based on the algorithm described in
155  *  "Numerical recipes in C", Second Edition,
156  *  Cambridge University Press, 1992, Section 8.5, ISBN 0-521-43108-5
157  *
158  *  This code by Nicolas Devillard - 1998. Public domain,
159  *  available at http://ndevilla.free.fr/median/median/
160  */
161 smpl_t vec_median(fvec_t * input);
162
163 /** finds exact maximum position by quadratic interpolation*/
164 smpl_t vec_quadint(fvec_t * x,uint_t pos);
165
166 /** finds exact minimum position by quadratic interpolation*/
167 smpl_t vec_quadint_min(fvec_t * x,uint_t pos, uint_t span);
168
169 /** Quadratic interpolation using Lagrange polynomial.
170  *
171  * inspired from ``Comparison of interpolation algorithms in real-time sound
172  * processing'', Vladimir Arnost, 
173  * 
174  * estimate = s0 + (pf/2.)*((pf-3.)*s0-2.*(pf-2.)*s1+(pf-1.)*s2);
175  *    where 
176  *    \param s0,s1,s2 are 3 known points on the curve,
177  *    \param pf is the floating point index [0;2]
178  */
179 smpl_t aubio_quadfrac(smpl_t s0, smpl_t s1, smpl_t s2, smpl_t pf);
180
181 /** returns 1 if X1 is a peak and positive */
182 uint_t vec_peakpick(fvec_t * input, uint_t pos);
183
184 smpl_t aubio_bintomidi(smpl_t bin, smpl_t samplerate, smpl_t fftsize);
185 smpl_t aubio_miditobin(smpl_t midi, smpl_t samplerate, smpl_t fftsize);
186 smpl_t aubio_bintofreq(smpl_t bin, smpl_t samplerate, smpl_t fftsize);
187 smpl_t aubio_freqtobin(smpl_t freq, smpl_t samplerate, smpl_t fftsize);
188 smpl_t aubio_freqtomidi(smpl_t freq);
189 smpl_t aubio_miditofreq(smpl_t midi);
190
191 uint_t aubio_silence_detection(fvec_t * ibuf, smpl_t threshold);
192 smpl_t aubio_level_detection(fvec_t * ibuf, smpl_t threshold);
193 /** 
194  * calculate normalised autocorrelation function
195  */
196 void aubio_autocorr(fvec_t * input, fvec_t * output);
197 /**
198  * clean up cached memory at the end of program
199  *
200  * use this function at the end of programs to purge all
201  * cached memory. so far this function is only used to clean
202  * fftw cache.
203  */
204 void aubio_cleanup(void);
205
206 #ifdef __cplusplus
207 }
208 #endif
209
210 #endif
211